js.texi

一个类似windows

@example
var fp = new File ("output.txt");
if (!fp.open ("w"))
  System.error ("couldn't create output file `", fp, "': ",
                System.strerror (System.errno), "\n");
@print{} couldn't create output file `output.txt': Permission denied
@end example
@end defcv

@defcv {Static Property} System lineBreakSequence
The line break sequence that is used in the underlying system.  For
example, the outputs from the following lines are identical:

@example
System.stdout.writeln ("Hello!");
@print{} Hello!
System.stdout.write ("Hello!" + System.lineBreakSequence);
@print{} Hello!
@end example

@end defcv

@defcv {Static Property} System stderr
The system's standard error stream.  This is a normal JavaScript file
and all methods of the File object can be called for it.

@example
System.stderr.writeln ("panic: must exit");
System.exit (1);
@print{} panic: must exit
@end example
@end defcv

@defcv {Static Property} System stdin
The system's standard input stream.
@end defcv

@defcv {Static Property} System stdout
The system's standard output stream.
@end defcv


@node VM,  , System, Native Objects
@subsection VM

@table @strong
@item Standard
@value{NGS}
@end table


@defop {Static Method} VM garbageCollect ()
Perform a garbage collection for the virtual machine heap.  Normally,
the garbage collection is triggered automatically, but the
@code{garbageCollect()} method can be used to trigger the collection
explicitly.
@end defop

@defop {Static Method} VM stackTrace ([@var{limit}])
Print the contents of the virtual machine stack.  Optional argument
@var{limit} specifies how many stack frames are printed.  If no
arguments are given, the whole virtual machine stack is printed.

@c @cartouche
@example
function recursive (n)
@{
  if (n > 5)
    VM.stackTrace ();
  else
    recursive (n + 1);
@}

recursive (0);
@print{}VM: stacktrace: stacksize=2048, used=78
@print{}#0   recursive(): builtin 0
@print{}#1   recursive(): null 1 6
@print{}#2   recursive(): null 1 5
@print{}#3   recursive(): null 1 4
@print{}#4   recursive(): null 1 3
@print{}#5   recursive(): null 1 2
@print{}#6   recursive(): null 1 1
@print{}#7   .global(): null 1 0
@end example
@c @end cartouche
@end defop

@defcv {Static Property} VM dispatchMethod
The name of the dispatch method, currently used in the virtual machine.
The method returns a string that describes the method.  The possible
return values are @samp{switch-basic}, @samp{switch}, and @samp{jumps}.
@end defcv

@defcv {Static Property} VM gcCount
How many times the garbage collection has been performed for the heap.
@end defcv

@defcv {Static Property} VM gcTrigger
The garbage collection trigger.  When the virtual machine heap has
allocated more than @code{gcTrigger} number of bytes of memory, the
virtual machine will perform a garbage collection.
@end defcv

@defcv {Static Property} VM heapAllocated
The number of bytes of memory the system has allocated from the heap.
@end defcv

@defcv {Static Property} VM heapFree
The number of bytes of memory the heap freelist contains.
@end defcv

@defcv {Static Property} VM heapSize
The size of the heap in bytes.
@end defcv

@defcv {Static Property} VM numConstants
The number of constants defined in the virtual machine.
@end defcv

@defcv {Static Property} VM numGlobals
The number of global symbols defined in the virtual machine.  This value
equals to the number of global variables and functions, defined in the
system.
@end defcv

@defcv {Static Property} VM stackSize
The size of the virtual machine stack.
@end defcv

@defcv {Static Property} VM stacktraceOnError
A boolean flag that tells whether the virtual machine stack trace is
printed if an error occurs in the program execution.
@end defcv

@defcv {Static Property} VM verbose
The verbosity level of the virtual machine.
@end defcv

@defcv {Static Property} VM verboseStacktrace
A boolean flag that tells whether the virtual machine prints the normal
or verbose stacktrace.
@end defcv

@defcv {Static Property} VM version
The version string of the interpreter virtual machine.
@end defcv

@defcv {Static Property} VM versionMajor
The major version number of the virtual machine.
@end defcv

@defcv {Static Property} VM versionMinor
The minor version number of the virtual machine.
@end defcv

@defcv {Static Property} VM versionPatch
The patch level number of the virtual machine.
@end defcv

@defcv {Static Property} VM warnUndef
A boolean flag that tells whether the virtual machine should print a
warning message if an undefined variable is used.
@end defcv



