swig/Doc/Devel/Javascript/V8_CodeGeneratorSpecification.md

Javascript: Specification of a Code Generator for V8
====================================================

The aim of this is to evolve a specification for a code generator.

## Top Level structure

The generated code consists of the following blocks:

~~~~
<HELPER_FUNCTIONS>

<INCLUDES>

<CLASS_TEMPLATES>

<FUNCTION_WRAPPERS>

<INITIALIZER>

~~~~

- `HELPER_FUNCTIONS`: static, from swg-file
- `INCLUDES`: static, module property
- `CLASS_TEMPLATES`: dynamically growing, on class declarations
- `FUNCTION_WRAPPERS`: dynamically growing, on method declarations
- `INITIALIZER`: dynamically growing, aggregates everything (to be specified in more detail)

### INCLUDES

~~~~
#include <v8.h>

<USER_DEFINED_INCLUDES>
~~~~

`USER_DEFINED_INCLUDES`: a module property

### CLASS_TEMPLATES

Static references to class templates which are (should be) read-only and can be reused.

~~~~
v8::Persistent<v8::FunctionTemplate> SWIGV8_${NAME_MANGLED};
~~~~

Notes:
 - it is very important to consider namespaces from the beginning.
   `NAME_MANGLED` is the mangled qualified class name, e.g., `foo_bar_MyClass` for `foo::bar::MyClass`,
   which is retrieved ny `Swig_string_mangle(Getattr(n, "name"))`
 - namespaces do not need a function template, as they will not be
   instantiated

## FUNCTION_WRAPPERS

There are different types of function wrappers:

 - Global Functions (global/namespace/class) 
 - Constructors / Destructors
 - Getters / Settters
 - Member Functions

### Global Functions

~~~~
v8::Handle<v8::Value> wrap_${NAME_MANGLED}(const v8::Arguments &args) {
    v8::HandleScope scope;
    v8::Handle<v8::Value> ret;

    ${LOCALS}
    ${MARSHAL_INPUT}
    ${ACTION}
    ${MARSHAL_OUTPUT}
    
    return scope.Close(ret);
}
~~~~

### Constructors

~~~~
v8::Handle<v8::Value> ${NAME_MANGLED}_new(const v8::Arguments& args) {
    v8::HandleScope scope;
    v8::Handle<v8::Object> self = args.Holder();
    ${LOCALS}
    ${MARSHAL_INPUT}
    ${ACTION}
    self->SetInternalField(0, v8::External::New(ptr));
    return self;        
}
~~~~

- `LOCALS`: declaration and marshalling for input arguments
- `MARSHAL_INPUT`: code is generated by applying input typemaps
- `ACTION`: the C/C++ ctor to be executed

### Destructors

TODO: I haven't found out yet how a descrtuctor can be registered

### Getters

~~~~
v8::Handle<v8::Value> ${NAME_MANGLED}_get(v8::Local<v8::String> property, const v8::AccessorInfo& info) {
    v8::HandleScope scope;
    v8::Handle<v8::Object> ret;
    ${LOCALS}
    ${ACTION}
    ${MARSHAL_OUTPUT}
    return scope.Close(ret);
}
~~~~

- `NAME_MANGLED`: the qualified mangled name of the variable, E.g., `foo::x -> foo_x`,  `A.x -> A_x`
- `LOCALS`: declare C return variable
- `MARSHAL_OUTPUT`: code is generated by applying output typemaps

### Setters

~~~~
void ${NAME_MANGLED}_set(v8::Local<v8::String> property, v8::Local<v8::Value> value, const v8::AccessorInfo& info) {
    ${LOCALS}
    ${MARSHAL_INPUT}
    ${ACTION}
}
~~~~
- `NAME_MANGLED`: the qualified mangled name of the variable, E.g., `foo::x -> foo_x`,  `A.x -> A_x`
- `LOCALS`: declarations for input arguments
- `MARSHAL_INPUT`: code is generated by applying input typemaps

### Functions

~~~~
v8::Handle<v8::Value> ${NAME_MANGLED}(const Arguments &args) {
    v8::HandleScope scope;
    v8::Handle<v8::Object> ret;
    ${LOCALS}
    ${MARSHAL_INPUT}
    ${ACTION}
    ${MARSHAL_OUTPUT}
    return scope.Close(ret);
}
~~~~

