dust3d/thirdparty/quickjs/quickjs-2019-07-09-dust3d/doc/quickjs.texi

\input texinfo

@iftex
@afourpaper
@headings double
@end iftex

@titlepage
@afourpaper
@sp 7
@center @titlefont{QuickJS Javascript Engine}
@sp 3
@end titlepage

@setfilename spec.info
@settitle QuickJS Javascript Engine

@contents

@chapter Introduction

QuickJS is a small and embeddable Javascript engine. It supports the
ES2019 specification including modules, asynchronous
generators and proxies.

It optionally supports mathematical extensions such as big integers
(BigInt), big floating point numbers (BigFloat) and operator
overloading.

@section Main Features

@itemize

@item Small and easily embeddable: just a few C files, no external dependency, 180 KiB of x86 code for a simple ``hello world'' program.

@item Fast interpreter with very low startup time: runs the 56000 tests of the ECMAScript Test Suite@footnote{@url{https://github.com/tc39/test262}} in about 100 seconds on a single core of a desktop PC. The complete life cycle of a runtime instance completes in less than 300 microseconds.

@item Almost complete ES2019 support including modules, asynchronous
generators and full Annex B support (legacy web compatibility).

@item Passes 100% of the ECMAScript Test Suite tests.

@item Can compile Javascript sources to executables with no external dependency.

@item Garbage collection using reference counting (to reduce memory usage and have deterministic behavior) with cycle removal.

@item Mathematical extensions: BigInt, BigFloat, operator overloading, bigint mode, math mode.

@item Command line interpreter with contextual colorization and completion implemented in Javascript.

@item Small built-in standard library with C library wrappers.

@end itemize

@chapter Usage

@section Installation

A Makefile is provided to compile the engine on Linux or MacOS/X.  A
preliminary Windows support is available thru cross compilation on a
Linux host with the MingGW tools.

Edit the top of the @code{Makefile} if you wish to select specific
options then run @code{make}.

You can type @code{make install} as root if you wish to install the binaries and support files to
@code{/usr/local} (this is not necessary to use QuickJS).

@section Quick start

@code{qjs} is the command line interpreter (Read-Eval-Print Loop). You can pass
Javascript files and/or expressions as arguments to execute them:

@example
./qjs examples/hello.js
@end example

@code{qjsc} is the command line compiler:

@example
./qjsc -o hello examples/hello.js
./hello
@end example

generates a @code{hello} executable with no external dependency.

@code{qjsbn} and @code{qjscbn} are the corresponding interpreter and
compiler with the mathematical extensions:

@example
./qjsbn examples/pi.js 1000
@end example

displays 1000 digits of PI.

@example
./qjsbnc -o pi examples/pi.js
./pi 1000
@end example

compiles and executes the PI program.

@section Command line options

@subsection @code{qjs} interpreter

@verbatim
usage: qjs [options] [files]
@end verbatim

Options are:
@table @code
@item -h
@item --help
List options.

@item -e @code{EXPR}
@item --eval @code{EXPR}
Evaluate EXPR.

@item -i
@item --interactive
Go to interactive mode (it is not the default when files are provided on the command line).

@item -m
@item --module
Load as ES6 module (default if .mjs file extension).

@end table

Advanced options are:

@table @code
@item -d
@item --dump
Dump the memory usage stats.

@item -q
@item --quit
just instantiate the interpreter and quit.

@end table

@subsection @code{qjsc} compiler

@verbatim
usage: qjsc [options] [files]
@end verbatim

Options are:
@table @code
@item -c
Only output bytecode in a C file. The default is to output an executable file.
@item -e 
Output @code{main()} and bytecode in a C file. The default is to output an
executable file.
@item -o output
Set the output filename (default = @file{out.c} or @file{a.out}).

@item -N cname
Set the C name of the generated data.

@item -m
Compile as Javascript module (default if @file{.mjs} extension).

@item -M module_name[,cname]
Add initialization code for an external C module. See the
@code{c_module} example.

@item -x
Byte swapped output (only used for cross compilation).

@item -flto
Use link time optimization. The compilation is slower but the
executable is smaller and faster. This option is automatically set
when the @code{-fno-x} options are used.

@item -fno-[eval|string-normalize|regexp|json|proxy|map|typedarray|promise]
Disable selected language features to produce a smaller executable file.

@end table

@section @code{qjscalc} application

The @code{qjscalc} application is a superset of the @code{qjsbn}
command line interpreter implementing a Javascript calculator with
arbitrarily large integer and floating point numbers, fractions,
complex numbers, polynomials and matrices. The source code is in
@file{qjscalc.js}. More documentation and a web version are available at
@url{http://numcalc.com}.

@section Built-in tests

Run @code{make test} to run the few built-in tests included in the
QuickJS archive.

@section Test262 (ECMAScript Test Suite)

A test262 runner is included in the QuickJS archive.

For reference, the full test262 tests are provided in the archive
@file{qjs-tests-yyyy-mm-dd.tar.xz}. You just need to untar it into the
QuickJS source code directory.

Alternatively, the test262 tests can be installed with:

@example
git clone https://github.com/tc39/test262.git test262
cd test262
git checkout 94b1e80ab3440413df916cd56d29c5a2fa2ac451
patch -p1 < ../tests/test262.patch
cd ..
@end example

The patch adds the implementation specific @code{harness} functions
and optimizes the inefficient RegExp character classes and Unicode
property escapes tests (the tests themselves are not modified, only a
slow string initialization function is optimized).

The tests can be run with
@example
make test2
@end example

For more information, run @code{./run-test262} to see the options of
the test262 runner. The configuration files @code{test262.conf} and
@code{test262bn.conf} contain the options to run the various tests.

@chapter Specifications

@section Language support

@subsection ES2019 support

The ES2019 specification
@footnote{@url{https://tc39.github.io/ecma262/}} is almost fully
supported including the Annex B (legacy web compatibility) and the
Unicode related features. The following features are not supported
yet:

@itemize

@item Realms (althougth the C API supports different runtimes and contexts)

@item Tail calls@footnote{We believe the current specification of tails calls is too complicated and presents limited practical interests.}

@end itemize

@subsection JSON

The JSON parser is currently more tolerant than the specification.

@subsection ECMA402

ECMA402 (Internationalization API) is not supported.

@subsection Extensions

@itemize

@item The directive @code{"use strip"} indicates that the debug information (including the source code of the functions) should not be retained to save memory. As @code{"use strict"}, the directive can be global to a script or local to a function.

@item The first line of a script beginning with @code{#!} is ignored.

@end itemize

@subsection Mathematical extensions

The mathematical extensions are available in the @code{qjsbn} version and are fully
backward compatible with standard Javascript. See @code{jsbignum.pdf}
for more information.

@itemize

@item The @code{BigInt} (big integers) TC39 proposal is supported.

@item @code{BigFloat} support: arbitrary large floating point numbers in base 2.

@item Operator overloading.

@item The directive @code{"use bigint"} enables the bigint mode where integers are @code{BigInt} by default.

@item The directive @code{"use math"} enables the math mode where the division and power operators on integers produce fractions. Floating point literals are @code{BigFloat} by default and integers are @code{BigInt} by default.

@end itemize

@section Modules

ES6 modules are fully supported. The default name resolution is the
following:

@itemize

@item Module names with a leading @code{.} or @code{..} are relative
to the current module path.

@item Module names without a leading @code{.} or @code{..} are system
modules, such as @code{std} or @code{os}.

@item Module names ending with @code{.so} are native modules using the
QuickJS C API.

@end itemize

@section Standard library

The standard library is included by default in the command line
interpreter. It contains the two modules @code{std} and @code{os} and
a few global objects.

@subsection Global objects

@table @code
@item scriptArgs
Provides the command line arguments. The first argument is the script name.
@item print(...args)
Print the arguments separated by spaces and a trailing newline.
@item console.log(...args)
Same as print().

@end table

@subsection @code{std} module

The @code{std} module provides wrappers to the libc @file{stdlib.h}
and @file{stdio.h} and a few other utilities.

Available exports:

@table @code

@item exit(n)
Exit the process.

@item evalScript(str)
Evaluate the string @code{str} as a script (global eval).

@item loadScript(filename)
Evaluate the file @code{filename} as a script (global eval).

@item Error(errno)

@code{std.Error} constructor. Error instances contain the field
@code{errno} (error code) and @code{message} (result of
@code{std.Error.strerror(errno)}).

The constructor contains the following fields:

  @table @code
  @item EINVAL
  @item EIO
  @item EACCES
  @item EEXIST
  @item ENOSPC
  @item ENOSYS
  @item EBUSY
  @item ENOENT
  @item EPERM
  @item EPIPE
    Integer value of common errors (additional error codes may be defined).
  @item strerror(errno)
    Return a string that describes the error @code{errno}.
  @end table

@item open(filename, flags)
Open a file (wrapper to the libc @code{fopen()}). Throws 
@code{std.Error} in case of I/O error.

@item tmpfile()
Open a temporary file. Throws @code{std.Error} in case of I/O error.

@item puts(str)
Equivalent to @code{std.out.puts(str)}.

@item printf(fmt, ...args)
Equivalent to @code{std.out.printf(fmt, ...args)}

@item sprintf(fmt, ...args)
Equivalent to the libc sprintf().

@item in
@item out
@item err
Wrappers to the libc file @code{stdin}, @code{stdout}, @code{stderr}.

@item SEEK_SET
@item SEEK_CUR
@item SEEK_END
Constants for seek().

@item global
Reference to the global object.

@item gc()
Manually invoke the cycle removal algorithm. The cycle removal
algorithm is automatically started when needed, so this function is
useful in case of specific memory constraints or for testing.

@item getenv(name)
Return the value of the environment variable @code{name} or
@code{undefined} if it is not defined.

@end table

FILE prototype:

@table @code
@item close()
Close the file.
@item puts(str)
Outputs the string with the UTF-8 encoding.
@item printf(fmt, ...args)
Formatted printf, same formats as the libc printf.
@item flush()
Flush the buffered file.
@item seek(offset, whence)
Seek to a give file position (whence is @code{std.SEEK_*}). Throws a
@code{std.Error} in case of I/O error.
@item tell()
Return the current file position.
@item eof()
Return true if end of file.
@item fileno()
Return the associated OS handle.

@item read(buffer, position, length)
Read @code{length} bytes from the file to the ArrayBuffer @code{buffer} at byte
position @code{position} (wrapper to the libc @code{fread}).

@item write(buffer, position, length)
Write @code{length} bytes to the file from the ArrayBuffer @code{buffer} at byte
position @code{position} (wrapper to the libc @code{fread}).

@item getline()
Return the next line from the file, assuming UTF-8 encoding, excluding
the trailing line feed.

@item getByte()
Return the next byte from the file.

@item putByte(c)
Write one byte to the file.
@end table

@subsection @code{os} module

The @code{os} module provides Operating System specific functions:

@itemize
@item low level file access
@item signals
@item timers
@item asynchronous I/O
@end itemize

The OS functions usually return 0 if OK or an OS specific negative
error code.

Available exports:

@table @code
@item open(filename, flags, mode = 0o666)
Open a file. Return a handle or < 0 if error.

@item O_RDONLY
@item O_WRONLY        
@item O_RDWR
@item O_APPEND
@item O_CREAT
@item O_EXCL
@item O_TRUNC
POSIX open flags.

@item O_TEXT
(Windows specific). Open the file in text mode. The default is binary mode.

@item close(fd)
Close the file handle @code{fd}.

@item seek(fd, offset, whence)
Seek in the file. Use @code{std.SEEK_*} for @code{whence}.

@item read(fd, buffer, offset, length)
Read @code{length} bytes from the file handle @code{fd} to the
ArrayBuffer @code{buffer} at byte position @code{offset}.
Return the number of read bytes or < 0 if error.

@item write(fd, buffer, offset, length)
Write @code{length} bytes to the file handle @code{fd} from the
ArrayBuffer @code{buffer} at byte position @code{offset}.
Return the number of written bytes or < 0 if error.

@item isatty(fd)
Return @code{true} is @code{fd} is a TTY (terminal) handle.

@item ttyGetWinSize(fd)
Return the TTY size as @code{[width, height]} or @code{null} if not available.

@item ttySetRaw(fd)
Set the TTY in raw mode.

@item remove(filename)
Remove a file. Return 0 if OK or < 0 if error.

@item rename(oldname, newname)
Rename a file. Return 0 if OK or < 0 if error.

@item setReadHandler(fd, func)
Add a read handler to the file handle @code{fd}. @code{func} is called
each time there is data pending for @code{fd}. A single read handler
per file handle is supported. Use @code{func = null} to remove the
hander.

@item setWriteHandler(fd, func)
Add a write handler to the file handle @code{fd}. @code{func} is
called each time data can be written to @code{fd}. A single write
handler per file handle is supported. Use @code{func = null} to remove
the hander.

@item signal(signal, func)
Call the function @code{func} when the signal @code{signal}
happens. Only a single handler per signal number is supported. Use
@code{null} to set the default handler or @code{undefined} to ignore
the signal.

@item SIGINT
@item SIGABRT
@item SIGFPE
@item SIGILL
@item SIGSEGV
@item SIGTERM
POSIX signal numbers.

@item setTimeout(delay, func)
Call the function @code{func} after @code{delay} ms. Return a handle
to the timer.

@item clearTimer(handle)
Cancel a timer.

@item platform
Return a string representing the platform: @code{"linux"}, @code{"darwin"},
@code{"win32"} or @code{"js"}.

@end table

@section QuickJS C API

The C API was designed to be simple and efficient. The C API is
defined in the header @code{quickjs.h}.

@subsection Runtime and contexts

@code{JSRuntime} represents a Javascript runtime corresponding to an
object heap. Several runtimes can exist at the same time but they
cannot exchange objects. Inside a given runtime, no multi-threading is
supported.

@code{JSContext} represents a Javascript context (or Realm). Each
JSContext has its own global objects and system objects. There can be
several JSContexts per JSRuntime and they can share objects, similary
to frames of the same origin sharing Javascript objects in a
web browser.

@subsection JSValue

@code{JSValue} represents a Javascript value which can be a primitive
type or an object. Reference counting is used, so it is important to
explicitely duplicate (@code{JS_DupValue()}, increment the reference
count) or free (@code{JS_FreeValue()}, decrement the reference count)
JSValues.

@subsection C functions

C functions can be created with
@code{JS_NewCFunction()}. @code{JS_SetPropertyFunctionList()} is a
shortcut to easily add functions, setters and getters properties to a
given object.

Unlike other embedded Javascript engines, there is no implicit stack,
so C functions get their parameters as normal C parameters. As a
general rule, C functions take constant @code{JSValue}s as parameters
(so they don't need to free them) and return a newly allocated (=live)
@code{JSValue}.

@subsection Exceptions

Exceptions: most C functions can return a Javascript exception. It
must be explicitely tested and handled by the C code. The specific
@code{JSValue} @code{JS_EXCEPTION} indicates that an exception
occured. The actual exception object is stored in the
@code{JSContext} and can be retrieved with @code{JS_GetException()}.

@subsection Script evaluation

Use @code{JS_Eval()} to evaluate a script or module source.

If the script or module was compiled to bytecode with @code{qjsc},
@code{JS_EvalBinary()} achieves the same result. The advantage is that
no compilation is needed so it is faster and smaller because the compiler
can be removed from the executable if no @code{eval} is required.

Note: the bytecode format is linked to a given QuickJS
version. Moreover, no security check is done before its
execution. Hence the bytecode should not be loaded from untrusted
sources. That's why there is no option to output the bytecode to a
binary file in @code{qjsc}.

@subsection JS Classes

C opaque data can be attached to a Javascript object. The type of the
C opaque data is determined with the class ID (@code{JSClassID}) of
the object. Hence the first step is to register a new class ID and JS
class (@code{JS_NewClassID()}, @code{JS_NewClass()}). Then you can
create objects of this class with @code{JS_NewObjectClass()} and get or
set the C opaque point with
@code{JS_GetOpaque()}/@code{JS_SetOpaque()}.

When defining a new JS class, it is possible to declare a finalizer
which is called when the object is destroyed. A @code{gc_mark} method
can be provided so that the cycle removal algorithm can find the other
objects referenced by this object. Other methods are available to
define exotic object behaviors.

The Class ID are globally allocated (i.e. for all runtimes). The
JSClass are allocated per @code{JSRuntime}. @code{JS_SetClassProto()}
is used to define a prototype for a given class in a given
JSContext. @code{JS_NewObjectClass()} sets this prototype in the
created object.

Examples are available in @file{js_libc.c}.

@subsection C Modules

Native ES6 modules are supported and can be dynamically or statically
linked. Look at the @file{test_bjson} and @file{bjson.so}
examples. The standard library @file{js_libc.c} is also a good example
of a native module.

@subsection Memory handling

Use @code{JS_SetMemoryLimit()} to set a global memory allocation limit
to a given JSRuntime.

Custom memory allocation functions can be provided with
@code{JS_NewRuntime2()}.

The maximum system stack size can be set with @code{JS_SetMaxStackSize()}.

@subsection Execution timeout and interrupts

Use @code{JS_SetInterruptHandler()} to set a callback which is
regularly called by the engine when it is executing code. This
callback can be used to implement an execution timeout.

It is used by the command line interpreter to implement a
@code{Ctrl-C} handler.

@chapter Internals

@section Bytecode

The compiler generates bytecode directly with no intermediate
representation such as a parse tree, hence it is very fast. Several
optimizations passes are done over the generated bytecode.

A stack-based bytecode was chosen because it is simple and generates 
compact code.

For each function, the maximum stack size is computed at compile time so that
no runtime stack overflow tests are needed.

A separate compressed line number table is maintained for the debug
information.

Access to closure variables is optimized and is almost as fast as local
variables.

Direct @code{eval} in strict mode is optimized.

@section Executable generation

@subsection @code{qjsc} compiler

The @code{qjsc} compiler generates C sources from Javascript files. By
default the C sources are compiled with the system compiler
(@code{gcc} or @code{clang}).

The generated C source contains the bytecode of the compiled functions
or modules. If a full complete executable is needed, it also
contains a @code{main()} function with the necessary C code to initialize the
Javascript engine and to load and execute the compiled functions and
modules.

Javascript code can be mixed with C modules.

In order to have smaller executables, specific Javascript features can
be disabled, in particular @code{eval} or the regular expressions. The
code removal relies on the Link Time Optimization of the system
compiler.

@subsection Binary JSON

@code{qjsc} works by compiling scripts or modules and then serializing
them to a binary format. A subset of this format (without functions or
modules) can be used as binary JSON. The example @file{test_bjson.js}
shows how to use it.

Warning: the binary JSON format may change without notice, so it
should not be used to store persistent data. The @file{test_bjson.js}
example is only used to test the binary object format functions.

@section Runtime

@subsection Strings

Strings are stored either as an 8 bit or a 16 bit array of
characters. Hence random access to characters is always fast.

The C API provides functions to convert Javascript Strings to C UTF-8 encoded
strings. The most common case where the Javascript string contains
only ASCII characters involves no copying.

@subsection Objects

The object shapes (object prototype, property names and flags) are shared
between objects to save memory.

Arrays with no holes (except at the end of the array) are optimized.

TypedArray accesses are optimized.

@subsection Atoms

Object property names and some strings are stored as Atoms (unique
strings) to save memory and allow fast comparison. Atoms are
represented as a 32 bit integer. Half of the atom range is reserved for
immediate integer literals from @math{0} to @math{2^{31}-1}.

@subsection Numbers

Numbers are represented either as 32-bit signed integers or 64-bit IEEE-754
floating point values. Most operations have fast paths for the 32-bit
integer case.

@subsection Garbage collection

Reference counting is used to free objects automatically and
deterministically. A separate cycle removal pass is done when the allocated
memory becomes too large. The cycle removal algorithm only uses the
reference counts and the object content, so no explicit garbage
collection roots need to be manipulated in the C code.

@subsection JSValue

It is a Javascript value which can be a primitive type (such as
Number, String, ...) or an Object. NaN boxing is used in the 32-bit version
to store 64-bit floating point numbers. The representation is
optimized so that 32-bit integers and reference counted values can be
efficiently tested.

In 64-bit code, JSValue are 128-bit large and no NaN boxing is used. The
rationale is that in 64-bit code memory usage is less critical.

In both cases (32 or 64 bits), JSValue exactly fits two CPU registers,
so it can be efficiently returned by C functions.

@subsection Function call

The engine is optimized so that function calls are fast. The system
stack holds the Javascript parameters and local variables.

@section RegExp

A specific regular expression engine was developped. It is both small
and efficient and supports all the ES2019 features including the
Unicode properties. As the Javascript compiler, it directly generates
bytecode without a parse tree.

Backtracking with an explicit stack is used so that there is no
recursion on the system stack. Simple quantizers are specifically
optimized to avoid recursions.

Infinite recursions coming from quantizers with empty terms are
avoided.

The full regexp library weights about 15 KiB (x86 code), excluding the
Unicode library.

@section Unicode

A specific Unicode library was developped so that there is no
dependency on an external large Unicode library such as ICU. All the
Unicode tables are compressed while keeping a reasonnable access
speed.

The library supports case conversion, Unicode normalization, Unicode
script queries, Unicode general category queries and all Unicode
binary properties.

The full Unicode library weights about 45 KiB (x86 code).

@section BigInt and BigFloat

BigInt and BigFloat are implemented with the @code{libbf}
library@footnote{@url{https://bellard.org/libbf}}. It weights about 60
KiB (x86 code) and provides arbitrary precision IEEE 754 floating
point operations and transcendental functions with exact rounding.

@chapter License

QuickJS is released under the MIT license.

Unless otherwise specified, the QuickJS sources are copyright Fabrice
Bellard and Charlie Gordon.

@bye