@amritk/nish-x86_64-linux 0.18.0 → 0.21.0

package/runtime/core/strings.mjs

@@ -0,0 +1,169 @@
+/**
+ * The strings of the core: an Nish string is its UTF-8 bytes, so every length
+ * and offset here counts bytes. Only the web's `TextEncoder` and `TextDecoder`
+ * are used, and the decoder keeps a leading byte-order mark, as a cut through
+ * the bytes must. Decoding is lossy where native is not: bytes that are not
+ * UTF-8, or a cut through a character, decode to U+FFFD, whose three bytes
+ * then change the string's length.
+ */
+import { panicIndex, panicSlice, toIndex } from "./checks.mjs";
+
+const ENCODER = new TextEncoder();
+const DECODER = new TextDecoder("utf-8", { ignoreBOM: true });
+
+/** The string `bytesOf` encoded last, and its bytes. */
+let lastString = "";
+let lastBytes = new Uint8Array(0);
+
+/**
+ * The UTF-8 bytes of `s`, which is what an Nish string holds. The last string
+ * encoded is kept with its bytes, so a loop of `s.charCodeAt(i)` over one
+ * string encodes it once rather than once per byte. Nothing here writes to
+ * the bytes it is handed.
+ */
+function bytesOf(s) {
+  if (s !== lastString) {
+    lastBytes = ENCODER.encode(s);
+    lastString = s;
+  }
+  return lastBytes;
+}
+
+/**
+ * `s.length`: UTF-8 byte length for strings (arrays keep their own `.length`).
+ * The engine's encoder outruns a count in JavaScript, and the loop condition
+ * `i < s.length` then leaves the bytes for the `s.charCodeAt(i)` it guards.
+ */
+export function strLen(x) {
+  return typeof x === "string" ? bytesOf(x).length : x.length;
+}
+
+/**
+ * `s?.length` in a `?.` chain: `undefined` when the chain has stopped at a
+ * `null` or `undefined` link, as `?.` answers, and the byte length otherwise.
+ * The chain is its argument, so it is evaluated once and its short circuit
+ * kept.
+ */
+export function strLenOpt(x) {
+  return x === null || x === undefined ? undefined : strLen(x);
+}
+
+/** `s.charCodeAt(i)`: the byte at `i`, bounds-checked as `a[i]` is (JavaScript answers NaN). */
+export function charCodeAt(s, i) {
+  const bytes = bytesOf(s);
+  const k = toIndex(i);
+  if (!(k >= 0 && k < bytes.length)) panicIndex(k, bytes.length);
+  return bytes[k];
+}
+
+/** `s.substring(a, b)`: JavaScript's clamp and swap, over byte offsets. */
+export function substring(s, a, b) {
+  const bytes = bytesOf(s);
+  const clamp = (v) => Math.max(0, Math.min(toIndex(v), bytes.length));
+  const from = clamp(a);
+  const to = b === undefined ? bytes.length : clamp(b);
+  return DECODER.decode(bytes.subarray(Math.min(from, to), Math.max(from, to)));
+}
+
+/**
+ * `s.slice(a, b)`: the bytes of `[a, b)` with no clamp, `b` defaulting to the
+ * byte length (WP15 §4). Out of range panics rather than clamping, so the two
+ * compares the native code emits are reproduced here rather than JavaScript's
+ * negative-from-the-end rule.
+ */
+export function slice(s, a, b) {
+  const bytes = bytesOf(s);
+  const from = toIndex(a);
+  const to = b === undefined ? bytes.length : toIndex(b);
+  if (!(from >= 0 && from <= to && to <= bytes.length)) panicSlice(from, to, bytes.length);
+  return DECODER.decode(bytes.subarray(from, to));
+}
+
+/** Whether `needle` sits in `bytes` at byte offset `at`. */
+function bytesAt(bytes, at, needle) {
+  if (!(at >= 0 && at + needle.length <= bytes.length)) return false;
+  for (let j = 0; j < needle.length; j++) {
+    if (bytes[at + j] !== needle[j]) return false;
+  }
+  return true;
+}
+
+/**
+ * `s.indexOf(sub, from)`: the first *byte* offset at or after `from`, or -1.
+ * `from` is converted as JavaScript's `ToIntegerOrInfinity` converts it (NaN
+ * is 0) and clamped into `[0, len]`, so an empty `sub` is found at `from`.
+ * The engine's `indexOf` over the bytes finds each candidate for `sub`'s
+ * first byte, and only those are compared in full.
+ */
+export function indexOf(s, sub, from) {
+  const haystack = bytesOf(s);
+  const at = from === undefined ? 0 : toIndex(from);
+  const start = Number.isNaN(at) ? 0 : Math.max(0, Math.min(at, haystack.length));
+  if (sub.length === 0) return start;
+  const needle = ENCODER.encode(sub);
+  const last = haystack.length - needle.length;
+  for (let i = haystack.indexOf(needle[0], start); i >= 0 && i <= last; i = haystack.indexOf(needle[0], i + 1)) {
+    if (bytesAt(haystack, i, needle)) return i;
+  }
+  return -1;
+}
+
+/** `nish_str_at`: whether `sub`'s bytes sit at byte offset `at`. */
+function occursAt(s, at, sub) {
+  return bytesAt(bytesOf(s), at, ENCODER.encode(sub));
+}
+
+export function startsWith(s, sub) {
+  return occursAt(s, 0, sub);
+}
+
+export function endsWith(s, sub) {
+  const bytes = bytesOf(s);
+  const needle = ENCODER.encode(sub);
+  return bytesAt(bytes, bytes.length - needle.length, needle);
+}
+
+/**
+ * `String.fromCharCode(c)`: the one-unit string of `c & 0xFF`. Under 128 that
+ * is the one byte native builds; from 128 it is the Latin-1 character, two
+ * UTF-8 bytes where native holds one (LANGUAGE.md's C row).
+ */
+export function fromCharCode(code) {
+  return String.fromCharCode(toIndex(code) & 0xff);
+}
+
+/**
+ * `String.fromBytes(bytes, start, end)`: the bytes of `[start, end)`, one
+ * code unit each as `fromCharCode` builds them, checked as `s.slice`'s range
+ * is and failing with its panic. The copy into a `Uint8Array` reduces each
+ * element to a byte as a `Buffer` store does, and the string is built a chunk
+ * at a time so that no call passes more arguments than the engine takes.
+ */
+export function fromBytes(bytes, start, end) {
+  const from = toIndex(start);
+  const to = toIndex(end);
+  if (!(from >= 0 && from <= to && to <= bytes.length)) panicSlice(from, to, bytes.length);
+  const out = new Uint8Array(to - from);
+  for (let i = from; i < to; i++) out[i - from] = bytes[i];
+  let text = "";
+  for (let i = 0; i < out.length; i += 8192) {
+    text += String.fromCharCode.apply(null, out.subarray(i, i + 8192));
+  }
+  return text;
+}
+
+/**
+ * `String.fromBytes(bytes, start, end)` as `--emit-ts` writes it: the bytes of
+ * `[start, end)` decoded as UTF-8, which is the string a native program holds,
+ * checked as `fromBytes`'s range is. A sequence that is not UTF-8 decodes to
+ * U+FFFD where native keeps the bytes. `fromBytes` above stays the
+ * one-unit-per-byte reading the prelude's programs are pinned to.
+ */
+export function utf8FromBytes(bytes, start, end) {
+  const from = toIndex(start);
+  const to = toIndex(end);
+  if (!(from >= 0 && from <= to && to <= bytes.length)) panicSlice(from, to, bytes.length);
+  const out = new Uint8Array(to - from);
+  for (let i = from; i < to; i++) out[i - from] = bytes[i];
+  return DECODER.decode(out);
+}

