Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Docs for Script class of 'evals' binding.

  • Loading branch information...
commit 8daa1f8d04bca8464a3192cad202980509096503 1 parent 4ff45c2
@herby herby authored ry committed
Showing with 125 additions and 22 deletions.
  1. +125 −22 doc/api.markdown
View
147 doc/api.markdown
@@ -490,7 +490,9 @@ Example of using `process.compile` and `eval` to run the same code:
`process.compile` does not have access to the local scope, so `localVar` is unchanged.
`eval` does have access to the local scope, so `localVar` is changed.
-See also: `process.evalcx`
+In case of syntax error in `code`, `process.compile` exits node.
+
+See also: `Script`
### process.cwd()
@@ -506,27 +508,6 @@ An object containing the user environment. See environ(7).
-### process.evalcx(code, sandbox, filename)
-
-Similar to `eval` and `process.compile`. `process.evalcx` compiles `code` to run in `sandbox`
-as if it were loaded from `filename`. The object `sandbox` will be used as the global object for
-`code`. `sandbox` and `filename` are optional.
-
- var sys = require('sys'),
- sandbox = {
- animal: 'cat',
- count: 2
- };
-
- process.evalcx('count += 1; name = 'kitty'', sandbox, 'myfile.js');
- sys.puts(sys.inspect(sandbox));
-
-Note that running untrusted code is a tricky business requiring great care. To prevent accidental
-global variable leakage, `process.evalcx` is quite useful, but to safely run untrusted code, many more steps
-must be taken.
-
-
-
### process.exit(code)
Ends the process with the specified `code`. If omitted, exit uses the
@@ -944,6 +925,128 @@ the child process is killed.
+## Script
+
+`Script` class provides with compiling, remembering and running pieces of Javascript code. You can get `Script` class by issuing
+
+ var Script = process.binding('evals').Script;
+
+
+
+### Script.runInThisContext(code, filename='evalmachine.< anonymous >')
+
+Similar to `process.compile`. `Script.runInThisContext` compiles `code` as if it were loaded from `filename`,
+runs it and returns the result. Running code does not have access to local scope. `filename` is optional.
+
+Example of using `Script.runInThisContext` and `eval` to run the same code:
+
+ var sys = require('sys'),
+ localVar = 123,
+ usingscript, evaled;
+
+ usingscript = Script.runInThisContext('localVar = 1;', 'myfile.js');
+ sys.puts('localVar: ' + localVar + ', usingscript: ' + usingscript);
+ evaled = eval('localVar = 1;');
+ sys.puts('localVar: ' + localVar + ', evaled: ' + evaled);
+
+ // localVar: 123, usingscript: 1
+ // localVar: 1, evaled: 1
+
+`Script.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 case of syntax error in `code`, `Script.runInThisContext` emits the syntax error to stderr
+and throws.an exception.
+
+
+
+### Script.runInNewContext(code, sandbox={}, filename='evalmachine.< anonymous >')
+
+`Script.runInNewContext` compiles `code` to run in `sandbox` as if it were loaded from `filename`,
+then runs it and returns the result. Running code does not have access to local scope and
+the object `sandbox` will be used as the global object for `code`.
+`sandbox` and `filename` are optional.
+
+ var sys = require('sys'),
+ sandbox = {
+ animal: 'cat',
+ count: 2
+ };
+
+ Script.runInNewContext('count += 1; name = 'kitty'', sandbox, 'myfile.js');
+ sys.puts(sys.inspect(sandbox));
+
+Note that running untrusted code is a tricky business requiring great care. To prevent accidental
+global variable leakage, `Script.runInNewContext` is quite useful, but to safely run untrusted code, many more steps
+must be taken.
+
+In case of syntax error in `code`, `Script.runInThisContext` emits the syntax error to stderr
+and throws.an exception.
+
+
+
+### new Script(code, filename='evalmachine.< anonymous >')
+
+`new Script` compiles `code` as if it were loaded from `filename`,
+but does not run it. Instead, it returns Script object representing this compiled code.
+This script can be run later many times using methods below.
+The returned script is not bound to any global object,
+it is bound before each run, just for that run. `filename` is optional.
+
+In case of syntax error in `code`, `new Script` emits the syntax error to stderr
+and throws.an exception.
+
+
+
+### script.runInThisContext()
+
+Similar to "static" version in `Script.runInThisContext`, but now being a method of precompiled Script object.
+`script.runInThisContext` runs the code of `script` and returns the result. Running code does not have access to local scope
+and is run for actual `global` object (v8: in actual context).
+
+Example of using `script.runInThisContext` and `eval` to run the same code:
+
+ var sys = require('sys'),
+ localVar = 123,
+ script, usingscript, evaled;
+
+ script = new Script('localVar = 1', 'myfile.js');
+ usingscript = script.runInThisContext();
+ sys.puts('localVar: ' + localVar + ', usingscript: ' + usingscript);
+ evaled = eval('localVar = 1;');
+ sys.puts('localVar: ' + localVar + ', evaled: ' + evaled);
+
+ // localVar: 123, usingscript: 1
+ // localVar: 1, evaled: 1
+
+`script.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.
+
+
+
+### script.runInNewContext(sandbox={})
+
+Similar to "static" version in `Script.runInNewContext`, but now being a method of precompiled Script object.
+`script.runInNewContext` runs the code of `script` in a `sandbox` and returns the result.
+Running code does not have access to local scope and the object `sandbox` will be used as the global object for the code.
+`sandbox`is optional.
+
+ var sys = require('sys'),
+ script = new Script('count += 1; name = 'kitty'', 'myfile.js'),
+ sandbox = {
+ animal: 'cat',
+ count: 2
+ };
+
+ script.runInNewContext(sandbox);
+ sys.puts(sys.inspect(sandbox));
+
+Note that running untrusted code is a tricky business requiring great care. To prevent accidental
+global variable leakage, `Script.runInNewContext` is quite useful, but to safely run untrusted code, many more steps
+must be taken.
+
+
+
## File System
File I/O is provided by simple wrappers around standard POSIX functions. To
Please sign in to comment.
Something went wrong with that request. Please try again.