This is Info file js.info, produced by Makeinfo version 1.68 from the
input file js.texi.

INFO-DIR-SECTION NGS JavaScript Interpreter
START-INFO-DIR-ENTRY
* libjs: (js).			The JavaScript interpreter library.
* js: (js)The js Program.	JavaScript interpreter.
END-INFO-DIR-ENTRY

   This file documents NGS JavaScript interpreter 0.2.5

   Copyright (C) 1998 New Generation Software (NGS) Oy

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: js.info,  Node: MD5,  Prev: JS,  Up: Extensions

MD5
---

 - Constructor: MD5 ()
     Create a new MD5 message digest object.

          var md5 = new MD5 ();

 - Method on MD5: final ()
     Return the MD5 value of the data, set to the object with the
     `update()' method.  The method returns a 32 bytes long string that
     holds the MD5 value as a hexadecimal number.

          function print_md5 (str)
          {
            var md5 = new MD5 ();
            md5.update (str);
            System.print ("MD5 of \"", str, "\" is ",
                          md5.final (), ".\n");
          }
          print_md5 ("Hello, world!");
          -| MD5 of "Hello, world!" is 6CD3556DEB0DA54BCA060B4C39479839.

 - Method on MD5: finalBinary ()
     Return the MD5 value of the data.  The method returns a 128 bits
     long MD5 value.

 - Method on 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
     `update()' method.

 - Method on 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.

          function count_md5_for_file (stream)
          {
            var md5 = new MD5 ();
          
            while (!stream.eof ())
              {
                var data = stream.read (1024);
                md5.update (data);
              }
          
            return md5.final ();
          }


File: js.info,  Node: The js Program,  Next: The jsas Program,  Prev: NGS JavaScript Language,  Up: Top

The `js' Program
****************

   The `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::


File: js.info,  Node: Invoking The js Program,  Next: Evaluating and Executing Code,  Prev: The js Program,  Up: The js Program

Invoking The `js' Program
=========================

   The `js' program is invoked as:

   `js' OPTION... FILE [ARGUMENT...]

The `js' program processes the command line options and when the first
non-option argument, or the option `--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 `ARGS' array.  The items in the array are strings
containing the arguments ARGUMENT....  The first item of the array is
always the name of the script FILE.

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

`-a'
`--annotate-assembler'
     Annotate the created assembler listing with the original JavaScript
     source code.  The option can be used only with the `--assembler'
     option.

`-c'
`--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 `.js' with the suffix `.jsc'.  The
     compilation can be controlled with options `--debug',
     `--optimize', and `--compiler-option'.

`-d TYPE'
`--dispatch=TYPE'
     Use the byte-code instruction dispatch method TYPE.  The current
     implementation supports the following dispatch methods:

    `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
          `--with-all-dispatchers'.

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

    `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.

     The default dispatch method, for environments that has the GNU
     C-compiler, is `jumps'.  For all other environments, the default
     method is `switch'.

`-e CODE'
`--eval=CODE'
     Evaluate JavaScript code CODE.

          $ js --eval='System.print ("Hello, world!\n");'
          -| Hello, world!

`-E'
`--events'
     Print the interpreter events to the standard error.

          $ js -E -c test.js
          [js: garbage collect]
          [js: garbage collect]
          [js: garbage collect]
          [js: garbage collect]

`-f'
`--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 `ARGS' array.  The first
     item of the array will be the name of the script, i.e. the
     argument that follows the option `--file'.

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

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

`-g'
`--debug'
     Make the compiler to generate debugging information to the
     generated byte-code files.  This option can be used with the option
     `--compile'.

`-h'
`--help'
     Print a short help message that describes the options that can be
     given to the `js' program.

`-l'
`--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 `--load', multiple files can be loaded the to the
     interpreter.  The loading can be stopped with option `--file' that
     specifies the last file to load.

     For example, if we have files `a.js':

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

     `b.js':

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

     and `main.js':

          do_a ();
          do_b ();

     the whole application can be run as:

          $ js --load a.js b.js --file main.js ARGUMENTS...
          -| do_a()
          -| do_b()

`-N'
`--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 `eval'
     global method.

`-O [LEVEL]'
`--optimize[=LEVEL]'
     Set the compiler optimization level to LEVEL.  The compiler has
     three different optimization levels:

    `0'
          Do not optimize.

    `1'
          Perform all cheap optimizations which do not required heavy
          assembler instruction analyzing.

    `2'
          Perform all optimizations, supported by the compiler.

     The default optimization level is 1.

`-r OPTION'
`--secure=OPTION'
     Turn on virtual machine security option OPTION.  The following
     security options are available:

    `file'
          Disable insecure methods from the buit-in File object.

    `system'
          Disable insecure methods from the buit-in System object.

`-s SIZE'
`--stack-size=SIZE'
     Set the size of the virtual machine operand stack to 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.

`-S'
`--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 `.js' with the
     suffix `.jas'.  The compilation can be controlled with options
     `--optimize', and `--compiler-option'.

