From 7cb31505738ef0beaf984bebf8bb7f0529097f33 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Fri, 2 Nov 2012 13:30:30 +0000 Subject: improve example binding docuemntation --- javascript/jsapi/bindings/example.bnd | 227 +++++++++++++++++++++++++++------- 1 file changed, 183 insertions(+), 44 deletions(-) diff --git a/javascript/jsapi/bindings/example.bnd b/javascript/jsapi/bindings/example.bnd index 897e9a530..f2f81fb2d 100644 --- a/javascript/jsapi/bindings/example.bnd +++ b/javascript/jsapi/bindings/example.bnd @@ -1,4 +1,7 @@ -/* Binding to generate Navigator interface +/* Example binding to generate Example interface + * + * The js_libdom (javascript to libdom) binding type is currently the + * only one implemented and this principly describes that binding. * * Copyright 2012 Vincent Sanders * @@ -8,15 +11,26 @@ * http://www.opensource.org/licenses/mit-license */ +/* additional binding fragments may be included + * Note: this is not preprocessed despite the #include name, the + * parser will simply switch input to the included file and carry on + * cosntructing the bindings Abstract Syntax Tree (AST) + */ #include "dom.bnd" +/* directive to read WebIDL file and add its contents to the webidl AST */ webidlfile "html.idl"; +/* The hdrcomment are added into the geenrated output comment header */ hdrcomment "Copyright 2012 Vincent Sanders "; hdrcomment "This file is part of NetSurf, http://www.netsurf-browser.org/"; hdrcomment "Released under the terms of the MIT License,"; hdrcomment " http://www.opensource.org/licenses/mit-license"; +/* the preamble block is copied verbatum into the generated output + * + * This can be used for includes, comments or whatever else is desired + */ preamble %{ #include @@ -27,64 +41,189 @@ preamble %{ #include "javascript/jsapi.h" #include "javascript/jsapi/binding.h" -/* - * navigator properties for netsurf - * - * Property | Everyone else | NetSurf | Notes - * ------------+-----------------+--------------+------------------------------ - * appCodeName | "Mozilla" | "NetSurf" | This is kinda a pointless - * | | | constant as everyone returns - * | | | "Mozilla" which is dumb - * ------------+-----------------+--------------+------------------------------ - * appName | "" | "NetSurf" | Browsers named other than - * | | | "Netscape", "Mozilla", - * | | | "Netscape Navigator", - * | | | "Microsoft Internet Explorer" - * | | | often other browser have - * | | | "(compatible with Netscape)" - * | | | append. - * ------------+-----------------+--------------+------------------------------ - * appVersion | " ()"| "" | Actually just the version - * | | | number e.g "3.0". - * ------------+-----------------+--------------+------------------------------ - * language | "" | "" | The language the frontend is - * | | | configured for - * ------------+-----------------+--------------+------------------------------ - * platform | " " | " " | Efectively uname -s -i, - * | | | eg "Linux x86_64" - * ------------+-----------------+--------------+------------------------------ - * userAgent | "Mozilla/5.0 (" | "NetSurf" | The usual useragent string - * | | | with excessive lies - * ------------+-----------------+--------------+------------------------------ - */ - %} -binding navigator { +/* this block describes the binding to be generated + * + * Depending on the type of binding being generated multiple blocks + * may be allowed. + * + * Note: the js_libdom (javascript to libdom) binding as currently + * implemented only allows for a single binding per file, this may + * be improved in future. + */ +binding example { type js_libdom; /* the binding type */ - interface Navigator; /* Web IDL interface to generate */ + interface Navigator; /* The WebIDL interface to generate a binding for */ /* private members: * - stored in private context structure. * - passed as parameters to constructor and stored automatically. * - are *not* considered for property getters/setters. - * - * internal members: + */ + private "dom_document *" node; + + /* internal members: * - value stored in private context structure * - not passed to constructor * - must be instantiated by constructor * - are considered for property getters/setters. */ - private "dom_document *" node; - private "struct html_content *" htmlc; + internal "void *" fluff; + } -operation write %{ - LOG(("content %p parser %p writing %s", - private->htmlc, private->htmlc->parser, text)); +/* operation implementation code. + * + * The body is copied verbatum into operation binding + * + * several values are generated automatically: + * + * - The generated operations use a macro to create a JSNative JSAPI + * callback. The interface allows a uniform interface despite the + * evolution of the interface over differing spidermonkey versions. + * + * - The above implies the javascript context is in a variable called cx + * + * - If private or internal binding members are present they may be + * accessed through a structure named "private" + * + * - if there are arguemnts they may be accesed via an argc/argv jsval + * vector. + * + * - Arguments are automatically converted into c variables (named as + * per the WebIDL names. + * + * - Return values (excepting void return types where its omitted) are + * always named "retval" and are of the appropriate c type. The + * initial value is set appropriately. + */ +operation foo %{ + retval = JS_NewStringCopyN(cx, "foo", SLEN("foo")); +%} - if (private->htmlc->parser != NULL) { - dom_hubbub_parser_insert_chunk(private->htmlc->parser, (uint8_t *)text, text_len); - } +/* property getter implementation code. + * + * The body is copied verbatum into property getter binding + * + * several values are generated automatically: + * + * - The generated operations use a macro to create a JSPropertyOp + * JSAPI callback. The interface allows a uniform interface despite + * the evolution of the interface over differing spidermonkey + * versions. + * + * - The above implies the javascript context is available in a + * variable called "cx". + * + * - If private or internal binding members are present they may be + * accessed through a structure named "private" + * + * - Return values (void on a getter is not possible) are always named + * "retval" and are of the appropriate c type. The initial value is + * set appropriately. + * + * - If the getter is omitted altogether but an internal or private + * value of the same name appears in the private structure a getter + * is automatically constructed to return that value. + */ +getter bar %{ + retval = JS_NewStringCopyN(cx, "bar", SLEN("bar")); %} + +/* property setter implementation code. + * + * The body is copied verbatum into property getter binding + * + * several values are generated automatically: + * + * - The generated operations use a macro to create a JSPropertyOp + * JSAPI callback. The interface allows a uniform interface despite + * the evolution of the interface over differing spidermonkey + * versions. + * + * - The above implies the javascript context is available in a + * variable called "cx". + * + * - If private or internal binding members are present they may be + * accessed through a structure named "private" + * + * - Value to set is placed in a c variable named "setval" of the + * appropriate type. + * + * - Return value, named retval" is a boolean (default true) which + * indicates if the set was performed. + * + * - If the setter is omitted altogether but an internal or private + * value of the same name appears in the private structure a setter + * is automatically constructed to assign that value. + */ +setter baz %{ + printf("%s\n", setval); +%} + +/* implementation of the class initilisation + * + * This allows the default JS_InitClass to be overriden - currently + * only used for the window (global) object to cause all the other class + * initialisors to be called. + * + * function prototype is: + * JSObject *jsapi_InitClass_HTMLElement(JSContext *cx, JSObject *parent) + */ +api init %{ + %} + +/* implementation of the c instance creation + * + * This allows the overriding of the construction of an interface instance. + * + * The body is copied verbatum and must return the new object in the + * "newobject" variable. + * + * The base prototype is + * JSObject *jsapi_new_HTMLElement(JSContext *cx, JSObject *prototype, JSObject *parent, ...) + * The varadic elements are private variables as specified in the binding + * + * If there are private or internal values the private struct is + * constructed and instantiated. The struct is available during the + * new function and is automatically attached as the private value to + * the object. + * + * The default implemenattion simply calls JS_NewObject() + * + * Note this does *not* rely upon (or even call) the instances + * javascript constructor allowing the c code to create objects that + * cannot be instantiated from javascript. + * + */ +api new %{ + %} + +/* additional code in the instance finalise operation. + * + * The body is copied verbatum into the output + * + * Prototype is + * void jsclass_finalize(JSContext *cx, JSObject *obj) + * + * private is available (if appropriate) and freed after the body + */ +api finalise %{ + %} + +/* resolver code + * + * A resolver is only generated if this api is provided. This is a + * JSResolveOp with JSCLASS_NEW_RESOLVE specified and must provide a + * complete implementation. + * + * The body is copied verbatum into the output + * + * Prototype is: + * JSBool jsclass_resolve(JSContext *cx, JSObject *obj, jsval id, uintN flags, JSObject **objp) + * + */ +api resolve %{ + %} -- cgit v1.2.3