@zappdev/cli 0.1.0 → 0.2.0

package/native/vendor/quickjs-ng/docs/docs/stdlib.md

@@ -0,0 +1,605 @@
+---
+sidebar_position: 5
+---
+
+# Standard library
+
+The standard libary is provided as part of the `qjs` executable and the `quickjs-libc.c` source file
+and it's not part of the core engine.
+
+## Globals
+
+### `argv0`
+
+Provides the executable path.
+
+### `scriptArgs`
+
+Provides the command line arguments. The first argument is the script name.
+
+### `print(...args)`
+
+Print the arguments separated by spaces and a trailing newline.
+
+### `console.log(...args)`
+
+Same as `print()`.
+
+### `navigator.userAgent`
+
+Returns `quickjs-ng/<version>`.
+
+### `gc()`
+
+Shorthand for `std.gc()`.
+
+## `qjs:bjson` module
+
+### `bjson.write(obj, [flags])`
+
+Serializes the given object into the QuickJS internal serialization format.
+Returns an ArrayBuffer with the serialized data.
+
+Supported flags:
+
+- `WRITE_OBJ_BYTECODE`: allow serializing functions and modules
+- `WRITE_OBJ_REFERENCE`: allow serializing object references
+- `WRITE_OBJ_SAB`: allow serializing SharedArrayBuffer instances
+- `WRITE_OBJ_STRIP_DEBUG`: strip debugging information when serializing
+- `WRITE_OBJ_STRIP_SOURCE`: strip the source information when serializing
+
+### `bjson.read(buf, [pos], [len], [flags])`
+
+De-serialize the given ArrayBuffer (in QuickJS internal serialization format) back into a JavaScript value.
+
+Supported flags:
+
+- `READ_OBJ_BYTECODE`: allow de-serializing functions and modules
+- `READ_OBJ_REFERENCE`: allow de-serializing object references
+
+Security caveat: `bjson.read()` is resilient against malformed input (the wire
+format is checksummed) but is not designed to withstand adversarial attacks.
+Don't feed it untrusted input.
+
+## `qjs:os` module
+
+The `os` module provides Operating System specific functions:
+
+- low level file access
+- signals
+- timers
+- basic asynchronous I/O
+- workers (threads)
+
+The OS functions usually return 0 if OK or an OS specific negative
+error code.
+
+### `open(filename, flags, mode = 0o666)`
+
+Open a file. Return a handle or < 0 if error.
+
+Supported flags:
+
+- `O_RDONLY`
+- `O_WRONLY`
+- `O_RDWR`
+- `O_APPEND`
+- `O_CREAT`
+- `O_EXCL`
+- `O_TRUNC`
+
+POSIX open flags.
+
+- `O_TEXT`
+
+(Windows specific). Open the file in text mode. The default is binary mode.
+
+### `close(fd)`
+
+Close the file handle `fd`.
+
+### `seek(fd, offset, whence)`
+
+Seek in the file. Use `std.SEEK_*` for
+`whence`. `offset` is either a number or a BigInt. If
+`offset` is a BigInt, a BigInt is returned too.
+
+### `read(fd, buffer, offset, length)`
+
+Read `length` bytes from the file handle `fd` to the
+ArrayBuffer `buffer` at byte position `offset`.
+Return the number of read bytes or < 0 if error.
+
+### `write(fd, buffer, offset, length)`
+
+Write `length` bytes to the file handle `fd` from the
+ArrayBuffer `buffer` at byte position `offset`.
+Return the number of written bytes or < 0 if error.
+
+### `isatty(fd)`
+
+Return `true` is `fd` is a TTY (terminal) handle.
+
+### `ttyGetWinSize(fd)`
+
+Return the TTY size as `[width, height]` or `null` if not available.
+
+### `ttySetRaw(fd)`
+
+Set the TTY in raw mode.
+
+### `remove(filename)`
+
+Remove a file. Return 0 if OK or `-errno`.
+
+### `rename(oldname, newname)`
+
+Rename a file. Return 0 if OK or `-errno`.
+
+### `realpath(path)`
+
+Return `[str, err]` where `str` is the canonicalized absolute
+pathname of `path` and `err` the error code.
+
+### `getcwd()`
+
+Return `[str, err]` where `str` is the current working directory
+and `err` the error code.
+
+### `exePath()`
+
+Returns the full path of the current executable or `undefined` if not available / supported.
+
+### `chdir(path)`
+
+Change the current directory. Return 0 if OK or `-errno`.
+
+### `mkdir(path, mode = 0o777)`
+
+Create a directory at `path`. Return 0 if OK or `-errno`.
+
+### `mkdtemp(pattern = "tmpXXXXXX")`
+
+Create a temporary directory. `XXXXXX` must be at the end of the pattern
+string and is replaced with a random name. The directory is created with
+file mode `0o700`.
+
+Return `[path, err]` where `path` is a string and `err` is 0 or `-errno`.
+
+Not available on Windows and WASI.
+
+### `mkstemp(pattern = "tmpXXXXXX")`
+
+Create a temporary file and open it. `XXXXXX` must be at the end of the
+pattern string and is replaced with a random name. The file is created with
+file mode `0o600` and opened in read/write mode.
+
+Return `[path, fd]` where `path` is a string and `fd` is the file descriptor
+or `-errno`, i.e., the error code if less than zero.
+
+Unlike `std.tmpfile()`, the file is not automatically deleted on close.
+
+See also `std.fdopen()`.
+
+Not available on Windows and WASI.
+
+### `stat(path)` / `lstat(path)`
+
+Return `[obj, err]` where `obj` is an object containing the
+file status of `path`. `err` is the error code. The
+following fields are defined in `obj`: `dev`, `ino`, `mode`, `nlink`,
+`uid`, `gid`, `rdev`, `size`, `blocks`, `atime`, `mtime`, `ctime`. The times are
+specified in milliseconds since 1970. `lstat()` is the same as
+`stat()` excepts that it returns information about the link
+itself.
+
+- `S_IFMT`
+- `S_IFIFO`
+- `S_IFCHR`
+- `S_IFDIR`
+- `S_IFBLK`
+- `S_IFREG`
+- `S_IFSOCK`
+- `S_IFLNK`
+- `S_ISGID`
+- `S_ISUID`
+
+Constants to interpret the `mode` property returned by
+`stat()`. They have the same value as in the C system header
+`sys/stat.h`.
+
+### `utimes(path, atime, mtime)`
+
+Change the access and modification times of the file `path`. The
+times are specified in milliseconds since 1970. Return 0 if OK or `-errno`.
+
+### `symlink(target, linkpath)`
+
+Create a link at `linkpath` containing the string `target`. Return 0 if OK or `-errno`.
+
+### `readlink(path)`
+
+Return `[str, err]` where `str` is the link target and `err`
+the error code.
+
+### `readdir(path)`
+
+Return `[array, err]` where `array` is an array of strings
+containing the filenames of the directory `path`. `err` is
+the error code. `array` contains at least `"."` and `".."`
+if successful.
+
+### `setReadHandler(fd, func)`
+
+Add a read handler to the file handle `fd`. `func` is called
+each time there is data pending for `fd`. A single read handler
+per file handle is supported. Use `func = null` to remove the
+handler.
+
+### `setWriteHandler(fd, func)`
+
+Add a write handler to the file handle `fd`. `func` is
+called each time data can be written to `fd`. A single write
+handler per file handle is supported. Use `func = null` to remove
+the handler.
+
+### `signal(signal, func)`
+
+Call the function `func` when the signal `signal`
+happens. Only a single handler per signal number is supported. Use
+`null` to set the default handler or `undefined` to ignore
+the signal. Signal handlers can only be defined in the main thread.
+
+- `SIGINT`
+- `SIGABRT`
+- `SIGFPE`
+- `SIGILL`
+- `SIGSEGV`
+- `SIGTERM`
+
+POSIX signal numbers.
+
+### `kill(pid, sig)`
+
+Send the signal `sig` to the process `pid`.
+
+### `exec(args[, options])`
+
+Execute a process with the arguments `args`. `options` is an
+object containing optional parameters:
+
+- `block` - Boolean (default = true). If true, wait until the process is
+  terminated. In this case, `exec` return the exit code if positive
+  or the negated signal number if the process was interrupted by a
+  signal. If false, do not block and return the process id of the child.
+- `usePath` - Boolean (default = true). If true, the file is searched in the
+  `PATH` environment variable.
+- `file` - String (default = `args[0]`). Set the file to be executed.
+- `cwd` - String. If present, set the working directory of the new process.
+- `stdin`, `stdout`, `stderr` - If present, set the handle in the child for stdin, stdout or stderr.
+- `env` - Object. If present, set the process environment from the object
+  key-value pairs. Otherwise use the same environment as the current
+  process.
+- `uid` - Integer. If present, the process uid with `setuid`.
+- `gid` - Integer. If present, the process gid with `setgid`.
+- `groups` - Array of integer. If present, the supplementary
+   group IDs with `setgroup`.
+
+### `waitpid(pid, options)`
+
+`waitpid` Unix system call. Return the array `[ret, status]`.
+`ret` contains `-errno` in case of error.
+
+- `WNOHANG`
+
+Constant for the `options` argument of `waitpid`.
+
+### `dup(fd)`
+
+`dup` Unix system call.
+
+### `dup2(oldfd, newfd)`
+
+`dup2` Unix system call.
+
+### `pipe()`
+
+`pipe` Unix system call. Return two handles as `[read_fd, write_fd]` or null in case of error.
+
+### `sleep(delay_ms)`
+
+Sleep during `delay_ms` milliseconds.
+
+### `sleepAsync(delay_ms)`
+
+Asynchronouse sleep during `delay_ms` milliseconds. Returns a promise. Example:
+
+```js
+await os.sleepAsync(500);
+```
+
+### `setTimeout(func, delay)`
+
+Call the function `func` after `delay` ms. Return a timer ID.
+
+### `clearTimeout(id)`
+
+Cancel a timer.
+
+### `platform`
+
+Return a string representing the platform: `"linux"`, `"darwin"`, `"win32"` or `"js"`.
+
+### `Worker(module_filename)`
+
+Constructor to create a new thread (worker) with an API close to that of
+`WebWorkers`. `module_filename` is a string specifying the
+module filename which is executed in the newly created thread. As for
+dynamically imported module, it is relative to the current script or
+module path. Threads normally don't share any data and communicate
+between each other with messages. Nested workers are not supported. An
+example is available in `tests/test_worker.js`.
+
+The worker class has the following static properties:
+
+- `parent` - In the created worker, `Worker.parent` represents the parent
+  worker and is used to send or receive messages.
+
+The worker instances have the following properties:
+
+- `postMessage(msg)` - Send a message to the corresponding worker. `msg` is cloned in
+  the destination worker using an algorithm similar to the `HTML`
+  structured clone algorithm. `SharedArrayBuffer` are shared
+  between workers.
+
+- `onmessage` - Getter and setter. Set a function which is called each time a
+  message is received. The function is called with a single
+  argument. It is an object with a `data` property containing the
+  received message. The thread is not terminated if there is at least
+  one non `null` `onmessage` handler.
+
+## `qjs:std` module
+
+The `std` module provides wrappers to libc (`stdlib.h` and `stdio.h`) and a few other utilities.
+
+### `exit(n)`
+
+Exit the process.
+
+### `evalScript(str, options = undefined)`
+
+Evaluate the string `str` as a script (global
+eval). `options` is an optional object containing the following
+optional properties:
+
+- `backtrace_barrier` - Boolean (default = false). If true, error backtraces do not list the
+  stack frames below the evalScript.
+- `async` - Boolean (default = false). If true, `await` is accepted in the
+  script and a promise is returned. The promise is resolved with an
+  object whose `value` property holds the value returned by the
+  script.
+
+### `loadScript(filename)`
+
+Evaluate the file `filename` as a script (global eval).
+
+### `loadFile(filename, [options])`
+
+Load the file `filename` and return it as a string assuming UTF-8
+encoding. Return `null` in case of I/O error.
+
+If `options.binary` is set to `true` a `Uint8Array` is returned instead.
+
+### `writeFile(filename, data)`
+
+Create the file `filename` and write `data` into it.
+
+`data` can be a string, a typed array or an `ArrayBuffer`. `undefined` is
+treated as the empty string.
+
+When `data` is a string, the file is opened in text mode; otherwise it is
+opened in binary mode. (This distinction is only relevant on Windows.)
+
+Throws an exception if the file cannot be created or written to.
+
+### `open(filename, flags, errorObj = undefined)`
+
+Open a file (wrapper to the libc `fopen()`). Return the FILE
+object or `null` in case of I/O error. If `errorObj` is not
+undefined, set its `errno` property to the error code or to 0 if
+no error occurred.
+
+### `popen(command, flags, errorObj = undefined)`
+
+Open a process by creating a pipe (wrapper to the libc
+`popen()`). Return the FILE
+object or `null` in case of I/O error. If `errorObj` is not
+undefined, set its `errno` property to the error code or to 0 if
+no error occurred.
+
+### `fdopen(fd, flags, errorObj = undefined)`
+
+Open a file from a file handle (wrapper to the libc
+`fdopen()`). Return the FILE
+object or null` in case of I/O error. If `errorObj` is not
+undefined, set its `errno` property to the error code or to 0 if
+no error occurred.
+
+### `tmpfile(errorObj = undefined)`
+
+Open a temporary file. Return the FILE
+object or `null` in case of I/O error. If `errorObj` is not
+undefined, set its `errno` property to the error code or to 0 if
+no error occurred.
+
+### `puts(str)`
+
+Equivalent to `std.out.puts(str)`.
+
+### `printf(fmt, ...args)`
+
+Equivalent to `std.out.printf(fmt, ...args)`.
+
+### `sprintf(fmt, ...args)`
+
+Equivalent to the libc sprintf().
+
+### `in`, `out`, `err`
+
+Wrappers to the libc file `stdin`, `stdout`, `stderr`.
+
+### `Error`
+
+Enumeration object containing the integer value of common errors
+(additional error codes may be defined):
+
+- `EINVAL`
+- `EIO`
+- `EACCES`
+- `EEXIST`
+- `ENOSPC`
+- `ENOSYS`
+- `EBUSY`
+- `ENOENT`
+- `EPERM`
+- `EPIPE`
+
+### `strerror(errno)`
+
+Return a string that describes the error `errno`.
+
+### `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.
+
+### `getenv(name)`
+
+Return the value of the environment variable `name` or
+`undefined` if it is not defined.
+
+### `setenv(name, value)`
+
+Set the value of the environment variable `name` to the string
+`value`.
+
+### `unsetenv(name)`
+
+Delete the environment variable `name`.
+
+### `getenviron()`
+
+Return an object containing the environment variables as key-value pairs.
+
+### `urlGet(url, options = undefined)`
+
+Download `url` using the `curl` command line
+utility. `options` is an optional object containing the following
+optional properties:
+
+- `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.
+- `full` - Boolean (default = false). If true, return the an object contains
+  the properties `response` (response content),
+  `responseHeaders` (headers separated by CRLF), `status`
+  (status code). `response` is `null` is case of protocol or
+  network error. If `full` is false, only the response is
+  returned if the status is between 200 and 299. Otherwise `null`
+  is returned.
+
+### `FILE`
+
+File object.
+
+#### `close()`
+
+Close the file. Return 0 if OK or `-errno` in case of I/O error.
+
+#### `puts(str)`
+
+Outputs the string with the UTF-8 encoding.
+
+#### `printf(fmt, ...args)`
+
+Formatted printf.
+
+The same formats as the standard C library `printf` are
+supported. Integer format types (e.g. `%d`) truncate the Numbers
+or BigInts to 32 bits. Use the `l` modifier (e.g. `%ld`) to
+truncate to 64 bits.
+
+#### `flush()`
+
+Flush the buffered file.
+
+#### `seek(offset, whence)`
+
+Seek to a give file position (whence is
+`std.SEEK_*`). `offset` can be a number or a BigInt. Return
+0 if OK or `-errno` in case of I/O error.
+
+- `SEEK_SET`
+- `SEEK_CUR`
+- `SEEK_END`
+
+Constants for seek().
+
+#### `tell()`
+
+Return the current file position.
+
+#### `tello()`
+
+Return the current file position as a BigInt.
+
+#### `eof()`
+
+Return true if end of file.
+
+#### `fileno()`
+
+Return the associated OS handle.
+
+#### `error()`
+
+Return true if there was an error.
+
+#### `clearerr()`
+
+Clear the error indication.
+
+#### `read(buffer, position = 0, length = buffer.length)`
+
+Read `length` bytes from the file to the ArrayBuffer `buffer` at byte
+position `position`. Wrapper to the libc function `fread`.
+
+#### `write(buffer, position = 0, length = buffer.length)`
+
+Write `length` bytes to the file from the ArrayBuffer or string `buffer`
+at byte position `position`. Wrapper to the libc function `fwrite`.
+
+#### `getline()`
+
+Return the next line from the file, assuming UTF-8 encoding, excluding
+the trailing line feed.
+
+#### `readAsArrayBuffer(max_size = undefined)`
+
+Read `max_size` bytes from the file and return them as an ArrayBuffer.
+If `max_size` is not present, the file is read until its end.
+
+#### `readAsString(max_size = undefined)`
+
+Read `max_size` bytes from the file and return them as a string
+assuming UTF-8 encoding. If `max_size` is not present, the file
+is read until its end.
+
+#### `getByte()`
+
+Return the next byte from the file. Return -1 if the end of file is reached.
+
+#### `putByte(c)`
+
+Write one byte to the file.

package/native/vendor/quickjs-ng/docs/docs/supported_platforms.md

@@ -0,0 +1,20 @@
+---
+sidebar_position: 8
+---
+
+# Supported Platforms
+
+|  System | Supported versions | Notes |
+|---|---|---|
+| GNU/Linux | * | glibc and musl are supported |
+| macOS | macOS >= 11 | Currently supported macOS releases |
+| Windows | >= Windows 7* | VS >= 2022 and Clang are supported; requires `<stdatomic.h>` |
+| FreeBSD | * | Limited testing |
+| OpenBSD | * | Limited testing |
+| NetBSD | * | Limited testing |
+| Android | NDK >= 26.0.10792818 | Limited testing |
+| iOS | * | Limited testing |
+| MinGW | MinGW-w64 | |
+| Other | N/A | Missing? Open a PR! |
+
+- `*`: Windows 7 is EOL and only supported in this project as long as it doesn't interfere with its progress.