`-t'
`--stacktrace'
     Print a stack trace on error.  When an error occurs during the
     evaluation of a script, the virtual machine will halt and the `js'
     program terminates.  If the option `--stacktrace' was given to the
     interpreter, the virtual machine will print a stack trace that
     shows the call stack at the point of the error.

     The following listing showns an program that raises an error at the
     specified recursion level.

          function recursive (level)
          {
            if (level <= 0)
              error ("recursion limit exceeded");
            else
              recursive (level - 1);
          }
          
          recursive (5);

     If the program is executed without the `--stacktrace' option, the
     following result is shown:

          $ js hello.js
          js: evaluation of file `hello.js' failed:
          hello.js:6: recursion limit exceeded

     With the `--stacktrace' option, the `js' program will print the
     following error message:

          $ js --stacktrace hello.js
          -| VM: error: hello.js:6: recursion limit exceeded
          -| VM: stacktrace: stacksize=2048, used=44
          -| #0   recursive(): null 1 "recursion limit exceeded"
          -| #1   recursive(): null 1 0
          -| #2   recursive(): null 1 1
          -| #3   recursive(): null 1 2
          -| #4   recursive(): null 1 3
          -| #5   recursive(): null 1 4
          -| #6   .global(): null 1 5
          -| js: evaluation of file `hello.js' failed:
          -| hello.js:6: recursion limit exceeded

`-v'
`--verbose'
     Increase the verbosity of the interpreter.  The option can be given
     multiple times to increase the amount of messages the interpreter
     prints.

`-V'
`--version'
     Print the version number of the `js' program.

`-W OPTION'
`--compiler-option=OPTION'
     Set JavaScript compiler options according to the option
     specification OPTION.  The specification OPTION can be given in
     two forms.  In the normal form, the option specifies a compiler
     option that should be set on.  If the specification OPTION starts
     with the prefix ``no-'', the specified option will be turn off.
     The following option specifications are currently implemented:

    `all'
          match most of the compile time options

    `pedantic'
          match all compile time options.  This option generates as
          much warnings as possible.  It will also complain about some
          things that are allowed by the ECMAScript standard, but which
          are consired to show bad programming style, for example,
          missing semicolons.

    `runtime'
          match all runtime options

    `shadow'
          warn if a variable declaration shadows a parameter

    `undefined'
          runtime check for undefined global variables

    `unused-argument'
          warn about unused arguments

    `unused-variable'
          warn about unused local variables

    `with-clobber'
          warn if the with-lookup of a symbol is clobbered because the
          symbol is defined to be a local variable or a function
          argument

    `missing-semicolon'
          warn about missing semicolons that are fixed by the missing
          semicolon inserting during the compilation

    `strict-ecma'
          warn about things that are supported by this implementation,
          but are not allowed by the ECMAScript standard.  These
          features are:

             * line terminators in string and regular expression
               constants

    `deprecated'
          warn if deprecated features has been used in the source code

`-x'
`--executable'
     Add execute permissions to the generated byte-code files.  This
     option is useful on Linux environments where JavaScript byte-code
     files can be executed natively with the `binfmt_js' module.

          $ cat hello.js
          -| System.stdout.writeln ("Hello, world!");
          $ js -cx hello.js
          $ ./hello.jsc
          -| Hello, world!


File: js.info,  Node: Evaluating and Executing Code,  Next: Compiling JavaScript Code,  Prev: Invoking The js Program,  Up: The js Program

Evaluating and Executing Code
=============================


File: js.info,  Node: Compiling JavaScript Code,  Prev: Evaluating and Executing Code,  Up: The js Program

Compiling JavaScript Code
=========================

   The compilation of JavaScript code is carried out with the following
command:

   `js' [OPTIONS] `-c' FILE...

where FILE is a JavaScript source file to compile and OPTIONS specify
additional compiler options.

   In the simplest form, the compilation goes as follows:

     $ js -c hello.js

This example compiles file `hello.js' to byte-code file `hello.jsc'
with the default compiler options.

* Menu:

* Warning Messages::
* Optimization::
* Debugging Information::
* Assembler Listings::


File: js.info,  Node: Warning Messages,  Next: Optimization,  Prev: Compiling JavaScript Code,  Up: Compiling JavaScript Code

Warning Messages
----------------

   It is nice to get as many error messages as possible at the
compilation time.  However, sometimes some error messages are false and
it is annoying to see them every time you compile your project.  The
option `--compiler-option' can be used to adjust the level of warning
messages the compiler generates.

   Normally we want to get all possible compiler time warnings.  They
can be enable with the `-Wall' option.  To set the warnings
individually, the following options can be given for the
`--compiler-option' option.  The option names can be prefixed with
string `no-' to turn them off instead of setting them.  For example,
let's assume that we want to get as much warnings as possible, but we
do not care about unused function arguments:

     $ js -Wall -Wno-unused-arguments -c hello.js

In this example, we turn on all warnings `-Wall', but we turn off
warnings about unused arguments `-Wno-unused-arguments'.

   The `js' program knows the following warning options:

`shadow'
     Warn if a variable declaration shadows a parameter.  For example,
     when compiling file `test.js' containing code:

          function foo (a, b)
          {
            var a = 1;
            return a + b;
          }

     the following warning is generated:

          $ js -Wshadow -c test.js
          -| test.js:3: warning: declaration of `a' shadows a parameter

`unused-argument'
     Warn if an argument is not used in the function body.  For
     example, when compiling file `test.js' containing code:

          function foo (a, b)
          {
            return a + 5;
          }

     the following warning is generated:

          $ js -Wunused-argument -c test.js
          -| test.js:1: warning: unused argument `b'

`unused-variable'
     Warn if a local variable is not used in the function body.  For
     example, when compiling file `test.js' containing code:

          function foo (a, b)
          {
            var c;
            return a + b;
          }

     the following warning is generated:

          $ js -Wunused-variable -c test.js
          -| test.js:3: warning: unused variable `c'

