JS::CompileOptions

This article covers features introduced in SpiderMonkey 17

Compile options classes.

Constructor

JS::ReadOnlyCompileOptions(); // Added in SpiderMonkey 31

JS::OwningCompileOptions(JSContext *cx); // Added in SpiderMonkey 31

JS::CompileOptions(JSContext *cx, JSVersion version = JSVERSION_UNKNOWN);

Name	Type	Description
`cx`	`JSContext *`	Pointer to a JS context from which to derive runtime information. Requires request. In a `JS_THREADSAFE` build, the caller must be in a request on this `JSContext`.
`version`	`JSVersion`	JavaScript version used to compile the script.

Methods

Some methods of JS::OwningCompileOptions and JS::CompileOptions return the instance itself to allow method chain.

Methods of `JS::ReadOnlyCompileOptions`
Method	Description
`bool mutedErrors() const`	Determines if errors are muted. The Web Platform allows scripts to be loaded from arbitrary cross-origin sources. This allows an attack by which a malicious website loads a sensitive file (say, a bank statement) cross-origin (using the user's cookies), and sniffs the generated syntax errors (via a window.onerror handler) for juicy morsels of its contents. To counter this attack, HTML5 specifies that script errors should be sanitized ("muted") when the script is not same-origin with the global for which it is loaded. Callers should set this flag for cross-origin scripts, and it will be propagated appropriately to child scripts and passed back in `JSErrorReport`s.
`const char *filename() const`	Returns filename of the source code.
`const char *introducerFilename() const`	Returns filename of the file which introduces the file.
`const char16_t *sourceMapURL() const`	Returns the URL of the source map.

Methods of `JS::OwningCompileOptions`
Method	Description
`JSObject *element() const`	Returns the DOM element to which this source code belongs, if any, or `NULL` if it belongs to no DOM element. Source belongs to a DOM element in the following cases: Source belongs to a `<script>` element if it is the element's text content (that is, it is written out as the body of the `<script>` element in the markup text), or is the source document referenced by its `src` attribute. Source belongs to a DOM element if it is an event handler content attribute (that is, if it is written out in the markup text as an attribute value). Source belongs to a DOM element if it was assigned to one of the element's event handler IDL attributes as a string. (Note that one may assign both strings and functions to DOM elements' event handler IDL attributes. If one assigns a function, that function's script's source does not belong to the DOM element; the function's definition must appear elsewhere.)
`JSString *elementAttributeName() const`	If this source belongs to a DOM element because it is an event handler content attribute or an event handler IDL attribute, this returns the name of that attribute, a string. Otherwise, this returns `NULL`.
`JSScript *introductionScript() const`	Returns a pointer to `JSScript` which introduces the file.
`bool copy(JSContext *cx, const ReadOnlyCompileOptions &rhs)`	Copy compile options from `rhs`. Returns `false` if it failed to duplicate owning properties.
`bool setFile(JSContext cx, const char f)`	Duplicate null-terminated string `f` for `filename()`. Returns `false` if it failed to duplicate.
`bool setFileAndLine(JSContext cx, const char f, unsigned l)`	Duplicate null-terminated string `f` for `filename()` and set `lineno` property. Returns `false` if it failed to duplicate.
`bool setSourceMapURL(JSContext cx, const char16_t s)`	Duplicate null-terminated string `s` for `sourceMapURL`. Returns `false` if it failed to duplicate.
`bool setIntroducerFilename(JSContext cx, const char s)`	Duplicate null-terminated string `s` for `introducerFilename`. Returns `false` if it failed to duplicate.
`OwningCompileOptions &setLine(unsigned l)`	Sets each property and returns the instance itself.
`OwningCompileOptions &setElement(JSObject *e)`
`OwningCompileOptions &setElementAttributeName(JSString *p)`
`OwningCompileOptions &setIntroductionScript(JSScript *s)`
`OwningCompileOptions &setMutedErrors(bool mute)`
`OwningCompileOptions &setVersion(JSVersion v)`
`OwningCompileOptions &setUTF8(bool u)`
`OwningCompileOptions &setColumn(unsigned c)`
`OwningCompileOptions &setCompileAndGo(bool cng)`
`OwningCompileOptions &setForEval(bool eval)`
`OwningCompileOptions &setNoScriptRval(bool nsr)`
`OwningCompileOptions &setSelfHostingMode(bool shm)`
`OwningCompileOptions &setCanLazilyParse(bool clp)`
`OwningCompileOptions &setSourceIsLazy(bool l)`
`OwningCompileOptions &setIntroductionType(const char *t)`
`bool setIntroductionInfo(JSContext cx, const char introducerFn, const char intro, unsigned line, JSScript script, uint32_t offset)`	Duplicate null-terminated string `introducerFn` for `introducerFilename` and set `introductionType`, `introductionLineno`, `introductionScriptRoot`, `introductionOffset`, and `hasIntroductionInfo` properties. Returns `false` if it failed to duplicate.

Methods of `JS::CompileOptions`
Method	Description
`JSObject *element() const`	Same as `JS::OwningCompileOptions`.
`JSString *elementAttributeName() const`
`JSScript *introductionScript() const`
`CompileOptions &setFile(const char *f)`	Sets each property and returns the instance itself.
`CompileOptions &setLine(unsigned l)`
`CompileOptions &setFileAndLine(const char *f, unsigned l)`
`CompileOptions &setSourceMapURL(const char16_t *s)`
`CompileOptions &setElement(JSObject *e)`
`CompileOptions &setElementAttributeName(JSString *p)`
`CompileOptions &setIntroductionScript(JSScript *s)`
`CompileOptions &setMutedErrors(bool mute)`
`CompileOptions &setVersion(JSVersion v)`
`CompileOptions &setUTF8(bool u)`
`CompileOptions &setColumn(unsigned c)`
`CompileOptions &setCompileAndGo(bool cng)`
`CompileOptions &setForEval(bool eval)`
`CompileOptions &setNoScriptRval(bool nsr)`
`CompileOptions &setSelfHostingMode(bool shm)`
`CompileOptions &setCanLazilyParse(bool clp)`
`CompileOptions &setSourceIsLazy(bool l)`
`CompileOptions &setIntroductionType(const char *t)`
`CompileOptions &setIntroductionInfo(const char introducerFn, const char intro, unsigned line, JSScript *script, uint32_t offset)`
`CompileOptions &maybeMakeStrictMode(bool strict)`

Properties

Properties of `JS::ReadOnlyCompileOptions`
Name	Type	Description
`version`	`JSVersion`	Version of the script.
`versionSet`	`bool`	`true` if `version` is set.
`utf8`	`bool`	`true` if the character set of the source code is UTF-8.
`lineno`	`unsigned`	Line number of the first line of the source code (1-origin).
`column`	`unsigned`	Column number of the first line of the source code (0-origin).
`compileAndGo`	`bool`	`true` if the code is going to be evaluated soon after the compile (e.g., `false` for `Function` constructor and event handler).
`forEval`	`bool`	`true` if the code is for `eval()`.
`noScriptRval`	`bool`	`false` means that the caller needs the return value of the script.
`selfHostingMode`	`bool`	`true` iff the code is self-hosted.
`canLazilyParse`	`bool`	`true` if the source code can be parsed lazily (check only syntax for first time, and fully parse when it's really needed).
`strictOption`	`bool`	`true` if the code is strict mode (`"use strict"`).
`extraWarningsOption`	`bool`	Show extra warning.
`werrorOption`	`bool`	Treat warning as error.
`asmJSOption`	`bool`	`true` if asm.js is allowed in the code.
`forceAsync`	`bool`	`false` means `JS::CanCompileOffThread` may returns `false` depends on the length of the code.
`installedFile`	`bool`	`true` iff pre-compiling js file in packaged app.
`sourceIsLazy`	`bool`	`true` indicates that, after compilation, script source should not be cached by the JS engine and should be lazily loaded from the embedding as-needed.
`introductionType`	`const char`	A statically allocated C string: one of following in general: `"eval"` - code passed to `eval` `"Function"` - code passed to the `Function` constructor. `"GeneratorFunction"` - code passed to the `GeneratorFunction` constructor. In addition to above, the following are used in browser: `"Worker"` - code loaded by calling the Web worker constructor—the worker's main script. `"importScript"` - code by calling `importScripts` in a web worker. `"eventHandler"` - code assigned to DOM elements' event handler IDL attributes as a string. `"scriptElement"` - code belonging to `<script>` elements. `"javascriptURL"` - code presented in `javascript:` URLs. `"setTimeout"` - code passed to `setTimeout` as a string. `"setInterval"` - code passed to `setInterval` as a string. The following are used in js shell: `"js shell file"` `"js shell interactive"` `"js shell load"` `"js shell evaluate"` `"js shell run"` `"js shell disFile"` `"js shell compFile"` `"js shell parse"` `"js shell syntaxParse"` `"js shell offThreadCompileScript"` And the following are used in self-hosted code and debugger: `"self-hosted"` `"debugger eval"`
`introductionLineno`	`unsigned`	Line number in the source code which introduces this source code.
`introductionOffset`	`uint32_t`	Bytecode offset in the code which introduces this source code.
`hasIntroductionInfo`	`bool`	`true` if `setIntroductionInfo` is called.

Description

In the most common use case, a CompileOptions instance is allocated on the stack, and holds non-owning references to non-POD option values: strings; principals; objects; and so on. The code declaring the instance guarantees that such option values will outlive the CompileOptions itself: objects are otherwise rooted; principals have had their reference counts bumped; strings will not be freed until the CompileOptions goes out of scope. In this situation, CompileOptions only refers to things others own, so it can be lightweight.

In some cases, however, we need to hold compilation options with a non-stack-like lifetime. For example, JS::CompileOffThread needs to save compilation options where a worker thread can find them, and then return immediately. The worker thread will come along at some later point, and use the options.

The compiler itself just needs to be able to access a collection of options; it doesn't care who owns them, or what's keeping them alive. It does its own addrefs/copies/tracing/etc.

So, we have a class hierarchy that reflects these three use cases:

ReadOnlyCompileOptions is the common base class. It can be used by code that simply needs to access options set elsewhere, like the compiler.
The usual CompileOptions class must be stack-allocated, and holds non-owning references to the filename, element, and so on. It's derived from ReadOnlyCompileOptions, so the compiler can use it.
OwningCompileOptions roots / copies / reference counts of all its values, and unroots / frees / releases them when it is destructed. It too is derived from ReadOnlyCompileOptions, so the compiler accepts it.

ReadOnlyCompileOptions

ReadOnlyCompileOptions is the common base class for the CompileOptions hierarchy.

Use this in code that only needs to access compilation options created elsewhere, like the compiler. Don't instantiate this class (the constructor is protected anyway); instead, create instances only of the derived classes: CompileOptions and OwningCompileOptions.

OwningCompileOptions

OwningCompileOptions is the compilation options, with dynamic lifetime. An instance of this type makes a copy of / holds / roots all dynamically allocated resources (principals; elements; strings) that it refers to. Its destructor frees / drops / unroots them. This is heavier than CompileOptions, below, but unlike CompileOptions, it can outlive any given stack frame.

Note that this *roots* any JS values it refers to - they're live unconditionally. Thus, instances of this type can't be owned, directly or indirectly, by a JavaScript object: if any value that this roots ever comes to refer to the object that owns this, then the whole cycle, and anything else it entrains, will never be freed.

CompileOptions

CompileOptions is the compilation options stored on the stack. An instance of this type simply holds references to dynamically allocated resources (element; filename; source map URL) that are owned by something else. If you create an instance of this type, it's up to you to guarantee that everything you store in it will outlive it.