numbl 0.4.7 → 0.4.9

package/dist-browser/numbl-core/runtime/axisCommand.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `axis(...)` argument parsing — the single place that turns every `axis`
+ * call form into `PlotInstruction`s.
+ *
+ * Supported forms (evaluated left to right, later options overriding earlier
+ * ones):
+ *   - a limit vector `[xmin xmax ymin ymax (zmin zmax (cmin cmax))]`, where a
+ *     non-finite bound (`inf`/`-inf`) leaves that bound automatic;
+ *   - a scalar `0/1` or logical `false/true` toggling axes visibility;
+ *   - a style word (`tight`, `padded`, `fill`, `equal`, `image`, `square`,
+ *     `vis3d`, `normal`, `tickaligned`);
+ *   - a limit mode (`manual`, `auto`, `'auto x'`, `'auto y'`, `'auto z'`,
+ *     `'auto xy'`, `'auto xz'`, `'auto yz'`);
+ *   - a y-direction (`xy`, `ij`);
+ *   - a visibility word (`on`, `off`).
+ *
+ * A leading axes handle (numbl has no real axes handles) is accepted and
+ * skipped, so `axis(ax, ...)` works. The query forms `lim = axis` /
+ * `lim = axis(ax)` carry no setting argument; the runtime detects them via
+ * the `false` return value and computes the limits separately.
+ */
+import type { RuntimeValue } from "./types.js";
+import type { PlotInstruction } from "../../graphics/types.js";
+/**
+ * Process an `axis(...)` call, pushing instructions onto `instructions`.
+ *
+ * @param freezeLimits  Optional provider of the current limit vector
+ *   `[xmin xmax ymin ymax (zmin zmax)]`, used to implement `axis manual`
+ *   (freeze the current limits). When omitted, `axis manual` records the
+ *   request without concrete values.
+ * @returns `true` if any setting was applied. `false` means the call carried
+ *   no setting argument (a query, e.g. `lim = axis`).
+ */
+export declare function applyAxisCommand(args: RuntimeValue[], instructions: PlotInstruction[], freezeLimits?: () => number[]): boolean;

package/dist-browser/numbl-core/runtime/compare.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Value conversion helpers and equality.
+ */
+import { type RuntimeValue } from "./types.js";
+export declare const valuesAreEqual: (a: RuntimeValue, b: RuntimeValue) => boolean;

