JSRef builds a library or DLL containing the JavaScript runtime (compiler, interpreter, decompiler, garbage collector, atom manager, standard classes). It then compiles a small "shell" program and links that with the library to make an interpreter that can be used interactively and with test .js files to run scripts. The code has no dependencies on the rest of the Mozilla codebase.
Quick start tip: skip to "Using the JS API" below, build the js shell, and play with the object named "it" (start by setting 'it.noisy = true').
By default, all platforms build a version of the JS engine that is not threadsafe. If you require thread-safety, you must also populate the mozilla/dist directory with NSPR headers and libraries. (NSPR implements a portable threading library, among other things. The source is downloadable via CVS from mozilla/nsprpub.) Next, you must define JS_THREADSAFE when building the JS engine, either on the command-line (gmake/nmake) or in a universal header file.
/*
* Tune this to avoid wasting space for shallow stacks, while saving on
* malloc overhead/fragmentation for deep or highly-variable stacks.
*/
#define STACK_CHUNK_SIZE 8192
JSRuntime *rt;
JSContext *cx;
/* You need a runtime and one or more contexts to do anything with JS. */
rt = JS_NewRuntime(0x400000L);
if (!rt)
fail("can't create JavaScript runtime");
cx = JS_NewContext(rt, STACK_CHUNK_SIZE);
if (!cx)
fail("can't create JavaScript context");
/*
* The context definitely wants a global object, in order to have standard
* classes and functions like Date and parseInt. See below for details on
* JS_NewObject.
*/
JSObject *globalObj;
globalObj = JS_NewObject(cx, &my_global_class, 0, 0);
JS_InitStandardClasses(cx, globalObj);
/* Statically initialize a class to make "one-off" objects. */
JSClass my_class = {
"MyClass",
/* All of these can be replaced with the corresponding JS_*Stub
function pointers. */
my_addProperty, my_delProperty, my_getProperty, my_setProperty,
my_enumerate, my_resolve, my_convert, my_finalize
};
JSObject *obj;
/*
* Define an object named in the global scope that can be enumerated by
* for/in loops. The parent object is passed as the second argument, as
* with all other API calls that take an object/name pair. The prototype
* passed in is null, so the default object prototype will be used.
*/
obj = JS_DefineObject(cx, globalObj, "myObject", &my_class, NULL,
JSPROP_ENUMERATE);
/*
* Define a bunch of properties with a JSPropertySpec array statically
* initialized and terminated with a null-name entry. Besides its name,
* each property has a "tiny" identifier (MY_COLOR, e.g.) that can be used
* in switch statements (in a common my_getProperty function, for example).
*/
enum my_tinyid {
MY_COLOR, MY_HEIGHT, MY_WIDTH, MY_FUNNY, MY_ARRAY, MY_RDONLY
};
static JSPropertySpec my_props[] = {
{"color", MY_COLOR, JSPROP_ENUMERATE},
{"height", MY_HEIGHT, JSPROP_ENUMERATE},
{"width", MY_WIDTH, JSPROP_ENUMERATE},
{"funny", MY_FUNNY, JSPROP_ENUMERATE},
{"array", MY_ARRAY, JSPROP_ENUMERATE},
{"rdonly", MY_RDONLY, JSPROP_READONLY},
{0}
};
JS_DefineProperties(cx, obj, my_props);
/*
* Given the above definitions and call to JS_DefineProperties, obj will
* need this sort of "getter" method in its class (my_class, above). See
* the example for the "It" class in js.c.
*/
static JSBool
my_getProperty(JSContext *cx, JSObject *obj, jsval id, jsval *vp)
{
if (JSVAL_IS_INT(id)) {
switch (JSVAL_TO_INT(id)) {
case MY_COLOR: *vp = . . .; break;
case MY_HEIGHT: *vp = . . .; break;
case MY_WIDTH: *vp = . . .; break;
case MY_FUNNY: *vp = . . .; break;
case MY_ARRAY: *vp = . . .; break;
case MY_RDONLY: *vp = . . .; break;
}
}
return JS_TRUE;
}
/* Define a bunch of native functions first: */
static JSBool
my_abs(JSContext *cx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
{
jsdouble x, z;
if (!JS_ValueToNumber(cx, argv[0], &x))
return JS_FALSE;
z = (x < 0) ? -x : x;
return JS_NewDoubleValue(cx, z, rval);
}
. . .
/*
* Use a JSFunctionSpec array terminated with a null name to define a
* bunch of native functions.
*/
static JSFunctionSpec my_functions[] = {
/* name native nargs */
{"abs", my_abs, 1},
{"acos", my_acos, 1},
{"asin", my_asin, 1},
. . .
{0}
};
/*
* Pass a particular object to define methods for it alone. If you pass
* a prototype object, the methods will apply to all instances past and
* future of the prototype's class (see below for classes).
*/
JS_DefineFunctions(cx, globalObj, my_functions);
/*
* This pulls together the above API elements by defining a constructor
* function, a prototype object, and properties of the prototype and of
* the constructor, all with one API call.
*
* Initialize a class by defining its constructor function, prototype, and
* per-instance and per-class properties. The latter are called "static"
* below by analogy to Java. They are defined in the constructor object's
* scope, so that 'MyClass.myStaticProp' works along with 'new MyClass()'.
*
* JS_InitClass takes a lot of arguments, but you can pass null for any of
* the last four if there are no such properties or methods.
*
* Note that you do not need to call JS_InitClass to make a new instance of
* that class -- otherwise there would be a chicken-and-egg problem making
* the global object -- but you should call JS_InitClass if you require a
* constructor function for script authors to call via new, and/or a class
* prototype object ('MyClass.prototype') for authors to extend with new
* properties at run-time. In general, if you want to support multiple
* instances that share behavior, use JS_InitClass.
*/
protoObj = JS_InitClass(cx, globalObj, NULL, &my_class,
/* native constructor function and min arg count */
MyClass, 0,
/* prototype object properties and methods -- these
will be "inherited" by all instances through
delegation up the instance's prototype link. */
my_props, my_methods,
/* class constructor properties and methods */
my_static_props, my_static_methods);
/* These should indicate source location for diagnostics. */
char *filename;
uintN lineno;
/*
* The return value comes back here -- if it could be a GC thing, you must
* add it to the GC's "root set" with JS_AddRoot(cx, &thing) where thing
* is a JSString *, JSObject *, or jsdouble *, and remove the root before
* rval goes out of scope, or when rval is no longer needed.
*/
jsval rval;
JSBool ok;
/*
* Some example source in a C string. Larger, non-null-terminated buffers
* can be used, if you pass the buffer length to JS_EvaluateScript.
*/
char *source = "x * f(y)";
ok = JS_EvaluateScript(cx, globalObj, source, strlen(source),
filename, lineno, &rval);
if (ok) {
/* Should get a number back from the example source. */
jsdouble d;
ok = JS_ValueToNumber(cx, rval, &d);
. . .
}
/* Call a global function named "foo" that takes no arguments. */ ok = JS_CallFunctionName(cx, globalObj, "foo", 0, 0, &rval); jsval argv[2]; /* Call a function in obj's scope named "method", passing two arguments. */ argv[0] = . . .; argv[1] = . . .; ok = JS_CallFunctionName(cx, obj, "method", 2, argv, &rval);
/* For each context you've created: */ JS_DestroyContext(cx); /* For each runtime: */ JS_DestroyRuntime(rt); /* And finally: */ JS_ShutDown();
JavaScript uses untyped bytecode and runtime type tagging of data values. The jsval type is a signed machine word that contains either a signed integer value (if the low bit is set), or a type-tagged pointer or boolean value (if the low bit is clear). Tagged pointers all refer to 8-byte-aligned things in the GC heap.
Objects consist of a possibly shared structural description, called the map or scope; and unshared property values in a vector, called the slots. Object properties are associated with nonnegative integers stored in jsval's, or with atoms (unique string descriptors) if named by an identifier or a non-integral index expression.
Scripts contain bytecode, source annotations, and a pool of string, number, and identifier literals. Functions are objects that extend scripts or native functions with formal parameters, a literal syntax, and a distinct primitive type ("function").
The compiler consists of a recursive-descent parser and a random-logic rather than table-driven lexical scanner. Semantic and lexical feedback are used to disambiguate hard cases such as missing semicolons, assignable expressions ("lvalues" in C parlance), etc. The parser generates bytecode as it parses, using fixup lists for downward branches and code buffering and rewriting for exceptional cases such as for loops. It attempts no error recovery. The interpreter executes the bytecode of top-level scripts, and calls itself indirectly to interpret function bodies (which are also scripts). All state associated with an interpreter instance is passed through formal parameters to the interpreter entry point; most implicit state is collected in a type named JSContext. Therefore, all API and almost all other functions in JSRef take a JSContext pointer as their first argument.
The decompiler translates postfix bytecode into infix source by consulting a separate byte-sized code, called source notes, to disambiguate bytecodes that result from more than one grammatical production.
The GC is a mark-and-sweep, non-conservative (exact) collector. It can allocate only fixed-sized things -- the current size is two machine words. It is used to hold JS object and string descriptors (but not property lists or string bytes), and double-precision floating point numbers. It runs automatically only when maxbytes (as passed to JS_NewRuntime()) bytes of GC things have been allocated and another thing-allocation request is made. JS API users should call JS_GC() or JS_MaybeGC() between script executions or from the branch callback, as often as necessary.
An important point about the GC's "exactness": you must add roots for new objects created by your native methods if you store references to them into a non-JS structure in the malloc heap or in static data. Also, if you make a new object in a native method, but do not store it through the rval result parameter (see math_abs in the "Using the JS API" section above) so that it is in a known root, the object is guaranteed to survive only until another new object is created. Either lock the first new object when making two in a row, or store it in a root you've added, or store it via rval. See the GC tips document for more.
The atom manager consists of a hash table associating strings uniquely with scanner/parser information such as keyword type, index in script or function literal pool, etc. Atoms play three roles in JSRef: as literals referred to by unaligned 16-bit immediate bytecode operands, as unique string descriptors for efficient property name hashing, and as members of the root GC set for exact GC.
Native objects and methods for arrays, booleans, dates, functions, numbers, and strings are implemented using the JS API and certain internal interfaces used as "fast paths".
In general, errors are signaled by false or unoverloaded-null return values, and are reported using JS_ReportError() or one of its variants by the lowest level in order to provide the most detail. Client code can substitute its own error reporting function and suppress errors, or reflect them into Java or some other runtime system as exceptions, GUI dialogs, etc..
14 function perfect(n)
15 {
16 print("The perfect numbers up to " + n + " are:");
17
18 // We build sumOfDivisors[i] to hold a string expression for
19 // the sum of the divisors of i, excluding i itself.
20 var sumOfDivisors = new ExprArray(n+1,1);
21 for (var divisor = 2; divisor <= n; divisor++) {
22 for (var j = divisor + divisor; j <= n; j += divisor) {
23 sumOfDivisors[j] += " + " + divisor;
24 }
25 // At this point everything up to 'divisor' has its sumOfDivisors
26 // expression calculated, so we can determine whether it's perfect
27 // already by evaluating.
28 if (eval(sumOfDivisors[divisor]) == divisor) {
29 print("" + divisor + " = " + sumOfDivisors[divisor]);
30 }
31 }
32 delete sumOfDivisors;
33 print("That's all.");
34 }
The line number to PC and back mappings can be tested using the js program
with the following script:
load("perfect.js")
print(perfect)
dis(perfect)
print()
for (var ln = 0; ln <= 40; ln++) {
var pc = line2pc(perfect,ln)
var ln2 = pc2line(perfect,pc)
print("\tline " + ln + " => pc " + pc + " => line " + ln2)
}
The result of the for loop over lines 0 to 40 inclusive is:
line 0 => pc 0 => line 16 line 1 => pc 0 => line 16 line 2 => pc 0 => line 16 line 3 => pc 0 => line 16 line 4 => pc 0 => line 16 line 5 => pc 0 => line 16 line 6 => pc 0 => line 16 line 7 => pc 0 => line 16 line 8 => pc 0 => line 16 line 9 => pc 0 => line 16 line 10 => pc 0 => line 16 line 11 => pc 0 => line 16 line 12 => pc 0 => line 16 line 13 => pc 0 => line 16 line 14 => pc 0 => line 16 line 15 => pc 0 => line 16 line 16 => pc 0 => line 16 line 17 => pc 19 => line 20 line 18 => pc 19 => line 20 line 19 => pc 19 => line 20 line 20 => pc 19 => line 20 line 21 => pc 36 => line 21 line 22 => pc 53 => line 22 line 23 => pc 74 => line 23 line 24 => pc 92 => line 22 line 25 => pc 106 => line 28 line 26 => pc 106 => line 28 line 27 => pc 106 => line 28 line 28 => pc 106 => line 28 line 29 => pc 127 => line 29 line 30 => pc 154 => line 21 line 31 => pc 154 => line 21 line 32 => pc 161 => line 32 line 33 => pc 172 => line 33 line 34 => pc 172 => line 33 line 35 => pc 172 => line 33 line 36 => pc 172 => line 33 line 37 => pc 172 => line 33 line 38 => pc 172 => line 33 line 39 => pc 172 => line 33 line 40 => pc 172 => line 33