- if the function does not have a return value, return v8::Undefined

### Overloading

TODO: if a function or a ctor is overloaded, a dispatcher function
must be generated which calls overloading wrappers depending on number
and type of input arguments.


## Initializer

~~~~
void ${MODULE}_Initialize(v8::Handle<v8::Context> context)
{
    v8::HandleScope scope;

    // register the module in globale context
    v8::Local<v8::Object> global = context->Global();

    ${PART_NAMESPACES}

    ${PART_CLASS_TEMPLATES}

    ${PART_WRAPPERS}

    ${PART_INHERITANCE}

    ${PART_REGISTER}
}
~~~~

### Namespaces

Namespaces are objects without class templates. I.e., instances are created,
referenced locally, used as contexts for other registrations, and stored
in the according parent contexts.

~~~~~
v8::Handle<v8::ObjectTemplate> ${NAME_MANGLED} = v8::ObjectTemplate::New();
~~~~~

### Class Templates

~~~~
SWIGV8_${NAME_MANGLED} = SWIGV8_CreateClassTemplate("${NAME_UNQUALIFIED}" , ${NAME_MANGLED}_new);
~~~~

- `NAME_UNQUALIFIED`: the class name without context, i.e., namespaces

### Inheritance

~~~~
SWIGV8_${NAME_MANGLED}->Inherit(SWIGV8_${BASE_CLASS});
~~~~

- Note: multiple inheritance is not possible; thus we will always take the first parent class

### Registration

The registration part consists of registering classes at contexts (i.e., global or namespace),
methods and properties at classes or contexts, and namespaces as objects at
parent contexts. 

#### Global Variable

~~~~
${CONTEXT}->SetAccessor(v8::String::NewSymbol("${NAME_UNQUALIFIED}"), ${GETTER}, ${SETTER});
~~~~

- `CONTEXT`: either global, or the according namespace template
- `${SETTER} = 0` for read-only variables

#### Global Function

~~~~
${CONTEXT}->Set(v8::String::NewSymbol("${NAME_UNQUALIFIED}"), v8::FunctionTemplate::New(wrap_${NAME_QUALIFIED})->GetFunction());
~~~~

- `CONTEXT`: either global, or the according namespace template

#### Class

~~~~
${CONTEXT}->Set(v8::String::NewSymbol("${NAME_UNQUALIFIED}", SWIGV8_${NAME_MANGLED}->GetFunction()));
~~~~

- Note: every class template has an associated ctor function wrapper, which is registered here
- `CONTEXT`: either global, or the according namespace instance

#### Class method

~~~~
SWIGV8_AddClassMethod(SWIGV8_${CLASSNAME_MANGLED}, "${NAME_UNQUALIFIED}", wrap_${NAME_MANGLED});
~~~~

Note: implemented in static helper function

#### Class variable

~~~~
SWIGV8_AddProperty(SWIGV8_${CLASSNAME_MANGLED}, "${NAME_UNQUALIFIED}", ${GETTER}, ${SETTER});
~~~~

- `GETTER`: the name of the generated wrapper for the property getter
- `SETTER`: the name of the generated wrapper for property setter; optional (i.e., maybe `NULL`)

### Namespace

~~~~
${CONTEXT}->Set(v8::String::NewSymbol("${NAME_UNQUALIFIED}", ${NAME_MANGLED}->NewInstance()));
~~~~

Note: it is important to register the namespace objects in reverse order,
e.g.,

~~~~
namespace foo { 
    namespace bar {}
}
~~~~

would be registered in this order:

~~~~
foo->Set(v8::String::NewSymbol("bar", bar->NewInstance()));
global->Set(v8::String::NewSymbol("foo", foo->NewInstance()));
~~~~

## HELPER_FUNCTIONS

A lot of boiler-plate code can be shifted into static helper functions:

~~~~

/**
 * Creates a class template for a class without extra initialization function. 
 */
v8::Persistent<v8::FunctionTemplate> SWIGV8_CreateClassTemplate(const char* symbol) {
    v8::Local<v8::FunctionTemplate> class_templ = v8::FunctionTemplate::New();
    class_templ->SetClassName(v8::String::NewSymbol(symbol));

    v8::Handle<v8::ObjectTemplate> inst_templ = class_templ->InstanceTemplate();
    inst_templ->SetInternalFieldCount(1);

    return v8::Persistent<v8::FunctionTemplate>::New(class_templ);
}

