XPCShell Reference

  • Revision slug: XPCShell_Reference
  • Revision title: XPCShell Reference
  • Revision id: 124591
  • Created:
  • Creator: Varmaa
  • Is current revision? No
  • Comment formatting, wording fixes

Revision Content

The Command Line

XPCShell is fairly simple to use. To start it up and have it present a prompt, simply execute <tt>xpcshell</tt>. The options are fairly simple. The command-line syntax is:

xpcshell [-s] [-w] [-W] [-v version] [-f scriptfile] [scriptfile] [scriptarg...]
<tt>-f</tt>
This option specifies a script file to execute. It's currently slightly broken. It was supposed to present the JS command prompt when the script has completed. It currently exits the program. You can specify multiple JS files to execute by using multiple <tt>-f</tt> arguments. The scripts will be executed in the order encountered. Also, XPCShell looks for <tt>xpcshell.js</tt> in the current directory. If that file is found it is executed before any other JS files specified.
<tt>-s</tt>
This option toggles the JavaScript strict option on and off. By default it is off.
<tt>-v version</tt>
This allows you to specify a specific version of JS to use. Essentially it calls <tt>JS_SetVersion</tt>; see the JS documentation for more details.
<tt>-w (lower case)</tt>
This option turns on JavaScript warnings.
<tt>-W (upper case)</tt>
This turns off JavaScript warnings. The last option seen is the one that wins.
<tt>{{mediawiki.external('scriptfile')}}</tt>
This is the file name of the script to execute.
<tt>{{mediawiki.external('scriptarg…')}}</tt>
These are arguments to be passed to the script. These arguments are only passed to “scriptfile” and not the scripts designated by <tt>–f</tt> options. These arguments appear on the global property <tt>arguments</tt>.

For instance, assume that you have a file called <tt>test.js</tt> with the following contents:

    for (prop in arguments)
    {
        print(prop + "=" + arguments[prop]);
    }

Entering the following at the command line:

    $ xpcshell test.js This is a test

Will output:

    0=This
    1=is
    2=a
    3=test

XPCShell Extensions

Once you execute XPCShell without a script you'll be at the <tt>JS></tt> command line. The following are some useful functions that can be invoked from the command line:

<tt>clear(object)</tt>
<tt>clear()</tt> removes all properties from an object. So say you created <tt>anObject</tt> with a property named <tt>value</tt> and then called <tt>clear(anObject)</tt>; the property <tt>value</tt> would no longer exist.
<tt>gc(heapDumpFilename)</tt>
<tt>gc()</tt> will invoke garbage collection. It takes an argument that can be used to dump the heap to. The argument is optional but if specified should equate to a valid file name.
<tt>load(scriptFilename)</tt>
<tt>load()</tt> allows you to load and run a script from the command line. For example, <tt>load("MyScript.js")</tt> will execute the script <tt>MyScript.js</tt> in the current directory.
<tt>print(obj1, obj2, )</tt>
<tt>print()</tt> is useful to print something to the screen. It dumps whatever passed to the screen. It can take multiple arguments as well. An example <tt>print(1, 2, 3)</tt> Will print <tt>1 2 3</tt>. Note: It puts spaces between things separated by commas and appends a newline at the end.
<tt>dump(object)</tt>
<tt>dump()</tt> is almost like <tt>print</tt>. It only handles one parameter and it doesn't append a newline.
<tt>dumpXPC(depth)</tt>
This function dumps the XPConnect object. See the documentation on <tt>debugDump</tt> for the <tt>nsIXPConnect</tt> interface for more information. This function takes one parameter for the depth.
<tt>version(newVersion)</tt>
<tt>version()</tt> returns the JavaScript engine version number. If you pass a number to it, it will set the version number.
<tt>quit(exitCode)</tt>
<tt>quit()</tt> exits the shell. You can specify arguments that will get translated to an exit code. <tt>quit(5)</tt> will exit XPCShell with a result code of 5.

Original Document Information

  • Author: David Bradley <dbradley@netscape.com>
  • Last Updated Date: 17 March 2003
  • Copyright Information: Portions of this content are © 1998–2008 by individual mozilla.org contributors; content available under a Creative Commons license.
{{ wiki.languages( { "fr": "fr/Xpcshell" } ) }}

Revision Source

