JS::Evaluate

This article covers features introduced in SpiderMonkey 17

Compile and execute a script.

Syntax

// Added in SpiderMonkey 45

bool
JS::Evaluate(JSContext *cx,
             const JS::ReadOnlyCompileOptions &options,
             JS::SourceBufferHolder &srcBuf, JS::MutableHandleValue rval);

bool
JS::Evaluate(JSContext *cx,
             const JS::ReadOnlyCompileOptions &options,
             const char16_t *chars, size_t length, JS::MutableHandleValue rval);

bool
JS::Evaluate(JSContext *cx,
             const JS::ReadOnlyCompileOptions &options,
             const char *bytes, size_t length, JS::MutableHandleValue rval);

bool
JS::Evaluate(JSContext *cx,
             const JS::ReadOnlyCompileOptions &options,
             const char *filename, JS::MutableHandleValue rval);

bool
JS::Evaluate(JSContext *cx, JS::AutoObjectVector &scopeChain,
             const ReadOnlyCompileOptions &options,
             const char16_t *chars, size_t length, JS::MutableHandleValue rval);

// Added in SpiderMonkey 17

bool
JS::Evaluate(JSContext *cx, JS::AutoObjectVector &scopeChain,
             const JS::ReadOnlyCompileOptions &options,
             JS::SourceBufferHolder &srcBuf, JS::MutableHandleValue rval);

// Obsolete since JSAPI 39

bool
JS::Evaluate(JSContext *cx, JS::HandleObject obj,
             const JS::ReadOnlyCompileOptions &options,
             JS::SourceBufferHolder &srcBuf, JS::MutableHandleValue rval);

bool
JS::Evaluate(JSContext *cx, JS::HandleObject obj,
             const JS::ReadOnlyCompileOptions &options,
             const char16_t *chars, size_t length, JS::MutableHandleValue rval);

bool
JS::Evaluate(JSContext *cx, JS::HandleObject obj,
             const JS::ReadOnlyCompileOptions &options,
             const char *bytes, size_t length, JS::MutableHandleValue rval);

bool
JS::Evaluate(JSContext *cx, JS::HandleObject obj,
             const JS::ReadOnlyCompileOptions &options,
             const char *filename, JS::MutableHandleValue rval);
Name Type Description
cx JSContext * The context in which to run the script. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext.
obj JS::HandleObject The scope in which to execute the script. This parameter is documented in detail at JS_ExecuteScript. Obsolete since JSAPI 39
scopeChain JS::AutoObjectVector & The scope in which to execute the script. This parameter is documented in detail at JS_ExecuteScript.
options JS::ReadOnlyCompileOptions & Compile options.
srcBuf JS::SourceBufferHolder & Source buffer containing the script to compile and execute.
chars const char16_t * String containing the script to compile and execute.
bytes const char * String containing the script to compile and execute.
length size_t The length of chars or bytes, in characters.
filename const char * Name of file or URL containing the script. Used to report filename or URL in error messages.
rval JS::MutableHandleValue Out parameter. On success, if rval is not NULL, *rval receives the result value.

Description

JS::Evaluate compiles and executes a script in the specified scope, obj or scopeChain.

srcBuf, chars and bytes are the string containing the text of the script. length indicates the size of the text version of the script in characters.

filename is the name of the file (or URL) containing the script. This information is used in messages if an error occurs during compilation.

rval is an optional out parameter. If it is non-null, then on success, the result value is stored in *rval. This value is determined the same way as for the standard eval function. In the common case where the script is just an expression, the result value is simply the value of that expression. More generally, the result value is the value of the last-executed expression statement in the script that isn't in a function.

If a script compiles and executes successfully, JS::Evaluate stores the result in *rval, if non-null, and returns true. Otherwise it returns false and the value left in *rval is undefined.

See Also