numbl 0.4.8 → 0.4.9

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

@@ -0,0 +1,336 @@
+/**
+ * Utilities for parsing plot() arguments at runtime.
+ *
+ * Handles: plot(Y), plot(X,Y), plot(X1,Y1,...,Xn,Yn),
+ * plot(X1,Y1,LineSpec1,...), and Name-Value pairs like 'Color','r','LineWidth',2.
+ */
+import { type RuntimeValue } from "./types.js";
+export type { PlotTrace, Plot3Trace, PatchTrace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace, } from "../../graphics/types.js";
+import type { PlotTrace, Plot3Trace, PatchTrace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace } from "../../graphics/types.js";
+export declare function resolveColor(v: RuntimeValue | string): [number, number, number] | undefined;
+export interface ParsedLineSpec {
+    color?: string;
+    lineStyle?: string;
+    marker?: string;
+}
+export declare function parsePlotArgs(args: RuntimeValue[]): PlotTrace[];
+/**
+ * Parse plot3() arguments.
+ *
+ * Supported forms:
+ *   plot3(X, Y, Z)
+ *   plot3(X, Y, Z, LineSpec)
+ *   plot3(X1,Y1,Z1,...,Xn,Yn,Zn)
+ *   plot3(X1,Y1,Z1,LineSpec1,...,Xn,Yn,Zn,LineSpecn)
+ *   plot3(..., Name, Value)
+ */
+export declare function parsePlot3Args(args: RuntimeValue[]): Plot3Trace[];
+/** Result of parsing line() arguments: a set of 2-D or 3-D traces. */
+export type ParsedLine = {
+    kind: "2d";
+    traces: PlotTrace[];
+} | {
+    kind: "3d";
+    traces: Plot3Trace[];
+};
+/**
+ * Parse line() arguments.
+ *
+ * Supported forms:
+ *   line                                  — line from (0,0) to (1,1)
+ *   line(x, y)                            — 2-D line(s)
+ *   line(x, y, z)                         — 3-D line(s)
+ *   line(___, Name, Value)               — Color/LineStyle/LineWidth/Marker/...
+ *   line('XData', x, 'YData', y, ...)    — low-level form (black line)
+ *   line(ax, ___)                        — leading axes handle (ignored)
+ *
+ * Like plot/plot3, vector inputs make a single line and matrix inputs make one
+ * line per column.
+ */
+export declare function parseLineArgs(args: RuntimeValue[]): ParsedLine;
+/** Apply a single patch property (lower-cased key) to the trace. Shared by the
+ *  Name-Value, struct, and `set`/handle paths. */
+export declare function applyPatchProp(trace: PatchTrace, key: string, val: RuntimeValue): void;
+/**
+ * Parse patch() arguments into a canonical PatchTrace.
+ *
+ * Supported forms:
+ *   patch(X, Y, C)                              — 2-D polygons, color C
+ *   patch(X, Y, Z, C)                           — 3-D polygons
+ *   patch('XData', X, 'YData', Y[, 'ZData', Z]) — coords as name-value
+ *   patch('Faces', F, 'Vertices', V)            — faces/vertices model
+ *   patch(S)                                    — struct of patch properties
+ *   patch(___, Name, Value)                     — patch properties
+ *   patch(ax, ___)                              — leading axes handle (ignored)
+ */
+export declare function parsePatchArgs(args: RuntimeValue[]): PatchTrace;
+/**
+ * Parse fill() arguments into one patch trace per (X,Y,C) group. fill is the
+ * 2-D coordinate form of patch repeated over groups, so it reuses the patch
+ * vertex/color/property helpers — the only fill-specific logic is splitting
+ * the argument list into X,Y,C triplets.
+ *
+ * Supported forms:
+ *   fill(X, Y, C)
+ *   fill(X1, Y1, C1, ..., Xn, Yn, Cn)
+ *   fill(___, Name, Value)
+ *   fill(ax, ___)
+ */
+export declare function parseFillArgs(args: RuntimeValue[]): PatchTrace[];
+/**
+ * Parse trimesh() arguments into a canonical PatchTrace.
+ *
+ * trimesh draws a triangular mesh and (per the MATLAB docs) returns a patch
+ * object, so it maps onto the PatchTrace model: the connectivity matrix T
+ * supplies the faces (one triangle per row, 1-based vertex indices) and the
+ * x/y[/z] vectors supply the vertices.
+ *
+ * Supported forms:
+ *   trimesh(T, x, y)              — 2-D triangular mesh
+ *   trimesh(T, x, y, z)           — 3-D triangular mesh
+ *   trimesh(T, x, y, z, c)        — c is per-vertex color data
+ *   trimesh(TO)                   — triangulation object (struct exposing
+ *                                   ConnectivityList + Points)
+ *   trimesh(___, Name, Value)     — patch properties
+ *   trimesh(ax, ___)              — leading axes handle (ignored)
+ */
+export declare function parseTriMeshArgs(args: RuntimeValue[]): PatchTrace;
+/**
+ * Parse surf() arguments.
+ *
+ * Supported forms:
+ *   surf(Z)           — Z is m×n, X = 1:n, Y = 1:m
+ *   surf(Z, C)        — Z is m×n, C is m×n color data
+ *   surf(X, Y, Z)     — X, Y, Z are m×n matrices (or X is 1×n / Y is m×1)
+ *   surf(X, Y, Z, C)  — with explicit color data
+ *   surf(..., Name, Value) — name-value pairs
+ */
+export declare function parseSurfArgs(args: RuntimeValue[]): SurfTrace;
+/**
+ * Parse pcolor() arguments.
+ *
+ * Supported forms:
+ *   pcolor(C)         — C is m×n, X = 1:n, Y = 1:m
+ *   pcolor(X, Y, C)   — X, Y, C are m×n matrices (or X is 1×n / Y is m×1)
+ *   pcolor(..., Name, Value) — name-value pairs (EdgeColor, FaceAlpha)
+ */
+export declare function parsePcolorArgs(args: RuntimeValue[]): PcolorTrace;
+/**
+ * Parse scatter() arguments.
+ *
+ * Supported forms:
+ *   scatter(X, Y)
+ *   scatter(X, Y, sz)
+ *   scatter(X, Y, sz, c)
+ *   scatter(X, Y, ..., 'filled')
+ *   scatter(X, Y, ..., mkr)
+ *   scatter(X, Y, ..., Name, Value)
+ */
+export declare function parseScatterArgs(args: RuntimeValue[]): PlotTrace[];
+/**
+ * Parse imagesc() arguments.
+ *
+ * Supported forms:
+ *   imagesc(C)         — C is m×n matrix
+ *   imagesc(x, y, C)   — x and y are vectors defining axis limits
+ */
+export declare function parseImagescArgs(args: RuntimeValue[]): ImagescTrace;
+/**
+ * Parse contour()/contourf() arguments.
+ *
+ * Supported forms:
+ *   contour(Z)
+ *   contour(Z, N)
+ *   contour(X, Y, Z)
+ *   contour(X, Y, Z, N)
+ *   contour(..., Name, Value)
+ */
+export declare function parseContourArgs(args: RuntimeValue[], filled: boolean): ContourTrace;
+/** Result of computing contour geometry: the MATLAB contour matrix `C`
+ *  (column-major `2 × n` data) plus the level list actually used. */
+export interface ContourMatrix {
+    /** Column-major `2 × n` data for a `RTV.tensor(data, [2, n])`. */
+    data: number[];
+    n: number;
+    levelList: number[];
+}
+/** Compute the MATLAB contour matrix for a parsed contour trace via marching
+ *  squares. Each marching-squares segment is emitted as its own two-vertex
+ *  contour line (header `[level; 2]` followed by the two `[x; y]` vertices) —
+ *  a valid contour matrix whose geometry matches MATLAB's connected polylines
+ *  segment-for-segment. */
+export declare function computeContourMatrix(trace: ContourTrace): ContourMatrix;
+/**
+ * Parse mesh() arguments — same as surf but with different default rendering.
+ */
+export declare function parseMeshArgs(args: RuntimeValue[]): SurfTrace;
+/**
+ * Parse bar() arguments.
+ *
+ * Supported forms:
+ *   bar(Y)             — Y values with x = 1:length(Y)
+ *   bar(X, Y)          — explicit X positions
+ *   bar(..., width)     — relative bar width (scalar 0–1)
+ *   bar(..., color)     — single-char color spec
+ */
+export declare function parseBarArgs(args: RuntimeValue[]): BarTrace[];
+/**
+ * Parse barh() arguments — same forms as bar() but rendered horizontally.
+ *
+ * Supported forms:
+ *   barh(Y)             — Y values (bar lengths) with positions = 1:length(Y)
+ *   barh(X, Y)          — explicit positions X, bar lengths Y
+ *   barh(..., width)    — relative bar thickness (scalar 0–1)
+ *   barh(..., color)    — single-char color spec
+ */
+export declare function parseBarHArgs(args: RuntimeValue[]): BarTrace[];
+/**
+ * Parse bar3() / bar3h() arguments.
+ *
+ * Supported forms:
+ *   bar3(Z)             — Z values with y = 1:m, x = 1:n
+ *   bar3(Y, Z)          — explicit Y positions
+ *   bar3(..., width)    — relative bar width (scalar 0–1)
+ *   bar3(..., color)    — single-char color spec
+ */
+export declare function parseBar3Args(args: RuntimeValue[]): Bar3Trace;
+/**
+ * Parse stairs() arguments — same forms as plot() but with staircase-transformed coordinates.
+ *
+ * Supported forms:
+ *   stairs(Y)
+ *   stairs(X, Y)
+ *   stairs(..., LineSpec)
+ *   stairs(..., Name, Value)
+ */
+export declare function parseStairsArgs(args: RuntimeValue[]): PlotTrace[];
+/**
+ * Parse errorbar() arguments.
+ *
+ * Supported forms:
+ *   errorbar(y, err)                    — symmetric vertical
+ *   errorbar(x, y, err)                 — symmetric vertical with explicit x
+ *   errorbar(x, y, neg, pos)            — asymmetric vertical
+ *   errorbar(x, y, yneg, ypos, xneg, xpos) — both axes
+ *   errorbar(..., LineSpec)
+ */
+export declare function parseErrorBarArgs(args: RuntimeValue[]): ErrorBarTrace[];
+/**
+ * Parse area() arguments.
+ *
+ * Supported forms:
+ *   area(Y)              — fill under Y with x = 1:length(Y)
+ *   area(X, Y)           — explicit X
+ *   area(..., basevalue)  — scalar baseline (default 0)
+ *   area(..., Name, Value)
+ *
+ * Returns { traces, baseValue }.
+ */
+export declare function parseAreaArgs(args: RuntimeValue[]): {
+    traces: PlotTrace[];
+    baseValue: number;
+};
+/**
+ * Parse scatter3() arguments.
+ *
+ * Supported forms:
+ *   scatter3(X, Y, Z)
+ *   scatter3(X, Y, Z, S)
+ *   scatter3(X, Y, Z, S, C)
+ *   scatter3(..., 'filled')
+ *   scatter3(..., markertype)
+ */
+export declare function parseScatter3Args(args: RuntimeValue[]): Plot3Trace[];
+/**
+ * Parse histogram() arguments.
+ *
+ * Supported forms:
+ *   histogram(X)
+ *   histogram(X, nbins)
+ *   histogram(X, edges)
+ */
+export declare function parseHistogramArgs(args: RuntimeValue[]): BarTrace[];
+/**
+ * Parse histogram2() arguments.
+ *
+ * Supported forms:
+ *   histogram2(X, Y)
+ *   histogram2(X, Y, nbins)        — nbins is scalar or [nx, ny]
+ *   histogram2(X, Y, Xedges, Yedges)
+ */
+export declare function parseHistogram2Args(args: RuntimeValue[]): Bar3Trace;
+/**
+ * Parse boxchart() arguments.
+ *
+ * Supported forms:
+ *   boxchart(ydata)           — one box per column of ydata
+ *   boxchart(xgroupdata, ydata) — group ydata by unique values in xgroupdata
+ */
+export declare function parseBoxchartArgs(args: RuntimeValue[]): BoxTrace[];
+/**
+ * Parse swarmchart() arguments.
+ *
+ * Supported forms:
+ *   swarmchart(x, y)
+ *   swarmchart(x, y, sz)
+ *   swarmchart(x, y, sz, c)
+ *   swarmchart(..., 'filled')
+ *   swarmchart(..., markertype)
+ */
+export declare function parseSwarmchartArgs(args: RuntimeValue[]): PlotTrace[];
+/**
+ * Parse swarmchart3() arguments.
+ *
+ * Supported forms:
+ *   swarmchart3(x, y, z)
+ *   swarmchart3(x, y, z, sz)
+ *   swarmchart3(x, y, z, sz, c)
+ *   swarmchart3(..., 'filled')
+ *   swarmchart3(..., markertype)
+ */
+export declare function parseSwarmchart3Args(args: RuntimeValue[]): Plot3Trace[];
+/**
+ * Parse piechart() / donutchart() arguments.
+ *
+ * Supported forms:
+ *   piechart(data)
+ *   piechart(data, names)
+ *
+ * @param innerRadius 0 for pie, >0 for donut
+ */
+export declare function parsePiechartArgs(args: RuntimeValue[], innerRadius: number): PieTrace;
+/**
+ * Parse heatmap() arguments.
+ *
+ * Supported forms:
+ *   heatmap(cdata)                — matrix of values
+ *   heatmap(xvalues, yvalues, cdata) — with axis labels
+ */
+export declare function parseHeatmapArgs(args: RuntimeValue[]): HeatmapTrace;
+/**
+ * Parse quiver() arguments.
+ *
+ * Supported forms:
+ *   quiver(U, V)
+ *   quiver(X, Y, U, V)
+ *   quiver(..., scale)        — scale: nonnegative number or 'off'
+ *   quiver(..., LineSpec)
+ *   quiver(..., LineSpec, 'filled')
+ *   quiver(..., Name, Value)  — Color, LineStyle, LineWidth, ShowArrowHead, etc.
+ *
+ * X, Y, U, V can be vectors or matrices. If U,V are matrices and X,Y are
+ * vectors, X and Y are expanded to a meshgrid.
+ */
+export declare function parseQuiverArgs(args: RuntimeValue[]): QuiverTrace[];
+/**
+ * Parse quiver3() arguments.
+ *
+ * Supported forms:
+ *   quiver3(Z, U, V, W)
+ *   quiver3(X, Y, Z, U, V, W)
+ *   quiver3(..., scale)         — scale: nonnegative number or 'off'
+ *   quiver3(..., LineSpec)
+ *   quiver3(..., LineSpec, 'filled')
+ *   quiver3(..., Name, Value)   — Color, LineStyle, LineWidth, ShowArrowHead, …
+ */
+export declare function parseQuiver3Args(args: RuntimeValue[]): Quiver3Trace;

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

