mathjslab
Version:
MathJSLab - An interpreter with language syntax like MATLAB®/Octave, ISBN 978-65-00-82338-7.
209 lines (208 loc) • 7.02 kB
TypeScript
import { ComplexType } from './Complex';
import { NodeExpr } from './AST';
import { Scope, Evaluator } from './Evaluator';
/**
* # FunctionHandle
*
* Represents a MATLAB/Octave-like **function handle**.
*
* A function handle can represent either:
*
* - A **reference to a named function**
* - An **anonymous function (lambda expression)**
*
* The distinction is defined by the presence of `id`:
*
* ```ts
* if (id !== undefined) → named function reference
* else → anonymous function (lambda)
* ```
*
* ---
*
* ## Internal Representation
*
* | Case | `id` | `expression` | `parameter` | Meaning |
* |-------------------|-------------|--------------|-------------|-----------------------------|
* | `@sin` | `"sin"` | `null` | `[]` | Named function reference |
* | `@(x) x^2` | `undefined` | AST | params | Anonymous function (lambda) |
* | `f =` `@sin` | `"sin"` | `null` | `[]` | Persistent reference |
* | `f =` `@(x)x^2` | `undefined` | AST | params | Persistent lambda |
*
* ---
*
* ## Closure Semantics
*
* When representing an anonymous function, a `closure` may be attached.
* This closure captures the lexical environment (`Scope`) at the moment
* the function handle is created.
*
* This enables proper implementation of:
* - lexical scoping
* - variable capture
* - higher-order functions
*
* ---
*
* ## Notes
*
* - `expression` is only meaningful for anonymous functions.
* - `parameter` defines the formal parameters of the lambda.
* - `closure` is optional and only relevant for lambdas.
* - This class does **not** execute functions — it only represents them.
*
* ---
*
* ## References
* - https://www.mathworks.com/help/matlab/function-handles.html
* - https://www.mathworks.com/help/matlab/matlab_prog/creating-a-function-handle.html
* - https://www.mathworks.com/help/matlab/matlab_prog/pass-a-function-to-another-function.html
* - https://www.mathworks.com/help/matlab/math/parameterizing-functions.html
* - https://www.mathworks.com/help/matlab/matlab_prog/call-local-functions-using-function-handles.html
* - https://www.mathworks.com/help/matlab/matlab_prog/compare-function-handles.html
* - https://www.mathworks.com/help/matlab/matlab_prog/anonymous-functions.html
* - https://www.mathworks.com/help/matlab/ref/function_handle.html
* - https://www.mathworks.com/help/matlab/ref/functions.html
* - https://docs.octave.org/latest/Function-Handles-and-Anonymous-Functions.html
* - https://docs.octave.org/latest/Function-Handles.html
* - https://docs.octave.org/latest/Anonymous-Functions.html
* - https://en.wikipedia.org/wiki/Closure_(computer_programming)
*/
declare class FunctionHandle {
/**
* Internal numeric type identifier.
*/
static readonly FUNCTION_HANDLE = 5;
/**
* Runtime type tag.
*/
readonly type = 5;
/**
* Parent AST node (if attached to a tree).
*/
parent: any;
/**
* Name of the referenced function.
*
* - Defined → named function (`@sin`)
* - Undefined → anonymous function (`@(x) x^2`)
*/
id?: string;
/**
* Formal parameters (AST nodes representing identifiers).
*
* Only meaningful for anonymous functions.
*/
parameter: NodeExpr[];
/**
* Function body as an AST node.
*
* Only meaningful for anonymous functions.
*
* May be `null` when representing a named function handle.
*/
expression: NodeExpr;
/**
* Captured lexical scope (closure).
*
* Only defined for anonymous functions that capture variables.
*/
closure?: Scope;
/**
* Type guard for FunctionHandle.
*
* @param obj - Value to test
* @returns True if `obj` is a FunctionHandle
*/
static isInstanceOf: (obj: unknown) => obj is FunctionHandle;
/**
* Private constructor.
*
* Use {@link FunctionHandle.create} instead.
*
* @param id - Function name (for named handles)
* @param parameter - Formal parameters (lambda only)
* @param expression - Function body AST (lambda only)
* @param closure - Captured scope (optional)
*/
private constructor();
/**
* Factory method for creating a FunctionHandle.
*
* @param id - Function name (optional)
* @param parameter - Formal parameters
* @param expression - Function body AST
* @param closure - Captured scope
* @returns A new FunctionHandle instance
*/
static create: (id?: string, parameter?: NodeExpr[], expression?: NodeExpr, closure?: Scope) => FunctionHandle;
/**
* Converts a FunctionHandle back to source code representation.
*
* @param fhandle - Function handle to unparse
* @param evaluator - Evaluator used for AST unparsing
* @param parentPrecedence - Operator precedence (currently unused)
* @returns String representation (MATLAB-like syntax)
*/
static unparse: (fhandle: FunctionHandle, evaluator: Evaluator, parentPrecedence?: number) => string;
/**
* Human-readable string representation.
*
* Does not fully reconstruct anonymous functions.
*
* @param fhandle - Function handle
* @returns Short string description
*/
static toString: (fhandle: FunctionHandle) => string;
/**
* Instance version of {@link FunctionHandle.toString}.
*/
toString(): string;
/**
* Converts the function handle into MathML representation.
*
* @param fhandle - Function handle
* @param evaluator - Evaluator for AST conversion
* @param parentPrecedence - Operator precedence (unused)
* @returns MathML string
*/
static unparseMathML: (fhandle: FunctionHandle, evaluator: Evaluator, parentPrecedence?: number) => string;
/**
* Creates a shallow copy of a FunctionHandle.
*
* Notes:
* - AST nodes (`parameter`, `expression`) are **not cloned**
* - `closure` is not copied
*
* @param fhandle - Source handle
* @returns New FunctionHandle instance
*/
static copy: (fhandle: FunctionHandle) => FunctionHandle;
/**
* Instance version of {@link FunctionHandle.copy}.
*
* @returns Shallow copy
*/
copy(): FunctionHandle;
/**
* Converts the function handle to a logical value.
*
* MATLAB/Octave semantics:
* Function handles are always considered **false** in logical context.
*
* @param fhandle - Function handle
* @returns Logical false
*/
static toLogical: (fhandle: FunctionHandle) => ComplexType;
/**
* Instance version of {@link FunctionHandle.toLogical}.
*
* @returns Logical false
*/
toLogical(): ComplexType;
}
export { FunctionHandle };
declare const _default: {
FunctionHandle: typeof FunctionHandle;
};
export default _default;