`with-clobber'
     Warn if the with-lookup of a symbol is clobbered because the
     symbol is defined to be a local variable or a function argument.
     For example, when compiling file `test.js' containing code:

          function foo (PI)
          {
            with (Math)
              System.print ("PI=", PI, "\n");
          }

     the following warning is generated:

          $ js -Wwith-clobber -c test.js
          -| test.js:4: warning: the with-lookup of symbol `PI' is
          -| clobbered by the argument definition

`missing-semicolon'
     Warn if a semicolon is missing from the input.  The missing
     semicolons are inserted during the parsing by the automatic
     semicolon inserting.  However, since the missing semicolons show
     bad programming style, this option will warn about them.  For
     example, when compiling file `test.js' containing code:

          function foo ()
          {
            return 1
          }
          
          foo ()

     the following warnings are generated:

          $ js -Wmissing-semicolon -c test.js
          test.js:3: warning: missing semicolon
          test.js:6: warning: missing semicolon

`strict-ecma'
     warn about things that are supported by this implementation, but
     are not allowed by the ECMAScript standard.  For example, when
     compiling file `test.js' containing code:

          function foo ()
          {
            System.stdout.writeln ("Hello, world!
          ");
          }

     the following warning is generated:

          $ js -Wstrict-ecma -c test.js
          test.js:3: warning: ECMAScript don't allow line terminators in
          string constants

`deprecated'
     warn if deprecated features has been used in the source code.  For
     example, when compiling file `test.js' containing code:

          function foo ()
          {
            for (var i in arguments)
              System.stdout.writeln (i);
          }

     the following warning is generated:

          $ js -Wdeprecated -c test.js
          test.js:1: warning: the `arguments' property of Function instance
          is deprecated

   Besides the compiler time checks, the virtual machine can also
perform some checks at the runtime.  These checks can be set and unset
with the `-Wruntime' option.

   The following runtime warnings are supported:

`undefined'
     Warn if the value of an undefined global variable is used.  For
     example, when running file `test.js' containing code:

          foo = an_undefined_variable;

     the following warning is generated:

          $ js test.js
          -| VM: warning: using undefined global `an_undefined_variable'


File: js.info,  Node: Optimization,  Next: Debugging Information,  Prev: Warning Messages,  Up: Compiling JavaScript Code

Optimization
------------


File: js.info,  Node: Debugging Information,  Next: Assembler Listings,  Prev: Optimization,  Up: Compiling JavaScript Code

Debugging Information
---------------------

   As a default, the JavaScript compiler do not include symbolic
debugging information to the generated byte-code files.  The debugging
information can be generated by giving the compiler `-g' option.  The
debugging information is also generated for the internal byte-code
files that are created when the interpreter evaluates plain JavaScript
source code.

   In the current implementation, the debugging information contains
only the names of the source files, and mappings from the virtual
machine program counter offsets to the source file locations.  In the
future, it will contain information about local variables and function
arguments, so that the symbolic debugger can print their values.

   The presence of the debugging information shows in the error messages
the interpreter shows.  For example, let's consider the following
JavaScript source code file `test.js':

     function foo (a)
     {
       a += 1;
       if (a > 50)
         error ("a overflow");
     
       return 1;
     }
     
     foo (50);

   When this file is compiled to the byte-code without debugging
information, the following error message is raised:

     $ js -c test.js
     $ js test.jsc
     -| js: evaluation of file `test.jsc' failed:
     -| a overflow

   If we recompile the file with the debugging information, we will get
a more precise error message from the interpreter:

     $ js -g -c test.js
     $ js test.jsc
     -| js: evaluation of file `test.js' failed:
     -| test.js:5: a overflow

Now we see the exact source code location where the error occurred.

   The debugging information can be removed from the byte-code files
after the compilation with the `jsdas' program.

     $ jsdas --strip test.jsc
     test.jsc:
     jsdas: removing section 3
     $ js test.jsc
     js: evaluation of file `test.jsc' failed:
     a overflow


File: js.info,  Node: Assembler Listings,  Prev: Debugging Information,  Up: Compiling JavaScript Code

Assembler Listings
------------------

   The JavaScript compiler can generate assembler listings from the
JavaScript source files.  The assembler listings are generated just
before the resulting byte-code data would be generated. So the resulting
assembler listing is exactly the same that will be in the resulting
byte-code data.  The assembler listing is generated with the
`--assembler' option.  For example, if we have a source file `hello.js'
with the following contents:

     function hello ()
     {
       System.stdout.writeln ("Hello, world!");
       return true;
     }
     
     hello ();

it can be compiled to assembler with command

     $ js -S hello.js

The command will save the assembler listing in file `hello.jas':

     hello:
             load_arg        1
             add_2_i
             min_args        2
             const           "Hello, world!"
             const_i1
             load_global     System
             load_property   stdout
             call_method     writeln
             pop_n           4
             const_true
             return
     
     .global:
             const_i0
             const_null
             jsr             hello
             apop            2

   The option `--annotate-assembler' can be used with the `--assembler'
option.  It mixes the original source code to the generated assembler
listing.  In this format, it is easy to see how different JavaScript
constructs are compiled in the assembler.  Our example file can be
compiled to the annotated assembler with the following command:

     $ js -a -S hello.js

