Introduction to the JavaScript shell

  • Revision slug: Introduction_to_the_JavaScript_shell
  • Revision title: Introduction to the JavaScript shell
  • Revision id: 144116
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment wording

Revision Content

The JavaScript shell is a command-line program included in the SpiderMonkey source distribution. It is the JavaScript equivalent of Python's interactive prompt, the Lisp read-eval-print loop, or Ruby's <tt>irb</tt>. This article explains how to use the shell to experiment with JavaScript code and run JavaScript programs.

To get the JavaScript shell, see SpiderMonkey Build Documentation.

Using the JavaScript shell

The shell offers two modes of operation. You can use it as an interactive shell, in which you type JavaScript code at a prompt and get instant gratification, which is handy for experimenting or testing new features. You can also pass in, on the command line, a JavaScript program file to run, in which case the program is run automatically.

Note: Because the JavaScript shell is used as a test environment for the JavaScript engine, the available options and built-in functions can change over time.

Command line options

There are a number of command line options you can specify to control the shell. These are summarized below.

  • -b branchlimit
    • Sets the branch limit.
  • -c stackchunksize
    • Sets the stack chunk size.
  • -C
    • Tells the shell to compile the program but not run it. This is a convenient way to quickly check for syntax errors in your program without actually running it.
  • -e script
    • Runs the specified script, which is a literal string containing the code to execute.
  • -f filename
    • Runs the JavaScript program specified by filename.
  • -i
    • Enables interactive mode.
  • -P
    • if the first line of the file is "/usr/bin/env js -P", then the file content will be interpreted by the javascript engine.
    • This allows to make a javascript file executable on unix/osx machines.
  • -s
    • Enables strict warning mode.
  • -S stacksize
    • Sets the maximum stack size.
  • -v version
    • Sets the version of JavaScript specified by version (e.g. 170 for JavaScript 1.7).
  • -w
    • Enables warning messages.
  • -W
    • Disables warning messages.
  • -x
    • Enables E4X XML mode.

Running the shell

If you want to run the shell in interactive mode, you can simply use the command:

js -i

If you'd like to run the JavaScript code in the file <tt>foo.js</tt>, you can use this command:

js -f foo.js

To run <tt>foo.js</tt> then drop into the interactive shell, do this:

js -f foo.js -f -

Using the shell in interactive mode

In interactive mode, you can enter JavaScript code by hand to create objects and functions, as well as individual statements. This is a convenient way to test out ideas and, more importantly to developers working on the JavaScript engine, test new features of the language.

Built-in functions

To make the JavaScript shell more useful, there are a number of built-in functions provided that you can use either from JavaScript programs or in interactive mode.

build()

Returns the date and time at which the JavaScript shell was built.

clear([object])

Clears properties of the specified object. Calling clear() with no parameter clears everything so you can start with a clean slate.

Note: clear() with no parameters really clears everything. This includes all these built-in functions.

clone(function, [scope])

Clones the specified function object. If scope isn't specified, the new object's parent is the same as the original object's. Otherwise, the new object is placed in the scope of the object specified by scope.

evalcx(string[, object])

Evaluates the JavaScript code in string. If object is specified, the code is executed in that object, treating it as a sandbox.

If string is empty and object is not specified, evalcx() returns a new object with eager standard classes.

If string is "lazy" and object is not specified, evalcx() returns a new object with lazy standard classes.

Note: evalcx() is only useful for people doing deep internal work on the JavaScript engine, for testing evalInSandbox-like environments in the shell.

gc()

Runs the garbage collector to clean up memory.

getpda(object)

Returns the property descriptors for the specified object.

getslx(object)

Returns the script line extent, which is the number of lines of code comprising the specified object.

help([command ...])

Displays brief help information about the specified commands, or about all available functions if none are specified.

intern(string)

Internalizes the specified string into the atom table. Every string has a unique identifier, called an atom. This system makes it easier to do comparisons between strings.

Note: This function is intended only for use when testing the JavaScript engine.

line2pc([function, ] line)

Returns the program counter value corresponding to the specified line of code. If function is specified, line is an offset into the specified function.

load(filename1 [filename])

Loads the files with the specified names.

options([option ...])

Lets you set or get options. If you specified options on the command line, the results of calling options will indicate which options you requested. You can also pass in new options to set.

If you start the shell with the command <tt>js -x</tt>, then the options() function will return <tt>xml</tt>. If you start the shell with no options, and decide you want to enable XML mode, you can do so by issuing the command:

