mathjslab/lib/types/FunctionIntrospection.d.ts

MathJSLab - An interpreter with language syntax like MATLAB®/Octave, ISBN 978-65-00-82338-7.

import type { FunctionTable, NodeExpr, NodeInput } from './AST';
import { MultiArray } from './MultiArray';
/**
 * Minimal scope contract required by introspection helpers.
 */
type IntrospectionScope = {
    /**
     * Functions visible from the inspected workspace.
     */
    functionTable: FunctionTable;
    /**
     * Lexical parent scope, used by function-file calls whose subfunctions live
     * in the definition scope rather than in the transient call scope.
     */
    parent?: IntrospectionScope;
};
/**
 * Minimal call-frame contract required by `dbstack` and `localfunctions`.
 */
type IntrospectionFrame = {
    /**
     * Workspace associated with the frame.
     */
    scope: IntrospectionScope;
    /**
     * Callable metadata, when the frame represents a function call.
     */
    func?: {
        type: string;
        node?: unknown;
    };
    /**
     * AST node that originated the call, used for line information.
     */
    callSite?: NodeExpr;
    /**
     * Explicit frame display name, if one was supplied by the caller.
     */
    name?: string;
    /**
     * Caller frame.
     */
    parentFrame?: IntrospectionFrame;
};
/**
 * Syntax-error callback supplied by the interpreter.
 */
type ThrowSyntaxError = (message: string) => never;
/**
 * Implements stack and local-function introspection built-ins.
 *
 * The browser runtime has no real MATLAB/Octave filesystem stack, so file
 * names are reported from optional virtual `sourceName` metadata attached by
 * host source resolvers. Function names, line numbers, and local function
 * handles are derived from active call frames and scopes.
 */
declare class FunctionIntrospection {
    /**
     * Read an optional string property from callable metadata.
     *
     * @param node Callable payload to inspect.
     * @param key Metadata key to read.
     * @returns String metadata value, or `undefined` when absent.
     */
    private static metadataString;
    private static functionNames;
    private static nearestFunctionScope;
    /**
     * Return handles for user-defined functions visible in the nearest function scope.
     *
     * @param currentFrame Active call frame.
     * @param currentScope Active scope used when no function frame exists.
     * @returns Column cell array of function handles.
     */
    static localFunctionHandles(currentFrame: IntrospectionFrame | undefined, currentScope: IntrospectionScope): MultiArray;
    /**
     * Compute the display name for a stack frame.
     *
     * @param frame Frame to inspect.
     * @returns User-facing function/frame name.
     */
    static frameName(frame: IntrospectionFrame): string;
    /**
     * Compute the virtual source file reported for a stack frame.
     *
     * Browser-hosted code does not necessarily have an operating-system path,
     * but host source resolvers may provide MATLAB/Octave-like identities such
     * as `+pkg/f.m` or `@Class/method.m`. Interactive definitions keep the
     * traditional empty file field.
     *
     * @param frame Frame to inspect.
     * @returns Virtual source file name, or an empty string when unavailable.
     */
    static frameFile(frame: IntrospectionFrame): string;
    /**
     * Build the structure array returned by `dbstack`.
     *
     * @param args Evaluated `dbstack` arguments.
     * @param callStack Current call stack.
     * @param throwSyntaxError Syntax-error callback for invalid options.
     * @returns Structure array with `file`, `name`, and `line` fields.
     */
    static dbstackResult(args: NodeInput[], callStack: IntrospectionFrame[], throwSyntaxError: ThrowSyntaxError): MultiArray;
    /**
     * Find the nearest user-defined function frame.
     *
     * @param currentFrame Active call frame.
     * @returns Nearest enclosing function frame, if any.
     */
    private static nearestFunctionFrame;
    /**
     * Parse `dbstack` skip/options arguments.
     *
     * @param args Evaluated `dbstack` arguments.
     * @param throwSyntaxError Syntax-error callback.
     * @returns Number of frames to omit from the top of the stack.
     */
    private static dbstackSkip;
}
export type { IntrospectionFrame, IntrospectionScope };
export { FunctionIntrospection };
declare const _default: {
    FunctionIntrospection: typeof FunctionIntrospection;
};
export default _default;