The result listing is saved to file `hello.jas':

     ; -*- asm -*-
     ; function hello ()
     
     hello:
     ; {
             load_arg        1
             add_2_i
             min_args        2
     ;   System.stdout.writeln ("Hello, world!");
             const           "Hello, world!"
             const_i1
             load_global     System
             load_property   stdout
             call_method     writeln
             pop_n           4
     ;   return true;
             const_true
             return
     ; }
     ;
     ; hello ();
     
     .global:
             const_i0
             const_null
             jsr             hello
             apop            2


File: js.info,  Node: The jsas Program,  Next: The jsdas Program,  Prev: The js Program,  Up: Top

The `jsas' Program
******************

   The `jsas' program is a assembler for the JavaScript assembler.  The
program can be used to compile assembler files into byte-code.

* Menu:

* Invoking The jsas Program::


File: js.info,  Node: Invoking The jsas Program,  Prev: The jsas Program,  Up: The jsas Program

Invoking The `jsas' Program
===========================

   The `jsas' program is invoked as:

   `jsas' OPTION... FILE...

   The program reads the options and processes the assembler files
FILE... according to the options. The options can be one of more of the
following command line options:

`-g'
`--debug'
     Make the assembler to generate debugging information to the
     generated byte-code files.

`-h'
`--help'
     Print a short help message that describes the options that can be
     given to the `jsas' program.

`-O'
`--optimize'
     Optimize the assembler instructions.

`-v'
`--verbose'
     Turn on verbose diagnostic messages.  When this options is given,
     the `jsas' program tells what it is doing.

`-V'
`--version'
     Print the version number of the `jsas' program.


File: js.info,  Node: The jsdas Program,  Next: The jswrap Program,  Prev: The jsas Program,  Up: Top

The `jsdas' Program
*******************

   The `jsdas' program is a disassembler and a manipulator for the
JavaScript byte-code files.  The program can be used to view,
disassemble and manipulate the byte-code files.

* Menu:

* Invoking The jsdas Program::
* Viewing Byte-Code Files::
* Manipulating Byte-Code Files::


File: js.info,  Node: Invoking The jsdas Program,  Next: Viewing Byte-Code Files,  Prev: The jsdas Program,  Up: The jsdas Program

Invoking The `jsdas' Program
============================

   The `jsdas' program is invoked as:

   `jsdas' OPTION... FILE...

   The program reads the options and processes the byte-code files
FILE... according to the options.  The options can be one or more of
the following command line options:

`-c'
`--code'
     Print the code section of the byte-code files.  This is the default
     action that is preformed if no options are given for the `jsdas'
     program.

`-C'
`--constants'
     Print the constants section of the byte-code file.

`-d'
`--debug'
     Print the debug section of the byte-code file.

`-h'
`--help'
     Print a short help message that describes the options that can be
     given to the `jsdas' program.

`-i'
`--info'
     Print the byte-code file information.

`-l TYPE DATA'
`--link TYPE DATA'
     Link a new section to the byte-code file.  The section's type is
     TYPE and its contents is read from file DATA.

`-r TYPE'
`--remove TYPE'
     Remove section of type TYPE from the byte-code files.

`-s'
`--symtab'
     Print the symbol table section of the byte-code file.

`-S'
`--strip'
     Remove the debug section from the byte-code files.

`-V'
`--version'
     Print the version number of the `jsdas' program.


File: js.info,  Node: Viewing Byte-Code Files,  Next: Manipulating Byte-Code Files,  Prev: Invoking The jsdas Program,  Up: The jsdas Program

Viewing Byte-Code Files
=======================

   In this section we assume that we have a source file `hello.js' with
the following contents:

     function main ()
     {
       System.print ("Hello, world!\n");
     }
     
     main ();

   The file has been compiled to byte-code file `hello.jsc' with the
following command:

     $ js -Wall -g -c hello.js

   The option `--info' is used to view the contents of the byte-code
file.  For example, our example file contains the following information:

     $ jsdas --info hello.jsc
     hello.jsc:
     
     * byte-code file information
     
       section 0: type=0 (code), length=34
       section 1: type=1 (constants), length=40
       section 2: type=2 (symtab), length=25
       section 3: type=3 (debug), length=40

We see that the byte-code file has four sections: code, constants,
symtab and debug.  The listing shows also their lengths.  The sections
are:

`code'
     the byte-code instructions of the file

`constants'
     the constant values of the file

`symtab'
     the symbol table

`debug'
     the debugging information

   Next, we would like to see a assembler listing of the byte-code,
