JS_CompileScript

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_CompileScript
  • Revision title: JS_CompileScript
  • Revision id: 77466
  • Created:
  • Creator: Petermichaux
  • Is current revision? No
  • Comment /* Description */

Revision Content

{{template.Jsapiref()}}

Summary

Function

Compiles a script for execution.

Syntax

JSScript * JS_CompileScript(JSContext *cx, JSObject *obj,
    const char *bytes, size_t length, const char *filename,
    uintN lineno);
Name Type Description
cx JSContext * Pointer to a JS context from which to derive runtime information.
obj JSObject * Object with which the script is associated.
bytes const char * String containing the script to compile.
length size_t Size, in bytes, of the script to compile.
filename const char * Name of file or URL containing the function. Used to report filename or URL in error messages.
lineno uintN Line number. Used to report the offending line in the file or URL if an error occurs.

Description

JS_CompileScript compiles a script, bytes, for execution. The script is associated with a JS object. bytes is the string containing the text of the script. length indicates the size of the text version of the script in bytes.

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

Similarly, lineno is used to report the line number of the script or file where an error occurred during compilation. lineno is an offset. The line number of the error in the script will will have the lineno added to it. Since line numbers in the script start with 0, using 1 for lineno will usually be a good idea.

If a script compiles successfully, JS_CompileScript returns a pointer to the compiled script. Otherwise JS_CompileScript returns NULL, and reports an error.

Notes

To compile a script using a Unicode character set, call JS_CompileUCScript instead of this function.

To compile a script from an external file source rather than passing the actual script as an argument, use JS_CompileFile instead of JS_CompileScript.

To avoid asserts in the JS engine, ensure lineno is > 0.

You should use JS_NewScriptObject and root a pointer to its return value to keep a JScript and its atoms safe from garbage collection after creating the script via JS_CompileScript and before a JS_ExecuteScript call.

Example (without error checks):

JSScript *script = JS_CompileFile(cx, global, filename);
JSObject *scrobj = JS_NewScriptObject(cx, script);
JS_AddNamedRoot(cx, &scrobj, "scrobj");
do {
        jsval result;
        JS_ExecuteScript(cx, global, script, &result);
        JS_GC();
} while (!JSVAL_IS_BOOLEAN(result) || JSVAL_TO_BOOLEAN(result));
JS_RemoveRoot(cx, &scrobj);

See Also

Groups Functions
Documents {{template.LXRSearch("ident", "i", "JS_CompileScript", "LXR ID Search")}}
Entries

JS_CompileFile, JS_CompileUCScript, JS_DecompileScript, JS_DestroyScript, JS_EvaluateScript, JS_ExecuteScript

Revision Source

<p> 
{{template.Jsapiref()}}
</p>
<h2 name="Summary"> Summary </h2>
<p><b>Function</b>
</p><p>Compiles a script for execution.
</p>
<h2 name="Syntax"> Syntax </h2>
<pre>JSScript * JS_CompileScript(JSContext *cx, JSObject *obj,
    const char *bytes, size_t length, const char *filename,
    uintN lineno);
</pre>
<table class="fullwidth-table">
<tbody><tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><code>cx</code></td>
<td><code>JSContext *</code></td>
<td>Pointer to a JS context from which to derive runtime information.</td>
</tr>
<tr>
<td><code>obj</code></td>
<td><code>JSObject *</code></td>
<td>Object with which the script is associated.</td>
</tr>
<tr>
<td><code>bytes</code></td>
<td><code>const char *</code></td>
<td>String containing the script to compile.</td>
</tr>
<tr>
<td><code>length</code></td>
<td><code>size_t</code></td>
<td>Size, in bytes, of the script to compile.</td>
</tr>
<tr>
<td><code>filename</code></td>
<td><code>const char *</code></td>
<td>Name of file or URL containing the function. Used to report filename or URL in error messages.</td>
</tr>
<tr>
<td><code>lineno</code></td>
<td><code>uintN</code></td>
<td>Line number. Used to report the offending line in the file or URL if an error occurs.</td>
</tr>
</tbody></table>
<h2 name="Description"> Description </h2>
<p><code>JS_CompileScript</code> compiles a script, <code>bytes</code>, for execution. The script is associated with a JS object. <code>bytes</code> is the string containing the text of the script. <code>length</code> indicates the size of the text version of the script in bytes.
</p><p><code>filename</code> is the name of the file (or URL) containing the script. This information is included in error messages if an error occurs during compilation.
</p><p>Similarly, <code>lineno</code> is used to report the line number of the script or file where an error occurred during compilation. <code>lineno</code> is an offset. The line number of the error in the script will will have the <code>lineno</code> added to it. Since line numbers in the script start with <code>0</code>, using <code>1</code> for <code>lineno</code> will usually be a good idea.
</p><p>If a script compiles successfully, <code>JS_CompileScript</code> returns a pointer to the compiled script. Otherwise <code>JS_CompileScript</code> returns <code>NULL</code>, and reports an error.
</p>
<h3 name="Notes"> Notes </h3>
<p>To compile a script using a Unicode character set, call <code><a href="en/JS_CompileUCScript">JS_CompileUCScript</a></code> instead of this function.
</p><p>To compile a script from an external file source rather than passing the actual script as an argument, use <code><a href="en/JS_CompileFile">JS_CompileFile</a></code> instead of <code>JS_CompileScript</code>.
</p><p>To avoid asserts in the JS engine, ensure <code>lineno</code> is &gt; 0.
</p><p>You should use <code><a href="en/JS_NewScriptObject">JS_NewScriptObject</a></code> and root a pointer to its return value to keep a <code>JScript</code> and its atoms safe from garbage collection after creating the script via <code>JS_CompileScript</code> and before a <code><a href="en/JS_ExecuteScript">JS_ExecuteScript</a></code> call.
</p><p>Example (without error checks):
</p>
<pre>JSScript *script = JS_CompileFile(cx, global, filename);
JSObject *scrobj = JS_NewScriptObject(cx, script);
JS_AddNamedRoot(cx, &amp;scrobj, "scrobj");
do {
        jsval result;
        JS_ExecuteScript(cx, global, script, &amp;result);
        JS_GC();
} while (!JSVAL_IS_BOOLEAN(result) || JSVAL_TO_BOOLEAN(result));
JS_RemoveRoot(cx, &amp;scrobj);
</pre>
<h2 name="See_Also"> See Also </h2>
<table class="fullwidth-table">
<tbody><tr>
<td>Groups</td>
<td><a href="en/JSAPI_Reference#Functions">Functions</a></td>
</tr>
<tr>
<td>Documents</td>
<td>{{template.LXRSearch("ident", "i", "JS_CompileScript", "LXR ID Search")}}</td>
</tr>
<tr>
<td>Entries</td>
<td>
<p><a href="en/JS_CompileFile">JS_CompileFile</a>,
<a href="en/JS_CompileUCScript">JS_CompileUCScript</a>,
<a href="en/JS_DecompileScript">JS_DecompileScript</a>,
<a href="en/JS_DestroyScript">JS_DestroyScript</a>,
<a href="en/JS_EvaluateScript">JS_EvaluateScript</a>,
<a href="en/JS_ExecuteScript">JS_ExecuteScript</a>
</p>
</td>
</tr>
</tbody></table>
Revert to this revision