Embedding Ejscript

It is easy to embed Ejscript into an application. Ejscript provides two levels of embedding APIs:

• One line embedding APIs
• Full control APIs

One Line Embedding

Ejscript provides three variety of one-line embedding APIs. These permit you to evaluate a script file, a script literal or a pre-compiled script module.

Evaluate a Script File

To create an application that can evaluate script files, use the ejsEvalFile API.

#include    "ejs/ejs.h"
int main(int argc, char **argv) 
{
    if (ejsEvalFile("test.es") < 0) {
        fprintf(stderr, "Error executing test.es\n");
        exit(1);
    }
    return 0;
}

To build this program, you just need to compile and link with Ejscript compiler library libejs. Here is the command for building such a test program called main.c on a MAC system.

cc -o main main.c -lejs

Evaluate a Script Literal

To create an application that can evaluate script literals, use the ejsEvalScript API.

#include    "ejs/ejs.h"
int main(int argc, char **argv) 
{
    if (argc != 2) {
        fprintf(stderr, "usage: main script\n");
        exit(1);
    }
    if (ejsEvalScript(argv[1]) < 0) {
        fprintf(stderr, "Error executing %s\n", argv[1]);
        exit(1);
    }
    return 0;
}

Then run this program and put a literal script on the command line.

./main "print('Hello World')"

Evaluate a Script Module

To create an application that can load and evaluate compiled script module files, use the ejsEvalModule API.

#include    "ejs/ejs.h"
int main(int argc, char **argv) 
{
    if (ejsEvalModule("test.mod") < 0) {
        fprintf(stderr, "Error executing test.mod\n");
        exit(1);
    }
    return 0;
}

To build this program, you just need link with Ejscript VM library libejs. Here is the command for building such a test program called main.c on a MAC system.

cc -o main main.c -lejs

Full Control Embedding

In some situations, your application may need full control over the Ejscript service. Some reasons for this include:

• You need to create multiple interpreter instances
• You want custom control over where Ejscript searches for modules
• You want to customize the interpreter with native types, methods or variables

Ejscript provides a comprehensive Ejscript Native API so you can fully control the configuration and operation of Ejscript. The APIs allow you to create and manage interpreters, create types, run methods, set and get properties and interact with all the objects held by the interpreter.

Ejscript leverages the Embedthis Portable Runtime (MPR) which is a cross-platform set of services that abstract the operating system. The MPR enhances the security of Ejscript by providing secure, high-performance, and well proven routines for managing memory, strings, lists, files, network sockets, http and threads. MPR APIs all begin with an mpr prefix whereas all Ejscript APIs begin with ejs for the VM or ejsc for the compiler.

The sample below demonstrates the full control steps to compile and evaluate a file.

int ejsEvalFile(int fileCount, char **fileList)
{
    Ejs     *ejs;         //  Handle to an Ejscript interpreter
    int     status;
    mprCreate(0, 0, 0);
    if ((ejs = ejsCreateVM(0, 0, 0)) == 0) {
        exit(1);
    }
    mprAddRoot(ejs);
    if (ejsLoadModules(ejs, 0, 0) < 0) {
        exit(2);
    } 
    if (ejsLoadScriptFile(ejs, path, NULL, 
            EC_FLAGS_NO_OUT | EC_FLAGS_DEBUG) < 0) {
        ejsReportError(ejs, "Error in program");
        exit(3);
    }
    mprDestroy(MPR_EXIT_DEFAULT);
    return 0;
}

Consult the Ejscript Native API and MPR Native API for details on each API. The MPR provides a hierarchical memory allocation service, so calls to mprFree will free the MPR instance and everything allocated off the MPR. This includes the Ejscript service, VM, interpreter and compiler. Be sure to read the MPR Memory Allocation Service for details.

See the Extending Ejscript for how to interact with the interpreter, objects, types, run methods, create types and properties, delete properties, throw exceptions, cast types and more.