including modules, asynchronous generators, proxies and BigInt.
It supports mathematical extensions such as big decimal float float
numbers (BigDecimal), big binary floating point numbers (BigFloat),
and operator overloading.
@section Main Features
@itemize
@item Small and easily embeddable: just a few C files, no external dependency, 210 KiB of x86 code for a simple ``hello world'' program.
@item Fast interpreter with very low startup time: runs the 69000 tests of the ECMAScript Test Suite@footnote{@url{https://github.com/tc39/test262}} in about 95 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). Many
features from the upcoming ES2020 specification
@footnote{@url{https://tc39.github.io/ecma262/}} are also supported.
@item Passes nearly 100% of the ECMAScript Test Suite tests when selecting the ES2019 features.
@item 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.
thru @code{eshost}. Unless you want to compare QuickJS with other
engines under the same conditions, we do not recommend to run the
tests this way as it is much slower (typically half an hour instead of
about 100 seconds).
@chapter Specifications
@section Language support
@subsection ES2019 support
The ES2019 specification 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 (although 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 fully backward compatible with
standard Javascript. See @code{jsbignum.pdf} for more information.
@itemize
@item @code{BigDecimal} support: arbitrary large floating point numbers in base 10.
@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, options = undefined)
Evaluate the string @code{str} as a script (global
eval). @code{options} is an optional object containing the following
optional properties:
@table @code
@item backtrace_barrier
Boolean (default = false). If true, error backtraces do not list the
stack frames below the evalScript.
@end table
@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 popen(command, flags)
Open a process by creating a pipe (wrapper to the libc @code{popen()}). Throws
@code{std.Error} in case of I/O error.
@item fdopen(fd, flags)
Open a file from a file handle (wrapper to the libc
@code{fdopen()}). 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 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.
@item urlGet(url, options = undefined)
Download @code{url} using the @file{curl} command line
utility. @code{options} is an optional object containing the following
optional properties:
@table @code
@item binary
Boolean (default = false). If true, the response is an ArrayBuffer
instead of a string. When a string is returned, the data is assumed
to be UTF-8 encoded.
@item full
Boolean (default = false). If true, return the an object contains
the properties @code{response} (response content),
@code{responseHeaders} (headers separated by CRLF), @code{status}
(status code). If @code{full} is false, only the response is
returned if the status is between 200 and 299. Otherwise an
@code{std.Error} exception is raised.
@end table
@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 readAsString(max_size = undefined)
Read @code{max_size} bytes from the file and return them as a string
assuming UTF-8 encoding. If @code{max_size} is not present, the file
is read up its end.
@item getByte()
Return the next byte from the file. Return -1 if the end of file is reached.
@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 realpath(path)
Return @code{[str, err]} where @code{str} is the canonicalized absolute
pathname of @code{path} and @code{err} the error code.
@item getcwd()
Return @code{[str, err]} where @code{str} is the current working directory