@@ -0,0 +1,85 @@
+/**
+ * Reference counting for RuntimeValue containers, used both for
+ * lifecycle (decref → _destroy chain) and for refcount-driven COW.
+ *
+ * Every container kind extends `Refcounted`. The count starts at 0
+ * (newly-constructed value, not yet bound to anything), is incremented
+ * when a slot (env binding, struct field, cell element, ...) takes
+ * ownership, and decremented when the slot releases ownership. When the
+ * count reaches 0, `_destroy` runs and decrefs every child value.
+ *
+ * COW uses `effectiveRc(v)` — the count minus the number of currently
+ * active per-statement scopes that hold the value. Scope adoption is
+ * a transient lifecycle artifact (it keeps the wrapper alive across an
+ * expression's evaluation); it isn't an ownership relationship that
+ * should force a copy.
+ *
+ * Strict mode (`rt.strictRefcount`) makes a decref of an already-zero
+ * count throw.
+ */
+export declare function pushCurrentRuntime(rt: RefcountRuntime): void;
+export declare function popCurrentRuntime(rt: RefcountRuntime): void;
+export declare function getCurrentRuntime(): RefcountRuntime | null;
+/** Minimal runtime surface used by the refcount API. The real `Runtime`
+ *  class satisfies this; using an interface here avoids a circular
+ *  import between refcount.ts ↔ runtime.ts ↔ types.ts. */
+export interface RefcountRuntime {
+    /** When true, decref of a zero count throws. */
+    strictRefcount?: boolean;
+    /** Per-statement transient scope. Constructors auto-adopt fresh
+     *  values here so an unbound expression result stays alive until end
+     *  of statement. Null when no statement is in flight. */
+    currentScope?: RefScope | null;
+}
+/** Base class for every refcounted runtime value. */
+export declare abstract class Refcounted {
+    /** Public so type guards can look for a `kind` discriminator without
+     *  walking the prototype. The string is set by every subclass. */
+    abstract readonly kind: string;
+    /** Reference count. Starts at 0; incremented when bound to a slot. */
+    _rc: number;
+    /** Subset of `_rc` contributed by active per-statement scopes. The
+     *  COW check uses `_rc - _scopeHolds` so transient scope holds don't
+     *  force unnecessary copies (a value freshly constructed during a
+     *  statement and passed to a function would otherwise look "shared"
+     *  to the callee). */
+    _scopeHolds: number;
+    constructor();
+    incref(): void;
+    decref(rt: RefcountRuntime): void;
+    /** Subclasses release child refs. Idempotent must NOT be assumed —
+     *  callers guarantee this fires exactly once. Default is a no-op for
+     *  kinds that have no child refs (RuntimeChar, RuntimeComplexNumber,
+     *  RuntimeDummyHandle, etc.). */
+    protected _destroy(_rt: RefcountRuntime): void;
+}
+/** True if the value is a container that participates in refcounting.
+ *  Primitives (number, boolean, string) return false. */
+export declare function isRefcountable(v: unknown): v is Refcounted;
+/** Increment refcount on a value if it's a container; primitives are noop. */
+export declare function incref(v: unknown): void;
+/** Decrement refcount on a value if it's a container; primitives are noop. */
+export declare function decref(rt: RefcountRuntime, v: unknown): void;
+/** True if `v` has more than one external (non-scope) holder — i.e. a
+ *  mutation through one slot would observably affect another holder.
+ *  Primitives return false; primitives can never be "shared" since
+ *  every slot stores a copy of the value. */
+export declare function isShared(v: unknown): boolean;
+/** Per-statement transients harness. Fresh values produced by constructors
+ *  and operators are adopted here at rc=1; on `drain`, every member is
+ *  decref'd. Anything bound to a slot during the statement gets an extra
+ *  incref from the slot, so it survives drain at slot count.
+ *
+ *  Each adopt also increments the value's `_scopeHolds`, which the COW
+ *  check (`isShared`) subtracts from `_rc` — the scope's hold is a
+ *  lifecycle artifact, not an ownership relationship that should force
+ *  a copy. */
+export declare class RefScope {
+    private members;
+    /** Take ownership of a fresh value: incref and remember for drain. */
+    adopt(v: unknown): void;
+    /** Release every adopted value. Called in `withScope`'s finally. */
+    drain(rt: RefcountRuntime): void;
+    /** Number of currently-adopted values (for assertions/tests). */
+    size(): number;
+}