FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: improve styling consistency in VM docs · nodejs/node@ee01371 · GitHub

/ node Public

Commit ee01371

Browse files
estliberitas
authored and
rvagg
committed
doc: improve styling consistency in VM docs
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>
1 parent 9824b0d commit ee01371

1 file changed

Lines changed: 47 additions & 36 deletions

File tree

‎doc/api/vm.markdown‎

Lines changed: 47 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,13 @@ The options when creating a script are:
4141

4242
### script.runInContext(contextifiedSandbox[, options])
4343

44-
Similar to `vm.runInContext` but a method of a precompiled `Script` object.
45-
`script.runInContext` runs `script`'s compiled code in `contextifiedSandbox`
46-
and returns the result. Running code does not have access to local scope.
44+
Similar to [`vm.runInContext()`][] but a method of a precompiled `Script`
45+
object. `script.runInContext()` runs `script`'s compiled code in
46+
`contextifiedSandbox` and returns the result. Running code does not have access
47+
to local scope.
4748

48-
`script.runInContext` takes the same options as `script.runInThisContext`.
49+
`script.runInContext()` takes the same options as
50+
[`script.runInThisContext()`][].
4951

5052
Example: compile code that increments a global variable and sets one, then
5153
execute the code multiple times. These globals are contained in the sandbox.
@@ -72,18 +74,19 @@ console.log(util.inspect(sandbox));
7274
```
7375

7476
Note that running untrusted code is a tricky business requiring great care.
75-
`script.runInContext` is quite useful, but safely running untrusted code
77+
`script.runInContext()` is quite useful, but safely running untrusted code
7678
requires a separate process.
7779

7880
### script.runInNewContext([sandbox][, options])
7981

80-
Similar to `vm.runInNewContext` but a method of a precompiled `Script` object.
81-
`script.runInNewContext` contextifies `sandbox` if passed or creates a new
82-
contextified sandbox if it's omitted, and then runs `script`'s compiled code
82+
Similar to [`vm.runInNewContext()`][] but a method of a precompiled `Script`
83+
object. `script.runInNewContext()` contextifies `sandbox` if passed or creates a
84+
new contextified sandbox if it's omitted, and then runs `script`'s compiled code
8385
with the sandbox as the global object and returns the result. Running code does
8486
not have access to local scope.
8587

86-
`script.runInNewContext` takes the same options as `script.runInThisContext`.
88+
`script.runInNewContext()` takes the same options as
89+
[`script.runInThisContext()`][].
8790

8891
Example: compile code that sets a global variable, then execute the code
8992
multiple times in different contexts. These globals are set on and contained in
@@ -107,17 +110,17 @@ console.log(util.inspect(sandboxes));
107110
```
108111

109112
Note that running untrusted code is a tricky business requiring great care.
110-
`script.runInNewContext` is quite useful, but safely running untrusted code
113+
`script.runInNewContext()` is quite useful, but safely running untrusted code
111114
requires a separate process.
112115

113116
### script.runInThisContext([options])
114117

115-
Similar to `vm.runInThisContext` but a method of a precompiled `Script` object.
116-
`script.runInThisContext` runs `script`'s compiled code and returns the result.
117-
Running code does not have access to local scope, but does have access to the
118-
current `global` object.
118+
Similar to [`vm.runInThisContext()`]() but a method of a precompiled `Script`
119+
object. `script.runInThisContext()` runs `script`'s compiled code and returns
120+
the result. Running code does not have access to local scope, but does have
121+
access to the current `global` object.
119122

120-
Example of using `script.runInThisContext` to compile code once and run it
123+
Example of using `script.runInThisContext()` to compile code once and run it
121124
multiple times:
122125

123126
```js
@@ -154,11 +157,11 @@ The options for running a script are:
154157
## vm.createContext([sandbox])
155158

156159
If given a `sandbox` object, will "contextify" that sandbox so that it can be
157-
used in calls to `vm.runInContext` or `script.runInContext`. Inside scripts run
158-
as such, `sandbox` will be the global object, retaining all its existing
159-
properties but also having the built-in objects and functions any standard
160-
[global object][] has. Outside of scripts run by the vm module, `sandbox` will
161-
be unchanged.
160+
used in calls to [`vm.runInContext()`][] or [`script.runInContext()`][]. Inside
161+
scripts run as such, `sandbox` will be the global object, retaining all its
162+
existing properties but also having the built-in objects and functions any
163+
standard [global object][] has. Outside of scripts run by the vm module,
164+
`sandbox` will be unchanged.
162165

163166
If not given a sandbox object, returns a new, empty contextified sandbox object
164167
you can use.
@@ -171,16 +174,16 @@ tags together inside that sandbox.
171174
## vm.isContext(sandbox)
172175

173176
Returns whether or not a sandbox object has been contextified by calling
174-
`vm.createContext` on it.
177+
[`vm.createContext()`][] on it.
175178

176179
## vm.runInContext(code, contextifiedSandbox[, options])
177180

178-
`vm.runInContext` compiles `code`, then runs it in `contextifiedSandbox` and
181+
`vm.runInContext()` compiles `code`, then runs it in `contextifiedSandbox` and
179182
returns the result. Running code does not have access to local scope. The
180183
`contextifiedSandbox` object must have been previously contextified via
181-
`vm.createContext`; it will be used as the global object for `code`.
184+
[`vm.createContext()`][]; it will be used as the global object for `code`.
182185

183-
`vm.runInContext` takes the same options as `vm.runInThisContext`.
186+
`vm.runInContext()` takes the same options as [`vm.runInThisContext()`][].
184187

185188
Example: compile and execute different scripts in a single existing context.
186189

@@ -200,13 +203,13 @@ console.log(util.inspect(sandbox));
200203
```
201204

