mathjslab/lib/types/FunctionValidation.d.ts

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

import { type BuiltInFunctionParameter, type BuiltInFunctionParameterValidator, type RuntimeExpressionValue } from './AST';
import { type ComplexType } from './Complex';
/**
 * Declarative validation contract for one evaluated function parameter.
 */
interface FunctionParameterValidationSpec {
    /** Optional parameter name used by callers for diagnostics. */
    name?: string;
    /** Accepted MATLAB-like class names. */
    classes?: string[];
    /** Low-level validator predicates such as `numeric`, `integer`, or `vector`. */
    validators?: BuiltInFunctionParameterValidator[];
    /** Literal string values accepted for text parameters. */
    allowedStrings?: string[];
    /** Whether text values must be valid identifiers. */
    identifier?: boolean;
    /** Whether numeric validators should accept positive infinity. */
    allowInfinity?: boolean;
}
/**
 * Options for extracting numeric scalar elements from runtime values.
 */
interface NumericElementOptions {
    /** Whether logical scalars should be accepted together with numeric values. */
    includeLogical?: boolean;
}
/**
 * Value validation shared by built-in signatures and `arguments` blocks.
 *
 * This module is intentionally value-oriented: it does not know how to evaluate
 * expressions or resolve variables. Callers provide evaluated `NodeInput`
 * values and receive boolean results, making the same validator vocabulary
 * usable for native built-ins and MATLAB-like function declarations.
 */
