MuJS Reference Manual

MuJS

Introduction

MuJS is a library, written in clean and simple C. Being an extension library, MuJS has no notion of a main program: it only works embedded in a host client program. The host program can invoke functions to execute Javascript code, read and write Javascript variables, and register C functions to be called by Javascript.

The MuJS distribution includes a sample host program called “mujs”, which uses the MuJS library to offer a standalone Javascript interpreter for interactive or batch use.

This reference manual assumes that you are already familiar with the Javascript language, in particular the type system and object prototype mechanisms.

Basic Concepts

Values and Types

There are six basic types in Javascript: undefined, null, boolean, number, string and object.

Each object also has a class: object, array, function, userdata, regular expression, etc.

Javascript can call functions written in C provided by the host program, as well as other Javascript functions.

Objects with the userdata class are provided to allow arbitrary C data to be attached to Javascript objects. A userdata object has a pointer to a block of raw memory, which is managed by the host. Userdata values cannot be created or modified in Javascript, only through the C API. This guarantees the integrity of data owned by the host program.

Custom properties on userdata objects can be implemented using getter and setter property accessor functions.

Numbers are represented using double precision floating point values.

Strings in the C interface are zero-terminated byte arrays in UTF-8 encoding.

Environments

Each function executes within an environment which defines which variables are accessible. This is a chain of all environment records in scope, with the global environment at the top. Each environment record in MuJS is represented as an object with the null prototype, including the global environment object.

The registry is a hidden environment record which is only accessible to C. This is where Javascript values and objects that should only be accessible to C functions may be stored.

Error Handling

All Javascript actions start from C code in the host program calling a function from the MuJS library. Whenever an exception is thrown during the compilation or execution of Javascript, control returns to the host, which can take appropriate measures (such as printing an error message). C code can also throw exceptions by calling functions to create an error object and return control to Javascript.

Internally, MuJS uses the C longjmp facility to handle errors. A protected environment uses setjmp to set a recovery point. The try statement in Javascript creates such a recovery point, as does calling js_dostring, js_dofile, js_ploadstring, js_ploadfile, js_pcall and js_pconstruct.

When an error occurs or an exception is thrown from Javascript, it does a long jump to the most recent active recovery point.

If an error occurs outside any protected environment, MuJS first calls the panic function and then calls abort, thus exiting the host application. Your panic function can avoid this exit by never returning (for example by doing a long jump to your own recovery point outside MuJS).

Garbage Collection

MuJS performs automatic memory management using a basic mark-and-sweep collector. Collection is automatically triggered when enough allocations have accumulated. You can also force a collection pass from C.

TODO: garbage collection of userdata.

The Stack

MuJS uses a virtual stack to pass values to and from C. Each element in this stack represents a Javascript value (null, number, string, etc).

Whenever Javascript calls C, the called function gets a new stack. This stack initially contains the this value and any arguments passed to the function. When the C function returns, the top value on the stack is passed back to the caller as the return value.

The stack values are accessed using stack indices. Index 0 always contains the this value, and function arguments are index 1 and up. Negative indices count down from the top of the stack, so index -1 is the top of the index and index -2 is the one below that.

The Application Program Interface

State

typedef struct js_State js_State;

The interpreter state is bundled up in the opaque struct js_State. This state contains the value stacks, protected environments, and environment records.

js_State *js_newstate(js_Alloc alloc, void *context, int flags);

Create a new state using the allocator function and allocator context. Pass NULL to use the default allocator.

The available flags:

JS_STRICT: compile and run code using ES5 strict mode.

void js_freestate(js_State *J);

Destroy the state and free all dynamic memory used by the state.

Allocator

The interpreter uses a host provided function for all memory allocation needs:

typedef void *(*js_Alloc)(void *memctx, void *ptr, int size);

When size is zero, the allocator should behave like free and return NULL. When size is not zero, the allocator should behave like realloc. The allocator should return NULL if it cannot fulfill the request. The default allocator uses malloc, realloc and free.

