summaryrefslogtreecommitdiff
path: root/javascript/jsapi/example.bnd
blob: f2f81fb2dfa1f9342be99b1ce9c5e5b099858e44 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
/* 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>
 *
 * This file is part of NetSurf, http://www.netsurf-browser.org/
 *
 * Released under the terms of the MIT License,
 *         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>
        
#include "utils/config.h"
#include "utils/log.h"

#include "javascript/jsapi.h"
#include "javascript/jsapi/binding.h"

%}

/* 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; /* 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.
     */
    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.
     */
    internal "void *" fluff;
     
}

/* 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"));
%}

/* 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 %{
  %}