Parent Directory
| 
Revision Log
Remove unnecessary CVS $Id$ tags
SEE SHELL
Synopsis
--------
see-shell [-gV] [-l library] [-c <compat>] [-d<debugflags>]
[-r <maxrecurse>]
[-e <program> | -f <file> | -h <htmlfile> | -i]...
Description
-----------
This is an ECMAScript shell program used to test and demonstrate
the SEE run-time library. It reads ECMAScript files and runs
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 and a simple interactive debugger.
The options are as follows:
-c <compat>
Sets the interpreter compatibility flags which affect
how subsequent programs on the command line are run.
The argument to this option must be a whitespace-separated
sequence of identifiers from the list below, each optionally
prefixed with 'no_'. If the string begins with the character '='
then the compatibility flag is initialised to zero, otherwise
the arguments are bitwise-or'ed into the compatibility flag field.
sgmlcom - treat SGML comments in program text as
normal comments
utf_unsafe - pass through invalid UTF-8 characters
without error
262_3b - provide the optional functions in
section 3B of standard
js11 - enable JavaScript 1.1 compatibility
js12 - enable JavaScript 1.2 compatibility
js13 - enable JavaScript 1.3 compatibility
js14 - enable JavaScript 1.4 compatibility
js15 - enable JavaScript 1.5 compatibility
The effects of these identifiers are documented in doc/USAGE.html.
-d <debugflags>
Enables debugging in the SEE library. This results in
messages being written to the standard error. This only makes
sense if the library was compiled with debugging enabled
and is intended for use by the maintainers of SEE. The flags
correspond to different parts of SEE:
-dE - error constructors
-dT - execution call tracing
-dc - code generator
-de - exception try/catch
-dg - enable gtrace (see below)
-dl - lexical analysis
-dm - trace memory allocation
-dn - native object interface
-dp - parser
-dr - regular expression processing
-ds - context and symbol scope operations
-dv - execution/evaluation
-e string
Executes the string as an ECMAscript program. The shell globals
are installed into the environment as with the -f option.
-f file
Executes a file containing an ECMAscript program.
Before execution, a couple of 'shell' functions are included
in the global environment. See below for details.
If the file is "-", then the text is read non-interactively
from standard input and then standard input is closed.
-g Drops into the interactive debugger. See the section below,
'Interactive debugger', for details.
-h file
Executes an HTML file containing <SCRIPT> elements.
The HTML content is copied to standard output, except for
the text inside <SCRIPT> elements. The script text is stripped
and run as ECMAScript (regardless of any LANGUAGE attribute).
There is no support for forms, URL inclusions or triggers such
as 'onLoad'. However, a minimal 'document' environment is set up
so that document.write() works.
-i Interactively reads commands from the standard input, one
line at a time. Each line entered must parse as a statement.
Line breaks can be entered by escaping them with a backslash ('\').
Before execution, the 'shell' functions are included into the
global environment.
-l library
Loads a library module. This option must come before
any -e/-f/-h/-i options. See the section 'Dynamically loaded
modules' below for details.
-r maxrecurse
Sets the function recursion limit. Default is -1 (no limit).
-V Prints the library and API versions then exits.
The '-e string', '-f file' and '-h htmlfile' options can each be specified
multiple times. Each time they are specified, the given files or program
are run before further options are processed.
If no -e, -f, -h or -i flags are given, an interactive prompt is produced as
if the command line arguments ended with "-i".
NOTE: The command line options have been chosen to be mostly compatible with
the perl script used in Mozilla/spidermonkey's test suite.
gtrace
------
On some systems, when -dg is specified, a trap will be installed that
prints the current traceback and garbage collector status whenever a
SIGINFO signal is sent to the process. This can be useful when a script
is taking a long time to complete.
Shell-provided objects and functions
------------------------------------
Besides the standard environment required by ECMA-262, the shell will
include some extra objects into the Global environment when the -e, -f or -i
options are used:
print([string[, ...]])
- This function prints its argument strings followed
by a newline. Without arguments, it prints a single newline.
compat([string]) -> string
- Changes SEE's compatibility flags as if passed with the
'-c' flag. Returns the old compatibility flag string, suitable
for use in restoring the flags. If no argument is given,
no change to the compatibility flags are made.
gc()
- This function forces a memory garbage collection if possible.
version([int])
- A Netscape-compatible compatibility setter/getter.
If called without arguments, returns the current JS
compatibility level (e.g. 120, 130, .., 150), or 150
if no compatible(!) If called with a numeric argument,
then sets the JS compatibility to that number.
Shell.isatty()
- Returns true if the output is a TTY
Shell.exit([int])
- Causes the interpreter to immediately exit with the given
exit code. If no argument is given, 0 is used.
Shell.gcdump()
- Causes the garbage collector to dump information or
statistics, if supported.
Shell.abort(msg)
- This function forces a library-level abort (SEE_ABORT)
Shell.regex_engines() -> Array
- Returns strings indicating Regex engines available to SEE
Shell.regex_engine([string]) -> string
- Without arguments, returns the current regex engine name.
With a string argument, changes the engine and returns the
name of the old one.
HTML document objects and functions
-----------------------------------
In HTML mode (-h) the following objects are inserted into the Global
environment:
document.write([string])
- a function to print a string to stdout.
Unlike print() described above, no newline is added.
document.userAgent - The string "SEE-shell (see-1.0)", or similar
document.navigator - a placeholder object that references [Global]
document.window - a placeholder object that references [Global]
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. Commands 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
Dynamically loaded modules
--------------------------
The -l option (which must be used before any -e, -f, -h or -i options) uses
dlopens to open a shared library. It then looks for an exported structure
called 'module', and passes a pointer to it to SEE_module_add(). The
structure must be a 'struct SEE_module' as defined in <see/module.h>:
struct SEE_module {
SEE_uint32_t magic; /* magic number */
const char *name; /* name of module */
const char *version; /* module version */
int (*mod_init)(void);
void (*alloc)(struct SEE_interpreter *);
void (*init)(struct SEE_interpreter *);
};
See doc/USAGE.html for details on how module initialisation is performed,
or read mod_File.c for an example loadable module.
David Leonard
| David Leonard | ViewVC Help |
| Powered by ViewVC 1.0.9 |