/**
 * Creates a class template for a class with specified initialization function. 
 */
v8::Persistent<v8::FunctionTemplate> SWIGV8_CreateClassTemplate(const char* symbol, v8::InvocationCallback _func) {
    v8::Local<v8::FunctionTemplate> class_templ = v8::FunctionTemplate::New(_func);
    class_templ->SetClassName(v8::String::NewSymbol(symbol));

    v8::Handle<v8::ObjectTemplate> inst_templ = class_templ->InstanceTemplate();
    inst_templ->SetInternalFieldCount(1);

    return v8::Persistent<v8::FunctionTemplate>::New(class_templ);
}

/**
 * Sets the pimpl data of a V8 class. 
 */
v8::Handle<v8::Value> V8GeneratorUtils::SetInstance(const v8::Arguments& args, void* data) {
    v8::HandleScope scope;

    v8::Handle<v8::Object> self = args.Holder();
    self->SetInternalField(0, v8::External::New(data));

    return self;
}

/**
 * Registers a class method with given name for a given class template. 
 */
void V8GeneratorUtils::AddClassMethod(v8::Handle<v8::FunctionTemplate> class_templ, const char* symbol, v8::InvocationCallback _func) {
    v8::Handle<v8::ObjectTemplate> proto_templ = class_templ->PrototypeTemplate();
    proto_templ->Set(v8::String::NewSymbol(symbol), v8::FunctionTemplate::New(_func));    
}

/**
 * Registers a class property with given name for a given class template. 
 */
void V8GeneratorUtils::AddProperty(v8::Handle<v8::FunctionTemplate> class_templ, const char* varname, v8::AccessorGetter getter, v8::AccessorSetter setter) {
    v8::Handle<v8::ObjectTemplate> proto_templ = class_templ->InstanceTemplate();
    proto_templ->SetAccessor(v8::String::New(varname), getter, setter);
}

~~~~

-------------------------

Examples
========

In this chapter manually coded wrappers are presented.
This has been useful for studying the addressed code generation on basis
of examples.

## Global variable

~~~~~
static double Foo = 42.0;

void Foo_set(v8::Local<v8::String> property, v8::Local<v8::Value> value, const v8::AccessorInfo& info) {
    v8::HandleScope scope;
    double arg1 ;
    arg1 = value->NumberValue();
    Foo = arg1;
}

v8::Handle<v8::Value> Foo_get(v8::Local<v8::String> property, const v8::AccessorInfo& info) {
  v8::HandleScope scope;
  v8::Handle<v8::Value> ret;
  double result;

  result = Foo;
  
  ret = v8::Number::New(result);
  return scope.Close(ret);
}

int GlobalVar_Initialize(v8::Handle<v8::Context> context) {
    
    v8::Local<v8::Object> global = context->Global();
    global->SetAccessor(v8::String::New("Foo"), Foo_get, Foo_set);

    return 0;
}
~~~~~

## Global functions

~~~~~

static double foo(int bla) {
    return (bla * 2.1);
}

v8::Handle<v8::Value> wrap_foo(const v8::Arguments &args) {
    v8::HandleScope scope;
    v8::Handle<v8::Value> ret;

    int arg1 ;
    double result;
    
    arg1 = args[0]->Int32Value();

    result = foo(arg1);

    ret = v8::Number::New(result);
    
    return scope.Close(ret);
}

int GlobalFunc_Initialize(v8::Handle<v8::Context> context) {
    
    v8::Local<v8::Object> global = context->Global();
        
    global->Set(v8::String::NewSymbol("foo"), v8::FunctionTemplate::New(wrap_foo)->GetFunction());

    return 0;
}
~~~~~


## Namespaces

~~~~~

namespace foo {
    static double bar = 42.0;
}

void foo_bar_set(v8::Local<v8::String> property, v8::Local<v8::Value> value, const v8::AccessorInfo& info) {
    v8::HandleScope scope;

    double arg1 ;
    arg1 = value->NumberValue();
    foo::bar = arg1;

}