package/dist-browser/numbl-core/runtime/constructors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * RuntimeValue constructor helpers (the RTV namespace).
+ */
+import { ItemType } from "../lowering/itemTypes.js";
+import { type RuntimeNumber, RuntimeTensor, type RuntimeString, RuntimeChar, type RuntimeLogical, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeClassInstance, RuntimeClassInstanceArray, RuntimeComplexNumber, RuntimeDummyHandle, RuntimeGraphicsHandle, RuntimeStructArray, RuntimeSparseMatrix, RuntimeDictionary, RuntimeStringArray, type RuntimeValue } from "./types.js";
+export declare const RTV: {
+    num(value: number): RuntimeNumber;
+    tensor(data: Float64Array | number[], shape: number[], imag?: Float64Array | number[]): RuntimeTensor;
+    /** Fast tensor constructor — data must be Float64Array, shape already normalized (no trailing singletons). */
+    tensorRaw(data: Float64Array, shape: number[]): RuntimeTensor;
+    /** Create a scalar tensor (1x1) */
+    scalar(value: number): RuntimeNumber;
+    /** Create a row vector [1 x n] */
+    row(data: number[], imag?: number[]): RuntimeTensor;
+    /** Create a column vector [n x 1] */
+    col(data: number[], imag?: number[]): RuntimeTensor;
+    /** Create a matrix from row-major data */
+    matrix(rows: number, cols: number, data: number[] | Float64Array, imag?: number[] | Float64Array): RuntimeTensor;
+    string(value: string): RuntimeString;
+    /** String array (does NOT collapse 1x1 — use stringArrayValue for that). */
+    stringArray(data: string[], shape: [number, number]): RuntimeStringArray;
+    char(value: string): RuntimeChar;
+    logical(value: boolean): RuntimeLogical;
+    cell(data: RuntimeValue[], shape: number[]): RuntimeCell;
+    struct(fields: Map<string, RuntimeValue> | Record<string, RuntimeValue>): RuntimeStruct;
+    func(name: string, impl: "builtin" | "user", captures?: RuntimeValue[]): RuntimeFunction;
+    classInstance(className: string, propertyNames: string[], isHandleClass?: boolean, defaults?: Map<string, RuntimeValue>): RuntimeClassInstance;
+    classInstanceArray(className: string, elements: RuntimeClassInstance[], shape?: [number, number]): RuntimeClassInstanceArray;
+    complex(re: number, im: number): RuntimeComplexNumber;
+    dummyHandle(): RuntimeDummyHandle;
+    graphicsHandle(trace: Record<string, unknown>, traceType: string): RuntimeGraphicsHandle;
+    structArray(fieldNames: string[], elements: RuntimeStruct[]): RuntimeStructArray;
+    sparseMatrix(m: number, n: number, ir: Int32Array, jc: Int32Array, pr: Float64Array, pi?: Float64Array): RuntimeSparseMatrix;
+    dictionary(entries?: Map<string, {
+        key: RuntimeValue;
+        value: RuntimeValue;
+    }>, keyType?: string, valueType?: string): RuntimeDictionary;
+};
+export declare const getItemTypeFromRuntimeValue: (value: RuntimeValue) => ItemType;

package/dist-browser/numbl-core/runtime/convert.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Value conversion helpers and equality.
+ */
+import { type RuntimeValue } from "./types.js";
+/** Extract a JS number from an RuntimeValue (scalar num, logical, or 1x1 tensor) */
+export declare function toNumber(v: RuntimeValue): number;
+/** Extract a boolean from an RuntimeValue */
+export declare function toBool(v: RuntimeValue): boolean;
+/** Extract a string from an RuntimeValue */
+export declare function toString(v: RuntimeValue): string;

package/dist-browser/numbl-core/runtime/cow.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Refcount-driven copy-on-write helpers.
+ *
+ * The lvalue write path uses these to make sure the chain from the env
+ * root to the leaf is uniquely owned before mutation: at each level, if
+ * the container is shared (`isShared`), it's cloned and the clone is
+ * rebound in the parent. After the chain is unique, in-place mutation
+ * at the leaf is observable only to the LHS variable.
+ */
+import { type RuntimeValue } from "./types.js";
+import { type RefcountRuntime } from "./refcount.js";
+/** Return a fresh wrapper that shadows `v`'s contents but has rc=0
+ *  (modulo scope adoption from the constructor). The new wrapper holds
+ *  its own copy of the underlying buffers (for tensors) or its own
+ *  fields/data array (for containers). Refs to child values are
+ *  shared with the original — child wrappers get incref'd by the new
+ *  container's constructor. Caller is responsible for binding the
+ *  fresh wrapper into the parent slot.
+ *
+ *  Returns the original value unchanged for kinds that don't need to
+ *  be copied (handle-class instances, primitives) — the caller can
+ *  `=== v` test if the copy was a no-op. */
+export declare function cowCopy(v: RuntimeValue): RuntimeValue;
+/** If `v` is shared (rc-driven), return a fresh non-shared copy;
+ *  otherwise return `v` unchanged. The new wrapper has refcount 0
+ *  (or 1 if the active scope adopts it via the constructor); the
+ *  caller must bind it into the parent slot to keep it alive.
+ *
+ *  Returns the original `v` for handle-class instances and primitives —
+ *  callers can `result === v` test to detect a no-op. */
+export declare function cowIfShared(v: RuntimeValue): RuntimeValue;
+export { isShared } from "./refcount.js";
+export type { RefcountRuntime };

