numbl 0.4.7 → 0.4.9

package/dist-browser/numbl-core/jitTypes.d.ts

@@ -0,0 +1,94 @@
+/**
+ * JIT type system.
+ *
+ * Used by the executor classification phase and by the JIT type
+ * adapter to map numbl runtime values onto JIT specializations.
+ * The IR node definitions that previously lived alongside this file
+ * (`JitExpr` / `JitStmt` / `JitCacheEntry`) belonged to the legacy
+ * in-tree JS-JIT / C-JIT pipeline and were deleted with it.
+ */
+export type SignCategory = "positive" | "nonneg" | "nonpositive" | "negative";
+export type JitType = {
+    kind: "number";
+    exact?: number;
+    sign?: SignCategory;
+    isInteger?: boolean;
+} | {
+    kind: "boolean";
+    value?: boolean;
+} | {
+    kind: "complex_or_number";
+    pureImaginary?: boolean;
+} | {
+    kind: "tensor";
+    isComplex: boolean;
+    shape?: number[];
+    ndim?: number;
+    isLogical?: boolean;
+    nonneg?: boolean;
+} | {
+    kind: "string";
+    value?: string;
+} | {
+    kind: "char";
+    value?: string;
+} | {
+    kind: "struct";
+    fields?: Record<string, JitType>;
+} | {
+    /**
+     * A 1-D homogeneous array of structs (matlab struct array form
+     * `T.nodes(i)`). `elemFields` records the per-element field types
+     * unified across all elements. `length` is optional and carries
+     * the statically-known element count when available.
+     */
+    kind: "struct_array";
+    elemFields?: Record<string, JitType>;
+    length?: number;
+} | {
+    kind: "class_instance";
+    className: string;
+    isHandleClass?: boolean;
+    fields?: Record<string, JitType>;
+} | {
+    kind: "sparse_matrix";
+    isComplex: boolean;
+    m?: number;
+    n?: number;
+} | {
+    kind: "cell";
+    shape?: number[];
+    /** Per-index element types (1-based), tracked when literal-index
+     *  writes happen with a known type. Reads with a literal index in
+     *  the map return the tracked type instead of `unknown`, which
+     *  unblocks chunkerfunc's `[out{1:3}] = fcurve(ts); r = out{1}; …`
+     *  pattern. Sparse — missing keys mean "unknown". */
+    elements?: Record<number, JitType>;
+} | {
+    kind: "dictionary";
+} | {
+    kind: "function_handle";
+} | {
+    kind: "unknown";
+};
+export declare function signFromNumber(v: number): SignCategory | undefined;
+export declare function isNonneg(t: JitType): boolean;
+export declare function flipSign(s?: SignCategory): SignCategory | undefined;
+export declare function unifySign(a?: SignCategory, b?: SignCategory): SignCategory | undefined;
+export declare function jitTypeKey(t: JitType): string;
+/** Widen/unify two types at control-flow join points. */
+export declare function unifyJitTypes(a: JitType, b: JitType): JitType;
+export declare function isScalarType(t: JitType): boolean;
+export declare function isNumericScalarType(t: JitType): boolean;
+export declare function isTensorType(t: JitType): boolean;
+export declare function isComplexType(t: JitType): boolean;
+/** True when the type guarantees an integer value at runtime (safe for |0). */
+export declare function isKnownInteger(t: JitType): boolean;
+/** Types that support arithmetic binary operations in the JIT. */
+export declare function isArithmeticType(t: JitType): boolean;
+export declare function shapeAfterReduction(shape: number[], dim?: number): {
+    scalar: true;
+} | {
+    scalar: false;
+    shape: number[];
+};