@node Extensions,  , Native Objects, NGS JavaScript Language
@section Extensions

@menu
* Curses::
* JS::
* MD5::
@end menu

@node Curses, JS, Extensions, Extensions
@subsection Curses


@node JS, MD5, Curses, Extensions
@subsection JS

@deffn Constructor JS ()
@end deffn

@defmethod JS compile (file, asm_file, bc_file)
@end defmethod

@defmethod JS eval (string)
@end defmethod

@defmethod JS evalFile (filename)
@end defmethod

@defmethod JS evalJavaScriptFile (filename)
@end defmethod

@defmethod JS executeByteCodeFile (filename)
@end defmethod

@defmethod JS getVar (name)
@end defmethod

@defmethod JS setVar (name, value)
@end defmethod

@defcv Property JS errorMessage
@end defcv

@c ----------------------------------------------------------------------
@node MD5,  , JS, Extensions
@subsection MD5

@deffn Constructor MD5 ()
Create a new MD5 message digest object.

@c @cartouche
@example
var md5 = new MD5 ();
@end example
@c @end cartouche
@end deffn

@defmethod MD5 final ()
Return the MD5 value of the data, set to the object with the
@code{update()} method.  The method returns a 32 bytes long string that
holds the MD5 value as a hexadecimal number.

@c @cartouche
@example
function print_md5 (str)
@{
  var md5 = new MD5 ();
  md5.update (str);
  System.print ("MD5 of \"", str, "\" is ",
                md5.final (), ".\n");
@}
print_md5 ("Hello, world!");
@print{} MD5 of "Hello, world!" is 6CD3556DEB0DA54BCA060B4C39479839.
@end example
@c @end cartouche
@end defmethod

@defmethod MD5 finalBinary ()
Return the MD5 value of the data.  The method returns a 128 bits long
MD5 value.
@end defmethod

@defmethod MD5 init ()
Initalize the object to the initial state.  The method can be used to
reset the object after some data has been set to it with the
@code{update()} method.
@end defmethod

@defmethod MD5 update (str)
Append data to the object.  The method can be called multiple times, so
that the MD5 message digest can be counted one block at a time.

@c @cartouche
@example
function count_md5_for_file (stream)
@{
  var md5 = new MD5 ();

  while (!stream.eof ())
    @{
      var data = stream.read (1024);
      md5.update (data);
    @}

  return md5.final ();
@}
@end example
@c @end cartouche
@end defmethod


@c ----------------------------------------------------------------------
@node The js Program, The jsas Program, NGS JavaScript Language, Top
@chapter The @file{js} Program

The @samp{js} program is the JavaScript interpreter command.  It can be
used to execute JavaScript and JavaScript byte-code files.  The progam
can also be used to compile JavaScript files into the byte-code files.

@menu
* Invoking The js Program::
* Evaluating and Executing Code::
* Compiling JavaScript Code::
@end menu

@node Invoking The js Program, Evaluating and Executing Code, The js Program, The js Program
@section Invoking The @samp{js} Program

The @code{js} program is invoked as:

@code{js} @var{option}@dots{} @var{file} [@var{argument}@dots{}]

@noindent The @code{js} program processes the command line options and
when the first non-option argument, or the option @samp{--file}, is
encountered, it is assumed to contain JavaScript or byte-code that
should be evaluated.  The interpreter will pass all remaining arguments
to the script throught the @samp{ARGS} array.  The items in the array
are strings containing the arguments @var{argument}@dots{}.  The first
item of the array is always the name of the script @var{file}.

The options can be one or more of the following command line options:

@table @code
@item -a
@itemx --annotate-assembler

Annotate the created assembler listing with the original JavaScript
source code.  The option can be used only with the @samp{--assembler}
option.

@item -c
@itemx --compile

Compile JavaScript files to byte-code.  The generated byte-code is saved
to file which name is created from the name of the input file by
replacing the suffix @samp{.js} with the suffix @samp{.jsc}.  The
compilation can be controlled with options @samp{--debug},
@samp{--optimize}, and @samp{--compiler-option}.

@item -d @var{type}
@itemx --dispatch=@var{type}

Use the byte-code instruction dispatch method @var{type}.  The current
implementation supports the following dispatch methods:

@table @code
@item switch-basic