declare class FunctionValidation {
    /** Current MATLAB `namelengthmax` value used by `isvarname`. */
    private static readonly matlabNameLengthMax;
    /** Reserved words rejected by MATLAB/Octave-compatible variable-name validation. */
    private static readonly reservedKeywords;
    /**
     * Return the MATLAB-like runtime class name for a value.
     *
     * @param value Evaluated runtime value.
     * @returns Class name used by `class`, validators, and diagnostics.
     */
    static className(value: RuntimeExpressionValue): string;
    /**
     * Return the MATLAB-like underlying type that determines array behavior.
     *
     * The current runtime does not yet model wrappers such as `gpuArray` or
     * `distributed`, so the underlying type is the same as the public class for
     * all supported values. Keeping this as a separate method gives future
     * container classes one override point without changing validators.
     *
     * @param value Evaluated runtime value.
     * @returns Underlying type name.
     */
    static underlyingType(value: RuntimeExpressionValue): string;
    /**
     * Extract numeric elements from a scalar or numeric array.
     *
     * @param value Evaluated runtime value.
     * @param options Extraction options.
     * @returns Numeric elements in linear order, or `undefined` for nonnumeric values.
     */
    static numericElements(value: RuntimeExpressionValue, options?: NumericElementOptions): ComplexType[] | undefined;
    /**
     * Test whether a value is a logical scalar or logical array.
     *
     * @param value Evaluated runtime value.
     * @returns `true` when every stored element is logical.
     */
    static isLogicalValue(value: RuntimeExpressionValue): boolean;
    /**
     * Test whether a value is a MATLAB character vector or character array.
     *
     * @param value Evaluated runtime value.
     * @returns `true` for single-quoted text scalars and arrays of them.
     */
    private static isCharArray;
    /**
     * Test whether a value is a MATLAB string scalar or string array.
     *
     * @param value Evaluated runtime value.
     * @returns `true` for double-quoted text scalars and arrays of them.
     */
    private static isStringArray;
    /**
     * Test whether a value is a cell array of character vectors.
     *
     * @param value Evaluated runtime value.
     * @returns `true` for cell arrays whose contents are single-quoted text.
     */
    private static isCellStringArray;
    /**
     * Test MATLAB's broad text category used by `mustBeText`.
     *
     * @param value Evaluated runtime value.
     * @returns `true` for char vectors, string arrays, and cellstr arrays.
     */
    private static isTextValue;
    /**
     * Test MATLAB's scalar text category used by `mustBeTextScalar`.
     *
     * @param value Evaluated runtime value.
     * @returns `true` for char vectors and scalar string values.
     */
    private static isTextScalarValue;
    /**
     * Extract text elements from text scalars, text arrays, or cellstr arrays.
     *
     * @param value Evaluated runtime value.
     * @returns Text payloads in linear order, or `undefined` for non-text values.
     */
    private static textElements;
    /**
     * Extract names accepted by MATLAB's `mustBeValidVariableName` input shape.
     *
     * The documented forms are a string scalar, a character vector, or a
     * cell array of character vectors. Non-scalar string arrays are rejected.
     *
     * @param value Evaluated runtime value.
     * @returns Candidate variable names, or `undefined` for unsupported shapes.
     */
    private static variableNameElements;
    /**
     * Test MATLAB/Octave-compatible variable-name syntax.
     *
     * @param name Candidate identifier text.
     * @returns `true` when the text is a non-keyword identifier.
     */
    private static isValidVariableNameText;
    /**
     * Check whether a value matches a supported class constraint.
     *
     * @param value Evaluated runtime value.
     * @param className MATLAB-like class name.
     * @returns `true` when the value belongs to the class.
     */
    static matchesClass(value: RuntimeExpressionValue, className: string): boolean;
    /**
     * Remove validators implied by more specific validators.
     *
     * @param validators Validator list to normalize.
     * @returns Validator list with redundant predicates removed.
     */
    static normalizeValidators(validators?: BuiltInFunctionParameterValidator[]): BuiltInFunctionParameterValidator[];
    /**
     * Check whether a value can be used as a dimension scalar.
     *
     * @param value Evaluated runtime value.
     * @param allowEmpty Whether empty values are accepted.
     * @returns `true` for nonnegative integer dimension values.
     */
    static isDimensionValue(value: RuntimeExpressionValue, allowEmpty: boolean): boolean;
    /**
     * Check whether a value is a valid dimension vector.
     *
     * @param value Evaluated runtime value.
     * @param allowEmpty Whether empty dimension entries are accepted.
     * @returns `true` for vector-shaped dimension lists.
     */
    static isDimensionVector(value: RuntimeExpressionValue, allowEmpty: boolean): boolean;
    /**
     * Check classes, literal allowed strings, identifier syntax, and validators.
     *
     * @param value Evaluated runtime value.
     * @param spec Declarative validation specification.
     * @returns `true` when all declared constraints match.
     */
    static matchesParameter(value: RuntimeExpressionValue, spec: FunctionParameterValidationSpec): boolean;
    /**
     * Match a built-in parameter before considering alternatives.
     *
     * @param value Evaluated argument value.
     * @param parameter Built-in parameter declaration.
     * @returns `true` when the primary parameter shape accepts the value.
     */
    static matchesBuiltInParameterBase(value: RuntimeExpressionValue, parameter: BuiltInFunctionParameter): boolean;
    /**
     * Match a built-in parameter, including alternative parameter shapes.
     *
     * A parameter with `alternatives` describes a union: the primary shape is
     * tried first when it declares its own constraints, then each alternative
     * is tried independently. This keeps declarations such as `char | cell`
     * from requiring the `char` branch to match before the `cell` branch is
     * considered, while an alternatives-only wrapper does not accidentally
     * accept every runtime value.
     *
     * @param value Evaluated argument value.
     * @param parameter Built-in parameter declaration.
     * @returns `true` when the primary shape or any alternative accepts the value.
     */
    static matchesBuiltInParameter(value: RuntimeExpressionValue, parameter: BuiltInFunctionParameter): boolean;
    /**
     * Check an evaluated argument list against declarative built-in parameters.
     *
     * @param args Evaluated argument list.
     * @param parameters Declarative built-in parameter list.
     * @returns `true` when every argument satisfies its parameter declaration.
     */
    static argumentsMatchBuiltInParameters(args: RuntimeExpressionValue[], parameters?: BuiltInFunctionParameter[]): boolean;
    /**
     * Check one low-level validator predicate.
     *
     * @param value Evaluated runtime value.
     * @param validator Validator predicate name.
     * @param allowInfinity Whether positive infinity is accepted by numeric predicates.
     * @returns `true` when the value satisfies the predicate.
     */
    static matchesBuiltInValidator(value: RuntimeExpressionValue, validator: BuiltInFunctionParameterValidator, allowInfinity?: boolean): boolean;
    /**
     * Map MATLAB `mustBe*` validator names to built-in signature validators.
     *
     * @param validator MATLAB-style validator function name.
     * @returns Equivalent low-level validator, if supported.
     */
    static builtInValidatorForArgumentValidator(validator: string): BuiltInFunctionParameterValidator | undefined;
}
export type { FunctionParameterValidationSpec };
export { FunctionValidation };
declare const _default: {
    FunctionValidation: typeof FunctionValidation;
};
export default _default;