Revision 992911 of loader/sandbox

{{AddonSidebar}}

<div class="note">
<p>Experimental</p>
</div>

<p><span class="seoSummary">Create JavaScript sandboxes and execute scripts in them.</span></p>

<h2 id="Usage">Usage</h2>

<h3 id="Create_a_sandbox">Create a sandbox</h3>

<p>To create a sandbox:</p>

<pre class="brush: js">
const { sandbox, evaluate, load } = require("sdk/loader/sandbox");
let scope = sandbox('https://example.com');</pre>

<p>The argument passed to the sandbox defines its privileges. The argument may be:</p>

<ul>
 <li>a URL string, in which case the sandbox will get the same privileges as a script loaded from that URL</li>
 <li>a DOM window object, to inherit privileges from the window being passed.</li>
 <li>omitted or <code>null</code>: then the sandbox will have chrome privileges giving it access to all the XPCOM components.</li>
</ul>

<p>Optionally the <code>sandbox</code> function can be passed a second argument (See <a href="https://developer.mozilla.org/en/Components.utils.Sandbox#Optional_parameter">sandbox documentation on MDN</a> for details).</p>

<h3 id="Evaluate_code">Evaluate code</h3>

<p>Module provides <code>evaluate</code> function that lets you execute code in the given sandbox:</p>

<pre class="brush: js">
evaluate(scope, 'var a = 5;');
evaluate(scope, 'a + 2;'); //=&gt; 7</pre>

<p>More details about evaluated script may be passed via optional arguments that may improve exception reporting:</p>

<pre class="brush: js">
// Evaluate code as if it was loaded from 'https://foo.com/bar.js' and
// start from 2nd line.
evaluate(scope, 'a ++', 'https://foo.com/bar.js', 2);</pre>

<p>Version of JavaScript can be also specified via an optional argument:</p>

<pre class="brush: js">
evaluate(scope, 'let b = 2;', 'bar.js', 1, '1.5');
// throws cause `let` is not defined in JS 1.5.</pre>

<h3 id="Load_scripts">Load scripts</h3>

<p>This module provides a limited API for loading scripts from local URLs. <code>data:</code> URLs are supported.</p>

<pre class="brush: js">
load(scope, 'resource://path/to/my/script.js');
load(scope, 'file:///path/to/script.js');
load(scope, 'data:,var a = 5;');</pre>

<h2 id="Globals">Globals</h2>

<h3 id="Functions">Functions</h3>

<h4 class="addon-sdk-api-name" id="sandbox(source)"><code>sandbox(source)</code></h4>

<p>Make a new sandbox that inherits principals from <code>source</code>.</p>

<h5 id="Parameters">Parameters</h5>

<p><strong>source : string|window|null</strong><br />
 An object that determines the privileges that will be given to the sandbox. This argument can be:</p>

<ul>
 <li>a URI string, giving the sandbox the same privileges as a script loaded from that URL</li>
 <li>a DOM window object, giving the sandbox the same privileges as the DOM window</li>
 <li><code>null</code>, to give the sandbox chrome privileges.</li>
</ul>

<h5 id="Returns">Returns</h5>

<p><strong>sandbox</strong> : A sandbox in which you can evaluate and load JavaScript.</p>

<h4 class="addon-sdk-api-name" id="evaluate(sandbox_code_uri_line_version)"><code>evaluate(sandbox, code, uri, line, version)</code></h4>

<p>Evaluate <code>code</code> in <code>sandbox</code>, and return the result.</p>

<h5 id="Parameters_2">Parameters</h5>

<p><strong>sandbox : sandbox</strong><br />
 The sandbox to use.</p>

<p><strong>code : string</strong><br />
 The code to execute.</p>

<p><strong>uri : string</strong><br />
 Evaluate the code as if it were being loaded from the given URI. Optional.</p>

<p><strong>line : number</strong><br />
 Evaluate the code starting at this line. Optional, defaults to 1.</p>

<p><strong>version : string</strong><br />
 Evaluate the code using this version of JavaScript. Defaults to 1.8.</p>

<h5 id="Returns_2">Returns</h5>

<p><strong>result</strong> : Returns whatever the evaluated code returns.</p>

<h4 class="addon-sdk-api-name" id="load(sandbox_uri)"><code>load(sandbox, uri)</code></h4>

<p>Evaluate code from <code>uri</code> in <code>sandbox</code>.</p>

<h5 id="Parameters_3">Parameters</h5>

<p><strong>sandbox : sandbox</strong><br />
 The sandbox to use.</p>

<p><strong>uri : string</strong><br />
 The URL pointing to the script to load. It must be a local <code>chrome:</code>, <code>resource:</code>, <code>file:</code> or <code>data:</code> URL.</p>

<h5 id="Returns_3">Returns</h5>

<p><strong>result</strong> : Returns whatever the evaluated code returns.</p>