v8::Handle<v8::Value> foo_bar_get(v8::Local<v8::String> property, const v8::AccessorInfo& info) {
  v8::HandleScope scope;
  v8::Handle<v8::Value> ret;
  double result;

  result = foo::bar;
  
  ret = v8::Number::New(result);
  return scope.Close(ret);
}

int Namespace_Initialize(v8::Handle<v8::Context> context) {
    
    v8::Local<v8::Object> global = context->Global();
    
    v8::Handle<v8::ObjectTemplate> foo = v8::ObjectTemplate::New();

    foo->SetAccessor(v8::String::New("bar"), foo_bar_get, foo_bar_set);
    
    global->Set(v8::String::New("foo"), foo->NewInstance());
    return 0;
}

~~~~~

-------------------------

Control flow analysis
=====================

## Global variables

### Example:
~~~~
int x;

namespace foo {
    double y;
}
~~~~

### Control flow:
Command:
~~~~
swig -analyze -c++ functionWrapper +before globalvariableHandler +before example.i
~~~~

~~~~
enter top() of example
enter variableHandler() of x
enter globalvariableHandler() of x
    | sym:name     - "x"
    | name         - "x"
    | type         - "int"

    enter variableWrapper() of x
    
        enter functionWrapper() of x
            | name         - "x"
            | sym:name     - "x_set"
            | parms        - int
            | wrap:action  - "x = arg1;"
            | type         - "void"
        exit functionWrapper() of x

        enter functionWrapper() of x
            | name         - "x"
            | sym:name     - "x_get"
            | type         - "int"
        exit functionWrapper() of x
    exit variableWrapper() of x
exit globalvariableHandler() of x
exit variableHandler() of x

enter variableHandler() of foo::y
enter globalvariableHandler() of foo::y
    | sym:name     - "y"
    | name         - "foo::y"
    | type         - "double"

    enter variableWrapper() of foo::y
        enter functionWrapper() of foo::y
            | name         - "foo::y"
            | sym:name     - "y_set"
            | parms        - double
            | wrap:action  - "foo::y = arg1;"
            | type         - "void"
        exit functionWrapper() of foo::y
        
        enter functionWrapper() of foo::y
            | name         - "foo::y"
            | sym:name     - "y_get"
            | wrap:action  - "result = (double)foo::y;"
            | type         - "double"
        exit functionWrapper() of foo::y
    exit variableWrapper() of foo::y
exit globalvariableHandler() of foo::y
exit variableHandler() of foo::y
exit top() of example

~~~~

## Simple class

### Example:

~~~~
class A {
public:
    A();
    ~A();
};

namespace foo {
    class B {
    };
}
~~~~

### Control flow:

~~~~
enter top() of example
    enter classHandler() of A
    enter constructorHandler() of A
        enter functionWrapper() of A
            | name         - "A"
            | sym:name     - "new_A"
            | access       - "public"
            | wrap:action  - "result = (A *)new A();"
            | type         - "p.A"
        exit functionWrapper() of A
    exit constructorHandler() of A
    enter destructorHandler() of ~A
        enter functionWrapper() of ~A
            | name         - "~A"
            | sym:name     - "delete_A"
            | parms        - A *
            | wrap:action  - "delete arg1;"
        exit functionWrapper() of ~A
    exit destructorHandler() of ~A
exit classHandler() of A
enter classHandler() of foo::B
    enter constructorHandler() of foo::B::B
        enter functionWrapper() of foo::B::B
            | name         - "foo::B::B"
            | sym:name     - "new_B"
            | access       - "public"
            | wrap:action  - "result = (foo::B *)new foo::B();"
            | type         - "p.foo::B"
        exit functionWrapper() of foo::B::B
    exit constructorHandler() of foo::B::B
    enter destructorHandler() of foo::B::~B
        enter functionWrapper() of foo::B::~B
            | name         - "foo::B::~B"
            | sym:name     - "delete_B"
            | parms        - foo::B *
            | wrap:action  - "delete arg1;"
            | type         - "void"
        exit functionWrapper() of foo::B::~B
    exit destructorHandler() of foo::B::~B
exit classHandler() of foo::B
exit top() of example

~~~~

### Example

~~~~
class A {
public:
    int x;
};
~~~~


