doc: improve documentation for the vm module

Add an intro section and example for the vm module.

PR-URL: https://github.com/nodejs/node/pull/16867
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
pull/16876/head
Franziska Hinkelmann 2017-11-07 18:22:23 +01:00 committed by Franziska Hinkelmann
parent f002c3d2ed
commit 5e1e460ac1
1 changed files with 28 additions and 4 deletions

View File

@ -7,14 +7,38 @@
<!--name=vm-->
The `vm` module provides APIs for compiling and running code within V8 Virtual
Machine contexts. It can be accessed using:
Machine contexts.
JavaScript code can be compiled and run immediately or
compiled, saved, and run later.
A common use case is to run the code in a sandboxed environment.
The sandboxed code uses a different V8 Context, meaning that
it has a different global object than the rest of the code.
One can provide the context by ["contextifying"][contextified] a sandbox
object. The sandboxed code treats any property on the sandbox like a
global variable. Any changes on global variables caused by the sandboxed
code are reflected in the sandbox object.
```js
const vm = require('vm');
```
JavaScript code can be compiled and run immediately or compiled, saved, and run
later.
const x = 1;
const sandbox = { x: 2 };
vm.createContext(sandbox); // Contextify the sandbox.
const code = 'x += 40; var y = 17;';
// x and y are global variables in the sandboxed environment.
// Initially, x has the value 2 because that is the value of sandbox.x.
vm.runInContext(code, sandbox);
console.log(sandbox.x); // 42
console.log(sandbox.y); // 17
console.log(x); // 1; y is not defined.
```
*Note*: The vm module is not a security mechanism.
**Do not use it to run untrusted code**.