package/dist-browser/numbl-core/jsUserFunctions.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Loader for .numbl.js user functions.
+ *
+ * Evaluates .numbl.js files that define IBuiltins via
+ *   register({ resolve }).
+ * Supports optional WASM and native shared library bindings via directives:
+ *   // wasm: <name>
+ *   // native: <name>
+ *
+ * The `.numbl.js` extension distinguishes numbl user functions from
+ * unrelated `.js` files (config files, source maps, etc.) so that they can
+ * be auto-discovered from the current working directory like `.m` files.
+ */
+import type { WorkspaceFile, NativeBridge } from "./workspace/index.js";
+import type { IBuiltin } from "./interpreter/builtins/types.js";
+/**
+ * Per-WASM-instance registry that exposes numbl function handles to WASM as
+ * integer ids. A `.numbl.js` apply registers a JS thunk (closing over a
+ * handle + `callHandle`) with `add()`, passes the returned id into a WASM
+ * export, and removes it once the export returns. Inside WASM the handle is
+ * invoked by calling the host-provided `env.numbl_cb_d(id, x)` import.
+ */
+export interface WasmCallbackRegistry {
+    /** Register a callback thunk; returns its integer id. */
+    add(fn: (...args: number[]) => number): number;
+    /** Drop a previously registered callback. */
+    remove(id: number): void;
+}
+/** A loaded JS user function ready for registration in the workspace. */
+export interface LoadedJsUserFunction {
+    name: string;
+    fileName: string;
+    builtin: IBuiltin;
+}
+/** Returns true if the file is a numbl JS user function file (`*.numbl.js`). */
+export declare function isNumblJsFile(fileName: string): boolean;
+/** Returns true if the file is an mtoc2-only user function file (`*.mtoc2.js`).
+ *  Numbl recognizes the extension for workspace discovery + function-name
+ *  resolution, but never executes the body — mtoc2's loader does that. */
+export declare function isMtoc2JsFile(fileName: string): boolean;
+/** Derive a function name from a `.mtoc2.js` workspace file path.
+ *    "myadd.mtoc2.js"            → "myadd"
+ *    "/path/to/myadd.mtoc2.js"   → "myadd" */
+export declare function funcNameFromMtoc2JsFile(fileName: string): string;
+/**
+ * Load .numbl.js user function files and return them as LoadedJsUserFunction
+ * records. Each loaded record carries the function name, source file name,
+ * and the IBuiltin object built from the file's `register()` call.
+ *
+ * Each .numbl.js file calls register({ resolve }) to define an
+ * IBuiltin. resolve(argTypes, nargout) returns { outputTypes, apply } or null.
+ *
+ * A .numbl.js file can specify bindings via directives at the top of the file:
+ *   // wasm: <name>    — load a WASM module (looked up by name in wasmFiles)
+ *   // native: <name>  — load a native shared library (resolved relative to file)
+ *
+ * Files whose basename starts with `_` are library files. They must not call
+ * register() and instead export values via `return`. Other .numbl.js files
+ * can import them with `importJS("_name")`.
+ */
+export declare function loadJsUserFunctions(jsFiles: WorkspaceFile[], wasmFiles?: WorkspaceFile[], nativeBridge?: NativeBridge): LoadedJsUserFunction[];

package/dist-browser/numbl-core/lexer/helpers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Helper functions for the lexer.
+ */
+import { Token } from "./types.js";
+export declare function isAlpha(ch: string): boolean;
+export declare function isAlnum(ch: string): boolean;
+export declare function isDigit(ch: string): boolean;
+export declare function isWhitespace(ch: string): boolean;
+/** Check if a token represents a "value" for transpose disambiguation. */
+export declare function isValueToken(tok: Token): boolean;
+/**
+ * Find the first line terminator (\n or \r\n or \r) in `s`.
+ * Returns [index, length] or undefined.
+ */
+export declare function findLineTerminator(s: string, offset?: number): [number, number] | undefined;

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

@@ -0,0 +1,4 @@
+export { Token } from "./types.js";
+export { KEYWORDS, VALUE_KEYWORDS } from "./keywords.js";
+export { isAlpha, isAlnum, isDigit, isWhitespace, isValueToken, findLineTerminator, } from "./helpers.js";
+export { tokenize, tokenizeDetailed } from "./tokenizer.js";