package/dist-browser/numbl-core/runtime/display.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Value display/formatting.
+ */
+import { type RuntimeValue } from "./types.js";
+/** Format a value for display */
+export declare function displayValue(v: RuntimeValue): string;

package/dist-browser/numbl-core/runtime/error.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Runtime error type and source location utilities.
+ */
+export interface Span {
+    file: string;
+    start: number;
+    end: number;
+}
+export type CallFrame = {
+    name: string;
+    callerFile: string | null;
+    callerLine: number;
+    /** Trimmed source text at callerLine (populated during error enrichment) */
+    callerSourceLine?: string;
+};
+export declare class CancellationError extends Error {
+    constructor();
+}
+export declare class RuntimeError extends Error {
+    /** Source span where the error occurred (carries file name + per-file offsets) */
+    span: Span | null;
+    /** 1-based line number (set when source is available) */
+    line: number | null;
+    /** 1-based column number (set when source is available) */
+    column: number | null;
+    /** Source file name (set from span or by error handler) */
+    file: string | null;
+    /** Code snippet showing error context */
+    snippet: string | null;
+    /** Underlying cause (for chained errors) */
+    cause?: Error;
+    /** Call stack at the time of the error (null = not yet captured) */
+    callStack: CallFrame[] | null;
+    /** Error identifier (e.g. 'myid:myerr') */
+    identifier: string;
+    /** File sources for resolving source lines in call stack display */
+    fileSources: Map<string, string> | null;
+    constructor(message: string, span?: Span | null);
+    /**
+     * Attach source location span to this error.
+     */
+    withSpan(span: Span): RuntimeError;
+    /**
+     * Enrich error with line/column/snippet from the file's source text.
+     * The fileSources map provides filename → source text lookups.
+     */
+    withContext(fileSources: Map<string, string>): RuntimeError;
+    /**
+     * Format error with location and snippet context.
+     */
+    toString(): string;
+    /** Format error with MATLAB-style call stack. */
+    private _formatWithCallStack;
+    /** Look up a single trimmed source line from fileSources. */
+    private _getSourceLine;
+}
+/**
+ * Compute 1-based line number from a character offset in source text.
+ */
+export declare function offsetToLine(source: string, offset: number): number;
+/**
+ * Build an array of newline character positions for fast offset→line lookup.
+ * Returns a sorted array where lineBreaks[i] is the offset of the (i+1)th '\n'.
+ */
+export declare function buildLineTable(source: string): number[];
+/**
+ * Compute 1-based line number from a character offset using a pre-built line table.
+ * Uses binary search — O(log n) instead of O(n).
+ */
+export declare function offsetToLineFast(lineBreaks: number[], offset: number): number;
+/**
+ * Compute 1-based column number from a character offset in source text.
+ */
+export declare function offsetToColumn(source: string, offset: number): number;
+/**
+ * Extract code snippet with context lines around the error location.
+ */
+export declare function extractSnippet(source: string, offset: number, contextLines?: number): string;

package/dist-browser/numbl-core/runtime/index.d.ts

@@ -0,0 +1,13 @@
+export type { RuntimeValue, RuntimeString, RuntimeLogical } from "./types.js";
+export { RuntimeTensor, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeDictionary, } from "./types.js";
+export { RuntimeError, CancellationError, offsetToLine, offsetToColumn, } from "./error.js";
+export type { CallFrame } from "./error.js";
+export { tensorSize2D, numel, colMajorIndex } from "./utils.js";
+export { toNumber, toBool, toString } from "./convert.js";
+export { valuesAreEqual } from "./compare.js";
+export { displayValue } from "./display.js";
+export { RTV } from "./constructors.js";
+export { mAdd, mSub, mMul, mElemMul, mDiv, mElemDiv, mPow, mElemPow, mNeg, mTranspose, mConjugateTranspose, mEqual, mNotEqual, mLess, mLessEqual, mGreater, mGreaterEqual, } from "../helpers/arithmetic.js";
+export { COLON_INDEX, indexIntoRTValue as mIndex, storeIntoRTValueIndex as mIndexStore, charToNumericTensor, numericTensorToChar, } from "./indexing.js";
+export { getRTValueField as mGetField, setRTValueField as mSetField, } from "./struct-access.js";
+export { makeRangeTensor as mRange, horzcat, vertcat, } from "./tensor-construction.js";

