numbl 0.4.7 → 0.4.9

package/dist-browser/numbl-core/ops/opCodes.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Op-code enums for the tensor-ops layer.
+ *
+ * SINGLE SOURCE OF TRUTH on the TS side. Mirrors native/ops/numbl_ops.h.
+ * Drift detection: src/__tests__/op-codes-sync.test.ts compares this file's
+ * values against numbl_dump_op_codes() at CI time.
+ */
+/** Real binary element-wise ops. */
+export declare const OpRealBin: {
+    readonly ADD: 0;
+    readonly SUB: 1;
+    readonly MUL: 2;
+    readonly DIV: 3;
+};
+/** Complex binary element-wise ops. */
+export declare const OpComplexBin: {
+    readonly ADD: 0;
+    readonly SUB: 1;
+    readonly MUL: 2;
+    readonly DIV: 3;
+};
+/** Flat reduction ops. */
+export declare const OpReduce: {
+    readonly SUM: 0;
+    readonly PROD: 1;
+    readonly MAX: 2;
+    readonly MIN: 3;
+    readonly ANY: 4;
+    readonly ALL: 5;
+    readonly MEAN: 6;
+};
+/** Comparison ops (logical output). */
+export declare const OpCmp: {
+    readonly EQ: 0;
+    readonly NE: 1;
+    readonly LT: 2;
+    readonly LE: 3;
+    readonly GT: 4;
+    readonly GE: 5;
+};
+/** Bessel function ops (real input). H-variants are in numbl_bessel_h (complex output). */
+export declare const OpBessel: {
+    readonly J: 0;
+    readonly Y: 1;
+    readonly I: 2;
+    readonly K: 3;
+};
+/** Unary element-wise ops (shared numbering for real + complex). */
+export declare const OpUnary: {
+    readonly EXP: 0;
+    readonly LOG: 1;
+    readonly LOG2: 2;
+    readonly LOG10: 3;
+    readonly SQRT: 4;
+    readonly ABS: 5;
+    readonly FLOOR: 6;
+    readonly CEIL: 7;
+    readonly ROUND: 8;
+    readonly TRUNC: 9;
+    readonly SIN: 10;
+    readonly COS: 11;
+    readonly TAN: 12;
+    readonly ASIN: 13;
+    readonly ACOS: 14;
+    readonly ATAN: 15;
+    readonly SINH: 16;
+    readonly COSH: 17;
+    readonly TANH: 18;
+    readonly SIGN: 19;
+};

