JS-Interpreter/docs.html at master · tomasescobar/JS-Interpreter · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>JS-Interpreter Documentation</title>
  <style>
    body {
      background-color: #fff;
      font-family: sans-serif;
    }
    a:hover {
      color: red
    }
    h1, h2, h3 {
      font-weight: normal;
    }
  </style>
</head>
<body>
  <h1>JS-Interpreter Documentation</h1>
  <p>JS-Interpreter is a sandboxed JavaScript interpreter written in JavaScript.
  It allows for execution of arbitrary JavaScript code line by line.  Execution
  is completely isolated from the main JavaScript environment.  Multiple
  instances of the JS-Interpreter allow for multi-threaded concurrent JavaScript
  without the use of Web Workers.</p>

  <p>Play with the <a href="index.html">JS-Interpreter demo</a>.</p>
  <p>Get the <a href="https://github.com/NeilFraser/JS-Interpreter">source code</a>.</p>

  <h2>Usage</h2>
  <p>Start by including the two JavaScript source files:</p>
  <pre>
    &lt;script src="acorn.js"&gt;&lt;/script&gt;
    &lt;script src="interpreter.js"&gt;&lt;/script&gt;
  </pre>
  <p>Alternatively, use the compressed bundle (58kb):</p>
  <pre>
    &lt;script src="acorn_interpreter.js"&gt;&lt;/script&gt;
  </pre>
  <p>Next, instantiate an interpreter with the JavaScript code that needs to be
  parsed:</p>
  <pre>
    var myCode = 'var a=1; for(var i=0;i&lt;4;i++){a*=i;} a;';
    var myInterpreter = new Interpreter(myCode);
  </pre>
  <p>To run the code step by step, call the <code>step</code> function
  repeatedly until it returns false:</p>
  <pre>
    function nextStep() {
      if (myInterpreter.step()) {
        window.setTimeout(nextStep, 0);
      }
    }
    nextStep();
  </pre>
  <p>Alternatively, if the code is known to be safe from infinite loops, it may
  be executed to completion by calling the <code>run</code> function once:</p>
  <pre>
    myInterpreter.run();
  </pre>

  <h2>External API</h2>
  <p>Similar to the <code>eval</code> function, the result of the last
  statement executed is available in <code>myInterpreter.value</code>:</p>
  <pre>
    var myInterpreter = new Interpreter('6 * 7');
    myInterpreter.run();
    alert(myInterpreter.value);
  </pre>

  <p>Additionally, API calls may be added to the interpreter during creation.
  Here is the addition of <code>alert()</code> and a <code>url</code>
  variable:</p>
  <pre>
    var myCode = 'alert(url);';
    var initFunc = function(interpreter, scope) {
      interpreter.setProperty(scope, 'url',
          interpreter.createPrimitive(location.toString()));

      var wrapper = function(text) {
        text = text ? text.toString() : '';
        return interpreter.createPrimitive(alert(text));
      };
      interpreter.setProperty(scope, 'alert',
          interpreter.createNativeFunction(wrapper));
    };
    var myInterpreter = new Interpreter(myCode, initFunc);
  </pre>
  <p>For more examples, see the <code>initGlobalScope</code> function which
  creates APIs for Math, Array, Function, and other globals.</p>

  <h2>Limitations</h2>
  <p>The version of JavaScript implemented by the interpreter has a few
  differences from that which executes in a browser:</p>
  <dl>
    <dt>API</dt>
    <dd>None of the DOM APIs are exposed.  That's kind of the point of a
    sandbox.  If you need these, write your own interfaces.</dd>
    <dt>Try</dt>
    <dd>The <code>try/catch</code> and <code>try/finally</code> constructs are
    not currently supported.  Feel free to add them if you need them.</dd>
    <dt>Wat</dt>
    <dd>Some of the more obscure type conversions (e.g. <code>[] + {}</code>)
    may return different results from JavaScript.  Patches are welcome.</dd>
    <dt>Todo</dt>
    <dd>A laundry list of random items that are currently missing but are slowly
    being worked on:
    <ul>
      <li>switch statements</li>
      <li>Regex class</li>
      <li>String search methods</li>
      <li>Array sort</li>
    </ul>
    </dd>
  </dl>

  <h2>Dependency</h2>
  <p>The only dependency is <a href="http://marijnhaverbeke.nl/acorn/">Acorn</a>,
  a beautifully written JavaScript parser by Marijn Haverbeke.  It is included
  in the JS-Interpreter package.</p>

  <h2>Compatibility</h2>
  <p>The limiting factor for browser support is the use of
  <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create"><code>Object.create(null)</code></a>
  to create hash objects in both Acorn and JS-Interpreter.
  This results in the following minimum browser requirements:</p>
  <ul>
    <li>Chrome 5</li>
    <li>Firefox 4.0</li>
    <li>IE 9</li>
    <li>Opera 11.6</li>
    <li>Safari 5</li>
  </ul>

  <h2>Disclaimer</h2>
  <p>This project is not an official Google product.</p>
</body>
</html>