<h3 name="The_Command_Line"> The Command Line </h3>
<p>XPCShell is fairly simple to use. To start it up and have it present a prompt, simply execute <tt>xpcshell</tt>. The options are fairly simple. The command-line syntax is:
</p>
<pre>xpcshell [-s] [-w] [-W] [-v version] [-f scriptfile] [scriptfile] [scriptarg...]</pre>
<dl><dt><tt>-f</tt>
</dt><dd>This option specifies a script file to execute. It's currently slightly broken. It was supposed to present the JS command prompt when the script has completed. It currently exits the program. You can specify multiple JS files to execute by using multiple <tt>-f</tt> arguments. The scripts will be executed in the order encountered. Also, XPCShell looks for <tt>xpcshell.js</tt> in the  current directory. If that file is found it is executed before any other JS files specified.
</dd></dl>
<dl><dt><tt>-s</tt>
</dt><dd>This option toggles the JavaScript strict option on and off. By default it is off.
</dd></dl>
<dl><dt><tt>-v version</tt>
</dt><dd>This allows you to specify a specific version of JS to use. Essentially it calls <tt>JS_SetVersion</tt>; see the JS documentation for more details.
</dd></dl>
<dl><dt><tt>-w (lower case)</tt>
</dt><dd>This option turns on JavaScript warnings.
</dd></dl>
<dl><dt><tt>-W (upper case)</tt>
</dt><dd>This turns off JavaScript warnings. The last option seen is the one that wins.
</dd></dl>
<dl><dt><tt>{{mediawiki.external('scriptfile')}}</tt>
</dt><dd>This is the file name of the script to execute.
</dd></dl>
<dl><dt><tt>{{mediawiki.external('scriptarg…')}}</tt>
</dt><dd>These are arguments to be passed to the script. These arguments are only passed to “scriptfile” and not the scripts designated by <tt>–f</tt> options. These arguments appear on the global property <tt>arguments</tt>.
</dd></dl>
<p>For instance, assume that you have a file called <tt>test.js</tt> with the following contents:
</p>
<pre>    for (prop in arguments)
    {
        print(prop + "=" + arguments[prop]);
    }
</pre>
<p>Entering the following at the command line:
</p>
<pre>    $ xpcshell test.js This is a test
</pre>
<p>Will output:
</p>
<pre>    0=This
    1=is
    2=a
    3=test
</pre>
<h3 name="XPCShell_Extensions"> XPCShell Extensions </h3>
<p>Once you execute XPCShell without a script you'll be at the <tt>JS&gt;</tt> command line. The following are some useful functions that can be invoked from the command line:
</p>
<dl><dt><tt>clear(<i>object</i>)</tt>
</dt><dd><tt>clear()</tt> removes all properties from an object. So say you created <tt>anObject</tt> with a property named <tt>value</tt> and then called <tt>clear(anObject)</tt>; the property <tt>value</tt> would no longer exist.
</dd></dl>
<dl><dt><tt>gc(<i>heapDumpFilename</i>)</tt>
</dt><dd><tt>gc()</tt> will invoke garbage collection. It takes an argument that can be used to dump the heap to. The argument is optional but if specified should equate to a valid file name.
</dd></dl>
<dl><dt><tt>load(<i>scriptFilename</i>)</tt>
</dt><dd><tt>load()</tt> allows you to load and run a script from the command line. For example, <tt>load("MyScript.js")</tt> will execute the script <tt>MyScript.js</tt> in the current directory.
</dd></dl>
<dl><dt><tt>print(<i>obj1</i>, <i>obj2</i>, <i>…</i>)</tt>
</dt><dd><tt>print()</tt> is useful to print something to the screen. It dumps whatever passed to the screen. It can take multiple arguments as well. An example <tt>print(1, 2, 3)</tt> Will print <tt>1 2 3</tt>. <b>Note:</b> It puts spaces between things separated by commas and appends a newline at the end.
</dd></dl>
<dl><dt><tt>dump(<i>object</i>)</tt>
</dt><dd><tt>dump()</tt> is almost like <tt>print</tt>. It only handles one parameter and it doesn't append a newline.
</dd></dl>
<dl><dt><tt>dumpXPC(<i>depth</i>)</tt>
</dt><dd>This function dumps the XPConnect object. See the documentation on <tt>debugDump</tt> for the <tt>nsIXPConnect</tt> interface for more information. This function takes one parameter for the depth.
</dd></dl>
<dl><dt><tt>version(<i>newVersion</i>)</tt>
</dt><dd><tt>version()</tt> returns the JavaScript engine version number. If you pass a number to it, it will set the version number.
</dd></dl>
<dl><dt><tt>quit(<i>exitCode</i>)</tt>
</dt><dd><tt>quit()</tt> exits the shell. You can specify arguments that will get translated to an exit code. <tt>quit(5)</tt> will exit XPCShell with a result code of 5.
</dd></dl>
<div class="originaldocinfo">
<h2 name="Original_Document_Information"> Original Document Information </h2>
<ul><li> Author: David Bradley &lt;dbradley@netscape.com&gt;
</li><li> Last Updated Date: 17 March 2003
</li><li> Copyright Information: Portions of this content are © 1998–2008 by individual mozilla.org contributors; content available under a Creative Commons license.
</li></ul>
</div>
{{ wiki.languages( { "fr": "fr/Xpcshell" } ) }}
Revert to this revision