package/dist-browser/numbl-core/lexer/keywords.d.ts

@@ -0,0 +1,3 @@
+import { Token } from "./types.js";
+export declare const KEYWORDS: ReadonlyMap<string, Token>;
+export declare const VALUE_KEYWORDS: ReadonlySet<Token>;

package/dist-browser/numbl-core/lexer/token-config.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Token configuration types and loader.
+ */
+import { Token } from "./types.js";
+export interface OperatorConfig {
+    pattern: string;
+    token: string;
+    special?: string;
+}
+export interface BlockCommentConfig {
+    start: string;
+    end: string;
+    consumeTrailingNewline?: boolean;
+}
+export interface SectionMarkerConfig {
+    pattern: string;
+    requireLineStart: boolean;
+    token: string;
+    consumeToEOL: boolean;
+    consumeTrailingNewline?: boolean;
+    fallbackToLineComment?: boolean;
+}
+export interface LineCommentConfig {
+    start: string;
+}
+export interface CommentsConfig {
+    blockComment: BlockCommentConfig;
+    sectionMarker: SectionMarkerConfig;
+    lineComment: LineCommentConfig;
+}
+export interface StringDisambiguation {
+    type: "transpose";
+    transposeToken: string;
+    conditions: {
+        requireAdjacency: boolean;
+        requirePrevValueOrDot: boolean;
+    };
+}
+export interface StringConfig {
+    delimiter: string;
+    escape: string;
+    token: string;
+    allowMultiline: boolean;
+    disambiguation?: StringDisambiguation;
+}
+export interface SpecialPatternConfig {
+    pattern: string;
+    token: string;
+    consumeToEOL?: boolean;
+    consumeTrailingNewline?: boolean;
+    coalesceMultiple?: boolean;
+    setsLineStart?: boolean;
+}
+export interface NumbersConfig {
+    allowUnderscores: boolean;
+    stripUnderscores: boolean;
+    integerToken: string;
+    floatToken: string;
+    exponentChars: string[];
+    decimalPoint: string;
+    dotOperatorPrefixes: string[];
+}
+export interface IdentifiersConfig {
+    token: string;
+    startChars: "alpha";
+    continueChars: "alnum";
+}
+export interface TokenConfig {
+    operators: {
+        twoChar: OperatorConfig[];
+        singleChar: OperatorConfig[];
+    };
+    comments: CommentsConfig;
+    strings: StringConfig[];
+    special: {
+        ellipsis: SpecialPatternConfig;
+        newline: SpecialPatternConfig;
+    };
+    numbers: NumbersConfig;
+    identifiers: IdentifiersConfig;
+}
+export declare const TOKEN_CONFIG: TokenConfig;
+/**
+ * Build a map from pattern to token for two-character operators.
+ */
+export declare function buildTwoCharMap(): Map<string, Token>;
+/**
+ * Build a map from pattern to token for single-character operators.
+ */
+export declare function buildSingleCharMap(): Map<string, Token>;
+/**
+ * Get the special behavior flag for a single-character operator.
+ */
+export declare function getSingleCharSpecial(pattern: string): string | undefined;

package/dist-browser/numbl-core/lexer/tokenizer.d.ts

@@ -0,0 +1,9 @@
+import { SpannedToken, Token } from "./types.js";
+/**
+ * Tokenize source into a flat token array (no newlines).
+ */
+export declare function tokenize(input: string): Token[];
+/**
+ * Tokenize source with full span information.
+ */
+export declare function tokenizeDetailed(input: string): SpannedToken[];

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

