numbl 0.1.0 → 0.1.2

package/dist-lib/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-lib/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-lib/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-lib/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-lib/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-lib/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-lib/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-lib/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-lib/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-lib/numbl-core/parser/types.d.ts

@@ -0,0 +1,316 @@
+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;
+};
+export interface AbstractSyntaxTree {
+    body: Stmt[];
+}

package/dist-lib/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-lib/numbl-core/runtime/constructors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * RuntimeValue constructor helpers (the MV namespace).
+ */
+import { ItemType } from "../lowering/itemTypes.js";
+import { type RuntimeNumber, type RuntimeTensor, type RuntimeString, type RuntimeChar, type RuntimeLogical, type RuntimeCell, type RuntimeStruct, type RuntimeFunction, type RuntimeClassInstance, type RuntimeComplexNumber, type RuntimeDummyHandle, type RuntimeStructArray, type RuntimeSparseMatrix, type RuntimeDictionary, type RuntimeValue, type FloatXArrayType } from "./types.js";
+export declare const RTV: {
+    num(value: number): RuntimeNumber;
+    tensor(data: FloatXArrayType | number[], shape: number[], imag?: FloatXArrayType | number[]): RuntimeTensor;
+    /** Fast tensor constructor — data must be FloatXArray, shape already normalized (no trailing singletons). */
+    tensorRaw(data: FloatXArrayType, 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[] | FloatXArrayType, imag?: number[] | FloatXArrayType): RuntimeTensor;
+    string(value: string): RuntimeString;
+    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;
+    complex(re: number, im: number): RuntimeComplexNumber;
+    dummyHandle(): RuntimeDummyHandle;
+    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-lib/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-lib/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-lib/numbl-core/runtime/error.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 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;
+    /** 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-lib/numbl-core/runtime/index.d.ts

@@ -0,0 +1,12 @@
+export type { RuntimeValue, RuntimeTensor, RuntimeString, RuntimeLogical, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeDictionary, } from "./types.js";
+export { RuntimeError, offsetToLine, offsetToColumn } from "./error.js";
+export type { CallFrame } from "./error.js";
+export { tensorSize2D, numel, colMajorIndex, shareRuntimeValue, } 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, } 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-lib/numbl-core/runtime/indexing.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Indexing, struct field access, range creation, and tensor concatenation.
+ */
+import { type RuntimeValue } from "./types.js";
+/** Sentinel marker for colon (:) indexing — means "all indices in this dimension" */
+export declare const COLON_INDEX: RuntimeValue;
+/** 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): RuntimeValue;