Update v8 code generator specification.

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/oliverb-javascript-v8@13744 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Doc/Devel/Javascript/V8_CodeGeneratorSpecification.md

@@ -41,12 +41,12 @@ The generated code consists of the following blocks:
 Static references to class templates which are (should be) read-only and can be reused.
 
 ~~~~
-v8::Persistent<v8::FunctionTemplate> SWIGV8_$CLASSNAME;
+v8::Persistent<v8::FunctionTemplate> SWIGV8_${NAME_MANGLED};
 ~~~~
 
 Notes:
  - it is very important to consider namespaces from the beginning.
-   `CLASSNAME` should be the mangled qualified class name, e.g., `foo_bar_MyClass` for `foo::bar::MyClass`,
+   `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
@@ -67,115 +67,96 @@ TODO
 ## Constructors
 
 ~~~~
-v8::Handle<v8::Value> $CLASSNAME_new(const v8::Arguments& args) {
+v8::Handle<v8::Value> ${NAME_MANGLED}_new(const v8::Arguments& args) {
     v8::HandleScope scope;
-    
-    // retrieve the instance
     v8::Handle<v8::Object> self = args.Holder();
-    
+    ${LOCALS}
-    // TODO: declare arguments
+    ${MARSHAL_INPUT}
-
+    ${ACTION}
-    //convert JS arguments to C++
-    // TODO: apply input typemaps
-
-    $CLASS_LVAL* ptr = new $CLASS_LVAL($ARGS);
     self->SetInternalField(0, v8::External::New(ptr));
-    
     return self;        
 }
 ~~~~
 
-- `$CLASS_LVAL`: should be the canonical name of the class, e.g. `ns1::ns2::MyClass`,
+- `LOCALS`: declaration and marshalling for input arguments
-  which can be retrieved using `Getattr(n, "name")`
+- `MARSHAL_INPUT`: code is generated by applying input typemaps
-- `$ARGS`: arguments should be declared at the beginning and checked and set in the
+- `ACTION`: the C/C++ ctor to be executed
-   input typemap block
 
 ## Destructors
 
-TODO
+TODO: I haven't found out yet how a descrtuctor can be registered
 
 ## Getters
 
 ~~~~
-v8::Handle<v8::Value> $CLASSNAME_get$VARNAME(v8::Local<v8::String> property, const v8::AccessorInfo& info) {
+v8::Handle<v8::Value> ${NAME_MANGLED}_get(v8::Local<v8::String> property, const v8::AccessorInfo& info) {
     v8::HandleScope scope;
-
+    v8::Handle<v8::Object> ret;
-    // retrieve pointer to C++-this
+    ${LOCALS}
-    $CLASS_LVAL* self = SWIGV8_UnwrapThisPointer<$CLASS_LVAL>(info.Holder());
+    ${ACTION}
-    $RET_LVAL retval = self->$VARNAME;
+    ${MARSHAL_OUTPUT}
-    
-    v8::Handle<v8::Value> ret = <output_mapping(retval)>;
     return scope.Close(ret);
 }
 ~~~~
 
-- TODO: output typemapping
+- `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 $CLASSNAME_set$VARNAME(v8::Local<v8::String> property, v8::Local<v8::Value> value, const v8::AccessorInfo& info) {
+void ${NAME_MANGLED}_set(v8::Local<v8::String> property, v8::Local<v8::Value> value, const v8::AccessorInfo& info) {
-    v8::HandleScope scope;
+    ${LOCALS}
-
+    ${MARSHAL_INPUT}
-    // retrieve pointer to this
+    ${ACTION}
-    $CLASS_LVAL* self = SWIGV8_UnwrapThisPointer<$CLASS_LVAL>(info.Holder());
-
-    // TODO: declare input arg
-    
-    // map java-script type to C++ type    
-    self->$VARNAME = <input_typemapping>;
-
 }
 ~~~~
+- `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
 
-TODO: 
+## Functions
- - input type mapping should be addressed in extra step, together with type check
-
-## Member functions
 
 ~~~~
-v8::Handle<v8::Value> $CLASSNAME_$FUNCTIONNAME(const v8::Arguments& args)
+v8::Handle<v8::Value> ${NAME_MANGLED}(const Arguments &args) {
-{
     v8::HandleScope scope;
-
+    v8::Handle<v8::Object> ret;
-    $CLASS_LVAL* self = SWIGV8_UnwrapThisPointer<$CLASS_LVAL>(args.Holder());
+    ${LOCALS}
-
+    ${MARSHAL_INPUT}
-    // TODO: declare input args
+    ${ACTION}
-
+    ${MARSHAL_OUTPUT}
-    //convert JS arguments to C++
-    // TODO: input typemappings and type checking
-
-    //call C++ method
-    $RET_LTYPE result = self->$FUNCTIONNAME($ARGS);
-
-    //convert C++ JS arguments to C++
-    v8::Handle<v8::Value> ret = <output_typemapping>;
-
     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 $MODULENAME_Initialize(v8::Handle<v8::Context> context)
+void ${MODULE}_Initialize(v8::Handle<v8::Context> context)
 {
     v8::HandleScope scope;
 
     // register the module in globale context
     v8::Local<v8::Object> global = context->Global();
 
-    <CREATE_NAME_SPACES>
+    ${PART_NAMESPACES}
-    
-    <CREATE_CLASS_TEMPLATES>
 
-    <ADD_CLASS_METHODS>
+    ${PART_CLASS_TEMPLATES}
 
-    <INHERITANCES>
+    ${PART_WRAPPERS}
 
-    <REGISTER_CLASSES>
+    ${PART_INHERITANCE}
+
+    ${PART_REGISTER}
 }
 ~~~~
 
@@ -188,11 +169,10 @@ in the according parent contexts.
 ## Create Class Template
 
 ~~~~
-    SWIGV8_$CLASSNAME = SWIGV8_CreateClassTemplate("$LOCAL_CLASSNAME" , $CLASSNAME_new);
+SWIGV8_${NAME_MANGLED} = SWIGV8_CreateClassTemplate("${NAME_UNQUALIFIED}" , ${NAME_MANGLED}_new);
 ~~~~
 
-- `LOCAL_CLASSNAME`: the class name without context, i.e., namespaces,
+- `NAME_UNQUALIFIED`: the class name without context, i.e., namespaces
-  which is retrieved by `Getattr(n, "sym:name")`
 
 ## Add Member Function
 
@@ -216,7 +196,7 @@ in the according parent contexts.
 ## Inheritance
 
 ~~~~
-    SWIGV8_$CLASSNAME->Inherit(SWIGV8_$SUPERCLASS);
+SWIGV8_${NAME_MANGLED}->Inherit(SWIGV8_${BASE_CLASS});
 ~~~~
 
 - Note: multiple inheritance is not possible; thus we will always take the first parent class
@@ -224,7 +204,7 @@ in the according parent contexts.
 ## Register class
 
 ~~~~
-    $CONTEXT->Set(v8::String::NewSymbol("$LOCAL_CLASSNAME"), SWIGV8_$CLASSNAME->GetFunction());
+${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

Lib/javascript/v8/javascriptcode.swg

@@ -35,6 +35,7 @@ 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;