The basic switch-method using a big switch-case table to dispatch the
instruction.  This method is available only if the interpreter has been
configured with the option @samp{--with-all-dispatchers}.

@item switch

An optimized version of the switch-method.  This method is supported on
all environments.

@item jumps

The fastest dispatch method that uses the `computed goto' statement of
the GNU C-compiler.  This method is available if the interpreter has
been compiler with the GNU C-compiler.
@end table

The default dispatch method, for environments that has the GNU
C-compiler, is @samp{jumps}.  For all other environments, the default
method is @samp{switch}.


@item -e @var{code}
@itemx --eval=@var{code}

Evaluate JavaScript code @var{code}.

@cartouche
@example
$ js --eval='System.print ("Hello, world!\n");'
@print{} Hello, world!
@end example
@end cartouche


@item -E
@itemx --events

Print the interpreter events to the standard error.

@cartouche
@example
$ js -E -c test.js
[js: garbage collect]
[js: garbage collect]
[js: garbage collect]
[js: garbage collect]
@end example
@end cartouche


@item -f
@itemx --file

Stop processing options and use the next argument as the name of the
JavaScript (or byte-code) file.  All the remaining arguments are passed
to the interpreter through the @code{ARGS} array.  The first item of the
array will be the name of the script, i.e. the argument that follows the
option @samp{--file}.

@cartouche
@example
$ cat hello.js
@print{} var i;
@print{} for (i = 0; i < ARGS.length; i++)
@print{}   System.print (i, ": ", ARGS[i], "\n");
$ js --file hello.js a b c d
@print{} 0: hello.js
@print{} 1: a
@print{} 2: b
@print{} 3: c
@print{} 4: d
@end example
@end cartouche

The option can also be used with the option @samp{--load} to indicate
the last file to load.  Also in that case, the remaining arguments will
be passed to the script through the @code{ARGS} array.

@item -g
@itemx --debug

Make the compiler to generate debugging information to the generated
byte-code files.  This option can be used with the option
@samp{--compile}.

@item -h
@itemx --help

Print a short help message that describes the options that can be given
to the @samp{js} program.

@item -l
@itemx --load

Load multiple JavaScript and JavaScript byte-code files to the
interpreter.  Normally, the first non-option argument is evaluated and
all remaining arguments are passed to the script as arguments.  With the
option @code{--load}, multiple files can be loaded the to the
interpreter.  The loading can be stopped with option @code{--file} that
specifies the last file to load.

For example, if we have files @file{a.js}:

@example
function do_a ()
@{
  System.print ("do_a()\n");
@}
@end example

@noindent @file{b.js}:

@example
function do_b ()
@{
  System.print ("do_b()\n");
@}
@end example

@noindent and @file{main.js}:

@example
do_a ();
do_b ();
@end example

@noindent the whole application can be run as:

@cartouche
@example
$ js --load a.js b.js --file main.js @var{arguments}@dots{}
@print{} do_a()
@print{} do_b()
@end example
@end cartouche

@item -N
@itemx --no-compiler

Do not define the compiler to the virtual machine.  This option makes
the interpreter smaller, but the interpreter can only execute
pre-compiled byte-code files.  The option disables the @samp{eval}
global method.

@item -O [@var{level}]
@itemx --optimize[=@var{level}]

Set the compiler optimization level to @var{level}.  The compiler has
three different optimization levels:

@table @code
@item 0
Do not optimize.

@item 1
Perform all cheap optimizations which do not required heavy assembler
instruction analyzing.

@item 2
Perform all optimizations, supported by the compiler.
@end table

The default optimization level is 1.

@item -r @var{option}
@itemx --secure=@var{option}

Turn on virtual machine security option @var{option}.  The following
security options are available:

@table @code
@item file
Disable insecure methods from the buit-in File object.

@item system
Disable insecure methods from the buit-in System object.
@end table


@item -s @var{size}
@itemx --stack-size=@var{size}

Set the size of the virtual machine operand stack to @var{size}.  The
size of the virtual machine operand stack is set at the startup-time and
it can't be enlarged dynamically at the runtime.

@item -S
@itemx --assembler

Compile JavaScript files to JavaScript assembler.  The generated
assembler listing is saved to file which name is created from the name
of the input file by replacing the suffix @samp{.js} with the suffix
@samp{.jas}.  The compilation can be controlled with options
@samp{--optimize}, and @samp{--compiler-option}.

@item -t
@item