package/runtime/core.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `nish/runtime`: the host-agnostic core (runtime/core.mjs). Pair it with
+ * `nish/runtime/node` or `nish/runtime/browser`, which install a host.
+ */
+export * from "./core/arrays.js";
+export * from "./core/host.js";
+export * from "./core/numbers.js";
+export * from "./core/result.js";
+export * from "./core/strings.js";

package/runtime/core.mjs

@@ -0,0 +1,55 @@
+/**
+ * Nish builtins, host-agnostic (WP13 differential testing, WP33 R3).
+ *
+ * The differential runner (tests/differential/run.js) rewrites an Nish
+ * program into plain JavaScript and runs it under Node with this module as
+ * `__nish` (`runtime/shim.mjs`, which is this core with `runtime/node.mjs`
+ * installed as its host). Every helper here reproduces the *runtime* semantics the compiled
+ * binary has (runtime/runtime.c and runtime/runtime-os.c, the system-call half,
+ * plus the intrinsics in docs/wp7-runtime.md) where JavaScript's own semantics
+ * differ:
+ *
+ *   - `number` is a 32-bit integer in the default mode (`--number-mode i32`),
+ *     `i64` is a 64-bit integer, both wrapping; JS has doubles and BigInt.
+ *   - `u8`/`u16`/`u32`/`u64` are unsigned and wrapping, and JavaScript has no
+ *     unsigned integers at all: the narrow three live in a `number` masked
+ *     back into range (`& 0xFF`, `& 0xFFFF`, `>>> 0`) and `u64` is a BigInt
+ *     kept in range with `BigInt.asUintN(64, x)`.
+ *   - `f32` is a 32-bit float and JavaScript has only doubles, so every `f32`
+ *     result is rounded with `Math.fround`.
+ *   - `s.length` is the UTF-8 byte length, and so is every index the string
+ *     methods take or return: `charCodeAt` yields a byte (and bounds-checks
+ *     instead of returning `NaN`), `substring` cuts on byte offsets, and
+ *     `indexOf` answers with one. `slice` cuts on byte offsets too and panics
+ *     on a range the string does not contain, where JavaScript would clamp and
+ *     read a negative offset from the end. `String.fromCharCode` builds a
+ *     one-byte string from the low 8 bits, and `String.fromBytes` one such
+ *     string per byte of its range.
+ *   - `a[i]` is bounds-checked: out of range prints
+ *     `index out of range: <i> >= <len>` to stderr and exits 1, and so is
+ *     `a.pop()` on an empty array, which has no `undefined` to return.
+ *   - `toI32/toI64` from f64 saturate (NaN -> 0), integer conversions wrap.
+ *   - `console.log(x)` never prints the `n` suffix of an i64 and writes
+ *     synchronously so `process.exit` cannot lose output.
+ *   - file I/O errors print `nish: cannot read <path>` and exit 1.
+ *   - a directory listing is sorted by UTF-8 bytes, which is `strcmp`'s order
+ *     and not `Array#sort`'s UTF-16 one; `monotonicNanos` reads a clock whose
+ *     origin is arbitrary, so two readings can agree with a native run and a
+ *     single reading never can.
+ *   - `process.argv[0]` is the program (the script here, the executable
+ *     natively); `parseInt` is base 10 only and saturates into i32 (0 for no
+ *     digits); `parseFloat`/`Number` accept ASCII whitespace, decimal forms,
+ *     `Infinity`, and a `0x` hex prefix (parseFloat too, unlike JS).
+ *
+ * The core names no `node:` module and neither `process` nor `Buffer`: what it
+ * needs of the world goes through the host `runtime/core/host.mjs` holds, so
+ * another adapter can stand where `runtime/node.mjs` stands. A check in
+ * `tests/run.js` (`runtime-hosts`) holds it to that.
+ *
+ * The rewrite rules that call these helpers are listed in docs/wp13-differential.md.
+ */
+export * from "./core/arrays.mjs";
+export * from "./core/host.mjs";
+export * from "./core/numbers.mjs";
+export * from "./core/result.mjs";
+export * from "./core/strings.mjs";