package/dist-browser/numbl-core/runtime/indexing.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Indexing, struct field access, range creation, and tensor concatenation.
+ */
+import { type RuntimeValue, RuntimeTensor, RuntimeChar } from "./types.js";
+import { type RefcountRuntime } from "./refcount.js";
+/** Runtime surface needed by index-store mutations. The full Runtime
+ *  class satisfies this structurally. */
+type StoreRuntime = RefcountRuntime;
+/** Sentinel marker for colon (:) indexing — means "all indices in this dimension" */
+export declare const COLON_INDEX: RuntimeValue;
+/** Convert a char value to a numeric (column-major) tensor of its code
+ *  points. A RuntimeChar stores its `value` row-major (each of `shape[0]`
+ *  rows is `shape[1]` chars, concatenated), so we transpose into the
+ *  tensor's column-major layout. Used so indexed assignment into / from a
+ *  char array runs on the numeric tensor machinery (MATLAB treats char as
+ *  numeric for indexed assignment). */
+export declare function charToNumericTensor(c: RuntimeChar): RuntimeTensor;
+/** Inverse of charToNumericTensor: read a numeric tensor's column-major
+ *  data into a row-major char value, rounding codes to integers. */
+export declare function numericTensorToChar(t: RuntimeTensor): RuntimeChar;
+/** Resolve one subscript against a dimension of extent `extent` to 0-based
+ *  positions. Handles colon, scalars, numeric vectors, and logical masks. */
+export declare function stringArraySubscript(idx: RuntimeValue, extent: number): number[];
+/** Index into a value: v(i1, i2, ...) */
+export declare function indexIntoRTValue(base: RuntimeValue, indices: RuntimeValue[]): RuntimeValue;
+/** Store into indexed position: base(indices) = rhs — uses copy-on-write for shared data */
+export declare function storeIntoRTValueIndex(base: RuntimeValue, indices: RuntimeValue[], rhs: RuntimeValue, parenAssign?: boolean, rt?: StoreRuntime): RuntimeValue;
+export {};