defined in the `code' section of the file.  This can be viewed with the
option `--code' that is the `jsdas''s default option (so no options for
the following example).

     $ jsdas hello.jsc
     hello.jsc:
     
     * section `Code'
     
     main:
       0     load_arg        1
       2     add_2_i
       3     min_args        2
       5     const           "Hello, world!\n"
       10    const_i1
       11    load_global     System
       16    call_method     print
       21    pop_n           4
       23    const_undefined
       24    return
     
     .global:
       25    const_i0
       26    const_null
       27    jsr             main
       32    apop            2

   The constants section holds the constant data the byte-code
instructions need.  These constants are pushed to the stack with the
`const' byte-code operand, or they are used to name a symbol in method
invocation or in subroutine call.

   The constant section can be viewed with the `--constants' option.

     $ jsdas --constants hello.jsc
     hello.jsc:
     
     * section `Constants'
     
       0:    "Hello, world!\n"
       1:    System
       2:    print
       3:    main

   Our example file defines four constants.  A string `Hello, world!\n'
and three symbols `System', `print', and `main'.

   The debugging information holds line number information about the
source file from which the file was compiled.  The debugging section
can be viewed with the option `--debug':

     $ jsdas --debug hello.jsc
     hello.jsc:
     
     * section `Debug'
     
       2     hello.js:2
       10    hello.js:3
       26    hello.js:6

   The symbol table hold the information about the global symbols the
byte-code file defines.  For each symbol, the symbol table has an offset
that points to the appropriate location in the byte-code instruction
stream.

   The symbol table information can be viewed with the `--symtab'
option:

     $ jsdas --symtab hello.jsc
     hello.jsc:
     
     * section `Symtab'
     
       main                                    0
       .global                                 25


File: js.info,  Node: Manipulating Byte-Code Files,  Prev: Viewing Byte-Code Files,  Up: The jsdas Program

Manipulating Byte-Code Files
============================

     $ jsdas --link 7001 hello.js hello.jsc
     hello.jsc:
     jsdas: linking 67 bytes of data to section 7001
     $ jsdas --info hello.jsc
     hello.jsc:
     
     * byte-code file information
     
       section 0: type=0 (code), length=34
       section 1: type=1 (constants), length=40
       section 2: type=2 (symtab), length=25
       section 3: type=3 (debug), length=40
       section 4: type=7001, length=67

     $ jsdas --remove 3 hello.jsc
     hello.jsc:
     jsdas: removing section 3
     $ jsdas --remove 7001 hello.jsc
     hello.jsc:
     jsdas: removing section 7001
     $ jsdas -i hello.jsc
     hello.jsc:
     
     * byte-code file information
     
       section 0: type=0 (code), length=34
       section 1: type=1 (constants), length=40
       section 2: type=2 (symtab), length=25


File: js.info,  Node: The jswrap Program,  Next: JavaScript API,  Prev: The jsdas Program,  Up: Top

The ``jswrap'' Program
**********************

   The `jswrap' program is a tool that helps implementing C functions
in JavaScript.

* Menu:

* Invoking The jswrap Program::
* Definition File Format::
* Re-Entrant Functions::
* Calling the Functions from C::
* Sample Project::


File: js.info,  Node: Invoking The jswrap Program,  Next: Definition File Format,  Prev: The jswrap Program,  Up: The jswrap Program

Invoking The `jswrap' Program
=============================

   The `jswrap' program is invoked as:

   `jswrap' OPTIONS... FILE

The `jswrap' program processes the command line options and according
to them and the default values, it converts the input file FILE to the
corresponding `.h' and `.c' files.  The options can be one of more of
the following command line options:

`-g'
`--debug'
     Generate debugging information to the generated JavaScript
     byte-code.

`-h FILE'
`--header FILE'
     Generate the C header file to file FILE.  The default C header
     file name is constructed from the input file name by replacing the
     suffix `.jsw' with suffix `.h'.

`-n'
`--no-error-handler'
     Do not generate the default error handler to the generated C
     files.  If this option is specified, then the error handler must
     be defined in your code.

`-o'
`--output FILE'
     Generate the C output to file FILE.  The default output file name
     is constructed from the input file name by replacing the suffix
     `.jsw' with suffix `.c'.

`-r'
`--reentrant'
     Generate re-entrant C functions.  The option adds a ``JSInterpPtr''
     argument to all C functions it generates.