Panic

typedef void (*js_Panic)(js_State *J);

js_Panic js_atpanic(js_State *J, js_Panic panic);

Set a new panic function, and return the old one.

Garbage collection

js_gc(js_State *J, int report);

Force a garbage collection pass. If the report argument is non-zero, print a summary of garbage collection statistics to stdout.

Loading and compiling scripts

A script is compiled by calling js_loadstring or js_loadfile. The result of a successful compilation is a function on the top of the stack. This function can then be executed with js_call.

Like js_loadstring/js_loadfile but in a protected environment. In case of success, return 0 with the result as a function on the stack. In case of failure, return 1 with the error object on the stack.

Calling functions

void js_call(js_State *J, int n);

To call a function, you must use the following protocol: 1) push the function to call onto the stack, 2) push the this value to be used by the function, 3) push the arguments to the function in order, 4) finally, call js_call with the number of arguments pushed in step 3.

Pop the function, the this value, and all arguments; execute the function; then push the return value from the function.

void js_construct(js_State *J, int n);

The construct function implements the ‘new’ expression in Javascript. This is similar to js_call, but without pushing a this value: 1) push the constructor function to call onto the stack, 2) push the arguments to the constructor function in order, 3) finally, call js_construct with the number of arguments pushed in step 2.

Like js_call and js_construct but in a protected environment. In case of success, return 0 with the result on the stack. In case of failure, return 1 with the error object on the stack.

Script helpers

There are two convenience functions for loading and executing code.

int js_dostring(js_State *J, const char *source);

Compile and execute the script in the zero-terminated string in source argument. If any errors occur, print the error message to stderr and return 1. Return 0 on success.

int js_dofile(js_State *J, const char *filename);

Load the script from the file with the given filename, then compile and execute it. If any errors occur, print the error message to stderr and return 1. Return 0 on success.

Protected environments

The js_try macro pushes a new protected environment and calls setjmp. If it returns true, an error has occurred. The protected environment has been popped and the error object is located on the top of the stack.

At the end of the code you want to run in the protected environment you must call js_endtry in order to pop the protected environment. Note: you should not call js_endtry when an error has occurred and you are in the true-branch of js_try.

Since the macro is a wrapper around setjmp, the usual restrictions apply. Use the following example as a guide for how to use js_try:

Most of the time you shouldn’t need to worry about protected environments. The functions prefixed with ‘p’ (js_pcall, js_ploadstring, etc) handle setting up the protected environment and return simple error codes.

Errors

void js_throw(js_State *J);

Pop the error object on the top of the stack and return control flow to the most recent protected environment.

Push primitive values. js_pushstring makes a copy of the string, so it may be freed or changed after passing it in. js_pushliteral keeps a pointer to the string, so it must not be changed or freed after passing it in.

Define the getter and setter attributes of a property on the object. Pop the two getter and setter functions from the stack. Use null instead of a function object if you want to leave any of the functions unset.

Pop the object to set as the “prototype” property for the constructor function object. Push a function object wrapping a C function pointer, allowing for separate function pointers for regular calls and ‘new’ operator calls.

void js_currentfunction(js_State *J);

Push the currently executing function object.

Userdata

void js_newuserdata(js_State *J, const char *tag, void *data);

Pop an object from the top of the stack to use as the internal prototype property for the new object. Push a new userdata object wrapping a pointer to C memory. The userdata object is tagged using a string, to represent the type of the C memory.

int js_isuserdata(js_State *J, int idx, const char *tag);

Test if an object is a userdata object with the given type tag string.

void *js_touserdata(js_State *J, int idx, const char *tag);

Return the wrapped pointer from a userdata object. If the object is undefined or null, return NULL. If the object is not a userdata object with the given type tag string, throw a type error.

Registry

The registry can be used to store references to Javascript objects accessible from C, but hidden from Javascript to prevent tampering.