Extending Embedded JavaScript

The version of JavaScript implemented in AppWeb is a subset, suitable for use in embedded systems. As JavaScript 1.2 is now quite a large language, its size prohibits its use in most embedded devices. Embedded JavaScript is designed to solve this dilemma. It is a strict subset of JavaScript that implements the essential elements of the language and is extensible by the user to support new functions.

JavaScript may be extended via several mechanisms:

• JavaScript Functions
• JavaScript Libraries
• C/C++ Functions

JavaScript functions may be created using the function statement. JavaScript functions, object definitions and variables can be grouped into JavaScript libraries that can be re-used via the include function.

To extend JavaScript for use with Embedded Server Pages, please read the Extending Embedded Server Pages for details.

JavaScript Libraries

Libraries of JavaScript functions, object definitions and constructors and variable declarations may be created and then re-used by JavaScripts. The include function will include the named file as though it were cut and pasted into the current file. For example:

<% include("inc.js"); %>

Creating JavaScript Functions from C Functions

JavaScript functions can most easily be created using the JavaScript function statement. However, there are times when you need to create a JavaScript function using the C language. This may be because you need the highest level of performance or you need to call C APIs as part of the function. Embedded JavaScript allows you to easily create JavaScript functions in C.

To create an EJS function in C, you create a function to execute when the JavaScript function name is invoked. This function is passed the EJS instance handle and the actual arguments passed to the JavaScript function at run-time.

You can create two kinds of EJS C functions. The simplest, shown below, automatically converts all arguments to strings before calling the C function. These are called String EJS Functions and are created via the ejsDefineStringCFunction API call. This method of function definition is ideal when the arguments and function result will always be strings.

The other kind of function definition does not convert the arguments to strings. Arguments are passed in an array of MprVar variables. These variables may be strings, boolean, integer, floating point or object variables. This style of function definition is best when any type of argument may be passed into the function.

For example, the following code fragment creates a String EJS function that will be invoked when a script calls the myProc function.

#include "ejs.h"

static int myProc(EjsHandle eid, int argc, char **argv)
{
    ejsSetReturnString(eid, "sunny day");
}

// Somewhere in the main program

espDefineStringCFunction(0, "myProc", myProc, 0);

Rebuilding From Source

Embedded JavaScript has several compile time constants that tailor the its operation. EJS permits you to select the default number type to be either a 32-bit integer, 64-bit integer or floating point. Depending on whether your system supports floating point or if you intend to use floating point, setting the default number type to be an integer will result in a smaller faster JavaScript interpreter. The default EJS build defines numbers as 32-bit integers. Standard ECMAScript defines numbers to be floating point numbers.

You may also select to disable floating point and 64-bit integer support. This further shrinks the size of the interpreter.