mathjslab/lib/types/FunctionArguments.d.ts

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

import type { NodeArgumentValidation, NodeExpr, ExpressionBoundaryValue, RuntimeExpressionValue, NodeFunctionDefinition, NodeInput } from './AST';
type ThrowSyntaxError = (message: string) => never;
type ThrowEvalError = (message: string) => never;
/** Literal size dimension accepted by MATLAB-style `arguments` declarations. */
type ArgumentSizeDimension = number | {
    type: 'symbol';
    name: string;
} | {
    type: 'any';
};
/** Normalized validator call extracted from a declaration's `{mustBe...}` list. */
type ArgumentValidatorSpec = {
    name: string;
    value?: NodeExpr;
    bounds?: NodeExpr[];
    custom?: 'implicit' | 'explicit';
    expression?: NodeExpr;
};
/** Resolved workspace entry used during call-time validation. */
type ValidationEntry = {
    node?: NodeInput;
};
/** Value that has crossed an expression boundary and can be validated as data. */
type EvaluatedArgumentValue = ExpressionBoundaryValue;
/** Concrete runtime value accepted by built-in argument validators. */
type RuntimeArgumentValue = RuntimeExpressionValue;
/** Host callbacks for validators that depend on a virtual filesystem. */
type PathValidationCallbacks = {
    /** Return whether a text path refers to a host-provided file. */
    fileExists?: (path: string) => boolean;
    /** Return whether a text path refers to a host-provided folder. */
    folderExists?: (path: string) => boolean;
};
/** Interpreter services needed by parser-independent argument validation. */
type ArgumentValidationCallbacks = PathValidationCallbacks & {
    /** Resolve the argument or return value currently being validated. */
    resolveEntry: (validation: NodeArgumentValidation, localNamesOnly: boolean) => ValidationEntry | undefined;
    /** Evaluate a validator expression or default-dependent bound. */
    evaluate: (expr: NodeExpr) => NodeInput;
    /** Optional class matcher that can include user-defined classes. */
    matchesClass?: (value: RuntimeArgumentValue, className: string) => boolean;
    /** Evaluation-error callback supplied by the interpreter. */
    throwEvalError: ThrowEvalError;
    /** Syntax-error callback supplied by the interpreter/parser layer. */
    throwSyntaxError: ThrowSyntaxError;
};
/** Callback set used for `arguments (Repeating)` validation over `varargin`. */
type RepeatingArgumentValidationCallbacks = Omit<ArgumentValidationCallbacks, 'resolveEntry'> & {
    /** Validate one repeated value with a per-group symbolic dimension map. */
    validateRepeatingValue: (validation: NodeArgumentValidation, validationName: string, value: EvaluatedArgumentValue, displayName: string, symbolicDimensions: Map<string, number>) => void;
};
/** One requested repeating output value and its one-based cell index. */
type RepeatingOutputValue = {
    value: EvaluatedArgumentValue;
    index: number;
};
/** Metadata for a MATLAB-style repeating output argument. */
type OutputRepeatingInfo = {
    name: string;
    fixedReturnCount: number;
};
/**
 * Parser-independent support for MATLAB-like `arguments` blocks.
 *
 * The parser produces `NodeArgumentValidation` records. This module interprets
 * those records for:
 *
 * - input/output/repeating argument blocks,
 * - literal and symbolic size declarations,
 * - supported class declarations,
 * - built-in and user-defined `mustBe*` validators,
 * - default values for input parameters,
 * - name-value option declarations such as `opts.Field`,
 * - call splitting for positional and name-value arguments.
 *
 * It deliberately receives callbacks for lookup, evaluation, and error
 * construction so validation rules remain independent from `Interpreter.ts`.
 */