@@ -0,0 +1,80 @@
+export declare enum Token {
+    Integer = 0,
+    Float = 1,
+    Str = 2,
+    Char = 3,
+    Ident = 4,
+    Function = 5,
+    If = 6,
+    Else = 7,
+    ElseIf = 8,
+    For = 9,
+    ParFor = 10,
+    While = 11,
+    Break = 12,
+    Continue = 13,
+    Return = 14,
+    End = 15,
+    ClassDef = 16,
+    Properties = 17,
+    Methods = 18,
+    Events = 19,
+    Enumeration = 20,
+    Arguments = 21,
+    Import = 22,
+    Switch = 23,
+    Case = 24,
+    Otherwise = 25,
+    Try = 26,
+    Catch = 27,
+    Global = 28,
+    Persistent = 29,
+    True = 30,
+    False = 31,
+    Plus = 32,
+    Minus = 33,
+    Star = 34,
+    Slash = 35,
+    Backslash = 36,
+    Caret = 37,
+    And = 38,
+    Or = 39,
+    Tilde = 40,
+    At = 41,
+    Question = 42,
+    Less = 43,
+    Greater = 44,
+    Dot = 45,
+    Colon = 46,
+    Comma = 47,
+    Assign = 48,
+    Semicolon = 49,
+    LParen = 50,
+    RParen = 51,
+    LBracket = 52,
+    RBracket = 53,
+    LBrace = 54,
+    RBrace = 55,
+    DotStar = 56,
+    DotSlash = 57,
+    DotBackslash = 58,
+    DotCaret = 59,
+    AndAnd = 60,
+    OrOr = 61,
+    Equal = 62,
+    NotEqual = 63,
+    LessEqual = 64,
+    GreaterEqual = 65,
+    Transpose = 66,
+    Ellipsis = 67,
+    Newline = 68,
+    Section = 69,
+    Error = 70,
+    Directive = 71
+}
+export interface SpannedToken {
+    token: Token;
+    lexeme: string;
+    start: number;
+    end: number;
+}

package/dist-browser/numbl-core/lowering/classInfo.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Class information types and extraction utilities.
+ */
+import { type Expr, type Stmt } from "../parser/index.js";
+/**
+ * Metadata about a class definition.
+ * The ctx field is typed as 'unknown' to avoid circular dependencies with LoweringContext.
+ * At runtime, it will hold a LoweringContext instance.
+ */
+export interface ClassInfo {
+    name: string;
+    qualifiedName: string;
+    fileName: string;
+    source: string;
+    superClass: string | null;
+    propertyNames: string[];
+    propertyDefaults: Map<string, Expr>;
+    methodNames: Set<string>;
+    staticMethodNames: Set<string>;
+    constructorName: string | null;
+    ast: (Stmt & {
+        type: "ClassDef";
+    }) | null;
+    isOldStyle?: boolean;
+    inferiorClasses: string[];
+    externalMethodFiles: Map<string, {
+        fileName: string;
+        source: string;
+    }>;
+    ctx?: any;
+}
+/**
+ * Extract ClassInfo from a parsed ClassDef AST node.
+ */
+export declare function extractClassInfo(classDef: Stmt & {
+    type: "ClassDef";
+}, qualifiedName: string, fileName: string, source: string): ClassInfo;
+/**
+ * Build ClassInfo for an old-style (pre-classdef) `@ClassName` folder class.
+ * There is no classdef AST: the constructor is the `@Name/Name.m` plain
+ * function (which calls `obj = class(struct, 'Name')`), and every other `.m`
+ * in the folder is an external method dispatched on instances. Fields are
+ * dynamic (defined by the constructor's struct), so there are no declared
+ * property names.
+ */
+export declare function makeOldStyleClassInfo(qualifiedName: string, baseName: string, constructorFile: {
+    fileName: string;
+    source: string;
+}, methodFiles: {
+    name: string;
+    fileName: string;
+    source: string;
+}[]): ClassInfo;

package/dist-browser/numbl-core/lowering/constants.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Built-in Constants and Functions
+ */
+export declare const BUILTIN_CONSTANTS: Set<string>;

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

