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>
process-exit-stdio-flushing
Alexander Makarenko 9 years ago
committed by James M Snell
parent
d74eb5fe01
commit
0c924ea39f
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
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 83
      doc/api/vm.markdown

83
doc/api/vm.markdown
View File

@ -47,11 +47,13 @@ The options when creating a script are:
### 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`
and returns the result. Running code does not have access to local scope.
Similar to [`vm.runInContext()`][] but a method of a precompiled `Script`
object. `script.runInContext()` runs `script`'s compiled code in
`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
execute the code multiple times. These globals are contained in the sandbox.
@ -78,18 +80,19 @@ console.log(util.inspect(sandbox));
```
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.
### 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
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`.
`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
@ -113,17 +116,17 @@ console.log(util.inspect(sandboxes));
```
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.
### 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.
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
Example of using `script.runInThisContext()` to compile code once and run it
multiple times:
```js
@ -160,11 +163,11 @@ The options for running a script are:
## vm.createContext([sandbox])
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
as such, `sandbox` will be the global object, retaining all 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.
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
standard [global object][] has. Outside of scripts run by the vm module,
`sandbox` will be unchanged.
If not given a sandbox object, returns a new, empty contextified sandbox object
you can use.
@ -177,16 +180,16 @@ tags together inside that sandbox.
## vm.isContext(sandbox)
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` 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
`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.
@ -206,13 +209,13 @@ console.log(util.inspect(sandbox));
```
Note that running untrusted code is a tricky business requiring great care.
`vm.runInContext` is quite useful, but safely running untrusted code requires a
separate process.
`vm.runInContext()` is quite useful, but safely running untrusted code requires
a separate process.
## vm.runInDebugContext(code)
`vm.runInDebugContext` compiles and executes `code` inside the V8 debug context.
The primary use case is to get access to the V8 debug object:
`vm.runInDebugContext()` compiles and executes `code` inside the V8 debug
context. The primary use case is to get access to the V8 debug object:
```js
const Debug = vm.runInDebugContext('Debug');
@ -226,11 +229,11 @@ The debug object can also be exposed with the `--expose_debug_as=` switch.
## 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
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
new one. These globals are contained in the sandbox.
@ -251,7 +254,7 @@ console.log(util.inspect(sandbox));
```
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.
## vm.runInThisContext(code[, options])
@ -260,7 +263,7 @@ a separate process.
code does not have access to local scope, but does have access to the current
`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
const vm = require('vm');
@ -278,10 +281,11 @@ console.log('localVar: ', localVar);
// evalResult: 'eval', localVar: 'eval'
```
`vm.runInThisContext` does not have access to the local scope, so `localVar` is
unchanged. `eval` does have access to the local scope, so `localVar` is changed.
`vm.runInThisContext()` does not have access to the local scope, so `localVar`
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:
- `filename`: allows you to control the filename that shows up in any stack
@ -297,6 +301,13 @@ e.g. `(0,eval)('code')`. However, it also has the following additional options:
- `timeout`: a number of milliseconds to execute `code` before terminating
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
[`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