From 12a3d0120b6ec48cf21a39cb77e77e4ded04f7e6 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 17 May 2016 21:56:01 -0700 Subject: [PATCH] doc: improve vm.md copy General improvements to vm module documentation PR-URL: https://github.com/nodejs/node/pull/6827 Reviewed-By: Ben Noordhuis --- doc/api/vm.md | 397 +++++++++++++++++++++++++++++--------------------- 1 file changed, 234 insertions(+), 163 deletions(-) diff --git a/doc/api/vm.md b/doc/api/vm.md index b212cc6e29327f..8de2775dccb802 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -4,7 +4,8 @@ -You can access this module with: +The `vm` module provides APIs for compiling and running code within V8 Virtual +Machine contexts. It can be accessed using: ```js const vm = require('vm'); @@ -13,66 +14,81 @@ const vm = require('vm'); JavaScript code can be compiled and run immediately or compiled, saved, and run later. -## Class: Script +## Class: vm.Script -A class for holding precompiled scripts, and running them in specific sandboxes. +Instances of the `vm.Script` class contain precompiled scripts that can be +executed in specific sandboxes (or "contexts"). ### new vm.Script(code, options) -Creating a new `Script` compiles `code` but does not run it. Instead, the -created `vm.Script` object represents 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. - -The options when creating a script are: - -- `filename`: allows you to control the filename that shows up in any stack - traces produced from this script. -- `lineOffset`: allows you to add an offset to the line number that is - displayed in stack traces -- `columnOffset`: allows you to add an offset to the column number that is - displayed in stack traces -- `displayErrors`: if `true`, on error, attach the line of code that caused - the error to the stack trace. Applies only to syntax errors compiling the - code; errors while running the code are controlled by the options to the - script's methods. -- `timeout`: a number of milliseconds to execute `code` before terminating - execution. If execution is terminated, an [`Error`][] will be thrown. -- `cachedData`: an optional `Buffer` with V8's code cache data for the supplied - source. When supplied `cachedDataRejected` value will be set to either - `true` or `false` depending on acceptance of the data by V8. -- `produceCachedData`: if `true` and no `cachedData` is present - V8 tries to - produce code cache data for `code`. Upon success, a `Buffer` with V8's code - cache data will be produced and stored in `cachedData` property of the - returned `vm.Script` instance. `cachedDataProduced` value will be set to - either `true` or `false` depending on whether code cache data is produced - successfully. +* `code` {string} The JavaScript code to compile. +* `options` + * `filename` {string} Specifies the filename used in stack traces produced + by this script. + * `lineOffset` {number} Specifies the line number offset that is displayed + in stack traces produced by this script. + * `columnOffset` {number} Specifies the column number offset that is displayed + in stack traces produced by this script. + * `displayErrors` {boolean} When `true`, if an [`Error`][] error occurs + while compiling the `code`, the line of code causing the error is attached + to the stack trace. + * `timeout` {number} Specifies the number of milliseconds to execute `code` + before terminating execution. If execution is terminated, an [`Error`][] + will be thrown. + * `cachedData` {Buffer} Provides an optional `Buffer` with V8's code cache + data for the supplied source. When supplied, the `cachedDataRejected` value + will be set to either `true` or `false` depending on acceptance of the data + by V8. + * `produceCachedData` {boolean} When `true` and no `cachedData` is present, V8 + will attempt to produce code cache data for `code`. Upon success, a + `Buffer` with V8's code cache data will be produced and stored in the + `cachedData` property of the returned `vm.Script` instance. + The `cachedDataProduced` value will be set to either `true` or `false` + depending on whether code cache data is produced successfully. + +Creating a new `vm.Script` object compiles `code` but does not run it. The +compiled `vm.Script` can be run later multiple times. It is important to note +that the `code` is not bound to any global object; rather, it is bound before +each run, just for that run. ### script.runInContext(contextifiedSandbox[, options]) -Similar to [`vm.runInContext()`][] but a method of a precompiled `Script` -object. `script.runInContext()` runs `script`'s compiled code in +* `contextifiedSandbox` {Object} A [contextified][] object as returned by the + `vm.createContext()` method. +* `options` {Object} + * `filename` {string} Specifies the filename used in stack traces produced + by this script. + * `lineOffset` {number} Specifies the line number offset that is displayed + in stack traces produced by this script. + * `columnOffset` {number} Specifies the column number offset that is displayed + in stack traces produced by this script. + * `displayErrors` {boolean} When `true`, if an [`Error`][] error occurs + while compiling the `code`, the line of code causing the error is attached + to the stack trace. + * `timeout` {number} Specifies the number of milliseconds to execute `code` + before terminating execution. If execution is terminated, an [`Error`][] + will be thrown. + +Runs the compiled code contained by the `vm.Script` object within the given `contextifiedSandbox` and returns the result. Running code does not have access to local scope. -`script.runInContext()` takes the same options as -[`script.runInThisContext()`][]. - -Example: compile code that increments a global variable and sets one, then -execute the code multiple times. These globals are contained in the sandbox. +The following example compiles code that increments a global variable, sets +the value of another global variable, then execute the code multiple times. +The globals are contained in the `sandbox` object. ```js const util = require('util'); const vm = require('vm'); -var sandbox = { +const sandbox = { animal: 'cat', count: 2 }; -var context = new vm.createContext(sandbox); -var script = new vm.Script('count += 1; name = "kitty"'); +const script = new vm.Script('count += 1; name = "kitty";'); +const context = new vm.createContext(sandbox); for (var i = 0; i < 10; ++i) { script.runInContext(context); } @@ -82,33 +98,39 @@ console.log(util.inspect(sandbox)); // { animal: 'cat', count: 12, name: 'kitty' } ``` -Note that running untrusted code is a tricky business requiring great care. -`script.runInContext()` is quite useful, but safely running untrusted code -requires a separate process. - ### script.runInNewContext([sandbox][, options]) -Similar to [`vm.runInNewContext()`][] but a method of a precompiled `Script` -object. `script.runInNewContext()` contextifies `sandbox` if passed or creates a -new contextified sandbox if it's omitted, and then runs `script`'s compiled code -with the sandbox as the global object and returns the result. Running code does -not have access to local scope. - -`script.runInNewContext()` takes the same options as -[`script.runInThisContext()`][]. - -Example: compile code that sets a global variable, then execute the code -multiple times in different contexts. These globals are set on and contained in -the sandboxes. +* `sandbox` {Object} An object that will be [contextified][]. If `undefined`, a + new object will be created. +* `options` {Object} + * `filename` {string} Specifies the filename used in stack traces produced + by this script. + * `lineOffset` {number} Specifies the line number offset that is displayed + in stack traces produced by this script. + * `columnOffset` {number} Specifies the column number offset that is displayed + in stack traces produced by this script. + * `displayErrors` {boolean} When `true`, if an [`Error`][] error occurs + while compiling the `code`, the line of code causing the error is attached + to the stack trace. + * `timeout` {number} Specifies the number of milliseconds to execute `code` + before terminating execution. If execution is terminated, an [`Error`][] + will be thrown. + +First contextifies the given `sandbox`, runs the compiled code contained by +the `vm.Script` object within the created sandbox, and returns the result. +Running code does not have access to local scope. + +The following example compiles code that sets a global variable, then executes +the code multiple times in different contexts. The globals are set on and +contained within each individual `sandbox`. ```js const util = require('util'); const vm = require('vm'); -const sandboxes = [{}, {}, {}]; - const script = new vm.Script('globalVar = "set"'); +const sandboxes = [{}, {}, {}]; sandboxes.forEach((sandbox) => { script.runInNewContext(sandbox); }); @@ -118,19 +140,28 @@ console.log(util.inspect(sandboxes)); // [{ globalVar: 'set' }, { globalVar: 'set' }, { globalVar: 'set' }] ``` -Note that running untrusted code is a tricky business requiring great care. -`script.runInNewContext()` is quite useful, but safely running untrusted code -requires a separate process. - ### script.runInThisContext([options]) -Similar to [`vm.runInThisContext()`][] but a method of a precompiled `Script` -object. `script.runInThisContext()` runs `script`'s compiled code and returns -the result. Running code does not have access to local scope, but does have -access to the current `global` object. - -Example of using `script.runInThisContext()` to compile code once and run it -multiple times: +* `options` {Object} + * `filename` {string} Specifies the filename used in stack traces produced + by this script. + * `lineOffset` {number} Specifies the line number offset that is displayed + in stack traces produced by this script. + * `columnOffset` {number} Specifies the column number offset that is displayed + in stack traces produced by this script. + * `displayErrors` {boolean} When `true`, if an [`Error`][] error occurs + while compiling the `code`, the line of code causing the error is attached + to the stack trace. + * `timeout` {number} Specifies the number of milliseconds to execute `code` + before terminating execution. If execution is terminated, an [`Error`][] + will be thrown. + +Runs the compiled code contained by the `vm.Script` within the context of the +current `global` object. Running code does not have access to local scope, but +*does* have access to the current `global` object. + +The following example compiles code that increments a `global` variable then +executes that code multiple times: ```js const vm = require('vm'); @@ -148,53 +179,60 @@ console.log(globalVar); // 1000 ``` -The options for running a script are: - -- `filename`: allows you to control the filename that shows up in any stack - traces produced. -- `lineOffset`: allows you to add an offset to the line number that is - displayed in stack traces -- `columnOffset`: allows you to add an offset to the column number that is - displayed in stack traces -- `displayErrors`: if `true`, on error, attach the line of code that caused - the error to the stack trace. Applies only to runtime errors executing the - code; it is impossible to create a `Script` instance with syntax errors, as - the constructor will throw. -- `timeout`: a number of milliseconds to execute the script before terminating - execution. If execution is terminated, an [`Error`][] will be thrown. - ## vm.createContext([sandbox]) -If given a `sandbox` object, will "contextify" that sandbox so that it can be +* `sandbox` {Object} + +If given a `sandbox` object, the `vm.createContext()` method will [prepare +that sandbox][#vm_what_does_it_mean_to_contextify_an_object] so that it can be used in calls to [`vm.runInContext()`][] or [`script.runInContext()`][]. Inside -scripts run as such, `sandbox` will be the global object, retaining all its -existing properties but also having the built-in objects and functions any +such scripts, the `sandbox` object will be the global object, retaining all of +its existing properties but also having the built-in objects and functions any standard [global object][] has. Outside of scripts run by the vm module, -`sandbox` will be unchanged. +`sandbox` will remain unchanged. -If not given a sandbox object, returns a new, empty contextified sandbox object -you can use. +If `sandbox` is omitted (or passed explicitly as `undefined`), a new, empty +[contextified][] sandbox object will be returned. -This function is useful for creating a sandbox that can be used to run multiple -scripts, e.g. if you were emulating a web browser it could be used to create a -single sandbox representing a window's global object, then run all `