options('xml');

The available options are:

Option Name Description
strict Strict mode is enabled.
werror Warnings should be treated as errors.
atline When atline is enabled, comments of the form //@line num set the number of the following line to num.
xml XML mode is enabled.

pc2line(function, [pc])

Returns the line number of the JavaScript code that corresponds to the first line of the specified function. If you specify a program counter offset into the function, the line number of the line of code containing that offset is returned.

print([expression ...])

Evaluates the expression and displays the result on <tt>stdout</tt>.

quit()

Exits the shell.

readline()

Reads a single line of input from <tt>stdin</tt>, returning it to the caller. You can use this to create interactive shell programs in JavaScript.

scatter(fnArray)

(New in SpiderMonkey 1.8, not yet released, only in JS_THREADSAFE builds) Calls each function in fnArray without arguments, each in a different thread. When all threads have finished, this returns an array of the return values. Errors are not propagated; if any of the function calls fails, the corresponding element in the results array gets the exception object, if any, otherwise undefined.

Note: This function is intended only for use when testing the JavaScript engine.

seal(object[, deep])

Seals the specified object, or an object graph if deep is true. By sealing an object or object graph, you disable modification of those objects.

sleep(dt)

(New in SpiderMonkey 1.8, not yet released, only in JS_THREADSAFE builds) Sleep for dt seconds. Fractions of a second are supported. Returns true on success, false if the sleep was interrupted.

stringsAreUTF8()

Returns true if strings are encoded in UTF8 format; otherwise, returns false.

testUTF8(mode)

Performs UTF-8 tests. The mode parameter may be an integer from 1 to 4.

This is a debugging command that simply runs some checks on UTF-8 string handling, and isn't of general use, unless you're working on the JavaScript engine itself.

throwError()

Throws an error from the JS_ReportError() function.

Note: This function is intended only for use when testing the JavaScript engine.

trap([function, [pc,]] expression)

Sets a trap at the specific point in the JavaScript code. When the bytecode at the offset specified by pc in the function function is about to be executed, the expression is evaluated.

This is a powerful debugging mechanism when used in concert with line2pc(). For example, if you want to display a message when line 6 of a function, doSomething() is executed, you can enter the following:

trap(doSomething, line2pc(doSomething, 6), "print('line 6!\n')");
Note: When a trap is set, the corresponding bytecode in the program is replaced with a trap bytecode until you use untrap() to remove the trap.

untrap(function [, pc])

Removes a trap from the specified function at the offset pc. If pc isn't specified, the trap is removed from the function's entry point.

This function has no effect if there is no trap at the specified location.

version([number])

The version() function lets you get or set the JavaScript version number. This may be useful for gaining access to syntax only available in certain versions of JavaScript (for example, see Using JavaScript 1.7).

Debug functions

These built-in functions are only available in DEBUG builds.

dis([function])

Disassembles the JavaScript bytecode for the entire program, or for the specified function.

For example, if you enter the JavaScript function below:

function test() {
  var i = 3;
  print(i+2);
}

Then run the command <tt>dis(test);</tt>, you get this output:

main:
00000:  uint16 3
00003:  setvar 0
00006:  pop
00007:  name "print"
00010:  pushobj
00011:  getvar 0
00014:  uint16 2
00017:  add
00018:  call 1
00021:  pop
00022:  stop

Source notes:
  0:     0 [   0] newline 
  1:     3 [   3] decl     offset 0
  2:     7 [   4] newline 
  3:    18 [  11] xdelta  
  4:    18 [   0] pcbase   offset 11

dissrc([function])

Disassembles the JavaScript bytecode for the entire program, or for the specified function, showing the source lines. This function only works with programs loaded from files, either using the -f flag on launching the shell, or by using the load() function.

If your program includes a function, doStuff(), like this:

function doStuff(input) {
	print("Enter a number: ");
	var n1 = readline();
	print("Enter another one: ");
	var n2 = readline();
	
	print("You entered " + n1 + " and " + n2 + "\n");
}

Calling dissrc(doStuff) function would give this output:

