lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc: improve styling consistency in VM docs 

Improve functions styling. Connect sections with links.

PR-URL: https://github.com/nodejs/node/pull/5005
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
v5.x
Alexander Makarenko 9 years ago
committed by Rod Vagg
parent
9824b0d132
commit
ee013715b9
1 changed files with 47 additions and 36 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 83
      doc/api/vm.markdown

83
doc/api/vm.markdown
View File

@ -41,11 +41,13 @@ The options when creating a script are:
### script.runInContext(contextifiedSandbox[, options]) ### script.runInContext(contextifiedSandbox[, options])
Similar to `vm.runInContext` but a method of a precompiled `Script` object. Similar to [`vm.runInContext()`][] but a method of a precompiled `Script`
`script.runInContext` runs `script`'s compiled code in `contextifiedSandbox` object. `script.runInContext()` runs `script`'s compiled code in
and returns the result. Running code does not have access to local scope. `contextifiedSandbox` and returns the result. Running code does not have access
to local scope.
`script.runInContext` takes the same options as `script.runInThisContext`. `script.runInContext()` takes the same options as
[`script.runInThisContext()`][].
Example: compile code that increments a global variable and sets one, then Example: compile code that increments a global variable and sets one, then
execute the code multiple times. These globals are contained in the sandbox. execute the code multiple times. These globals are contained in the sandbox.
@ -72,18 +74,19 @@ console.log(util.inspect(sandbox));
``` ```
Note that running untrusted code is a tricky business requiring great care. Note that running untrusted code is a tricky business requiring great care.
`script.runInContext` is quite useful, but safely running untrusted code `script.runInContext()` is quite useful, but safely running untrusted code
requires a separate process. requires a separate process.
### script.runInNewContext([sandbox][, options]) ### script.runInNewContext([sandbox][, options])
Similar to `vm.runInNewContext` but a method of a precompiled `Script` object. Similar to [`vm.runInNewContext()`][] but a method of a precompiled `Script`
`script.runInNewContext` contextifies `sandbox` if passed or creates a new object. `script.runInNewContext()` contextifies `sandbox` if passed or creates a
contextified sandbox if it's omitted, and then runs `script`'s compiled code 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 with the sandbox as the global object and returns the result. Running code does
not have access to local scope. not have access to local scope.
`script.runInNewContext` takes the same options as `script.runInThisContext`. `script.runInNewContext()` takes the same options as
[`script.runInThisContext()`][].
Example: compile code that sets a global variable, then execute the code 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 multiple times in different contexts. These globals are set on and contained in
@ -107,17 +110,17 @@ console.log(util.inspect(sandboxes));
``` ```
Note that running untrusted code is a tricky business requiring great care. Note that running untrusted code is a tricky business requiring great care.
`script.runInNewContext` is quite useful, but safely running untrusted code `script.runInNewContext()` is quite useful, but safely running untrusted code
requires a separate process. requires a separate process.
### script.runInThisContext([options]) ### script.runInThisContext([options])
Similar to `vm.runInThisContext` but a method of a precompiled `Script` object. Similar to [`vm.runInThisContext()`]() but a method of a precompiled `Script`
`script.runInThisContext` runs `script`'s compiled code and returns the result. object. `script.runInThisContext()` runs `script`'s compiled code and returns
Running code does not have access to local scope, but does have access to the the result. Running code does not have access to local scope, but does have
current `global` object. access to the current `global` object.
Example of using `script.runInThisContext` to compile code once and run it Example of using `script.runInThisContext()` to compile code once and run it
multiple times: multiple times:
```js ```js
@ -154,11 +157,11 @@ The options for running a script are:
## vm.createContext([sandbox]) ## vm.createContext([sandbox])
If given a `sandbox` object, will "contextify" that sandbox so that it can be If given a `sandbox` object, will "contextify" that sandbox so that it can be
used in calls to `vm.runInContext` or `script.runInContext`. Inside scripts run used in calls to [`vm.runInContext()`][] or [`script.runInContext()`][]. Inside
as such, `sandbox` will be the global object, retaining all its existing scripts run as such, `sandbox` will be the global object, retaining all its
properties but also having the built-in objects and functions any standard existing properties but also having the built-in objects and functions any
[global object][] has. Outside of scripts run by the vm module, `sandbox` will standard [global object][] has. Outside of scripts run by the vm module,
be unchanged. `sandbox` will be unchanged.
If not given a sandbox object, returns a new, empty contextified sandbox object If not given a sandbox object, returns a new, empty contextified sandbox object
you can use. you can use.
@ -171,16 +174,16 @@ tags together inside that sandbox.
## vm.isContext(sandbox) ## vm.isContext(sandbox)
Returns whether or not a sandbox object has been contextified by calling Returns whether or not a sandbox object has been contextified by calling
`vm.createContext` on it. [`vm.createContext()`][] on it.
## vm.runInContext(code, contextifiedSandbox[, options]) ## vm.runInContext(code, contextifiedSandbox[, options])
`vm.runInContext` compiles `code`, then runs it in `contextifiedSandbox` and `vm.runInContext()` compiles `code`, then runs it in `contextifiedSandbox` and
returns the result. Running code does not have access to local scope. The returns the result. Running code does not have access to local scope. The
`contextifiedSandbox` object must have been previously contextified via `contextifiedSandbox` object must have been previously contextified via
`vm.createContext`; it will be used as the global object for `code`. [`vm.createContext()`][]; it will be used as the global object for `code`.
`vm.runInContext` takes the same options as `vm.runInThisContext`. `vm.runInContext()` takes the same options as [`vm.runInThisContext()`][].
Example: compile and execute different scripts in a single existing context. Example: compile and execute different scripts in a single existing context.
@ -200,13 +203,13 @@ console.log(util.inspect(sandbox));
``` ```
Note that running untrusted code is a tricky business requiring great care. Note that running untrusted code is a tricky business requiring great care.
`vm.runInContext` is quite useful, but safely running untrusted code requires a `vm.runInContext()` is quite useful, but safely running untrusted code requires
separate process. a separate process.
## vm.runInDebugContext(code) ## vm.runInDebugContext(code)
`vm.runInDebugContext` compiles and executes `code` inside the V8 debug context. `vm.runInDebugContext()` compiles and executes `code` inside the V8 debug
The primary use case is to get access to the V8 debug object: context. The primary use case is to get access to the V8 debug object:
```js ```js
const Debug = vm.runInDebugContext('Debug'); const Debug = vm.runInDebugContext('Debug');
@ -220,11 +223,11 @@ The debug object can also be exposed with the `--expose_debug_as=` switch.
## vm.runInNewContext(code[, sandbox][, options]) ## vm.runInNewContext(code[, sandbox][, options])
`vm.runInNewContext` compiles `code`, contextifies `sandbox` if passed or `vm.runInNewContext()` compiles `code`, contextifies `sandbox` if passed or
creates a new contextified sandbox if it's omitted, and then runs the code with creates a new contextified sandbox if it's omitted, and then runs the code with
the sandbox as the global object and returns the result. the sandbox as the global object and returns the result.
`vm.runInNewContext` takes the same options as `vm.runInThisContext`. `vm.runInNewContext()` takes the same options as [`vm.runInThisContext()`][].
Example: compile and execute code that increments a global variable and sets a Example: compile and execute code that increments a global variable and sets a
new one. These globals are contained in the sandbox. new one. These globals are contained in the sandbox.
@ -245,7 +248,7 @@ console.log(util.inspect(sandbox));
``` ```
Note that running untrusted code is a tricky business requiring great care. Note that running untrusted code is a tricky business requiring great care.
`vm.runInNewContext` is quite useful, but safely running untrusted code requires `vm.runInNewContext()` is quite useful, but safely running untrusted code requires
a separate process. a separate process.
## vm.runInThisContext(code[, options]) ## vm.runInThisContext(code[, options])
@ -254,7 +257,7 @@ a separate process.
code does not have access to local scope, but does have access to the current code does not have access to local scope, but does have access to the current
`global` object. `global` object.
Example of using `vm.runInThisContext` and `eval` to run the same code: Example of using `vm.runInThisContext()` and [`eval()`][] to run the same code:
```js ```js
const vm = require('vm'); const vm = require('vm');
@ -272,10 +275,11 @@ console.log('localVar: ', localVar);
// evalResult: 'eval', localVar: 'eval' // evalResult: 'eval', localVar: 'eval'
``` ```
`vm.runInThisContext` does not have access to the local scope, so `localVar` is `vm.runInThisContext()` does not have access to the local scope, so `localVar`
unchanged. `eval` does have access to the local scope, so `localVar` is changed. is unchanged. [`eval()`][] does have access to the local scope, so `localVar` is
changed.
In this way `vm.runInThisContext` is much like an [indirect `eval` call][], In this way `vm.runInThisContext()` is much like an [indirect `eval()` call][],
e.g. `(0,eval)('code')`. However, it also has the following additional options: e.g. `(0,eval)('code')`. However, it also has the following additional options:
- `filename`: allows you to control the filename that shows up in any stack - `filename`: allows you to control the filename that shows up in any stack
@ -291,6 +295,13 @@ e.g. `(0,eval)('code')`. However, it also has the following additional options:
- `timeout`: a number of milliseconds to execute `code` before terminating - `timeout`: a number of milliseconds to execute `code` before terminating
execution. If execution is terminated, an [`Error`][] will be thrown. execution. If execution is terminated, an [`Error`][] will be thrown.
[indirect `eval` call]: https://es5.github.io/#x10.4.2 [indirect `eval()` call]: https://es5.github.io/#x10.4.2
[global object]: https://es5.github.io/#x15.1 [global object]: https://es5.github.io/#x15.1
[`Error`]: errors.html#errors_class_error [`Error`]: errors.html#errors_class_error
[`script.runInContext()`]: #vm_script_runincontext_contextifiedsandbox_options
[`script.runInThisContext()`]: #vm_script_runinthiscontext_options
[`vm.createContext()`]: #vm_vm_createcontext_sandbox
[`vm.runInContext()`]: #vm_vm_runincontext_code_contextifiedsandbox_options
[`vm.runInNewContext()`]: #vm_vm_runinnewcontext_code_sandbox_options
[`vm.runInThisContext()`]: #vm_vm_runinthiscontext_code_options
[`eval()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval

Write Preview
Loading…
Cancel
Save