
SEE SHELL

This is an ECMAScript shell program used to test and demonstrate 
the SEE run-time library. It reads ECMAScript files and executes
them. It includes a simplistic 'HTML' mode where it will pre-process
a HTML document a little bit like a browser would. It also provides
an interactive (prompted) mode.


Usage
-----
	shell [-g] [-v] [-r <num>] [-d<debugflags>] [-c value] 
	      [-f file] [-h htmlfile] 

The '-g' option drops into the interactive debugger - see below for details.

The '-v' option prints the library version and API version used.

The '-r' option sets the function recursion limit. Default is -1 (indefinite).

The '-f file' and '-h htmlfile' options can be specified multiple times.
Each time they are specified, the given files are loaded and run.

Files specified with -f are loaded and run as pure ECMAScript. The
entire file is parsed as a 'Program' (see the language grammar), and the
global statements are evaluated.  If an exception occurs during execution of
the file, it terminates the process (exit 1), otherwise processing continues.

Files specified with -h are loaded as HTML. The HTML content is copied to
stdout, except for text found inside <SCRIPT> elements. It is stripped and run
as ECMAScript (regardless of the LANGUAGE attribute).  Exceptions
are ignored in HTML files. (Lazy browser behaviour!) There is no support for
forms, URL inclusions or triggers such as 'onLoad'. It is very spartan.

If no -f or -h flags are given (or a "-f -" argument is given), an
interactive prompt is produced, and individual statements are read
from standard input until EOF.

The -c flag adds flags to the compatibility field of the interpreter.
Each occurrence of the -c flag bitwise-ors its integer argument into the
flag. The value may also be an identifier, optionally prefixed with 'no'.
These identifiers are documented in detail in USAGE.html:

    sgmlcom     - treat SGML comments in program text as normal comments
    utf_unsafe  - pass through invalid UTF-8 characters without error
    undefdef    - return undefined for unknown names instead of throwing
    262_3b      - provide the optional functions in section 3B of standard
    ext1        - enable local SEE extension set number 1


NOTE: The command line arguments were chosen to be compatible with
the perl script used with Mozilla/spidermonkey's test suite.

The debug flags for -d only make sense if you are debugging the engine,
although the trace option (-dT) can be useful. The flags are:

    -dE         - debug the error constructors
    -dT         - enable call tracing
    -dc         - debug context and symbol scope operations
    -de         - debug exception try/catch
    -dl         - debug the lexical analysis stage
    -dn         - debug the native object module interface
    -dp         - debug the parsing stage
    -dr         - debug regular expression processing
    -dv         - debug the evaluation stage


Shell-provided objects and functions
------------------------------------

Besides the standard environment required by ECMA-262,
the shell provides a couple of objects useful for testing.

 print       - a function object which takes one
               string argument and prints it, followed
               by a newline.
 version     - an undefined value, used to satisfy some tests.

In HTML mode the following objects are provided:

 document            - a simple Object with some properties:
 document.write      - a function to print a string to stdout
 document.navigator  - a simple Object used as a placeholder
 document.userAgent  - "SEE-shell (see-1.0)" or similar
 document.window     - a reference to the Global object

Interactive debugger
--------------------

The simple interactive debugger demonstrates how the SEE library can be
controlled by a debugger via the trace() callback. The first time
ECMAScript code is excuted, the debugger provides a prompt to the
user. Command available at the prompt include:

	break [<filename>:]<lineno>	- add a new breakpoint
	show				- show current breakpoints
	delete <number>			- delete existing breakpoint

	step				- step to a new line
	cont				- continue execution

	where				- print traceback information
	info				- current context information
	eval <expr>			- evaluate expression in context
	throw <expr>			- throw an exception value


David Leonard

$Id: README 853 2005-12-12 11:51:25Z d $