@@ -0,0 +1,17 @@
+/**
+ * Semantic Errors
+ */
+import type { Span } from "../parser";
+export declare class SemanticError extends Error {
+    span: Span | null;
+    identifier: string | null;
+    /** Resolved source file name (set by prepare.ts) */
+    file: string | null;
+    /** Resolved 1-based line number (set by prepare.ts) */
+    line: number | null;
+    /** Resolved 1-based column number (set by prepare.ts) */
+    column: number | undefined;
+    constructor(message: string, span?: Span | null, identifier?: string | null);
+    withSpan(span: Span): SemanticError;
+    withIdentifier(identifier: string): SemanticError;
+}

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

@@ -0,0 +1,3 @@
+export * from "./errors.js";
+export * from "./constants.js";
+export { BinaryOperation } from "../parser/index.js";

package/dist-browser/numbl-core/lowering/itemTypes.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Type System for IR
+ */
+export type ItemType = {
+    kind: "Number";
+} | {
+    kind: "ComplexNumber";
+} | {
+    kind: "Boolean";
+} | {
+    kind: "Char";
+} | {
+    kind: "String";
+} | {
+    kind: "Tensor";
+    isComplex?: boolean;
+    isLogical?: boolean;
+} | {
+    kind: "Cell";
+    elementType: ItemType | "unknown";
+    length: number | "unknown";
+} | {
+    kind: "Function";
+    params: ItemType[];
+    returns: ItemType;
+} | {
+    kind: "Struct";
+    knownFields: Record<string, ItemType>;
+} | {
+    kind: "Void";
+} | {
+    kind: "Unknown";
+} | {
+    kind: "Union";
+    types: ItemType[];
+} | {
+    kind: "MultipleOutputs";
+    outputTypes: ItemType[];
+} | {
+    kind: "ClassInstance";
+    className: string;
+} | {
+    kind: "DummyHandle";
+} | {
+    kind: "SparseMatrix";
+    isComplex?: boolean;
+} | {
+    kind: "Dictionary";
+};
+/** Returns true if the type is definitely Num, false if definitely not, undefined if unknown. */
+export declare function isNum(t: ItemType): boolean | undefined;
+/** Returns true if the type is definitely Tensor, false if definitely not, undefined if unknown. */
+export declare function isTensor(t: ItemType): boolean | undefined;
+/** Returns true if the type is definitely Complex, false if definitely not, undefined if unknown. */
+export declare function isComplex(t: ItemType): boolean | undefined;
+/** Returns true if the type is fully unknown ({kind: "Unknown"}). */
+export declare function isFullyUnknown(t: ItemType): boolean;
+/** Returns true if the type is definitely String, false if definitely not, undefined if unknown. */
+export declare function isString(t: ItemType): boolean | undefined;
+/** Returns true if the type is definitely Char, false if definitely not, undefined if unknown. */
+export declare function isChar(t: ItemType): boolean | undefined;
+export declare const IType: {
+    Num: ItemType;
+    Complex: ItemType;
+    Bool: ItemType;
+    Logical: ItemType;
+    Char: ItemType;
+    String: ItemType;
+    Void: ItemType;
+    Unknown: ItemType;
+    DummyHandle: ItemType;
+    SparseMatrix: ItemType;
+    Dictionary: ItemType;
+    /** Create a Num type */
+    num(): ItemType;
+    tensor(opts?: {
+        isComplex?: boolean;
+        isLogical?: boolean;
+    }): ItemType;
+    cell(elementType?: ItemType | "unknown", length?: number | "unknown"): ItemType;
+    func(params: ItemType[], returns: ItemType): ItemType;
+    struct(fields?: Record<string, ItemType>): ItemType;
+    sparseMatrix(isComplex?: boolean): ItemType;
+    union(types: ItemType[]): ItemType;
+    /** Unify two types, producing a common supertype */
+    unify(a: ItemType | undefined, b: ItemType | undefined): ItemType | undefined;
+};