### Control flow

~~~~
enter top() of example
enter classHandler() of A
    enter variableHandler() of x
        enter membervariableHandler() of x
            enter functionWrapper() of x
                | name         - "x"
                | sym:name     - "A_x_set"
                | access       - "public"
                | parms        - A *,int
                | wrap:action  - "if (arg1) (arg1)->x = arg2;"
                | type         - "void"
                | memberset    - "1"
            exit functionWrapper() of x
            enter functionWrapper() of x
                | name         - "x"
                | sym:name     - "A_x_get"
                | access       - "public"
                | parms        - A *
                | wrap:action  - "result = (int) ((arg1)->x);"
                | type         - "int"
                | memberset    - "1"
                | memberget    - "1"
            exit functionWrapper() of x
        exit membervariableHandler() of x
    exit variableHandler() of x    
    enter constructorHandler() of A::A
        enter functionWrapper() of A::A
        exit functionWrapper() of A::A
    exit constructorHandler() of A::A
    enter destructorHandler() of A::~A
        enter functionWrapper() of A::~A
        exit functionWrapper() of A::~A
    exit destructorHandler() of A::~A
exit classHandler() of A
exit top() of example
~~~~

## Class method

### Example

~~~~
class A {
public:
    void foo(int x, double y);
private:
    void bar();
};
~~~~

### Control flow

~~~~
enter top() of example
enter classHandler() of A
    enter functionHandler() of foo
        enter memberfunctionHandler() of foo
            enter functionWrapper() of foo
                | name         - "foo"
                | sym:name     - "A_foo"
                | access       - "public"
                | parms        - A *,int,double
                | wrap:action  - "(arg1)->foo(arg2,arg3);"
                | type         - "void"
            exit functionWrapper() of foo
        exit memberfunctionHandler() of foo
    exit functionHandler() of foo
...
exit classHandler() of A
exit top() of example
~~~~

## Static class variable and method

### Example

~~~~
class A {
public:
    static int x;
    
    static void foo();
};
~~~~

### Control flow

~~~~
enter top() of example
enter classHandler() of A
    enter variableHandler() of x
        enter staticmembervariableHandler() of x
            enter variableWrapper() of A::x
                enter functionWrapper() of A::x
                    | name         - "A::x"
                    | sym:name     - "A_x_set"
                    | parms        - int
                    | wrap:action  - "A::x = arg1;"
                    | type         - "void"
                exit functionWrapper() of A::x
                enter functionWrapper() of A::x
                    +++ cdecl ----------------------------------------
                    | name         - "A::x"
                    | ismember     - "1"
                    | sym:name     - "A_x_get"
                    | variableWrapper:sym:name - "A_x"
                    | wrap:action  - "result = (int)A::x;"
                    | type         - "int"
                exit functionWrapper() of A::x
            exit variableWrapper() of A::x
        exit staticmembervariableHandler() of x
    exit variableHandler() of x
    enter functionHandler() of foo
        enter staticmemberfunctionHandler() of foo
            enter globalfunctionHandler() of A::foo
                enter functionWrapper() of A::foo
                    | name         - "A::foo"
                    | sym:name     - "A_foo"
                    | wrap:action  - "A::foo();"
                    | type         - "void"
                exit functionWrapper() of A::foo
            exit globalfunctionHandler() of A::foo
        exit staticmemberfunctionHandler() of foo
    exit functionHandler() of foo
    enter constructorHandler() of A::A
    exit constructorHandler() of A::A
    enter destructorHandler() of A::~A
    exit destructorHandler() of A::~A
exit classHandler() of A
exit top() of example
~~~~

## Inheritance

### Example

~~~~
class A {
};

class B: public A {
};
~~~~

### Control flow

~~~~
enter top() of example
enter classHandler() of A
    +++ class ----------------------------------------
    | name         - "A"
    | sym:name     - "A"
...
exit classHandler() of A
enter classHandler() of B
    | name         - "B"
    | sym:name     - "B"
    | privatebaselist - 0xf1238f10
    | protectedbaselist - 0xf1238ef0
    | baselist     - 0xf1238ed0
    | bases        - 0xf1239830
    | allbases     - 0xf1239c30
...
exit classHandler() of B
exit top() of example
~~~~