`-V'
`--version'
     Print the version number of the `jswrap' program.

`--help'
     Print a short help message that describes the options that can be
     given to the `jswrap' program.


File: js.info,  Node: Definition File Format,  Next: Re-Entrant Functions,  Prev: Invoking The jswrap Program,  Up: The jswrap Program

Definition File Format
======================

   The definition file contains the function definitions and their
implementation in JavaScript.  The function definitions are normal
JavaScript function definitions but they are extended with the type
information.  The type information is used to generate the C header
files and the glue code that is used in the function call.  The
definition file can also contain normal JavaScript comments.  The
comments are ignored and they are not copied to the generated C header
and implementation files.

   The syntax of the function definition is:

     function [RETURN_TYPE] FUNCTION_NAME `('ARGUMENT_TYPE... ARGUMENT[, ...]`)'
     {
       JAVASCRIPT CODE IMPLEMENTING THE FUNCTION.
     }

Where:

RETURN_TYPE
     specifies the return type of the function.  If the return type
     specification is omitted, the function is a `void' function
     returning no value.

FUNCTION_NAME
     is the name of the function.  The name must be a valid C identifier
     matching regular expression ``^[A-Za-z_][A-Za-z_0-9]*''.

ARGUMENT_TYPE
     specifies the type of the argument, its passing type, and the life
     scope of the value of the argument.

ARGUMENT
     is the name of the argument.  The name must be a valid C
     identifier.

* Menu:

* The Type Specifiers::
* The Pass-Type Specifiers::
* The Life Scope Specifiers::


File: js.info,  Node: The Type Specifiers,  Next: The Pass-Type Specifiers,  Prev: Definition File Format,  Up: Definition File Format

The Type Specifiers
-------------------

   The type specifiers specify the native C and JavaScript type that is
used for the argument or for the return value.  The following type are
supported:

`cstring'
     A `'\0'' terminated C-string.  In the C, this is presented as
     ``char *''.  In the JavaScript, this is a normal string.

`double'
     A floating point number.  In the C, this is a ``double'' floating
     point number.

`int'
     An integer Number.  In the C, this is a ``long'' integer.

`string'
     An arbitrary data block.  In the C, this is presented as ``unsigned
     char *', `unsigned int'' pair.  In the JavaScript, this is a normal
     string.  *Note!* Because the type's presentation in C is two
     types, this value can't be used as a return value of a function.

   The following example shows how the types are converted to the
corresponding C header file.  The input file `types.jsw' is as follows:

     function types (cstring vcstring, double vdouble, int vint,
                     string vstring)
     {
     }

   The resulting C header file `types.h' contains the following
definitions for the function `types':

     void types (
             char *vcstring,
             double vdouble,
             long vint,
             unsigned char *vstring,
             unsigned int vstring_len
             );


File: js.info,  Node: The Pass-Type Specifiers,  Next: The Life Scope Specifiers,  Prev: The Type Specifiers,  Up: Definition File Format

The Pass-Type Specifiers
------------------------

   The passing type specifiers specify how the argument is passed to the
function.  The following specifies are supported:

`in'
     An input argument.  This is the default pass-type for arguments.

`out'
     An output argument.  In the JavaScript, the initial value of the
     argument is `undefined'.  When the control returns from the
     implementation of the function, the argument's current value is
     returned to the calling C function.

     In the C, the output and input-output arguments are presented as
     pointers to the variables, containing the values.

`inout'
     An input-output argument.

   The following example shows show the output and input-output
arguments are presented in the C header file.  The input file
`pass.jsw' is as follows:

     function pass (out cstring vcstring, out double vdouble, inout int vint,
                    inout string vstring)
     {
     }

   The resulting C header file `pass.h' contains the following
definitions for the function `pass':

     void pass (
             char **vcstring,
             double *vdouble,
             long *vint,
             unsigned char **vstring,
             unsigned int *vstring_len
             );


File: js.info,  Node: The Life Scope Specifiers,  Prev: The Pass-Type Specifiers,  Up: Definition File Format

The Life Scope Specifiers
-------------------------

   The life scope specifiers specify the liveness of the value, passed
in an argument.  The following specifiers are supported:

`static'
     The argument points to static data that can't change while the
     execution is in the JavaScript code.  This means that the
     JavaScript can use the same data that is given to it; it don't
     have to make a private copy of the data.  The specifier can only
     be used with `cstring' and `string' types.

     The specifier don't have any affect for the generated C header
     file.


File: js.info,  Node: Re-Entrant Functions,  Next: Calling the Functions from C,  Prev: Definition File Format,  Up: The jswrap Program

Re-Entrant Functions
====================


File: js.info,  Node: Calling the Functions from C,  Next: Sample Project,  Prev: Re-Entrant Functions,  Up: The jswrap Program

Calling the Functions from C
============================


File: js.info,  Node: Sample Project,  Prev: Calling the Functions from C,  Up: The jswrap Program

Sample Project
==============

     function hello (cstring user)
     {
       System.stdout.writeln ("Hello, " + user + "!");
     }
     
     function int max_sum (int a, int b, int out sum)
     {
       sum = a + b;
     
       return a > b ? a : b;
     }

     $ jswrap sample.jsw

     /* This file is automatically generated from `hello.jsw' by jswrap. */
     
     #ifndef HELLO_H
     #define HELLO_H
     
     void hello (
             char *user
             );
     
     int max_sum (
             int a,
             int b,
             int *sum
             );
     
     #endif /* not HELLO_H */

     #include <js.h>
     #include "hello.h"
     
     JSInterpPtr jswrap_interp;
     
     int
     main (int argc, char *argv[])
     {
       int a, b, max, sum;
     
       jswrap_interp = js_create_interp (NULL);
     
       hello ("World");
     
       a = 5;
       b = 7;
       max = max_sum (a, b, &sum);
       printf ("%d + %d = %d, max(%d, %d) = %d\n", a, b, sum, a, b, max);
     
       return 0;
     }


File: js.info,  Node: JavaScript API,  Next: Virtual Machine,  Prev: The jswrap Program,  Up: Top

JavaScript API
**************

* Menu:

* Interpreter Handling::
* Evaluation and Compilation::
* Type Handling::
* Defining Global Methods::
* Classes::
* Modules::


File: js.info,  Node: Interpreter Handling,  Next: Evaluation and Compilation,  Prev: JavaScript API,  Up: JavaScript API

Interpreter Handling
====================

 - Function: const char * js_version ()
     Return a string that describes the JavaScript interpreter version
     number.  The returned string is in format `"MAJOR.MINOR.PATCH"',
     where MAJOR, MINOR, and PATCH are integer numbers.

 - Function: void js_init_default_options (JSInterpOptions *OPTIONS)
     Initialize the interpreter options OPTIONS to the default values.
     These are the same values that are used in the interpreter
     creation, if the argument OPTIONS of `js_create_interp()' is
     `NULL'.

 - Function: JSInterpPtr js_create_interp (JSInterpOptions *OPTIONS)
     Create a new JavaScript interpreter.  The function returns an
     interpreter handle that must be passed to all other interpreter API
     functions.  The argument OPTIONS specify additional options for
     the interpreter.  If the argument is NULL, the default values are
     used.  If the interpreter creation fails - due insufficient memory
     resources - the function return value `NULL'.

 - Function: void js_destroy_interp (JSInterpPtr INTERP)
     Destroy interpreter INTERP and free all resources the interpreter
     has allocated.  The handle INTERP must not be used after this
     function.

 - Function: const char * js_error_message (JSInterpPtr INTERP)
     Return an error message of the latest error in interpreter INTERP.

 - Function: void js_result (JSInterpPtr INTERP, JSType *RESULT_RETURN)
     Get the result of the latest evaluation or execution in interpreter
     INTERP.  The result is returned in RESULT_RETURN.  All data,
     returned in RESULT_RETURN, belongs to the interpreter.  The caller
     must not modify or changed it in any ways.

 - Function: void js_set_var (JSInterpPtr INTERP, char *NAME, JSType
          *VALUE)

 - Function: void js_get_var (JSInterpPtr INTERP, char *NAME, JSType
          *VALUE)

 - Function: void js_get_options (JSInterpPtr INTERP, JSInterpOptions
          *OPTIONS)
     Get the options of interpreter INTERP to OPTIONS.

 - Function: void js_set_options (JSInterpPtr INTERP, JSInterpOptions
          *OPTIONS)
     Modify the options of interpreter INTERP according to OPTIONS.


File: js.info,  Node: Evaluation and Compilation,  Next: Type Handling,  Prev: Interpreter Handling,  Up: JavaScript API

Evaluation and Compilation
==========================

 - Function: int js_eval (JSInterpPtr INTERP, char *CODE)
     Evaluate JavaScript code CODE with interpreter INTERP.  The
     argument CODE is NUL-terminated a C-string holding the JavaScript
     code.  The function returns 1 if the operation was successful or 0
     otherwise.  If the evaluation failed, the error message can be
     retrieved with function `js_error_message()'.

 - Function: int js_eval_data (JSInterpPtr INTERP, char *DATA, unsigned
          int DATALEN)
     Evaluate JavaScript code DATA, DATALEN with interpreter INTERP.

 - Function: int js_eval_file (JSInterpPtr INTERP, char *FILENAME)
     Evaluate file FILENAME with interpreter INTERP.  The file FILENAME
     can contain JavaScript or byte-code.

 - Function: int js_eval_javascript_file (JSInterpPtr INTERP, char
          *FILENAME)
     Evaluate JavaScript code file FILENAME with interpreter INTERP.

 - Function: int js_execute_byte_code_file (JSInterpPtr INTERP, char
          *FILENAME)
     Execute a byte-code file FILENAME with interpreter INTERP.

 - Function: int js_apply (JSInterpPtr INTERP, char *NAME, unsigned int
          ARGC, JSType *ARGV)
     Call function NAME with arguments ARGC, ARGV.  The return value of
     the function NAME can be retrieved with the `js_result()' function.

 - Function: int js_compile (JSInterpPtr INTERP, char *INPUT_FILE, char
          *ASSEMBLER_FILE, char *BYTE_CODE_FILE)
     Compile JavaScript input file INPUT_FILE.  If the argument
     ASSEMBLER_FILE is not `NULL', the generated assembler code is
     saved to the file, specified by the argument.  If the argument
     BYTE_CODE_FILE is not `NULL', the generated byte-code data is
     svaed to the file, specified by the argument.

 - Function: int js_compile_to_byte_code (JSInterpPtr INTERP, char
          *INPUT_FILE, unsigned char **BC_RETURN, unsigned int
          *BC_LEN_RETURN);
     Compile JavaScript file INPUT_FILE to byte-code and return the
     resulting byte-code data in BC_RETURN, BC_LEN_RETURN.  The
     returned byte-code data BC_RETURN belongs to the interpreter and
     it must be saved by the caller *before* any other JS functions is
     called.  If the data is not saved, its contents will be
     invalidated at the next garbage collection.

 - Function: int js_compile_data_to_byte_code (JSInterpPtr INTERP, char
          *DATA, unsigned int DATALEN, unsigned char **BC_RETURN,
          unsigned int *BC_LEN_RETURN);
     Compile JavaScript code DATA, DATALEN to byte-code and return the
     resulting byte-code data in BC_RETURN, BC_LEN_RETURN.

 - Function: int js_execute_byte_code (JSInterpPtr INTERP, unsigned
          char *BC, unsigned int BC_LEN);
     Execute byte-code data BC, BC_LEN.  The byte-code data is the
     contents of a byte-code file, or a copy of the data returned by the
     `js_compile_to_byte_code()' or `js_compile_data_to_byte_code()'
     functions.

     *Note!* You can't use the data from the
     `js_compile_to_byte_code()', `js_compile_data_to_byte_code()'
     functions as an input for this function.  You must take a private
     copy of the data and pass that copy to the function:

          if (js_compile_to_byte_code (interp, file, &bc, &bclen))
            {
              char *bc_copy = xmalloc (bclen);
              memcpy (bc_copy, bc, bclen);
              js_execute_byte_code (interp, bc_copy, bclen);
              xfree (bc_copy);
            }


File: js.info,  Node: Type Handling,  Next: Defining Global Methods,  Prev: Evaluation and Compilation,  Up: JavaScript API

Type Handling
=============

 - Function: void js_type_make_string (JSInterpPtr INTERP, JSType
          *TYPE, unsigned char *DATA, unsigned int LENGTH)
     Create a new string type from LENGTH bytes of data DATA.  The
     result string is created to TYPE.

 - Function: void js_type_make_array (JSInterpPtr INTERP, JSType *TYPE,
          unsigned int LENGTH)
     Create a new array type of length LENGTH.  The result array is
     created to TYPE.


File: js.info,  Node: Defining Global Methods,  Next: Classes,  Prev: Type Handling,  Up: JavaScript API

Global Methods
==============

 - Function: void js_create_global_method (JSInterpPtr INTERP, char
          *NAME, JSGlobalMethodProc PROC, void *CONTEXT, JSFreeProc
          CONTEXT_FREE_PROC)


File: js.info,  Node: Classes,  Next: Modules,  Prev: Defining Global Methods,  Up: JavaScript API

Classes
=======

 - Function: JSClassPtr js_class_create (void *CLASS_CONTEXT,
          JSFreeProc CLASS_CONTEXT_DESTRUCTOR, int NO_AUTO_DESTROY,
          JSConstructor CONSTRUCTOR)
     Create a new class with class context data CLASS_CONTEXT.  The
     context data is destroyed with CLASS_CONTEXT_DESTRUCTOR.  If the
     argument NO_AUTO_DESTROY is not 0, the JavaScript interpreter will
     *not* destroy the class when the interpreter is destroyed.  In
     that case, it is the caller's responsibility to call
     `js_class_destroy()' for the returned class handle, after the
     interpreter has been destroyed.  If the argument CONSTRUCTOR is
     not `NULL', it is used to instantiate the class when a ``new
     'CLASS` ('ARGS[...]`);'' expression is evaluated in the JavaScript
     code.

 - Function: void js_class_destroy (JSClassPtr CLS)
     Destroy class handle CLS.  The class handle must be created by the
     `js_class_create()' function, so that value `1' was given for the
     NO_AUTO_DESTROY argument.

 - Function: JSVoidPtr js_class_context (JSClassPtr CLS)
     Return the class context of class CLS.  The returned value is the
     same that was given for the CLASS_CONTEXT argument in call of
     function `js_class_create()'.

 - Function: int js_class_define_method (JSClassPtr CLS, char *NAME,
          unsigned int FLAGS, JSMethodProc METHOD)
     Define a new method for the class CLS.  The name of the new method
     is NAME and its implementation is METHOD.  The argument FLAGS can
     have the following flags:

    `JS_CF_STATIC'
          The created method is a static method.

 - Function: int js_class_define_property (JSClassPtr CLS, char *NAME,
          unsigned int FLAGS, JSPropertyProc PROPERTY)
     Define a new property for the class CLS.  The name of the property
     is NAME and its setter and getter function is PROPERTY.  The
     argument FLAGS can have the following flags:

    `JS_CF_STATIC'
          The property is a static property.

    `JS_CF_IMMUTABLE'
          The property is immutable.  An error to try to set the
          property.

 - Function: int js_define_class (JSInterpPtr INTERP, JSClassPtr CLS,
          char *NAME)
     Define the class CLS to the interpreter INTERP with name NAME.  If
     the value `0' was given for the argument NO_AUTO_DESTROY of the
     function `js_class_create()', the handle CLS must not be used
     after this call.

 - Function: int js_instantiate_class (JSInterpPtr INTERP, JSClassPtr
          CLS, void *INSTANCE_CTX, JSFreeProc INSTANCE_CTX_DESTRUCTOR,
          JSType *RESULT_RETURN)

 - Function: const JSClassPtr js_lookup_class (JSInterpPtr INTERP, char
          *NAME)
     Lookup the class context by name from the interpreter INTERP.

 - Function: int js_isa (JSInterpPtr INTERP, JSType *OBJECT, JSClassPtr
          CLS, void **INSTANCE_CONTEXT_RETURN)
     Check if object OBJECT is an instance of class CLS.  The function
     returns a boolean success status.  If the argument
     INSTANCE_CONTEXT_RETURN is not `NULL', it will be set to the
     instance context of object OBJECT.


File: js.info,  Node: Modules,  Prev: Classes,  Up: JavaScript API

Modules
=======

 - Function: int js_define_module (JSInterpPtr INTERP, JSModuleInitProc
          INIT_PROC)


File: js.info,  Node: Virtual Machine,  Next: JavaScript Compiler,  Prev: JavaScript API,  Up: Top

Virtual Machine
***************

* Menu:

* Byte-Code File Format::
* Byte-Code Operands::
* Stack Frame::


File: js.info,  Node: Byte-Code File Format,  Next: Byte-Code Operands,  Prev: Virtual Machine,  Up: Virtual Machine

Byte-Code File Format
=====================

* Menu:

* File Header::
* Code Section::
* Constants Section::
* Symtab Section::
* Debug Section::


File: js.info,  Node: File Header,  Next: Code Section,  Prev: Byte-Code File Format,  Up: Byte-Code File Format

File Header
-----------

`magic'
     An `UInt32' number containing the JavaScript byte-code file magic.
     The value of the magic is `0xc0014a53'.

`nsects'
     An `UInt32' number containing the number of sections in this
     byte-code file.


File: js.info,  Node: Code Section,  Next: Constants Section,  Prev: File Header,  Up: Byte-Code File Format

Code Section
------------

