Skip to content

Commit

Permalink
doc: improve styling consistency in VM docs
Browse files Browse the repository at this point in the history 
Improve functions styling. Connect sections with links.

PR-URL: #5005
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
  • Loading branch information
@estliberitas @rvagg
estliberitas authored and rvagg committed Feb 8, 2016
1 parent 9824b0d commit ee01371
Showing 1 changed file with 47 additions and 36 deletions.
83 changes: 47 additions & 36 deletions doc/api/vm.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,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.
Expand All @@ -72,18 +74,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
Expand All @@ -107,17 +110,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
Expand Down Expand Up @@ -154,11 +157,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.
Expand All @@ -171,16 +174,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.

Expand All @@ -200,13 +203,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');
Expand All @@ -220,11 +223,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.
Expand All @@ -245,7 +248,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])
Expand All @@ -254,7 +257,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');
Expand All @@ -272,10 +275,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
Expand All @@ -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
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

0 comments on commit ee01371

Please sign in to comment.