202205
Note that running untrusted code is a tricky business requiring great care.
203-
`vm.runInContext` is quite useful, but safely running untrusted code requires a
204-
separate process.
206+
`vm.runInContext()` is quite useful, but safely running untrusted code requires
207+
a separate process.
205208

206209
## vm.runInDebugContext(code)
207210

208-
`vm.runInDebugContext` compiles and executes `code` inside the V8 debug context.
209-
The primary use case is to get access to the V8 debug object:
211+
`vm.runInDebugContext()` compiles and executes `code` inside the V8 debug
212+
context. The primary use case is to get access to the V8 debug object:
210213

211214
```js
212215
const Debug = vm.runInDebugContext('Debug');
@@ -220,11 +223,11 @@ The debug object can also be exposed with the `--expose_debug_as=` switch.
220223

221224
## vm.runInNewContext(code[, sandbox][, options])
222225

223-
`vm.runInNewContext` compiles `code`, contextifies `sandbox` if passed or
226+
`vm.runInNewContext()` compiles `code`, contextifies `sandbox` if passed or
224227
creates a new contextified sandbox if it's omitted, and then runs the code with
225228
the sandbox as the global object and returns the result.
226229

227-
`vm.runInNewContext` takes the same options as `vm.runInThisContext`.
230+
`vm.runInNewContext()` takes the same options as [`vm.runInThisContext()`][].
228231

229232
Example: compile and execute code that increments a global variable and sets a
230233
new one. These globals are contained in the sandbox.
@@ -245,7 +248,7 @@ console.log(util.inspect(sandbox));
245248
```
246249

247250
Note that running untrusted code is a tricky business requiring great care.
248-
`vm.runInNewContext` is quite useful, but safely running untrusted code requires
251+
`vm.runInNewContext()` is quite useful, but safely running untrusted code requires
249252
a separate process.
250253

251254
## vm.runInThisContext(code[, options])
@@ -254,7 +257,7 @@ a separate process.
254257
code does not have access to local scope, but does have access to the current
255258
`global` object.
256259

257-
Example of using `vm.runInThisContext` and `eval` to run the same code:
260+
Example of using `vm.runInThisContext()` and [`eval()`][] to run the same code:
258261

259262
```js
260263
const vm = require('vm');
@@ -272,10 +275,11 @@ console.log('localVar: ', localVar);
272275
// evalResult: 'eval', localVar: 'eval'
273276
```
274277

275-
`vm.runInThisContext` does not have access to the local scope, so `localVar` is
276-
unchanged. `eval` does have access to the local scope, so `localVar` is changed.
278+
`vm.runInThisContext()` does not have access to the local scope, so `localVar`
279+
is unchanged. [`eval()`][] does have access to the local scope, so `localVar` is
280+
changed.
277281

278-
In this way `vm.runInThisContext` is much like an [indirect `eval` call][],
282+
In this way `vm.runInThisContext()` is much like an [indirect `eval()` call][],
279283
e.g. `(0,eval)('code')`. However, it also has the following additional options:
280284

281285
- `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:
291295
- `timeout`: a number of milliseconds to execute `code` before terminating
292296
execution. If execution is terminated, an [`Error`][] will be thrown.
293297

294-
[indirect `eval` call]: https://es5.github.io/#x10.4.2
298+
[indirect `eval()` call]: https://es5.github.io/#x10.4.2
295299
[global object]: https://es5.github.io/#x15.1
296300
[`Error`]: errors.html#errors_class_error
301+
[`script.runInContext()`]: #vm_script_runincontext_contextifiedsandbox_options
302+
[`script.runInThisContext()`]: #vm_script_runinthiscontext_options
303+
[`vm.createContext()`]: #vm_vm_createcontext_sandbox
304+
[`vm.runInContext()`]: #vm_vm_runincontext_code_contextifiedsandbox_options
305+
[`vm.runInNewContext()`]: #vm_vm_runinnewcontext_code_sandbox_options
306+
[`vm.runInThisContext()`]: #vm_vm_runinthiscontext_code_options
307+
[`eval()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL