Craig Condon
337 lines
15 KiB
HTML
337 lines
15 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>Executing JavaScript Node.js v0.8.14 Manual & Documentation</title>
|
|
<link rel="stylesheet" href="assets/style.css">
|
|
<link rel="stylesheet" href="assets/sh.css">
|
|
<link rel="canonical" href="http://nodejs.org/api/vm.html">
|
|
</head>
|
|
<body class="alt apidoc" id="api-section-vm">
|
|
<div id="intro" class="interior">
|
|
<a href="/" title="Go back to the home page">
|
|
<img id="logo" src="http://nodejs.org/images/logo-light.png" alt="node.js">
|
|
</a>
|
|
</div>
|
|
<div id="content" class="clearfix">
|
|
<div id="column2" class="interior">
|
|
<ul>
|
|
<li><a href="/" class="home">Home</a></li>
|
|
<li><a href="/download/" class="download">Download</a></li>
|
|
<li><a href="/about/" class="about">About</a></li>
|
|
<li><a href="http://search.npmjs.org/" class="npm">npm Registry</a></li>
|
|
<li><a href="http://nodejs.org/api/" class="docs current">Docs</a></li>
|
|
<li><a href="http://blog.nodejs.org" class="blog">Blog</a></li>
|
|
<li><a href="/community/" class="community">Community</a></li>
|
|
<li><a href="/logos/" class="logos">Logos</a></li>
|
|
<li><a href="http://jobs.nodejs.org/" class="jobs">Jobs</a></li>
|
|
</ul>
|
|
<p class="twitter"><a href="http://twitter.com/nodejs">@nodejs</a></p>
|
|
</div>
|
|
|
|
<div id="column1" class="interior">
|
|
<header>
|
|
<h1>Node.js v0.8.14 Manual & Documentation</h1>
|
|
<div id="gtoc">
|
|
<p>
|
|
<a href="index.html" name="toc">Index</a> |
|
|
<a href="all.html">View on single page</a> |
|
|
<a href="vm.json">View as JSON</a>
|
|
</p>
|
|
</div>
|
|
<hr>
|
|
</header>
|
|
|
|
<div id="toc">
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><a href="#vm_executing_javascript">Executing JavaScript</a><ul>
|
|
<li><a href="#vm_caveats">Caveats</a><ul>
|
|
<li><a href="#vm_sandboxes">Sandboxes</a></li>
|
|
<li><a href="#vm_globals">Globals</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#vm_vm_runinthiscontext_code_filename">vm.runInThisContext(code, [filename])</a></li>
|
|
<li><a href="#vm_vm_runinnewcontext_code_sandbox_filename">vm.runInNewContext(code, [sandbox], [filename])</a></li>
|
|
<li><a href="#vm_vm_runincontext_code_context_filename">vm.runInContext(code, context, [filename])</a></li>
|
|
<li><a href="#vm_vm_createcontext_initsandbox">vm.createContext([initSandbox])</a></li>
|
|
<li><a href="#vm_vm_createscript_code_filename">vm.createScript(code, [filename])</a></li>
|
|
<li><a href="#vm_class_script">Class: Script</a><ul>
|
|
<li><a href="#vm_script_runinthiscontext">script.runInThisContext()</a></li>
|
|
<li><a href="#vm_script_runinnewcontext_sandbox">script.runInNewContext([sandbox])</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
|
|
<div id="apicontent">
|
|
<h1>Executing JavaScript<span><a class="mark" href="#vm_executing_javascript" id="vm_executing_javascript">#</a></span></h1>
|
|
<pre><code>Stability: 2 - Unstable. See Caveats, below.</code></pre>
|
|
<!--name=vm-->
|
|
|
|
<p>You can access this module with:
|
|
|
|
</p>
|
|
<pre><code>var vm = require('vm');</code></pre>
|
|
<p>JavaScript code can be compiled and run immediately or compiled, saved, and run later.
|
|
|
|
</p>
|
|
<h2>Caveats<span><a class="mark" href="#vm_caveats" id="vm_caveats">#</a></span></h2>
|
|
<p>The <code>vm</code> module has many known issues and edge cases. If you run into
|
|
issues or unexpected behavior, please consult
|
|
<a href="https://github.com/joyent/node/issues/search?q=vm">the open issues on GitHub</a>.
|
|
Some of the biggest problems are described below.
|
|
|
|
</p>
|
|
<h3>Sandboxes<span><a class="mark" href="#vm_sandboxes" id="vm_sandboxes">#</a></span></h3>
|
|
<p>The <code>sandbox</code> argument to <code>vm.runInNewContext</code> and <code>vm.createContext</code>,
|
|
along with the <code>initSandbox</code> argument to <code>vm.createContext</code>, do not
|
|
behave as one might normally expect and their behavior varies
|
|
between different versions of Node.
|
|
|
|
</p>
|
|
<p>The key issue to be aware of is that V8 provides no way to directly
|
|
control the global object used within a context. As a result, while
|
|
properties of your <code>sandbox</code> object will be available in the context,
|
|
any properties from the <code>prototype</code>s of the <code>sandbox</code> may not be
|
|
available. Furthermore, the <code>this</code> expression within the global scope
|
|
of the context evaluates to the empty object (<code>{}</code>) instead of to
|
|
your sandbox.
|
|
|
|
</p>
|
|
<p>Your sandbox's properties are also not shared directly with the script.
|
|
Instead, the properties of the sandbox are copied into the context at
|
|
the beginning of execution, and then after execution, the properties
|
|
are copied back out in an attempt to propagate any changes.
|
|
|
|
</p>
|
|
<h3>Globals<span><a class="mark" href="#vm_globals" id="vm_globals">#</a></span></h3>
|
|
<p>Properties of the global object, like <code>Array</code> and <code>String</code>, have
|
|
different values inside of a context. This means that common
|
|
expressions like <code>[] instanceof Array</code> or
|
|
<code>Object.getPrototypeOf([]) === Array.prototype</code> may not produce
|
|
expected results when used inside of scripts evaluated via the <code>vm</code> module.
|
|
|
|
</p>
|
|
<p>Some of these problems have known workarounds listed in the issues for
|
|
<code>vm</code> on GitHub. for example, <code>Array.isArray</code> works around
|
|
the example problem with <code>Array</code>.
|
|
|
|
</p>
|
|
<h2>vm.runInThisContext(code, [filename])<span><a class="mark" href="#vm_vm_runinthiscontext_code_filename" id="vm_vm_runinthiscontext_code_filename">#</a></span></h2>
|
|
<p><code>vm.runInThisContext()</code> compiles <code>code</code>, runs it and returns the result. Running
|
|
code does not have access to local scope. <code>filename</code> is optional, it's used only
|
|
in stack traces.
|
|
|
|
</p>
|
|
<p>Example of using <code>vm.runInThisContext</code> and <code>eval</code> to run the same code:
|
|
|
|
</p>
|
|
<pre><code>var localVar = 123,
|
|
usingscript, evaled,
|
|
vm = require('vm');
|
|
|
|
usingscript = vm.runInThisContext('localVar = 1;',
|
|
'myfile.vm');
|
|
console.log('localVar: ' + localVar + ', usingscript: ' +
|
|
usingscript);
|
|
evaled = eval('localVar = 1;');
|
|
console.log('localVar: ' + localVar + ', evaled: ' +
|
|
evaled);
|
|
|
|
// localVar: 123, usingscript: 1
|
|
// localVar: 1, evaled: 1</code></pre>
|
|
<p><code>vm.runInThisContext</code> does not have access to the local scope, so <code>localVar</code> is unchanged.
|
|
<code>eval</code> does have access to the local scope, so <code>localVar</code> is changed.
|
|
|
|
</p>
|
|
<p>In case of syntax error in <code>code</code>, <code>vm.runInThisContext</code> emits the syntax error to stderr
|
|
and throws an exception.
|
|
|
|
|
|
</p>
|
|
<h2>vm.runInNewContext(code, [sandbox], [filename])<span><a class="mark" href="#vm_vm_runinnewcontext_code_sandbox_filename" id="vm_vm_runinnewcontext_code_sandbox_filename">#</a></span></h2>
|
|
<p><code>vm.runInNewContext</code> compiles <code>code</code>, then runs it in <code>sandbox</code> and returns the
|
|
result. Running code does not have access to local scope. The object <code>sandbox</code>
|
|
will be used as the global object for <code>code</code>.
|
|
<code>sandbox</code> and <code>filename</code> are optional, <code>filename</code> is only used in stack traces.
|
|
|
|
</p>
|
|
<p>Example: compile and execute code that increments a global variable and sets a new one.
|
|
These globals are contained in the sandbox.
|
|
|
|
</p>
|
|
<pre><code>var util = require('util'),
|
|
vm = require('vm'),
|
|
sandbox = {
|
|
animal: 'cat',
|
|
count: 2
|
|
};
|
|
|
|
vm.runInNewContext('count += 1; name = "kitty"', sandbox, 'myfile.vm');
|
|
console.log(util.inspect(sandbox));
|
|
|
|
// { animal: 'cat', count: 3, name: 'kitty' }</code></pre>
|
|
<p>Note that running untrusted code is a tricky business requiring great care. To prevent accidental
|
|
global variable leakage, <code>vm.runInNewContext</code> is quite useful, but safely running untrusted code
|
|
requires a separate process.
|
|
|
|
</p>
|
|
<p>In case of syntax error in <code>code</code>, <code>vm.runInNewContext</code> emits the syntax error to stderr
|
|
and throws an exception.
|
|
|
|
</p>
|
|
<h2>vm.runInContext(code, context, [filename])<span><a class="mark" href="#vm_vm_runincontext_code_context_filename" id="vm_vm_runincontext_code_context_filename">#</a></span></h2>
|
|
<p><code>vm.runInContext</code> compiles <code>code</code>, then runs it in <code>context</code> and returns the
|
|
result. A (V8) context comprises a global object, together with a set of
|
|
built-in objects and functions. Running code does not have access to local scope
|
|
and the global object held within <code>context</code> will be used as the global object
|
|
for <code>code</code>.
|
|
<code>filename</code> is optional, it's used only in stack traces.
|
|
|
|
</p>
|
|
<p>Example: compile and execute code in a existing context.
|
|
|
|
</p>
|
|
<pre><code>var util = require('util'),
|
|
vm = require('vm'),
|
|
initSandbox = {
|
|
animal: 'cat',
|
|
count: 2
|
|
},
|
|
context = vm.createContext(initSandbox);
|
|
|
|
vm.runInContext('count += 1; name = "CATT"', context, 'myfile.vm');
|
|
console.log(util.inspect(context));
|
|
|
|
// { animal: 'cat', count: 3, name: 'CATT' }</code></pre>
|
|
<p>Note that <code>createContext</code> will perform a shallow clone of the supplied sandbox object in order to
|
|
initialize the global object of the freshly constructed context.
|
|
|
|
</p>
|
|
<p>Note that running untrusted code is a tricky business requiring great care. To prevent accidental
|
|
global variable leakage, <code>vm.runInContext</code> is quite useful, but safely running untrusted code
|
|
requires a separate process.
|
|
|
|
</p>
|
|
<p>In case of syntax error in <code>code</code>, <code>vm.runInContext</code> emits the syntax error to stderr
|
|
and throws an exception.
|
|
|
|
</p>
|
|
<h2>vm.createContext([initSandbox])<span><a class="mark" href="#vm_vm_createcontext_initsandbox" id="vm_vm_createcontext_initsandbox">#</a></span></h2>
|
|
<p><code>vm.createContext</code> creates a new context which is suitable for use as the 2nd argument of a subsequent
|
|
call to <code>vm.runInContext</code>. A (V8) context comprises a global object together with a set of
|
|
build-in objects and functions. The optional argument <code>initSandbox</code> will be shallow-copied
|
|
to seed the initial contents of the global object used by the context.
|
|
|
|
</p>
|
|
<h2>vm.createScript(code, [filename])<span><a class="mark" href="#vm_vm_createscript_code_filename" id="vm_vm_createscript_code_filename">#</a></span></h2>
|
|
<p><code>createScript</code> compiles <code>code</code> but does not run it. Instead, it returns a
|
|
<code>vm.Script</code> object representing this compiled code. This script can be run
|
|
later many times using methods below. The returned script is not bound to any
|
|
global object. It is bound before each run, just for that run. <code>filename</code> is
|
|
optional, it's only used in stack traces.
|
|
|
|
</p>
|
|
<p>In case of syntax error in <code>code</code>, <code>createScript</code> prints the syntax error to stderr
|
|
and throws an exception.
|
|
|
|
|
|
</p>
|
|
<h2>Class: Script<span><a class="mark" href="#vm_class_script" id="vm_class_script">#</a></span></h2>
|
|
<p>A class for running scripts. Returned by vm.createScript.
|
|
|
|
</p>
|
|
<h3>script.runInThisContext()<span><a class="mark" href="#vm_script_runinthiscontext" id="vm_script_runinthiscontext">#</a></span></h3>
|
|
<p>Similar to <code>vm.runInThisContext</code> but a method of a precompiled <code>Script</code> object.
|
|
<code>script.runInThisContext</code> runs the code of <code>script</code> and returns the result.
|
|
Running code does not have access to local scope, but does have access to the <code>global</code> object
|
|
(v8: in actual context).
|
|
|
|
</p>
|
|
<p>Example of using <code>script.runInThisContext</code> to compile code once and run it multiple times:
|
|
|
|
</p>
|
|
<pre><code>var vm = require('vm');
|
|
|
|
globalVar = 0;
|
|
|
|
var script = vm.createScript('globalVar += 1', 'myfile.vm');
|
|
|
|
for (var i = 0; i < 1000 ; i += 1) {
|
|
script.runInThisContext();
|
|
}
|
|
|
|
console.log(globalVar);
|
|
|
|
// 1000</code></pre>
|
|
<h3>script.runInNewContext([sandbox])<span><a class="mark" href="#vm_script_runinnewcontext_sandbox" id="vm_script_runinnewcontext_sandbox">#</a></span></h3>
|
|
<p>Similar to <code>vm.runInNewContext</code> a method of a precompiled <code>Script</code> object.
|
|
<code>script.runInNewContext</code> runs the code of <code>script</code> with <code>sandbox</code> as the global object and returns the result.
|
|
Running code does not have access to local scope. <code>sandbox</code> is optional.
|
|
|
|
</p>
|
|
<p>Example: compile code that increments a global variable and sets one, then execute this code multiple times.
|
|
These globals are contained in the sandbox.
|
|
|
|
</p>
|
|
<pre><code>var util = require('util'),
|
|
vm = require('vm'),
|
|
sandbox = {
|
|
animal: 'cat',
|
|
count: 2
|
|
};
|
|
|
|
var script = vm.createScript('count += 1; name = "kitty"', 'myfile.vm');
|
|
|
|
for (var i = 0; i < 10 ; i += 1) {
|
|
script.runInNewContext(sandbox);
|
|
}
|
|
|
|
console.log(util.inspect(sandbox));
|
|
|
|
// { animal: 'cat', count: 12, name: 'kitty' }</code></pre>
|
|
<p>Note that running untrusted code is a tricky business requiring great care. To prevent accidental
|
|
global variable leakage, <code>script.runInNewContext</code> is quite useful, but safely running untrusted code
|
|
requires a separate process.
|
|
</p>
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="footer">
|
|
<ul class="clearfix">
|
|
<li><a href="/">Node.js</a></li>
|
|
<li><a href="/download/">Download</a></li>
|
|
<li><a href="/about/">About</a></li>
|
|
<li><a href="http://search.npmjs.org/">npm Registry</a></li>
|
|
<li><a href="http://nodejs.org/api/">Docs</a></li>
|
|
<li><a href="http://blog.nodejs.org">Blog</a></li>
|
|
<li><a href="/community/">Community</a></li>
|
|
<li><a href="/logos/">Logos</a></li>
|
|
<li><a href="http://jobs.nodejs.org/">Jobs</a></li>
|
|
<li><a href="http://twitter.com/nodejs" class="twitter">@nodejs</a></li>
|
|
</ul>
|
|
|
|
<p>Copyright <a href="http://joyent.com/">Joyent, Inc</a>, Node.js is a <a href="/trademark-policy.pdf">trademark</a> of Joyent, Inc. View <a href="https://raw.github.com/joyent/node/v0.8.14/LICENSE">license</a>.</p>
|
|
</div>
|
|
|
|
<script src="../sh_main.js"></script>
|
|
<script src="../sh_javascript.min.js"></script>
|
|
<script>highlight(undefined, undefined, 'pre');</script>
|
|
<script>
|
|
window._gaq = [['_setAccount', 'UA-10874194-2'], ['_trackPageview']];
|
|
(function(d, t) {
|
|
var g = d.createElement(t),
|
|
s = d.getElementsByTagName(t)[0];
|
|
g.src = '//www.google-analytics.com/ga.js';
|
|
s.parentNode.insertBefore(g, s);
|
|
}(document, 'script'));
|
|
</script>
|
|
</body>
|
|
</html>
|
|
|