declare class FunctionArguments {
    private static isIdentifier;
    private static isDefaultedIdentifier;
    private static parameterName;
    /**
     * Validate a typed AST child list produced by AST factories.
     */
    private static checkedList;
    /**
     * Narrow a boundary-checked expression to the concrete runtime values that
     * MATLAB-style class, size, and `mustBe*` validators can inspect.
     */
    private static runtimeArgumentValue;
    /**
     * Return syntactically valid function parameters from the AST list.
     */
    private static functionParameters;
    /**
     * Return syntactically valid function return targets from the AST list.
     */
    private static functionReturns;
    /**
     * Return well-formed `arguments` blocks from a function definition.
     */
    private static argumentBlocks;
    /**
     * Return well-formed declarations from one `arguments` block.
     */
    private static argumentValidations;
    private static readonly supportedArgumentValidators;
    private static readonly supportedComparatorValidators;
    private static readonly supportedRangeValidators;
    private static readonly supportedMembershipValidators;
    private static readonly supportedClassRelationshipValidators;
    private static readonly supportedRangeOptions;
    private static readonly supportedBetweenOptions;
    private static readonly supportedBlockAttributes;
    /**
     * Return every syntactic attribute attached to an `arguments` block.
     */
    private static blockAttributeNames;
    /**
     * Normalize MATLAB-style block attributes to the semantic validation path.
     */
    private static blockKind;
    /**
     * Render one argument-size dimension for diagnostics.
     */
    private static argumentSizeDimensionDisplay;
    /**
     * Render a size declaration in a MATLAB-like diagnostic form.
     */
    static argumentSizeDisplay(dimensions: ArgumentSizeDimension[]): string;
    /**
     * Convert one validated numeric size node to a literal dimension.
     *
     * @param node Candidate size expression.
     * @param validationName Argument name used in diagnostics.
     * @param throwSyntaxError Parser/interpreter syntax error adapter.
     * @returns Positive integer size.
     */
    private static literalNumericSize;
    /**
     * Return the declared argument name, rejecting non-identifier declarations.
     */
    static validationName(validation: NodeArgumentValidation, throwSyntaxError: ThrowSyntaxError): string;
    /**
     * Decode a name-value declaration target.
     *
     * `arguments` declarations of the form `opts.Name` are represented as field
     * access nodes. The returned pair identifies the parameter object and the
     * option field.
     */
    static nameValueTarget(validation: NodeArgumentValidation, throwSyntaxError: ThrowSyntaxError): {
        parameter: string;
        field: string;
    } | undefined;
    /**
     * Return the diagnostic display name for ordinary or name-value declarations.
     */
    static validationDisplayName(validation: NodeArgumentValidation, throwSyntaxError: ThrowSyntaxError): string;
    /**
     * Return a referenced name-value argument/container inside an expression.
     *
     * MATLAB keeps name-value arguments independent: defaults cannot reference
     * name-value structures, and validators can reference only the value being
     * validated. This syntactic scan catches those dependencies before call
     * evaluation starts.
     */
    private static nameValueReferenceDisplay;
    /**
     * Return the first name-value reference found in an expression list.
     */
    private static firstNameValueReferenceDisplay;
    /**
     * Convert a size declaration to literal/symbolic dimensions.
     *
     * Numeric dimensions are fixed. Identifiers are symbolic dimensions shared
     * within one validation pass. `:` accepts any actual dimension.
     */
    static literalArgumentSize(validation: NodeArgumentValidation, throwSyntaxError: ThrowSyntaxError): ArgumentSizeDimension[] | undefined;
    /**
     * Return all supported class names declared for one argument.
     */
    static argumentClassNames(validation: NodeArgumentValidation, throwSyntaxError: ThrowSyntaxError): string[] | undefined;
    /**
     * Return a single class name when exactly one class is declared.
     */
    static argumentClassName(validation: NodeArgumentValidation, throwSyntaxError: ThrowSyntaxError): string | undefined;
    /**
     * Format a list of class names for diagnostics.
     */
    static argumentClassDisplay(classNames: string[]): string;
    /**
     * Parse function validators from an `arguments` declaration.
     *
     * Built-in validators are normalized to `ArgumentValidatorSpec` objects.
     * Unknown bare validators are treated as implicit user validators and called
     * with the argument value. Unknown indexed validators are treated as explicit
     * validator expressions and evaluated as written.
     */
    static argumentValidators(validation: NodeArgumentValidation, throwSyntaxError: ThrowSyntaxError): ArgumentValidatorSpec[];
    /**
     * Return the MATLAB-like size of a value.
     */
    static valueSize(value: RuntimeArgumentValue): number[];
    /**
     * Extract text elements from scalar text or a cell array of text values.
     */
    private static textElements;
    /**
     * Extract class-name strings from `mustBeA`'s accepted MATLAB forms.
     */
    private static classNameElements;
    /**
     * Return scalar or array elements using the runtime's value boundaries.
     */
    private static membershipElements;
    /**
     * Validate one built-in `mustBe*` function against an evaluated value.
     */
    static validateArgumentFunction(name: string, value: RuntimeArgumentValue, validator: string, bounds: RuntimeArgumentValue[], throwEvalError: ThrowEvalError, throwSyntaxError: ThrowSyntaxError, pathValidation?: PathValidationCallbacks, validationContext?: string): void;
    /**
     * Validate one declaration against the current function workspace.
     *
     * `symbolicDimensions` is shared by declarations in the same block pass so
     * `(n,1)` style declarations bind `n` once and require later uses to match.
     * `localNamesOnly` is used for output validation so inherited names cannot
     * accidentally satisfy a declared but unassigned return variable.
     */
    static validateArgumentValidation(validation: NodeArgumentValidation, symbolicDimensions: Map<string, number>, callbacks: ArgumentValidationCallbacks, localNamesOnly?: boolean, displayName?: string, validationContext?: string): void;
    /**
     * Validate all declarations for one block attribute (`Input` or `Output`).
     */
    static validateFunctionArguments(func: NodeFunctionDefinition, targetAttribute: 'Input' | 'Output', callbacks: ArgumentValidationCallbacks, namesToValidate?: Set<string>, localNamesOnly?: boolean): void;
    /**
     * Validate `arguments (Repeating)` values grouped across `varargin`.
     */
    static validateRepeatingArguments(func: NodeFunctionDefinition, values: EvaluatedArgumentValue[], callbacks: RepeatingArgumentValidationCallbacks): void;
    /**
     * Return the declared repeating output metadata, when present.
     */
    static outputRepeatingInfo(func: NodeFunctionDefinition, throwSyntaxError: ThrowSyntaxError): OutputRepeatingInfo | undefined;
    /**
     * Return the repeating output variable name, when present.
     */
    static outputRepeatingName(func: NodeFunctionDefinition, throwSyntaxError: ThrowSyntaxError): string | undefined;
    /**
     * Validate requested `arguments (Output,Repeating)` values.
     */
    static validateRepeatingOutputArguments(func: NodeFunctionDefinition, values: RepeatingOutputValue[], callbacks: RepeatingArgumentValidationCallbacks): void;
    /**
     * Validate the static consistency of all `arguments` blocks in a function.
     *
     * This is run when a function definition is registered, before any call, so
     * malformed declarations fail early and subsequent call-time validation can
     * assume the block structure is coherent.
     */
    static validateBlocks(func: NodeFunctionDefinition, throwSyntaxError: ThrowSyntaxError): void;
    /**
     * Return parameter names that are backed by name-value declarations.
     */
    static nameValueParameters(func: NodeFunctionDefinition, throwSyntaxError: ThrowSyntaxError): Set<string>;
    /**
     * Return name-value declarations grouped by their parameter object.
     */
    static nameValueDeclarations(func: NodeFunctionDefinition, throwSyntaxError: ThrowSyntaxError): Map<string, Map<string, NodeArgumentValidation>>;
    /**
     * Return ordinary input-parameter default expressions.
     */
    static inputArgumentDefaults(func: NodeFunctionDefinition, throwSyntaxError: ThrowSyntaxError): Map<string, NodeExpr>;
    /**
     * Split call arguments into positional and name-value maps.
     *
     * Supported MATLAB-like forms include `Name=value` and `'Name', value`.
     * Matching is case-insensitive and accepts unambiguous prefixes. Once a
     * name-value argument is seen, later positional arguments are rejected.
     */
    static splitCallNameValueArguments(func: NodeFunctionDefinition, args: ExpressionBoundaryValue[], throwEvalError: ThrowEvalError, throwSyntaxError: ThrowSyntaxError): {
        positional: ExpressionBoundaryValue[];
        named: Map<string, ExpressionBoundaryValue>;
    };
    /**
     * Determine which declared output names must be validated.
     *
     * Only requested fixed outputs are checked. This preserves the MATLAB-like
     * behavior where requesting fewer outputs does not require later return
     * variables to be assigned.
     */
    static outputNamesToValidate(func: NodeFunctionDefinition, requestedOutputCount: number, outputMask?: boolean[]): Set<string> | undefined;
}
export type { ArgumentValidatorSpec, PathValidationCallbacks };
export { FunctionArguments };
declare const _default: {
    FunctionArguments: typeof FunctionArguments;
};
export default _default;