package/dist-browser/numbl-core/runtime/plotBuiltinDispatch.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Plot builtin dispatch — the single source of truth for the
+ * `(name, args)` → `PlotInstruction[]` mapping that every plotting
+ * builtin performs.
+ *
+ * Historically this logic was scattered across two places:
+ *   - `runtime.ts` registered the data-bearing plot names
+ *     (`plot`, `surf`, `imagesc`, …) inside `initBuiltins`.
+ *   - `specialBuiltins.ts` registered the graphics ops (`figure`,
+ *     `title`, `xlabel`, `hold`, `subplot`, `clf`, …) inside
+ *     `registerSpecialBuiltins`.
+ *
+ * Both sites pushed onto `rt.plotInstructions` and (for `hold` /
+ * `tiledlayout` / `nexttile`) updated small flags on the Runtime.
+ * `dispatchPlotBuiltin` is the consolidation. The Runtime registers
+ * each name with a 1-line wrapper that calls this function and then
+ * returns the right `nargout`-handle value; the side-effect (the
+ * push) lives here.
+ *
+ * Out-of-scope names — kept registered separately because their
+ * semantics need the full Runtime context:
+ *   - `fplot` / `fplot3` — evaluate a user function-handle, need
+ *     the Runtime's executor.
+ *   - `drawnow` / `pause` — call the `ExecOptions` callbacks
+ *     (`onDrawnow`, `onPause`).
+ *   - `streamline` / `stream2` — return non-trivial values.
+ *   - `ishold` — reads `state.holdState`, but is a pure query (no
+ *     instructions pushed); the Runtime can call `state.holdState`
+ *     directly.
+ *
+ * Reusable from outside numbl: mtoc2 (the static-translation
+ * sibling project) imports this function to render plots in its
+ * browser IDE without reimplementing per-builtin logic.
+ */
+import type { RuntimeValue } from "./types.js";
+import type { PlotInstruction } from "../../graphics/types.js";
+/** State carried by graphics ops that need to remember things between
+ *  calls. `holdState` is read by `ishold()` so `hold on; if ishold ...`
+ *  works; `tiledLayoutState` lets `nexttile` know where to place the
+ *  next axes. The `Runtime` class implements this interface; mtoc2's
+ *  browser viewer keeps its own instance. */
+export interface PlotDispatchState {
+    holdState: boolean;
+    tiledLayoutState: TiledLayoutState | null;
+    /** Current figure handle (0 = none created yet). */
+    currentFigureHandle?: number;
+    /** Highest figure handle allocated so far. `figure` with no argument
+     *  creates a NEW figure with handle `maxFigureHandle + 1` (MATLAB
+     *  semantics), rather than always reusing handle 1. */
+    maxFigureHandle?: number;
+}
+/** Active tiled-layout grid. `mode` controls how the grid grows: in
+ *  `flow` (default), nexttile expands rows/cols to fit; `vertical` and
+ *  `horizontal` extend one axis; `fixed` uses the M/N from the
+ *  tiledlayout(M,N) call verbatim. */
+export interface TiledLayoutState {
+    rows: number;
+    cols: number;
+    mode: "fixed" | "flow" | "vertical" | "horizontal";
+    count: number;
+}
+/** Run a single plot-builtin call. Pushes onto `instructions` and
+ *  updates `state` to mirror what numbl's runtime did before this
+ *  refactor. Returns `true` iff `name` was a recognized plot builtin;
+ *  callers fall through to their own dispatch on `false`. */
+export declare function dispatchPlotBuiltin(name: string, args: RuntimeValue[], instructions: PlotInstruction[], state: PlotDispatchState): boolean;
+/** Names handled by `dispatchPlotBuiltin`. Useful for registering all
+ *  of them in a loop (numbl's `initBuiltins` / `registerSpecialBuiltins`
+ *  do that for the side-effect-only subset). Stays in sync with the
+ *  cases above by construction. */
+export declare const PLOT_DISPATCH_NAMES: ReadonlyArray<string>;
+/** Graphics-related names numbl exposes as no-op (or near-no-op)
+ *  stubs — they don't push plot instructions and don't render, but
+ *  numbl accepts them so MATLAB scripts compile and run. Sources:
+ *    - `interpreter/builtins/misc.ts` (`groot`, `gcf`, `gca`, `shg`,
+ *      `newplot`, `xlim`, `ylim`, `set`, `get`, `ishold`)
+ *    - `runtime/specialBuiltins.ts` (`drawnow`, `pause`)
+ *
+ *  These names belong here, alongside `PLOT_DISPATCH_NAMES`, because
+ *  downstream consumers (mtoc2's translator, syntax highlighters,
+ *  doc generators) want to know the full "plot-script surface area"
+ *  numbl tolerates — not just the renderable subset. Keeping the
+ *  union in one place is the whole point of consolidating dispatch
+ *  here. */
+export declare const PLOT_STUB_NAMES: ReadonlyArray<string>;
+/** The union of `PLOT_DISPATCH_NAMES` (renderable) and
+ *  `PLOT_STUB_NAMES` (recognized-but-no-render). Every name a plotting
+ *  script might invoke that numbl tolerates. Mtoc2 imports this to
+ *  drive its own builtin registration so the two repos stay in
+ *  lockstep — when numbl gains a new plot builtin, mtoc2 picks it up
+ *  at the next `tsc` / `vite build` with no mtoc2-side edit. */
+export declare const PLOT_ALL_NAMES: ReadonlyArray<string>;