package/dist-browser/numbl-core/ops/realBinaryElemwise.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pure-TS implementation of real binary element-wise ops.
+ * Mirrors native/ops/real_binary_elemwise.c.
+ *
+ * Caller-allocated input/output buffers; never copies.
+ */
+export declare function tsRealBinaryElemwise(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+export declare function tsRealScalarBinaryElemwise(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;

package/dist-browser/numbl-core/ops/realUnaryElemwise.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Pure-TS implementation of real unary element-wise ops.
+ * Mirrors native/ops/real_unary_elemwise.c.
+ */
+export declare function tsRealUnaryElemwise(op: number, n: number, a: Float64Array, out: Float64Array): void;

package/dist-browser/numbl-core/ops/reduce.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Pure-TS flat reductions.  Mirrors native/ops/reduce.c.
+ * Caller-allocated input and output (1-element).
+ */
+export declare function tsRealFlatReduce(op: number, n: number, a: Float64Array, out: Float64Array): void;
+export declare function tsComplexFlatReduce(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array | null): void;

package/dist-browser/numbl-core/parser/ArgumentsParser.d.ts

@@ -0,0 +1,33 @@
+import { ArgumentsBlock } from "./types.js";
+import { ControlFlowParser } from "./ControlFlowParser.js";
+export declare class ArgumentsParser extends ControlFlowParser {
+    /**
+     * Parse all consecutive arguments blocks at the top of a function body.
+     * Returns an array of ArgumentsBlock (may be empty if none present).
+     */
+    parseArgumentsBlocks(): ArgumentsBlock[];
+    private parseOneArgumentsBlock;
+    private parseArgumentsBlockKind;
+    private parseArgumentEntry;
+    /**
+     * Parse dimension list: (1,:) → ["1", ":"]
+     */
+    private parseArgDimensions;
+    /**
+     * Parse validator list: {mustBeNumeric, mustBePositive}. Validators may be
+     * full function calls with arguments, e.g.
+     * `{mustBeMember(x,["a","b"]), mustBeInRange(x,0,7)}`. The validator bodies
+     * are not enforced at runtime, so we capture the top-level validator name
+     * tokens and skip past any nested `(...)`, `[...]`, `{...}` so parsing
+     * resumes correctly at the default value (`= expr`) or end of line.
+     */
+    private parseArgValidators;
+    /**
+     * Consume a single line terminator (newline or semicolon).
+     */
+    private consumeLineEnd;
+    /**
+     * Consume all consecutive line terminators.
+     */
+    private consumeLineEnds;
+}

package/dist-browser/numbl-core/parser/ClassParser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ClassParser - Class and import definition parsing methods
+ */
+import { Stmt } from "./types.js";
+import { FunctionParser } from "./FunctionParser.js";
+export declare class ClassParser extends FunctionParser {
+    parseImport(): Stmt;
+    parseClassDef(): Stmt;
+    private parseNameBlock;
+    private parsePropertiesNamesBlock;
+    /** Consume a balanced `open ... close` run (handling nesting). Assumes the
+     *  next token is `open`; no-op otherwise. */
+    private skipBalanced;
+    private parseOptionalAttrList;
+    /**
+     * Parse a single method signature.
+     * Returns null if parsing fails or current position doesn't look like a signature.
+     */
+    private parseSingleMethodSignature;
+    private parseMethodSignatures;
+}

package/dist-browser/numbl-core/parser/CommandParser.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CommandParser - Command form parsing methods
+ */
+import { Expr } from "./types.js";
+import { ExpressionParser } from "./ExpressionParser.js";
+export declare class CommandParser extends ExpressionParser {
+    /**
+     * Detect whether the current position starts a command-form statement.
+     *
+     * Uses raw source scanning: an identifier followed by horizontal whitespace
+     * and then non-operator content is command form.  Zero-arg invocations
+     * (e.g. `hold` alone) are handled by the expression parser + lowering
+     * which resolves bare identifiers to zero-arg function calls.
+     */
+    canStartCommandForm(): boolean;
+    /**
+     * Parse command arguments from the raw source text.
+     *
+     * Each whitespace-delimited token becomes a Char (character vector) node,
+     * matching MATLAB's command-syntax semantics.  Single-quoted strings
+     * preserve interior spaces.
+     *
+     * Call this AFTER consuming the verb token with next().
+     */
+    parseCommandArgsGeneral(): Expr[];
+    /**
+     * Check whether the character at `pos` in `this.input` can start a
+     * command-syntax argument (as opposed to a binary operator).
+     */
+    private isCommandArgStart;
+}

package/dist-browser/numbl-core/parser/ControlFlowParser.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ControlFlowParser - Control flow parsing methods (if/while/for/switch/try-catch)
+ */
+import { Token } from "../lexer/index.js";
+import { Stmt } from "./types.js";
+import { CommandParser } from "./CommandParser.js";
+export declare class ControlFlowParser extends CommandParser {
+    parseIf(): Stmt;
+    parseWhile(): Stmt;
+    parseFor(): Stmt;
+    parseSwitch(): Stmt;
+    parseTryCatch(): Stmt;
+    parseBlock(term: (t: Token) => boolean): Stmt[];
+    protected parseStmt(): Stmt;
+    protected tryParseMultiAssign(): Stmt;
+}

package/dist-browser/numbl-core/parser/ExpressionParser.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ExpressionParser - Expression parsing methods
+ */
+import { Expr } from "./types.js";
+import { ParserBase } from "./ParserBase.js";
+export declare class ExpressionParser extends ParserBase {
+    parseExpr(): Expr;
+    private parseLogicalOr;
+    private parseLogicalAnd;
+    private parseBitwiseOr;
+    private parseBitwiseAnd;
+    private parseComparison;
+    private parseRange;
+    private parseAddSub;
+    private parseMulDiv;
+    private parsePow;
+    /** Parse the right-hand side of a ^ or .^ operator: unary prefixes then postfix. */
+    private parsePowRHS;
+    private parsePostfixWithBase;
+    private parsePostfix;
+    private parseUnary;
+    private parsePrimary;
+    private parseMatrix;
+    private parseMatrixExpr;
+    private parseCell;
+    /**
+     * Parse a single function call argument, handling MATLAB's Name=Value
+     * syntax. `foo(x, y, LineWidth=2)` is desugared to
+     * `foo(x, y, 'LineWidth', 2)` by pushing two args into the array.
+     */
+    private parseFuncArg;
+}

package/dist-browser/numbl-core/parser/FunctionParser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * FunctionParser - Function definition parsing methods
+ */
+import { Stmt } from "./types.js";
+import { ArgumentsParser } from "./ArgumentsParser.js";
+export declare class FunctionParser extends ArgumentsParser {
+    parseFunction(): Stmt;
+    parseGlobal(): Stmt;
+    parsePersistent(): Stmt;
+}

package/dist-browser/numbl-core/parser/Parser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parser - Main entry point
+ *
+ * This parser has been split into multiple modules for better maintainability:
+ * - ParserBase: Core state and utility methods
+ * - ExpressionParser: Expression and matrix/cell parsing
+ * - CommandParser: Command-form syntax parsing
+ * - ControlFlowParser: Control flow constructs (if/while/for/switch/try-catch)
+ * - FunctionParser: Function and global/persistent declarations
+ * - ClassParser: Class and import definitions
+ * - StatementParser: Top-level statement parsing and program entry
+ *
+ * All functionality is composed through class inheritance.
+ */
+import { StatementParser } from "./StatementParser.js";
+export declare class Parser extends StatementParser {
+}

package/dist-browser/numbl-core/parser/ParserBase.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ParserBase - Core parser state and utility methods
+ */
+import { Token } from "../lexer/index.js";
+import { Span, TokenInfo, Expr, BinaryOperation, UnaryOperation } from "./types.js";
+import { SyntaxError } from "./errors.js";
+export declare class ParserBase {
+    protected tokens: TokenInfo[];
+    protected pos: number;
+    protected input: string;
+    protected fileName: string;
+    protected inMatrixExpr: boolean;
+    constructor(tokens: TokenInfo[], input: string, fileName?: string);
+    protected peek(): TokenInfo | undefined;
+    protected currentPosition(): number;
+    protected peekToken(): Token | undefined;
+    protected peekTokenAt(offset: number): Token | undefined;
+    protected next(): TokenInfo | undefined;
+    protected consume(t: Token): boolean;
+    protected skipNewlines(): void;
+    protected tokensAdjacent(left: number, right: number): boolean;
+    protected spanFrom(start: number, end: number): Span;
+    protected spanBetween(start: Span, end: Span): Span;
+    protected lastTokenEnd(): number;
+    protected makeBinary(left: Expr, op: BinaryOperation, right: Expr): Expr;
+    protected makeUnary(op: UnaryOperation, operand: Expr, opStart: number): Expr;
+    protected isSimpleAssignmentAhead(): boolean;
+    protected error(message: string): SyntaxError;
+    protected errorWithExpected(message: string, expected: string): SyntaxError;
+    protected expectIdent(): string;
+    /** Accept an identifier or any keyword token as a member name (after '.') */
+    protected expectMemberName(): string;
+    protected expectIdentOrTilde(): string;
+    protected parseQualifiedName(): string;
+}

package/dist-browser/numbl-core/parser/StatementParser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * StatementParser - Statement parsing methods
+ */
+import { Stmt, AbstractSyntaxTree } from "./types.js";
+import { ClassParser } from "./ClassParser.js";
+export declare class StatementParser extends ClassParser {
+    parseProgram(): AbstractSyntaxTree;
+    private parseStmtWithSemicolon;
+    parseStmt(): Stmt;
+    private tryParseLValueAssign;
+    tryParseMultiAssign(): Stmt;
+    private parseMultiAssignLValue;
+}

package/dist-browser/numbl-core/parser/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Parser error classes.
+ */
+export declare class SyntaxError extends Error {
+    position: number;
+    line: number | null;
+    /** Source file name (set when parsing workspace files, or resolved in prepare.ts) */
+    file: string | null;
+    foundToken: string | null;
+    expected: string | null;
+    /** 1-based column number (resolved in prepare.ts for non-workspace-file errors) */
+    column: number | undefined;
+    constructor(message: string, position: number, foundToken?: string | null, expected?: string | null, line?: number | null);
+    toString(): string;
+}

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

@@ -0,0 +1,7 @@
+import { AbstractSyntaxTree } from "./types.js";
+export * from "./types.js";
+export { SyntaxError } from "./errors.js";
+/**
+ * Parse code with default options.
+ */
+export declare function parseMFile(input: string, fileName?: string): AbstractSyntaxTree;

package/dist-browser/numbl-core/parser/types.d.ts

@@ -0,0 +1,342 @@
+import { Token } from "../lexer/index.js";
+export interface Span {
+    file: string;
+    start: number;
+    end: number;
+}
+export interface TokenInfo {
+    token: Token;
+    lexeme: string;
+    position: number;
+    end: number;
+}
+export declare enum BinaryOperation {
+    Add = "Add",
+    Sub = "Sub",
+    Mul = "Mul",
+    ElemMul = "ElemMul",
+    Div = "Div",
+    ElemDiv = "ElemDiv",
+    LeftDiv = "LeftDiv",
+    ElemLeftDiv = "ElemLeftDiv",
+    Pow = "Pow",
+    ElemPow = "ElemPow",
+    Equal = "Equal",
+    NotEqual = "NotEqual",
+    Less = "Less",
+    LessEqual = "LessEqual",
+    Greater = "Greater",
+    GreaterEqual = "GreaterEqual",
+    OrOr = "OrOr",
+    AndAnd = "AndAnd",
+    BitOr = "BitOr",
+    BitAnd = "BitAnd"
+}
+export declare enum UnaryOperation {
+    Plus = "Plus",
+    Minus = "Minus",
+    Not = "Not",
+    Transpose = "Transpose",
+    NonConjugateTranspose = "NonConjugateTranspose"
+}
+export type Expr = {
+    type: "Number";
+    value: string;
+    span: Span;
+} | {
+    type: "Char";
+    value: string;
+    span: Span;
+} | {
+    type: "String";
+    value: string;
+    span: Span;
+} | {
+    type: "Ident";
+    name: string;
+    span: Span;
+} | {
+    type: "EndKeyword";
+    span: Span;
+} | {
+    type: "ImagUnit";
+    span: Span;
+} | {
+    type: "Colon";
+    span: Span;
+} | {
+    type: "MetaClass";
+    name: string;
+    span: Span;
+} | {
+    type: "Binary";
+    left: Expr;
+    op: BinaryOperation;
+    right: Expr;
+    span: Span;
+} | {
+    type: "Unary";
+    op: UnaryOperation;
+    operand: Expr;
+    span: Span;
+} | {
+    type: "Range";
+    start: Expr;
+    step: Expr | null;
+    end: Expr;
+    span: Span;
+} | {
+    type: "FuncCall";
+    name: string;
+    args: Expr[];
+    span: Span;
+} | {
+    type: "Index";
+    base: Expr;
+    indices: Expr[];
+    span: Span;
+} | {
+    type: "IndexCell";
+    base: Expr;
+    indices: Expr[];
+    span: Span;
+} | {
+    type: "Member";
+    base: Expr;
+    name: string;
+    span: Span;
+} | {
+    type: "MemberDynamic";
+    base: Expr;
+    nameExpr: Expr;
+    span: Span;
+} | {
+    type: "MethodCall";
+    base: Expr;
+    name: string;
+    args: Expr[];
+    span: Span;
+} | {
+    type: "SuperMethodCall";
+    methodName: string;
+    superClassName: string;
+    args: Expr[];
+    span: Span;
+} | {
+    type: "AnonFunc";
+    params: string[];
+    body: Expr;
+    span: Span;
+} | {
+    type: "FuncHandle";
+    name: string;
+    span: Span;
+} | {
+    type: "Tensor";
+    rows: Expr[][];
+    span: Span;
+} | {
+    type: "Cell";
+    rows: Expr[][];
+    span: Span;
+} | {
+    type: "ClassInstantiation";
+    className: string;
+    args: Expr[];
+    span: Span;
+};
+export type LValue = {
+    type: "Var";
+    name: string;
+} | {
+    type: "Ignore";
+} | {
+    type: "Index";
+    base: Expr;
+    indices: Expr[];
+} | {
+    type: "IndexCell";
+    base: Expr;
+    indices: Expr[];
+} | {
+    type: "Member";
+    base: Expr;
+    name: string;
+} | {
+    type: "MemberDynamic";
+    base: Expr;
+    nameExpr: Expr;
+};
+export interface Attr {
+    name: string;
+    value: string | null;
+}
+export interface MethodSignature {
+    name: string;
+    params: string[];
+    outputs: string[];
+    span: Span;
+}
+export type ClassMember = {
+    type: "Properties";
+    attributes: Attr[];
+    names: string[];
+    defaultValues: (Expr | null)[];
+} | {
+    type: "Methods";
+    attributes: Attr[];
+    body: Stmt[];
+    signatures?: MethodSignature[];
+} | {
+    type: "Events";
+    attributes: Attr[];
+    names: string[];
+} | {
+    type: "Enumeration";
+    attributes: Attr[];
+    names: string[];
+} | {
+    type: "Arguments";
+    attributes: Attr[];
+    names: string[];
+};
+export type ArgumentsBlockKind = "Input" | "Output" | "Repeating" | "OutputRepeating";
+export interface ArgumentEntry {
+    name: string;
+    dimensions: string[] | null;
+    className: string | null;
+    validators: string[];
+    defaultValue: Expr | null;
+}
+export interface ArgumentsBlock {
+    kind: ArgumentsBlockKind;
+    entries: ArgumentEntry[];
+}
+export type Stmt = {
+    type: "ExprStmt";
+    expr: Expr;
+    suppressed: boolean;
+    span: Span;
+} | {
+    type: "Assign";
+    name: string;
+    expr: Expr;
+    suppressed: boolean;
+    span: Span;
+} | {
+    type: "MultiAssign";
+    lvalues: LValue[];
+    expr: Expr;
+    suppressed: boolean;
+    span: Span;
+} | {
+    type: "AssignLValue";
+    lvalue: LValue;
+    expr: Expr;
+    suppressed: boolean;
+    span: Span;
+} | {
+    type: "If";
+    cond: Expr;
+    thenBody: Stmt[];
+    elseifBlocks: Array<{
+        cond: Expr;
+        body: Stmt[];
+    }>;
+    elseBody: Stmt[] | null;
+    span: Span;
+} | {
+    type: "While";
+    cond: Expr;
+    body: Stmt[];
+    span: Span;
+} | {
+    type: "For";
+    varName: string;
+    expr: Expr;
+    body: Stmt[];
+    span: Span;
+} | {
+    type: "Switch";
+    expr: Expr;
+    cases: Array<{
+        value: Expr;
+        body: Stmt[];
+    }>;
+    otherwise: Stmt[] | null;
+    span: Span;
+} | {
+    type: "TryCatch";
+    tryBody: Stmt[];
+    catchVar: string | null;
+    catchBody: Stmt[];
+    span: Span;
+} | {
+    type: "Function";
+    name: string;
+    functionId: string;
+    params: string[];
+    outputs: string[];
+    body: Stmt[];
+    argumentsBlocks: ArgumentsBlock[];
+    isFileLocalSubfunction?: boolean;
+    span: Span;
+} | {
+    type: "Global";
+    names: string[];
+    span: Span;
+} | {
+    type: "Persistent";
+    names: string[];
+    span: Span;
+} | {
+    type: "Break";
+    span: Span;
+} | {
+    type: "Continue";
+    span: Span;
+} | {
+    type: "Return";
+    span: Span;
+} | {
+    type: "Import";
+    path: string[];
+    wildcard: boolean;
+    span: Span;
+} | {
+    type: "ClassDef";
+    name: string;
+    classAttributes: Attr[];
+    superClass: string | null;
+    members: ClassMember[];
+    span: Span;
+} | {
+    /** Magic comment directive, e.g. `%!numbl:assert_jit` or `%!numbl:assert_jit c`. */
+    type: "Directive";
+    directive: string;
+    args: string[];
+    span: Span;
+} | {
+    /** Synthetic stmt produced by an executor-registered AST
+     *  transformer (e.g. the C-JIT chain pass). Wraps a contiguous
+     *  run of original stmts so a specialized executor can claim
+     *  them as a unit; the interpreter falls back to executing
+     *  `subStmts` in order when the executor isn't registered or
+     *  declines.
+     *
+     *  Never produced by the parser. */
+    type: "Synth";
+    /** Identifies the executor that this synth node was built for
+     *  (e.g. `"c-jit-chain"`). The matching executor reads `data`. */
+    tag: string;
+    /** Original adjacent stmts, in source order. Used by the
+     *  interpreter fallback. */
+    subStmts: Stmt[];
+    /** Executor-specific pre-computed analysis. Opaque to the
+     *  interpreter. */
+    data: unknown;
+    span: Span;
+};
+export interface AbstractSyntaxTree {
+    body: Stmt[];
+}

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

@@ -0,0 +1,12 @@
+/** Allocate a Float64Array. Thin wrapper around `new Float64Array(x)`
+ *  kept as a single allocation site so future strategies (pooling,
+ *  COW-aware allocation, etc.) can be reintroduced without touching
+ *  every callsite. */
+export declare function allocFloat64Array(x: number | number[] | Float64Array): Float64Array;
+/** No-op. Kept as a placeholder for future explicit-release strategies
+ *  (e.g. pool release, arena reset). With pure JS GC, scratch buffers
+ *  are reclaimed when the wrapper goes out of scope. */
+export declare function releaseFloat64Array(_buf: Float64Array): void;
+/** Pass-through. Kept as a placeholder for future scratch-arena
+ *  strategies. Today it just runs `fn` and returns its result. */
+export declare function withScratch<T>(fn: () => T): T;