5 You can access this module with:
7 var vm = require('vm');
9 JavaScript code can be compiled and run immediately or compiled, saved, and run later.
12 ## vm.runInThisContext(code, [filename])
14 `vm.runInThisContext()` compiles `code`, runs it and returns the result. Running
15 code does not have access to local scope. `filename` is optional, it's used only
18 Example of using `vm.runInThisContext` and `eval` to run the same code:
24 usingscript = vm.runInThisContext('localVar = 1;',
26 console.log('localVar: ' + localVar + ', usingscript: ' +
28 evaled = eval('localVar = 1;');
29 console.log('localVar: ' + localVar + ', evaled: ' +
32 // localVar: 123, usingscript: 1
33 // localVar: 1, evaled: 1
35 `vm.runInThisContext` does not have access to the local scope, so `localVar` is unchanged.
36 `eval` does have access to the local scope, so `localVar` is changed.
38 In case of syntax error in `code`, `vm.runInThisContext` emits the syntax error to stderr
39 and throws an exception.
42 ## vm.runInNewContext(code, [sandbox], [filename])
44 `vm.runInNewContext` compiles `code`, then runs it in `sandbox` and returns the
45 result. Running code does not have access to local scope. The object `sandbox`
46 will be used as the global object for `code`.
47 `sandbox` and `filename` are optional, `filename` is only used in stack traces.
49 Example: compile and execute code that increments a global variable and sets a new one.
50 These globals are contained in the sandbox.
52 var util = require('util'),
59 vm.runInNewContext('count += 1; name = "kitty"', sandbox, 'myfile.vm');
60 console.log(util.inspect(sandbox));
62 // { animal: 'cat', count: 3, name: 'kitty' }
64 Note that running untrusted code is a tricky business requiring great care. To prevent accidental
65 global variable leakage, `vm.runInNewContext` is quite useful, but safely running untrusted code
66 requires a separate process.
68 In case of syntax error in `code`, `vm.runInNewContext` emits the syntax error to stderr
69 and throws an exception.
71 ## vm.runInContext(code, context, [filename])
73 `vm.runInContext` compiles `code`, then runs it in `context` and returns the
74 result. A (V8) context comprises a global object, together with a set of
75 built-in objects and functions. Running code does not have access to local scope
76 and the global object held within `context` will be used as the global object
78 `filename` is optional, it's used only in stack traces.
80 Example: compile and execute code in a existing context.
82 var util = require('util'),
88 context = vm.createContext(initSandbox);
90 vm.runInContext('count += 1; name = "CATT"', context, 'myfile.vm');
91 console.log(util.inspect(context));
93 // { animal: 'cat', count: 3, name: 'CATT' }
95 Note that `createContext` will perform a shallow clone of the supplied sandbox object in order to
96 initialise the global object of the freshly constructed context.
98 Note that running untrusted code is a tricky business requiring great care. To prevent accidental
99 global variable leakage, `vm.runInContext` is quite useful, but safely running untrusted code
100 requires a separate process.
102 In case of syntax error in `code`, `vm.runInContext` emits the syntax error to stderr
103 and throws an exception.
105 ## vm.createContext([initSandbox])
107 `vm.createContext` creates a new context which is suitable for use as the 2nd argument of a subsequent
108 call to `vm.runInContext`. A (V8) context comprises a global object together with a set of
109 build-in objects and functions. The optional argument `initSandbox` will be shallow-copied
110 to seed the initial contents of the global object used by the context.
112 ## vm.createScript(code, [filename])
114 `createScript` compiles `code` but does not run it. Instead, it returns a
115 `vm.Script` object representing this compiled code. This script can be run
116 later many times using methods below. The returned script is not bound to any
117 global object. It is bound before each run, just for that run. `filename` is
118 optional, it's only used in stack traces.
120 In case of syntax error in `code`, `createScript` prints the syntax error to stderr
121 and throws an exception.
126 A class for running scripts. Returned by vm.createScript.
128 ### script.runInThisContext()
130 Similar to `vm.runInThisContext` but a method of a precompiled `Script` object.
131 `script.runInThisContext` runs the code of `script` and returns the result.
132 Running code does not have access to local scope, but does have access to the `global` object
133 (v8: in actual context).
135 Example of using `script.runInThisContext` to compile code once and run it multiple times:
137 var vm = require('vm');
141 var script = vm.createScript('globalVar += 1', 'myfile.vm');
143 for (var i = 0; i < 1000 ; i += 1) {
144 script.runInThisContext();
147 console.log(globalVar);
152 ### script.runInNewContext([sandbox])
154 Similar to `vm.runInNewContext` a method of a precompiled `Script` object.
155 `script.runInNewContext` runs the code of `script` with `sandbox` as the global object and returns the result.
156 Running code does not have access to local scope. `sandbox` is optional.
158 Example: compile code that increments a global variable and sets one, then execute this code multiple times.
159 These globals are contained in the sandbox.
161 var util = require('util'),
168 var script = vm.createScript('count += 1; name = "kitty"', 'myfile.vm');
170 for (var i = 0; i < 10 ; i += 1) {
171 script.runInNewContext(sandbox);
174 console.log(util.inspect(sandbox));
176 // { animal: 'cat', count: 12, name: 'kitty' }
178 Note that running untrusted code is a tricky business requiring great care. To prevent accidental
179 global variable leakage, `script.runInNewContext` is quite useful, but safely running untrusted code
180 requires a separate process.