;-------------------------  10:         print("Enter a number: ");
00000:  10  name "print"
00003:  10  pushobj
00004:  10  string "Enter a number: "
00007:  10  call 1
00010:  10  pop
;-------------------------  11:         var n1 = readline();
00011:  11  name "readline"
00014:  11  pushobj
00015:  11  call 0
00018:  11  setvar 0
00021:  11  pop
;-------------------------  12:         print("Enter another one: ");
00022:  12  name "print"
00025:  12  pushobj
00026:  12  string "Enter another one: "
00029:  12  call 1
00032:  12  pop
;-------------------------  13:         var n2 = readline();
00033:  13  name "readline"
00036:  13  pushobj
00037:  13  call 0
00040:  13  setvar 1
00043:  13  pop
;-------------------------  14: 
;-------------------------  15:         print("You entered " + n1 + " and " + n2 + "\n");
00044:  15  name "print"
00047:  15  pushobj
00048:  15  string "You entered "
00051:  15  getvar 0
00054:  15  add
00055:  15  string " and "
00058:  15  add
00059:  15  getvar 1
00062:  15  add
00063:  15  string "\\n"
00066:  15  add
00067:  15  call 1
00070:  15  pop
00071:  15  stop

dumpheap(([fileName[, start[, toFind[, maxDepth[, toIgnore]]]]])

Dump GC information. This is a thin wrapper for JS_DumpHeap.

gczeal(zeal)

Enable extra-frequent GC, to help find GC hazards. zeal is an integer. The meaning is the same as for the parameter to JS_SetGCZeal.

notes([function])

Shows the source notes for the specified function. Source notes contain information that map the bytecode to the source code, which is used when decompiling the code, such as when using the dissrc() function.

stats([string ...])

Dumps statistics. Valid options are arena, atom, and global.

Option Description
arena Outputs the arena table.
atom Outputs the atom table.
global Outputs the global name table.

An arena is a large block of memory from which the JavaScript engine allocates sub-blocks in order to optimize performance; issuing a large number of malloc() calls for each individual block is inefficient, so the engine creates arenas, then uses an internal memory management system to allocate memory from within those. The arena table is a list of all the arenas that have been allocated by the shell. stats("arena") lets you inspect the arena table so that you can see how a test case uses arenas.

An atom is a unique identifier for a string. In order to optimize comparisons between strings, each string is given an atom. These atoms are stored in a hash table, which you can display using the command stats("atom").

stats("global") displays the global name table, which contains the names and information about each object in memory.

tracing([toggle])

Enables or disables tracing mode. Pass true to enable tracing or false to turn it off. If you don't specify a parameter, tracing() returns the current setting.

Tip: This only works if you build JavaScript with JS_THREADED_INTERP turned off in the file <tt>jsinterp.c</tt>.
{{ wiki.languages( { "fr": "fr/Introduction_au_shell_JavaScript", "ja": "ja/Introduction_to_the_JavaScript_shell" } ) }}

Revision Source

<p>The <b>JavaScript shell</b> is a command-line program included in the <a href="en/SpiderMonkey">SpiderMonkey</a> source distribution.  It is the JavaScript equivalent of Python's interactive prompt, the Lisp read-eval-print loop, or Ruby's <tt>irb</tt>.  This article explains how to use the shell to experiment with JavaScript code and run JavaScript programs.
</p><p>To get the JavaScript shell, see <a href="en/SpiderMonkey_Build_Documentation">SpiderMonkey Build Documentation</a>.
</p>
<h2 name="Using_the_JavaScript_shell">Using the JavaScript shell</h2>
<p>The shell offers two modes of operation.  You can use it as an interactive shell, in which you type JavaScript code at a prompt and get instant gratification, which is handy for experimenting or testing new features.  You can also pass in, on the command line, a JavaScript program file to run, in which case the program is run automatically.
</p>
<div class="note"><b>Note:</b> Because the JavaScript shell is used as a test environment for the JavaScript engine, the available options and built-in functions can change over time.</div>
<h3 name="Command_line_options">Command line options</h3>
<p>There are a number of command line options you can specify to control the shell.  These are summarized below.
</p>
<ul><li> <code>-b <i>branchlimit</i></code>
<ul><li> Sets the branch limit.
</li></ul>
</li><li> <code>-c <i>stackchunksize</i></code>
<ul><li> Sets the stack chunk size.
</li></ul>
</li><li> <code>-C</code>
<ul><li> Tells the shell to compile the program but not run it.  This is a convenient way to quickly check for syntax errors in your program without actually running it.
</li></ul>
</li><li> <code>-e <i>script</i></code>
<ul><li> Runs the specified <i>script</i>, which is a literal string containing the code to execute.
</li></ul>
</li><li> <code>-f <i>filename</i></code>
<ul><li>Runs the JavaScript program specified by <i>filename</i>.
</li></ul>
</li><li> <code>-i</code>
<ul><li> Enables interactive mode.
</li></ul>
</li><li> <code>-P</code>
<ul><li> if the first line of the file is "/usr/bin/env js -P", then the file content will be interpreted by the javascript engine. 
</li><li> This allows to make a javascript file executable on unix/osx machines.
</li></ul>
</li><li> <code>-s</code>
<ul><li> Enables strict warning mode.
</li></ul>
</li><li> <code>-S <i>stacksize</i></code>
<ul><li> Sets the maximum stack size.
</li></ul>
</li><li> <code>-v <i>version</i></code>
<ul><li> Sets the version of JavaScript specified by <i>version</i> (e.g. <code>170</code> for JavaScript 1.7).
</li></ul>
</li><li><code> -w</code>
<ul><li> Enables warning messages.
</li></ul>
</li><li> <code>-W</code>
<ul><li> Disables warning messages.
</li></ul>
</li><li> <code>-x</code>
<ul><li> Enables <a href="en/E4X">E4X</a> XML mode.
</li></ul>
</li></ul>
<h3 name="Running_the_shell">Running the shell</h3>
<p>If you want to run the shell in interactive mode, you can simply use the command:
</p>
<pre class="eval">js -i
</pre>
<p>If you'd like to run the JavaScript code in the file <tt>foo.js</tt>, you can use this command:
</p>
<pre class="eval">js -f foo.js
</pre>
<p>To run <tt>foo.js</tt> then drop into the interactive shell, do this:
</p>
<pre class="eval">js -f foo.js -f -
</pre>
<h4 name="Using_the_shell_in_interactive_mode">Using the shell in interactive mode</h4>
<p>In interactive mode, you can enter JavaScript code by hand to create objects and functions, as well as individual statements.  This is a convenient way to test out ideas and, more importantly to developers working on the JavaScript engine, test new features of the language.
</p>
<h3 name="Built-in_functions">Built-in functions</h3>
<p>To make the JavaScript shell more useful, there are a number of built-in functions provided that you can use either from JavaScript programs or in interactive mode.
</p>
<h4 name="build.28.29"><code>build()</code></h4>
<p>Returns the date and time at which the JavaScript shell was built.
</p>
<h4 name="clear.28.5Bobject.5D.29"><code>clear(<i>[object]</i>)</code></h4>
<p>Clears properties of the specified <var>object</var>.  Calling <code>clear()</code> with no parameter clears everything so you can start with a clean slate.
</p>
<div class="note"><b>Note:</b> <code>clear()</code> with no parameters really clears everything.  This includes all these built-in functions.</div>
<h4 name="clone.28function.2C_.5Bscope.5D.29"><code>clone(<i>function, [scope]</i>)</code></h4>
<p>Clones the specified <var>function</var> object.  If <var>scope</var> isn't specified, the new object's parent is the same as the original object's.  Otherwise, the new object is placed in the scope of the object specified by <var>scope</var>.
</p>
<h4 name="evalcx.28string.5B.2C_object.5D.29"><code>evalcx(<i>string[, object]</i>)</code></h4>
<p>Evaluates the JavaScript code in <i>string</i>.  If <i>object</i> is specified, the code is executed in that object, treating it as a sandbox.
</p><p>If <i>string</i> is empty and <i>object</i> is not specified, <code>evalcx()</code> returns a new object with eager standard classes.
</p><p>If <i>string</i> is "lazy" and <i>object</i> is not specified, <code>evalcx()</code> returns a new object with lazy standard classes.
</p>
<div class="note"><b>Note:</b> <code>evalcx()</code> is only useful for people doing deep internal work on the JavaScript engine, for testing <code>evalInSandbox</code>-like environments in the shell.</div>
<h4 name="gc.28.29"><code>gc()</code></h4>
<p>Runs the garbage collector to clean up memory.
</p>
<h4 name="getpda.28object.29"><code>getpda(<i>object</i>)</code></h4>
<p>Returns the property descriptors for the specified <i>object</i>.
</p>
<h4 name="getslx.28object.29"><code>getslx(<i>object</i>)</code></h4>
<p>Returns the script line extent, which is the number of lines of code comprising the specified object.
</p>
<h4 name="help.28.5Bcommand_....5D.29"><code>help(<i>[command ...]</i>)</code></h4>
<p>Displays brief help information about the specified commands, or about all available functions if none are specified.
</p>
<h4 name="intern.28string.29"><code>intern(<i>string</i>)</code></h4>
<p>Internalizes the specified <var>string</var> into the atom table.  Every string has a unique identifier, called an atom.  This system makes it easier to do comparisons between strings.
</p>
<div class="note"><b>Note:</b> This function is intended only for use when testing the JavaScript engine.</div>
<h4 name="line2pc.28.5Bfunction.2C_.5D_line.29"><code>line2pc(<i>[function, ] line</i>)</code></h4>
<p>Returns the program counter value corresponding to the specified <i>line</i> of code.  If <i>function</i> is specified, <i>line</i> is an offset into the specified function.
</p>
<h4 name="load.28filename1_.5Bfilename.5D.29"><code>load(<i>filename1</i> <i>[filename]</i>)</code></h4>
<p>Loads the files with the specified names.
</p>
<h4 name="options.28.5Boption_....5D.29"><code>options(<i>[option ...]</i>)</code></h4>
<p>Lets you set or get options.  If you specified options on the command line, the results of calling <code>options</code> will indicate which options you requested.  You can also pass in new options to set.
</p><p>If you start the shell with the command <tt>js -x</tt>, then the <code>options()</code> function will return <tt>xml</tt>.  If you start the shell with no options, and decide you want to enable XML mode, you can do so by issuing the command:
</p>
<pre class="eval">options('xml');
</pre>
<p>The available options are:
</p>
<table class="standard-table">

<tbody><tr>
<td class="header">Option Name
</td><td class="header">Description
</td></tr>

<tr>
<td><code>strict</code>
</td><td> Strict mode is enabled.
</td></tr>
<tr>
<td><code>werror</code>
</td><td> Warnings should be treated as errors.
</td></tr>
<tr>
<td><code>atline</code>
</td><td> When <code>atline</code> is enabled, comments of the form <code>//@line <i>num</i></code> set the number of the following line to <code><i>num</i></code>.
</td></tr>
<tr>
<td><code>xml</code>
</td><td> XML mode is enabled.
</td></tr>
</tbody></table>
<h4 name="pc2line.28function.2C_.5Bpc.5D.29"><code>pc2line(<i>function, [pc]</i>)</code></h4>
<p>Returns the line number of the JavaScript code that corresponds to the first line of the specified <i>function</i>.  If you specify a program counter offset into the function, the line number of the line of code containing that offset is returned.
</p>
<h4 name="print.28.5Bexpression_....5D.29"><code>print(<i>[expression ...]</i>)</code></h4>
<p>Evaluates the <i>expression</i> and displays the result on <tt>stdout</tt>.
</p>
<h4 name="quit.28.29"><code>quit()</code></h4>
<p>Exits the shell.
</p>
<h4 name="readline.28.29"><code>readline()</code></h4>
<p>Reads a single line of input from <tt>stdin</tt>, returning it to the caller.  You can use this to create interactive shell programs in JavaScript.
</p>
<h4 name="scatter.28fnArray.29"><code>scatter(fnArray)</code></h4>
<p><i>(New in SpiderMonkey 1.8, not yet released, only in <code><a href="en/JS_THREADSAFE">JS_THREADSAFE</a></code> builds)</i> Calls each function in <i>fnArray</i> without arguments, each in a different thread.  When all threads have finished, this returns an array of the return values.  Errors are not propagated; if any of the function calls fails, the corresponding element in the results array gets the exception object, if any, otherwise <code>undefined</code>.
</p>
<div class="note"><b>Note:</b> This function is intended only for use when testing the JavaScript engine.</div>
<h4 name="seal.28object.5B.2C_deep.5D.29"><code>seal(<i>object[, deep]</i>)</code></h4>
<p>Seals the specified <i>object</i>, or an object graph if <i>deep</i> is <code>true</code>.  By sealing an object or object graph, you disable modification of those objects.
</p>
<h4 name="sleep.28dt.29"><code>sleep(dt)</code></h4>
<p><i>(New in SpiderMonkey 1.8, not yet released, only in <code><a href="en/JS_THREADSAFE">JS_THREADSAFE</a></code> builds)</i> Sleep for <i>dt</i> seconds.  Fractions of a second are supported.  Returns <code>true</code> on success, <code>false</code> if the sleep was interrupted.
</p>
<h4 name="stringsAreUTF8.28.29"><code>stringsAreUTF8()</code></h4>
<p>Returns <code>true</code> if strings are encoded in UTF8 format; otherwise, returns <code>false</code>.
</p>
<h4 name="testUTF8.28mode.29"><code>testUTF8(<i>mode</i>)</code></h4>
<p>Performs UTF-8 tests.  The mode parameter may be an integer from 1 to 4.
</p><p>This is a debugging command that simply runs some checks on UTF-8 string handling, and isn't of general use, unless you're working on the JavaScript engine itself.
</p>
<h4 name="throwError.28.29"><code>throwError()</code></h4>
<p>Throws an error from the <code>JS_ReportError()</code> function.
</p>
<div class="note"><b>Note:</b> This function is intended only for use when testing the JavaScript engine.</div>
<h4 name="trap.28.5Bfunction.2C_.5Bpc.2C.5D.5D_expression.29"><code>trap(<i>[function, [pc,]] expression</i>)</code></h4>
<p>Sets a trap at the specific point in the JavaScript code.  When the bytecode at the offset specified by <i>pc</i> in the function <i>function</i> is about to be executed, the <i>expression</i> is evaluated.
</p><p>This is a powerful debugging mechanism when used in concert with <code>line2pc()</code>.  For example, if you want to display a message when line 6 of a function, <code>doSomething()</code> is executed, you can enter the following:
</p>
<pre>trap(doSomething, line2pc(doSomething, 6), "print('line 6!\n')");
</pre>
<div class="note"><b>Note:</b> When a trap is set, the corresponding bytecode in the program is replaced with a <code>trap</code> bytecode until you use <code>untrap()</code> to remove the trap.</div>
<h4 name="untrap.28function_.5B.2C_pc.5D.29"><code>untrap(<i>function [, pc]</i>)</code></h4>
<p>Removes a trap from the specified <i>function</i> at the offset <i>pc</i>.  If <i>pc</i> isn't specified, the trap is removed from the function's entry point.
</p><p>This function has no effect if there is no trap at the specified location.
</p>
<h4 name="version.28.5Bnumber.5D.29"><code>version(<i>[number]</i>)</code></h4>
<p>The <code>version()</code> function lets you get or set the JavaScript version number.  This may be useful for gaining access to syntax only available in certain versions of JavaScript (for example, see <a href="en/New_in_JavaScript_1.7#Using_JavaScript_1.7">Using JavaScript 1.7</a>).
</p>
<div class="noinclude">
</div>
<h3 name="Debug_functions"> Debug functions </h3>
<p>These built-in functions are only available in <code>DEBUG</code> builds.
</p>
<h4 name="dis.28.5Bfunction.5D.29"><code>dis(<i>[function]</i>)</code></h4>
<p>Disassembles the JavaScript bytecode for the entire program, or for the specified <i>function</i>.
</p><p>For example, if you enter the JavaScript function below:
</p>
<pre class="eval">function test() {
  var i = 3;
  print(i+2);
}
</pre>
<p>Then run the command <tt>dis(test);</tt>, you get this output:
</p>
<pre>main:
00000:  uint16 3
00003:  setvar 0
00006:  pop
00007:  name "print"
00010:  pushobj
00011:  getvar 0
00014:  uint16 2
00017:  add
00018:  call 1
00021:  pop
00022:  stop

Source notes:
  0:     0 [   0] newline 
  1:     3 [   3] decl     offset 0
  2:     7 [   4] newline 
  3:    18 [  11] xdelta  
  4:    18 [   0] pcbase   offset 11
</pre>
<h4 name="dissrc.28.5Bfunction.5D.29"><code>dissrc(<i>[function]</i>)</code></h4>
<p>Disassembles the JavaScript bytecode for the entire program, or for the specified <i>function</i>, showing the source lines.  This function only works with programs loaded from files, either using the <code>-f</code> flag on launching the shell, or by using the <code>load()</code> function.
</p><p>If your program includes a function, <code>doStuff()</code>, like this:
</p>
<pre>function doStuff(input) {
	print("Enter a number: ");
	var n1 = readline();
	print("Enter another one: ");
	var n2 = readline();
	
	print("You entered " + n1 + " and " + n2 + "\n");
}
</pre>
<p>Calling <code>dissrc(doStuff)</code> function would give this output:
</p>
<pre>;-------------------------  10:         print("Enter a number: ");
00000:  10  name "print"
00003:  10  pushobj
00004:  10  string "Enter a number: "
00007:  10  call 1
00010:  10  pop
;-------------------------  11:         var n1 = readline();
00011:  11  name "readline"
00014:  11  pushobj
00015:  11  call 0
00018:  11  setvar 0
00021:  11  pop
;-------------------------  12:         print("Enter another one: ");
00022:  12  name "print"
00025:  12  pushobj
00026:  12  string "Enter another one: "
00029:  12  call 1
00032:  12  pop
;-------------------------  13:         var n2 = readline();
00033:  13  name "readline"
00036:  13  pushobj
00037:  13  call 0
00040:  13  setvar 1
00043:  13  pop
;-------------------------  14: 
;-------------------------  15:         print("You entered " + n1 + " and " + n2 + "\n");
00044:  15  name "print"
00047:  15  pushobj
00048:  15  string "You entered "
00051:  15  getvar 0
00054:  15  add
00055:  15  string " and "
00058:  15  add
00059:  15  getvar 1
00062:  15  add
00063:  15  string "\\n"
00066:  15  add
00067:  15  call 1
00070:  15  pop
00071:  15  stop
</pre>
<h4 name="dumpheap.28.28.5BfileName.5B.2C_start.5B.2C_toFind.5B.2C_maxDepth.5B.2C_toIgnore.5D.5D.5D.5D.5D.29"><code>dumpheap((<i>[fileName[, start[, toFind[, maxDepth[, toIgnore]]]]]</i>)</code></h4>
<p>Dump GC information.  This is a thin wrapper for <code><a href="en/JS_DumpHeap">JS_DumpHeap</a></code>.  
</p>
<h4 name="gczeal.28zeal.29"><code>gczeal(<i>zeal</i>)</code></h4>
<p>Enable extra-frequent GC, to help find GC hazards.  <i>zeal</i> is an integer.  The meaning is the same as for the parameter to <code><a href="en/JS_SetGCZeal">JS_SetGCZeal</a></code>.
</p>
<h4 name="notes.28.5Bfunction.5D.29"><code>notes(<i>[function]</i>)</code></h4>
<p>Shows the source notes for the specified function.  Source notes contain information that map the bytecode to the source code, which is used when decompiling the code, such as when using the <code>dissrc()</code> function.
</p>
<h4 name="stats.28.5Bstring_....5D.29"><code>stats(<i>[string ...]</i>)</code></h4>
<p>Dumps statistics.  Valid options are <i>arena</i>, <i>atom</i>, and <i>global</i>.
</p>
<table class="standard-table">

<tbody><tr>
<td class="header">Option
</td><td class="header">Description
</td></tr>

<tr>
<td><code>arena</code>
</td><td> Outputs the arena table.
</td></tr>
<tr>
<td><code>atom</code>
</td><td> Outputs the atom table.
</td></tr>
<tr>
<td><code>global</code>
</td><td> Outputs the global name table.
</td></tr>
</tbody></table>
<p>An <i>arena</i> is a large block of memory from which the  JavaScript engine allocates sub-blocks in order to optimize performance; issuing a large number of <code>malloc()</code> calls for each individual block is inefficient, so the engine creates arenas, then uses an internal memory management system to allocate memory from within those.  The arena table is a list of all the arenas that have been allocated by the shell.  <code>stats("arena")</code> lets you inspect the arena table so that you can see how a test case uses arenas.
</p><p>An <i>atom</i> is a unique identifier for a string. In order to optimize comparisons between strings, each string is given an atom.  These atoms are stored in a hash table, which you can display using the command <code>stats("atom")</code>.
</p><p><code>stats("global")</code> displays the global name table, which contains the names and information about each object in memory.
</p>
<h4 name="tracing.28.5Btoggle.5D.29"><code>tracing(<i>[toggle]</i>)</code></h4>
<p>Enables or disables tracing mode.  Pass <code>true</code> to enable tracing or <code>false</code> to turn it off.  If you don't specify a parameter, <code>tracing()</code> returns the current setting.
</p>
<div class="tip"><b>Tip:</b> This only works if you build JavaScript with <code> JS_THREADED_INTERP</code> turned off in the file <tt>jsinterp.c</tt>.</div>
{{ wiki.languages( { "fr": "fr/Introduction_au_shell_JavaScript", "ja": "ja/Introduction_to_the_JavaScript_shell" } ) }}
Revert to this revision