Add initial specification of code generator templates for V8 module.
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/oliverb-javascript-v8@13738 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Oliver Buchtala
parent
d71a5f483a
commit
ba40fffd91
1 changed files with 290 additions and 0 deletions
290
Doc/Devel/Javascript/V8_CodeGeneratorSpecification.md
Normal file
290
Doc/Devel/Javascript/V8_CodeGeneratorSpecification.md
Normal file
|
|
@ -0,0 +1,290 @@
|
|||
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_$CLASSNAME;
|
||||
~~~~
|
||||
|
||||
Notes:
|
||||
- it is very important to consider namespaces from the beginning.
|
||||
`CLASSNAME` should be fully canonical, e.g., `foo_bar_MyClass` for `foo::bar::MyClass`
|
||||
- namespaces do not need a function template, as they will not be
|
||||
instantiated
|
||||
|
||||
## FUNCTION_WRAPPERS
|
||||
|
||||
There are different types of function wrappers:
|
||||
|
||||
- Static Functions (global/namespace/class)
|
||||
- Constructors / Destructors
|
||||
- Getters / Settters
|
||||
- Member Functions
|
||||
|
||||
## Static Functions
|
||||
|
||||
TODO
|
||||
|
||||
## Constructors
|
||||
|
||||
~~~~
|
||||
v8::Handle<v8::Value> $CLASSNAME_new(const v8::Arguments& args) {
|
||||
v8::HandleScope scope;
|
||||
|
||||
// retrieve the instance
|
||||
v8::Handle<v8::Object> self = args.Holder();
|
||||
|
||||
// TODO: declare arguments
|
||||
|
||||
//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`
|
||||
- `$ARGS`: arguments should be declared at the beginning and checked and set in the
|
||||
input typemap block
|
||||
|
||||
## Destructors
|
||||
|
||||
TODO
|
||||
|
||||
## Getters
|
||||
|
||||
~~~~
|
||||
v8::Handle<v8::Value> $CLASSNAME_get$VARNAME(v8::Local<v8::String> property, const v8::AccessorInfo& info) {
|
||||
v8::HandleScope scope;
|
||||
|
||||
// retrieve pointer to C++-this
|
||||
$CLASS_LVAL* self = SWIGV8_UnwrapThisPointer<$CLASS_LVAL>(info.Holder());
|
||||
$RET_LVAL retval = self->$VARNAME;
|
||||
|
||||
v8::Handle<v8::Value> ret = <output_mapping(retval)>;
|
||||
return scope.Close(ret);
|
||||
}
|
||||
~~~~
|
||||
|
||||
- TODO: output typemapping
|
||||
|
||||
## Setters
|
||||
|
||||
~~~~
|
||||
void $CLASSNAME_set$VARNAME(v8::Local<v8::String> property, v8::Local<v8::Value> value, const v8::AccessorInfo& info) {
|
||||
v8::HandleScope scope;
|
||||
|
||||
// retrieve pointer to this
|
||||
$CLASS_LVAL* self = SWIGV8_UnwrapThisPointer<$CLASS_LVAL>(info.Holder());
|
||||
|
||||
// TODO: declare input arg
|
||||
|
||||
// map java-script type to C++ type
|
||||
self->$VARNAME = <input_typemapping>;
|
||||
|
||||
}
|
||||
~~~~
|
||||
|
||||
TODO:
|
||||
- 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::HandleScope scope;
|
||||
|
||||
$CLASS_LVAL* self = SWIGV8_UnwrapThisPointer<$CLASS_LVAL>(args.Holder());
|
||||
|
||||
// TODO: declare input args
|
||||
|
||||
//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
|
||||
|
||||
## Initializer
|
||||
|
||||
~~~~
|
||||
void $MODULENAME_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>
|
||||
|
||||
<CREATE_CLASS_TEMPLATES>
|
||||
|
||||
<ADD_CLASS_METHODS>
|
||||
|
||||
<INHERITANCES>
|
||||
|
||||
<REGISTER_CLASSES>
|
||||
}
|
||||
~~~~
|
||||
|
||||
## 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.
|
||||
|
||||
## Create Class Template
|
||||
|
||||
~~~~
|
||||
SWIGV8_$CLASSNAME = SWIGV8_CreateClassTemplate("$LOCAL_CLASSNAME" , $CLASSNAME_new);
|
||||
~~~~
|
||||
|
||||
- `LOCAL_CLASSNAME`: the class name without context, i.e., namespaces
|
||||
|
||||
## Add Member Function
|
||||
|
||||
~~~~
|
||||
SWIGV8_AddClassMethod(SWIGV8_$CLASSNAME, "$METHODNAME", $METHOD_WRAPPER);
|
||||
~~~~
|
||||
|
||||
- `METHODNAME`: the name of the function as in C++
|
||||
- `METHOD_WRAPPER`: the name of the generated wrapper function
|
||||
TODO: specify different versions
|
||||
|
||||
## Add Property
|
||||
|
||||
~~~~
|
||||
SWIGV8_AddProperty(SWIGV8_$CLASSNAME, "$VARNAME", $GET_WRAPPER, $SET_WRAPPER);
|
||||
~~~~
|
||||
|
||||
- `GET_WRAPPER`: the name of the generated wrapper for the property getter
|
||||
- `SET_WRAPPER`: the name of the generated wrapper for property setter; optional (i.e., maybe `NULL`)
|
||||
|
||||
## Inheritance
|
||||
|
||||
~~~~
|
||||
SWIGV8_$CLASSNAME->Inherit(SWIGV8_$SUPERCLASS);
|
||||
~~~~
|
||||
|
||||
- Note: multiple inheritance is not possible; thus we will always take the first parent class
|
||||
|
||||
## Register class
|
||||
|
||||
~~~~
|
||||
$CONTEXT->Set(v8::String::NewSymbol("$LOCAL_CLASSNAME"), SWIGV8_$CLASSNAME->GetFunction());
|
||||
~~~~
|
||||
|
||||
- Note: every class template has an associated ctor function wrapper, which is registered here
|
||||
- `CONTEXT`: either global, or the according namespace instance
|
||||
|
||||
## 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);
|
||||
}
|
||||
|
||||
~~~~
|
||||
Loading…
Add table
Add a link
Reference in a new issue