mathjslab/lib/types/ClassInstance.d.ts

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

import type { NodeInput, RuntimeExpressionValue } from './AST';
import type { ClassDefinition } from './ClassDefinition';
import type { FunctionHandle } from './FunctionHandle';
import type { RuntimeDisplay } from './RuntimeDisplay';
import { ClassEventListener } from './ClassEventListener';
/** Instance property storage keyed by property name. */
type ClassInstancePropertyTable = Record<string, RuntimeExpressionValue>;
/** Callback used to evaluate property default expressions at construction time. */
type ClassPropertyDefaultEvaluator = (expression: NodeInput) => RuntimeExpressionValue;
/**
 * Runtime value representing one MATLAB/Octave class object instance.
 *
 * Value classes are copied when passed to methods, while handle classes keep
 * identity and can be marked as deleted.
 */
declare class ClassInstance {
    /** Runtime type tag used by interpreter predicates. */
    static readonly CLASS_INSTANCE = 7;
    /** Runtime type tag stored on the instance. */
    readonly type = 7;
    /** Optional AST-style parent pointer used by generic value handling. */
    parent?: unknown;
    /** Class metadata that defines this instance. */
    readonly classDefinition: ClassDefinition;
    /** Concrete non-dependent property values. */
    readonly properties: ClassInstancePropertyTable;
    /** Event listeners grouped by event name. */
    readonly listeners: Record<string, ClassEventListener[]>;
    /** Whether a handle instance has been deleted. */
    deleted: boolean;
    /**
     * Test whether a value is a runtime class instance.
     *
     * @param obj Value to test.
     * @returns `true` when `obj` is a `ClassInstance`.
     */
    static readonly isInstanceOf: (obj: unknown) => obj is ClassInstance;
    /**
     * Create an instance with precomputed property storage.
     *
     * @param classDefinition Runtime class metadata.
     * @param properties Initial property table.
     */
    constructor(classDefinition: ClassDefinition, properties?: ClassInstancePropertyTable);
    /**
     * Validate a value before storing it in object property state.
     */
    private static readonly runtimePropertyValue;
    /**
     * Return class names declared by a property validation class expression.
     *
     * The parser stores simple declarations such as `x string` as an
     * identifier, and union-like forms as a list. Defaults only need the class
     * names to choose a compatible empty runtime value before validation runs.
     */
    private static readonly propertyClassNames;
    /**
     * Build a MATLAB/Octave-compatible implicit property default.
     *
     * Untyped and numeric properties keep the traditional empty double matrix.
     * Text and cell declarations need type-compatible empty values so that a
     * property declared without an explicit initializer validates successfully.
     */
    private static readonly implicitPropertyDefault;
    /**
     * Instantiate a class by evaluating defaults for all non-dependent
     * effective properties.
     *
     * @param classDefinition Class metadata to instantiate.
     * @param evaluateDefault Callback used to evaluate default expressions.
     * @returns New runtime instance.
     */
    static readonly instantiate: (classDefinition: ClassDefinition, evaluateDefault: ClassPropertyDefaultEvaluator) => ClassInstance;
    /**
     * Throw when an instance has been deleted.
     *
     * @param instance Instance to validate.
     */
    static readonly throwIfDeleted: (instance: ClassInstance) => void;
    /**
     * Delete a handle instance.
     *
     * Value class instances are left unchanged, matching their copy semantics.
     *
     * @param instance Instance to delete.
     */
    static readonly delete: (instance: ClassInstance) => void;
    /**
     * Test whether a handle instance is still valid.
     *
     * @param instance Instance to test.
     * @returns `true` for live handle objects.
     */
    static readonly isValid: (instance: ClassInstance) => boolean;
    /**
     * Read a concrete stored property.
     *
     * @param instance Source instance.
     * @param name Property name.
     * @returns Stored property value, if present.
     */
    static readonly getProperty: (instance: ClassInstance, name: string) => RuntimeExpressionValue | undefined;
    /**
     * Test whether a concrete stored property exists.
     *
     * @param instance Instance to inspect.
     * @param name Property name.
     * @returns `true` when the property has storage.
     */
    static readonly hasProperty: (instance: ClassInstance, name: string) => boolean;
    /**
     * Write a concrete stored property.
     *
     * @param instance Target instance.
     * @param name Property name.
     * @param value Value to store.
     */
    static readonly setProperty: (instance: ClassInstance, name: string, value: RuntimeExpressionValue) => void;
    /**
     * Register an event listener on this instance.
     *
     * @param instance Source instance.
     * @param eventName Event name.
     * @param callback Listener callback function handle.
     * @returns Created listener object.
     */
    static readonly addListener: (instance: ClassInstance, eventName: string, callback: FunctionHandle) => ClassEventListener;
    /**
     * Return enabled, non-deleted listeners for an event.
     *
     * @param instance Source instance.
     * @param eventName Event name.
     * @returns Snapshot of active listener objects.
     */
    static readonly listenersFor: (instance: ClassInstance, eventName: string) => ClassEventListener[];
    /**
     * Copy an instance according to value/handle semantics.
     *
     * @param instance Instance to copy.
     * @returns The same handle instance or a copied value instance.
     */
    static readonly copy: (instance: ClassInstance) => ClassInstance;
    /**
     * Prepare an instance for use as an object method argument.
     *
     * @param instance Instance being passed to a method.
     * @returns Original handle object or copied value object.
     */
    static readonly methodArgument: (instance: ClassInstance) => ClassInstance;
    /**
     * Render a compact textual summary of an instance.
     *
     * @param instance Instance to render.
     * @param _interpreter Interpreter requesting unparse.
     * @returns Human-readable object summary.
     */
    static readonly unparse: (instance: ClassInstance, _interpreter: RuntimeDisplay) => string;
    /**
     * Copy this instance according to value/handle semantics.
     *
     * @returns Copied or original instance.
     */
    copy(): ClassInstance;
}
export type { ClassInstancePropertyTable, ClassPropertyDefaultEvaluator };
export { ClassInstance };
declare const _default: {
    ClassInstance: typeof ClassInstance;
};
export default _default;