summaryrefslogtreecommitdiff
path: root/javascript
diff options
context:
space:
mode:
authorVincent Sanders <vince@kyllikki.org>2012-11-02 13:30:30 +0000
committerVincent Sanders <vince@kyllikki.org>2012-11-02 13:30:30 +0000
commit7cb31505738ef0beaf984bebf8bb7f0529097f33 (patch)
treebce9c48a799bef8fb62b7a9ea0b80a7fb7311422 /javascript
parentb84dc91e3dbf694de6d3e79ecd4755e8d0b699b7 (diff)
downloadnetsurf-7cb31505738ef0beaf984bebf8bb7f0529097f33.tar.gz
netsurf-7cb31505738ef0beaf984bebf8bb7f0529097f33.tar.bz2
improve example binding docuemntation
Diffstat (limited to 'javascript')
-rw-r--r--javascript/jsapi/bindings/example.bnd227
1 files 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 <vince@netsurf-browser.org>
*
@@ -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 <vince@netsurf-browser.org>";
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 <dom/dom.h>
@@ -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 | "<Browsername>" | "NetSurf" | Browsers named other than
- * | | | "Netscape", "Mozilla",
- * | | | "Netscape Navigator",
- * | | | "Microsoft Internet Explorer"
- * | | | often other browser have
- * | | | "(compatible with Netscape)"
- * | | | append.
- * ------------+-----------------+--------------+------------------------------
- * appVersion | "<ver> (<type>)"| "<ver>" | Actually just the version
- * | | | number e.g "3.0".
- * ------------+-----------------+--------------+------------------------------
- * language | "<lang>" | "<lang>" | The language the frontend is
- * | | | configured for
- * ------------+-----------------+--------------+------------------------------
- * platform | "<krn> <hw>" | "<krn> <hw>" | 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 %{
+ %}