package/runtime/host.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `nish/runtime/node` exports nothing: importing it installs that host on the
+ * core in `nish/runtime` (docs/RUN_UNDER_NODE.md). `nish/runtime/browser`
+ * installs its host too, and exports `NishExit` (`browser.d.ts`).
+ */
+export {};

package/runtime/nish.d.ts

@@ -112,10 +112,10 @@ declare function Err<T, E>(error: E): Result<T, E>;
 
 /**
  * The disposable protocol `using` reads (WP29 P2, docs/wp29-thread-surface.md
- * §5): declared here so that a program using `nish/threads`'s scope or
- * `arena()` needs no `"ESNext.Disposable"` in its `lib`. `nish` itself takes
- * `using` only for a `scope()` or an `arena()`, and `[Symbol.dispose]` only in
- * `nish/threads`.
+ * §5): declared here so that a program using `nish/threads`'s scope, a
+ * `Mutex`'s lock or `arena()` needs no `"ESNext.Disposable"` in its `lib`.
+ * `nish` itself takes `using` only for a `scope()`, a `lock()` or an
+ * `arena()`, and `[Symbol.dispose]` only in `nish/threads`.
  */
 interface SymbolConstructor {
   readonly dispose: unique symbol;
@@ -124,6 +124,16 @@ interface Disposable {
   [Symbol.dispose](): void;
 }
 
+/**
+ * `String.fromBytes` is Nish's, not JavaScript's, so it merges into the
+ * `StringConstructor` `lib.es2022` declares. Under `runtime/nish.mjs` each byte
+ * becomes one UTF-16 unit, as `String.fromCharCode`'s does.
+ */
+interface StringConstructor {
+  /** The bytes of `bytes[start..end)` as one string; panics unless `0 <= start <= end <= bytes.length`. */
+  fromBytes(bytes: readonly u8[], start: number, end: number): string;
+}
+
 interface Console {
   /** `x` and a newline to stdout. Statement position; exactly one argument. */
   log(x: string | number | boolean): void;
@@ -161,6 +171,8 @@ declare function toF64(x: number | boolean): f64;
 /** Reinterpret the 64 bits of an `f64`, never convert the value. */
 declare function f64ToBits(x: f64): i64;
 declare function bitsToF64(bits: i64): f64;
+/** Reinterpret the 32 bits of an `f32`, never convert the value. */
+declare function f32ToBits(x: f32): i32;
 
 // ---- Constant time (WP34 N6) ------------------------------------------------
 
@@ -193,7 +205,7 @@ declare function isExecutableSync(path: string): boolean;
 // ---- Unsafe (`nish:unsafe`) --------------------------------------------------
 //
 // Declared as globals so `tsc` reads a program that imports them, as every
-// `nish:` export is, but `nish` refuses a call to any of the five that is not
+// `nish:` export is, but `nish` refuses a call to any of the six that is not
 // imported from `nish:unsafe`: the import is the module's visible opt-in.
 
 /** `xs[i]` with no bounds check: undefined behaviour when `i` is out of range. */
@@ -206,6 +218,8 @@ declare function wrappingAdd<T extends i32 | i64>(a: T, b: T): T;
 declare function wrappingSub<T extends i32 | i64>(a: T, b: T): T;
 /** `a * b` wrapped to the operands' width. */
 declare function wrappingMul<T extends i32 | i64>(a: T, b: T): T;
+/** The `NUL`-terminated bytes at `p`, copied into a string: undefined behaviour unless `p` is a live C string. */
+declare function readCString(p: CPtr): string;
 
 // ---- Streams and files (globals: Nish has no package resolution) ---------
 
@@ -266,6 +280,28 @@ declare function spawnSync(argv: string[]): number;
  * either path is refused, as `writeFileSync` refuses one, and the answer is -1.
  */
 declare function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+/**
+ * Start `argv[0]` through `PATH` without waiting: the child's pid, or a
+ * negative errno. The child is the program's until `waitPid` reaps it. No
+ * reading under Node, which throws.
+ */
+declare function spawn(argv: string[]): i32;
+/**
+ * Send `sig` to `pid`: 0, or a negative errno (-3 when no such process). `sig`
+ * is 0, 2, 9 or 15, and anything else, like a `pid` of 0 or below, is -22.
+ */
+declare function kill(pid: i32, sig: i32): i32;
+/**
+ * Wait for the child `pid`, or any child for -1: `[pid, status]`, the status
+ * as `spawnSync` answers it. Flag 1 is WNOHANG, under which `[0, 0]` means a
+ * child remains and none has exited; a failure is `[-errno, 0]`, `[-10, 0]`
+ * with no child to wait for. No reading under Node, which throws.
+ */
+declare function waitPid(pid: i32, flags: i32): i32[];
+/** How many CPUs the program may use: at least 1, with or without `--threads`. */
+declare function availableParallelism(): i32;
+/** Bytes of physical memory, or -1 when the host does not say. */
+declare function totalMemory(): i64;
 /** One environment variable, or `null` when it is unset (an empty value is a set variable). */
 declare function getenv(name: string): string | null;
 /**
@@ -305,6 +341,8 @@ declare function netAddress(out: u8[], host: string, port: i32): i32;
 declare function netLocalPort(fd: i32): i32;
 /** A listening TCP socket with `SO_REUSEADDR`; `"::"` hears IPv4 and IPv6. */
 declare function tcpListen(host: string, port: i32, backlog: i32): i32;
+/** `tcpListen`'s socket, with `SO_REUSEPORT` for flag 1 and `TCP_NODELAY` on each accepted socket for flag 2; any other bit is -22. */
+declare function tcpListenFlags(host: string, port: i32, backlog: i32, flags: i32): i32;
 /** The next connection's descriptor, its address in `peer`; -11 when none waits. */
 declare function tcpAccept(fd: i32, peer: u8[]): i32;
 /** Up to `len` bytes into `buf` from `off`: the count, 0 at end of stream, or -11. */
@@ -344,6 +382,33 @@ declare function pollRemove(loop: i32, fd: i32): i32;
 /** Wait up to `timeoutMs` (negative: forever); pairs `ready[2k]` token, `ready[2k + 1]` events (4: hang-up or error). */
 declare function pollWait(loop: i32, ready: i32[], timeoutMs: i32): i32;
 
+// ---- `nish:term` ------------------------------------------------------------------
+//
+// stdin without blocking and the terminal it may be: the frame clock and the
+// keys of a terminal UI, with no `net` capability. -11 is "nothing is
+// waiting" and -25 "not a terminal" on every platform; any other failure is
+// the host's `-errno`. Under WASI the reading works, `readStdin` waiting for
+// its bytes (ask `waitStdin` first), and the terminal answers -25. Under Node `isTerminal` and `terminalSize` answer and the other four
+// throw.
+
+/** Up to `len` bytes of stdin into `buf` from `off`, never blocking: the count, 0 at end of stream, or -11 when nothing is waiting. */
+declare function readStdin(buf: u8[], off: i32, len: i32): i32;
+/** Wait up to `timeoutMs` (negative: forever) for stdin to be readable (its end and an error count): `true` when it is, `false` when the time passed. */
+declare function waitStdin(timeoutMs: i32): boolean;
+/** Whether descriptor `fd` is a terminal (`isatty`). */
+declare function isTerminal(fd: i32): boolean;
+/** `[columns, rows]` of the terminal on stdout, else stderr; `[-25, 0]` when neither is one, `[0, 0]` when it has no size set. */
+declare function terminalSize(): i32[];
+/**
+ * Raw mode on stdin's terminal, or the mode it had back: 0, -25 when stdin is
+ * not a terminal. No echo, no line editing; Ctrl-C stays SIGINT and "\n"
+ * still starts a line. The terminal is put back at exit, on a panic and on
+ * every signal that ends the program, SIGKILL aside.
+ */
+declare function setRawMode(on: boolean): i32;
+/** Bytes the runtime writes to the terminal on stdout at exit, on a panic and on every signal that ends the program (SIGKILL aside), before termios is restored. Replaces the previous string; "" clears it. 0, -25 when stdout is not a terminal, -7 (E2BIG) past NISH_TERM_RESTORE_MAX bytes. The cap is 4096 bytes. */
+declare function setTerminalRestore(bytes: string): i32;
+
 // ---- `Date` and `crypto` (WP34 N3) -----------------------------------------------
 //
 // `lib.es2022` already declares `Date`, whose `now()` is Nish's one member of it,
@@ -400,6 +465,16 @@ declare module "nish:process" {
    * at either path is refused, and the answer is -1.
    */
   export function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+  /** Start a child without waiting: its pid, or a negative errno. */
+  export function spawn(argv: string[]): i32;
+  /** Send 0, 2, 9 or 15 to `pid`: 0, or a negative errno; any other signal is -22. */
+  export function kill(pid: i32, sig: i32): i32;
+  /** `[pid, status]` for a child that exited, `[0, 0]` under WNOHANG (flag 1) with none, or `[-errno, 0]`. */
+  export function waitPid(pid: i32, flags: i32): i32[];
+  /** How many CPUs the program may use, at least 1. */
+  export function availableParallelism(): i32;
+  /** Bytes of physical memory, or -1. */
+  export function totalMemory(): i64;
   /**
    * A monotonic clock in nanoseconds. The origin is arbitrary, so only the
    * difference between two reads is meaningful.
@@ -424,6 +499,8 @@ declare module "nish:net" {
   export function netLocalPort(fd: i32): i32;
   /** A listening TCP socket with `SO_REUSEADDR`; `"::"` hears IPv4 and IPv6. */
   export function tcpListen(host: string, port: i32, backlog: i32): i32;
+  /** `tcpListen`'s socket, with `SO_REUSEPORT` for flag 1 and `TCP_NODELAY` on each accepted socket for flag 2; any other bit is -22. */
+  export function tcpListenFlags(host: string, port: i32, backlog: i32, flags: i32): i32;
   /** The next connection's descriptor, its address in `peer`; -11 when none waits. */
   export function tcpAccept(fd: i32, peer: u8[]): i32;
   /** Up to `len` bytes into `buf` from `off`: the count, 0 at end of stream, or -11. */
@@ -474,6 +551,8 @@ declare module "nish:unsafe" {
   export function wrappingSub<T extends i32 | i64>(a: T, b: T): T;
   /** `a * b` wrapped to the operands' width. */
   export function wrappingMul<T extends i32 | i64>(a: T, b: T): T;
+  /** The `NUL`-terminated bytes at `p`, copied into a string: undefined behaviour unless `p` is a live C string. */
+  export function readCString(p: CPtr): string;
 }
 
 declare module "nish:io" {
@@ -485,6 +564,21 @@ declare module "nish:io" {
   export function panic(message: string): never;
 }
 
+declare module "nish:term" {
+  /** Up to `len` bytes of stdin into `buf` from `off`, never blocking: the count, 0 at end of stream, or -11 when nothing is waiting. */
+  export function readStdin(buf: u8[], off: i32, len: i32): i32;
+  /** Wait up to `timeoutMs` (negative: forever) for stdin to be readable (its end and an error count): `true` when it is, `false` when the time passed. */
+  export function waitStdin(timeoutMs: i32): boolean;
+  /** Whether descriptor `fd` is a terminal (`isatty`). */
+  export function isTerminal(fd: i32): boolean;
+  /** `[columns, rows]` of the terminal on stdout, else stderr; `[-25, 0]` when neither is one, `[0, 0]` when it has no size set. */
+  export function terminalSize(): i32[];
+  /** Raw mode on stdin's terminal (0), or the mode it had back; -25 when stdin is not a terminal. Restored at exit, on a panic and on every signal that ends the program, SIGKILL aside. */
+  export function setRawMode(on: boolean): i32;
+  /** Bytes the runtime writes to the terminal on stdout at exit, on a panic and on every signal that ends the program (SIGKILL aside), before termios is restored. Replaces the previous string; "" clears it. 0, -25 when stdout is not a terminal, -7 (E2BIG) past NISH_TERM_RESTORE_MAX bytes. */
+  export function setTerminalRestore(bytes: string): i32;
+}
+
 // `nish:secret` has source behind it, `std/secret.ts`, but a program imports it
 // by this name, so `tsc` reads these declarations rather than that file. The
 // class is declared with a private constructor and a private field: `tsc` then