doc/api/vm.markdown

   1 # Executing JavaScript
   2
   3 <!--name=vm-->
   4
   5 You can access this module with:
   6
   7     var vm = require('vm');
   8
   9 JavaScript code can be compiled and run immediately or compiled, saved, and run later.
  10
  11
  12 ## vm.runInThisContext(code, [filename])
  13
  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
  16 in stack traces.
  17
  18 Example of using `vm.runInThisContext` and `eval` to run the same code:
  19
  20     var localVar = 123,
  21         usingscript, evaled,
  22         vm = require('vm');
  23
  24     usingscript = vm.runInThisContext('localVar = 1;',
  25       'myfile.vm');
  26     console.log('localVar: ' + localVar + ', usingscript: ' +
  27       usingscript);
  28     evaled = eval('localVar = 1;');
  29     console.log('localVar: ' + localVar + ', evaled: ' +
  30       evaled);
  31
  32     // localVar: 123, usingscript: 1
  33     // localVar: 1, evaled: 1
  34
  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.
  37
  38 In case of syntax error in `code`, `vm.runInThisContext` emits the syntax error to stderr
  39 and throws an exception.
  40
  41
  42 ## vm.runInNewContext(code, [sandbox], [filename])
  43
  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.
  48
  49 Example: compile and execute code that increments a global variable and sets a new one.
  50 These globals are contained in the sandbox.
  51
  52     var util = require('util'),
  53         vm = require('vm'),
  54         sandbox = {
  55           animal: 'cat',
  56           count: 2
  57         };
  58
  59     vm.runInNewContext('count += 1; name = "kitty"', sandbox, 'myfile.vm');
  60     console.log(util.inspect(sandbox));
  61
  62     // { animal: 'cat', count: 3, name: 'kitty' }
  63
  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.
  67
  68 In case of syntax error in `code`, `vm.runInNewContext` emits the syntax error to stderr
  69 and throws an exception.
  70
  71 ## vm.runInContext(code, context, [filename])
  72
  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
  77 for `code`.
  78 `filename` is optional, it's used only in stack traces.
  79
  80 Example: compile and execute code in a existing context.
  81
  82     var util = require('util'),
  83         vm = require('vm'),
  84         initSandbox = {
  85           animal: 'cat',
  86           count: 2
  87         },
  88         context = vm.createContext(initSandbox);
  89
  90     vm.runInContext('count += 1; name = "CATT"', context, 'myfile.vm');
  91     console.log(util.inspect(context));
  92
  93     // { animal: 'cat', count: 3, name: 'CATT' }
  94
  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.
  97
  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.
 101
 102 In case of syntax error in `code`, `vm.runInContext` emits the syntax error to stderr
 103 and throws an exception.
 104
 105 ## vm.createContext([initSandbox])
 106
 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.
 111
 112 ## vm.createScript(code, [filename])
 113
 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.
 119
 120 In case of syntax error in `code`, `createScript` prints the syntax error to stderr
 121 and throws an exception.
 122
 123
 124 ## Class: Script
 125
 126 A class for running scripts.  Returned by vm.createScript.
 127
 128 ### script.runInThisContext()
 129
 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).
 134
 135 Example of using `script.runInThisContext` to compile code once and run it multiple times:
 136
 137     var vm = require('vm');
 138
 139     globalVar = 0;
 140
 141     var script = vm.createScript('globalVar += 1', 'myfile.vm');
 142
 143     for (var i = 0; i < 1000 ; i += 1) {
 144       script.runInThisContext();
 145     }
 146
 147     console.log(globalVar);
 148
 149     // 1000
 150
 151
 152 ### script.runInNewContext([sandbox])
 153
 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.
 157
 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.
 160
 161     var util = require('util'),
 162         vm = require('vm'),
 163         sandbox = {
 164           animal: 'cat',
 165           count: 2
 166         };
 167
 168     var script = vm.createScript('count += 1; name = "kitty"', 'myfile.vm');
 169
 170     for (var i = 0; i < 10 ; i += 1) {
 171       script.runInNewContext(sandbox);
 172     }
 173
 174     console.log(util.inspect(sandbox));
 175
 176     // { animal: 'cat', count: 12, name: 'kitty' }
 177
 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.