mathjslab
Version:
MathJSLab - An interpreter with language syntax like MATLAB®/Octave, ISBN 978-65-00-82338-7.
536 lines (535 loc) • 21.1 kB
TypeScript
import { type ClassAttributeTable, type NodeClassDef, type NodeClassSection } from './AST';
import type { ClassEnumerationDefinition as ClassEnumerationDefinitionBase, ClassEventDefinition as ClassEventDefinitionBase, ClassMethodDefinition as ClassMethodDefinitionBase, ClassPropertyDefinition as ClassPropertyDefinitionBase } from './ClassMember';
import type { RuntimeDisplay } from './RuntimeDisplay';
type ClassPropertyDefinition = ClassPropertyDefinitionBase<ClassDefinition>;
type ClassMethodDefinition = ClassMethodDefinitionBase<ClassDefinition>;
type ClassEventDefinition = ClassEventDefinitionBase<ClassDefinition>;
type ClassEnumerationDefinition = ClassEnumerationDefinitionBase<ClassDefinition>;
/** Method lookup table keyed by method name. */
type ClassMethodTable = Record<string, ClassMethodDefinition[]>;
/** Property lookup table keyed by property name. */
type ClassPropertyTable = Record<string, ClassPropertyDefinition>;
/** Enumeration lookup table keyed by enumeration member name. */
type ClassEnumerationTable = Record<string, ClassEnumerationDefinition>;
/** Predicate used to filter overloaded method metadata during lookup. */
type ClassMethodPredicate = (method: ClassMethodDefinition) => boolean;
/**
* Normalized runtime representation of a parsed MATLAB/Octave `classdef`.
*
* The parser keeps the original AST shape. `ClassDefinition` indexes that AST
* into member tables, inheritance metadata, and attribute-derived flags used by
* the interpreter when instantiating objects or dispatching methods.
*/
declare class ClassDefinition {
/** Runtime type tag used by the interpreter's value predicates. */
static readonly CLASS_DEFINITION = 6;
/** Class-level attributes accepted by MATLAB/Octave classdef metadata. */
private static readonly classAttributes;
/** Property-section attributes accepted by MATLAB/Octave classdef metadata. */
private static readonly propertyAttributes;
/** Method-section attributes accepted by MATLAB/Octave classdef metadata. */
private static readonly methodAttributes;
/** Event-section attributes accepted by MATLAB/Octave classdef metadata. */
private static readonly eventAttributes;
/** Enumeration-section attributes accepted by MATLAB/Octave classdef metadata. */
private static readonly enumerationAttributes;
/** Class-level attributes that must be boolean markers when present. */
private static readonly classBooleanAttributes;
/** Property-section attributes that must be boolean markers when present. */
private static readonly propertyBooleanAttributes;
/** Method-section attributes that must be boolean markers when present. */
private static readonly methodBooleanAttributes;
/** Event-section attributes that must be boolean markers when present. */
private static readonly eventBooleanAttributes;
/** Enumeration-section attributes that must be boolean markers when present. */
private static readonly enumerationBooleanAttributes;
/** Built-in MATLAB mixin superclasses recognized without external source. */
private static readonly builtinSuperclassNames;
/**
* Keep the first item for each key while preserving input order.
*
* Effective inherited member lists follow superclass lookup order; later
* duplicate names should not appear as separate public metadata entries.
*/
private static readonly firstByKey;
/** Runtime type tag stored on each class definition instance. */
readonly type = 6;
/** Optional AST-style parent pointer used by generic copy/unparse paths. */
parent?: unknown;
/** Class name from the `classdef` header. */
readonly name: string;
/** Package prefix from a qualified class name, or empty for top-level classes. */
readonly packageName: string;
/** Unqualified class name without package prefix. */
readonly simpleName: string;
/** Source AST node that defines the class. */
readonly ast: NodeClassDef;
/** Class-level attribute table. */
readonly attributes: ClassAttributeTable;
/** Whether the class is explicitly or effectively abstract. */
readonly isAbstract: boolean;
/** Whether subclasses are forbidden. */
readonly isSealed: boolean;
/** Whether the class should be hidden from ordinary metadata listings. */
readonly isHidden: boolean;
/** Whether saved instances should reconstruct through load-time hooks. */
readonly isConstructOnLoad: boolean;
/** Whether the class was declared with `HandleCompatible`. */
readonly isHandleCompatible: boolean;
/** Class names declared in the `InferiorClasses` class attribute. */
readonly inferiorClasses: string[];
/** Class names declared in the `AllowedSubclasses` class attribute. */
readonly allowedSubclasses: string[];
/** Whether metadata should report subclassing as restricted. */
readonly isRestrictsSubclassing: boolean;
/** Whether this object represents the built-in `handle` base class. */
readonly isBuiltinHandleClass: boolean;
/** Superclass names from the class header. */
readonly superclasses: string[];
/** Resolved superclass definitions, excluding built-in `handle`. */
readonly superclassDefinitions: ClassDefinition[];
/** Parsed class sections in source order. */
readonly sections: NodeClassSection[];
/** Properties declared directly by this class. */
readonly properties: ClassPropertyDefinition[];
/** Direct-property lookup table. */
readonly propertyTable: ClassPropertyTable;
/** Methods declared directly by this class. */
readonly methods: ClassMethodDefinition[];
/** Static methods declared directly by this class. */
readonly staticMethods: ClassMethodDefinition[];
/** Instance methods declared directly by this class. */
readonly instanceMethods: ClassMethodDefinition[];
/** Direct methods grouped by effective access. */
readonly methodsByAccess: Record<string, ClassMethodDefinition[]>;
/** Direct-method lookup table keyed by method name. */
readonly methodTable: ClassMethodTable;
/** Events declared directly by this class. */
readonly events: ClassEventDefinition[];
/** Enumeration members declared directly by this class. */
readonly enumerations: ClassEnumerationDefinition[];
/** Direct-enumeration lookup table. */
readonly enumerationTable: ClassEnumerationTable;
/**
* Test whether a value is a runtime class definition.
*
* @param obj Value to test.
* @returns `true` when `obj` is a `ClassDefinition`.
*/
static readonly isInstanceOf: (obj: unknown) => obj is ClassDefinition;
/**
* Build runtime class metadata from a parsed classdef AST.
*
* Use `ClassDefinition.create` so construction remains centralized.
*
* @param ast Parsed classdef node.
*/
private constructor();
/**
* Create normalized runtime metadata for a parsed classdef node.
*
* @param ast Parsed classdef node.
* @returns Runtime class definition.
*/
static readonly create: (ast: NodeClassDef) => ClassDefinition;
/**
* Copy a class definition value.
*
* Class definitions are immutable metadata objects, so copying preserves the
* same instance.
*
* @param definition Definition to copy.
* @returns The same definition.
*/
static readonly copy: (definition: ClassDefinition) => ClassDefinition;
/**
* Render the original classdef AST.
*
* @param definition Definition to render.
* @param interpreter Interpreter that owns the unparser.
* @returns Unparsed classdef text.
*/
static readonly unparse: (definition: ClassDefinition, interpreter: RuntimeDisplay) => string;
/**
* Copy this class definition.
*
* @returns The same immutable metadata object.
*/
copy(): ClassDefinition;
/**
* Validate local classdef metadata that does not require superclass
* resolution or runtime class registration.
*
* Source lookup probes use this to reject malformed host-provided class
* sources without loading dependencies. Full class loading still calls
* `resolveSuperclasses`, which adds inherited constraints afterward.
*
* @param throwEvalError Interpreter error callback.
*/
validateLocalDefinition(throwEvalError: (message: string) => never): void;
/**
* Resolve named superclasses after all known classes have been registered.
*
* @param resolve Class lookup callback.
* @param throwEvalError Interpreter error callback.
*/
resolveSuperclasses(resolve: (name: string) => ClassDefinition | undefined, throwEvalError: (message: string) => never): void;
/**
* Test whether this class inherits from a resolved class definition.
*
* @param baseClass Candidate superclass.
* @returns `true` when `baseClass` is in the inheritance chain.
*/
isSubclassOf(baseClass: ClassDefinition): boolean;
/**
* Test whether this class inherits from a superclass name.
*
* @param baseClassName Candidate superclass name.
* @returns `true` when the name is declared or inherited.
*/
isSubclassOfName(baseClassName: string): boolean;
/**
* Test whether instances should have handle-object identity semantics.
*
* @returns `true` for `handle` or subclasses of `handle`.
*/
isHandleClass(): boolean;
/**
* Test whether the class inherits MATLAB's Set/Get mixin interface.
*
* @returns `true` for `matlab.mixin.SetGet`,
* `matlab.mixin.SetGetExactNames`, or subclasses of either.
*/
isSetGetClass(): boolean;
/**
* Test whether Set/Get property names must match exactly.
*
* @returns `true` for classes that inherit
* `matlab.mixin.SetGetExactNames`.
*/
isSetGetExactNamesClass(): boolean;
/**
* Find a resolved superclass by name.
*
* @param name Superclass name to search.
* @returns Matching superclass definition, if any.
*/
findSuperclass(name: string): ClassDefinition | undefined;
/**
* Return inherited and direct properties with direct definitions overriding
* inherited properties of the same name.
*
* @returns Effective property list.
*/
allProperties(): ClassPropertyDefinition[];
/**
* Return inherited and direct methods with direct definitions overriding
* inherited methods of the same static/instance kind and name.
*
* @returns Effective method list.
*/
allMethods(): ClassMethodDefinition[];
/**
* Return inherited methods in superclass lookup order without removing
* duplicate override keys.
*
* Public metadata lists deduplicate these entries, but validation rules
* such as sealed-method checks must still inspect every inherited method.
*/
private inheritedMethods;
/**
* Return inherited and direct events with direct names overriding inherited
* events.
*
* @returns Effective event list.
*/
allEvents(): ClassEventDefinition[];
/**
* Return inherited and direct enumeration members.
*
* @returns Effective enumeration list.
*/
allEnumerations(): ClassEnumerationDefinition[];
/**
* Find a property by name in this class or its superclasses.
*
* @param name Property name.
* @returns Matching property metadata, if any.
*/
findProperty(name: string): ClassPropertyDefinition | undefined;
/**
* Find a method by name and optional predicate in this class or its
* superclasses.
*
* @param name Method name.
* @param predicate Additional filter for overload kind/access.
* @returns Matching method metadata, if any.
*/
findMethod(name: string, predicate?: ClassMethodPredicate): ClassMethodDefinition | undefined;
/**
* Find this class constructor by canonical or unqualified class name.
*
* MATLAB package classes declare constructors with the simple class name
* inside `+pkg/@Class/Class.m`, while the runtime stores the class under
* the canonical `pkg.Class` name.
*
* @returns Instance constructor metadata, if declared.
*/
findConstructor(): ClassMethodDefinition | undefined;
/**
* Find an enumeration member by name.
*
* @param name Enumeration member name.
* @returns Matching enumeration metadata, if any.
*/
findEnumeration(name: string): ClassEnumerationDefinition | undefined;
/**
* Find an event by name.
*
* @param name Event name.
* @returns Matching event metadata, if any.
*/
findEvent(name: string): ClassEventDefinition | undefined;
/**
* Collect names of abstract methods that still require implementation.
*
* @returns Set of pending abstract method names.
*/
abstractMethodNames(): Set<string>;
/**
* Collect names of abstract properties that still require implementation.
*
* @returns Set of pending abstract property names.
*/
abstractPropertyNames(): Set<string>;
/**
* Resolve abstract methods inherited or declared by this class that have no
* concrete override.
*
* @returns Pending abstract method metadata.
*/
unresolvedAbstractMethods(): ClassMethodDefinition[];
/**
* Resolve abstract properties inherited or declared by this class that have
* no concrete property override.
*
* @returns Pending abstract property metadata.
*/
unresolvedAbstractProperties(): ClassPropertyDefinition[];
/**
* Test whether the class cannot be instantiated because of explicit or
* inherited abstract requirements.
*
* @returns `true` when the class is effectively abstract.
*/
isEffectivelyAbstract(): boolean;
/**
* Build keyed abstract-method entries for inheritance merging.
*
* @returns Abstract method entries keyed by override identity.
*/
private unresolvedAbstractMethodEntries;
/**
* Build keyed abstract-property entries for inheritance merging.
*
* @returns Abstract property entries keyed by property name.
*/
private unresolvedAbstractPropertyEntries;
/**
* Create the override identity used by MATLAB-like method resolution.
*
* @param method Method metadata.
* @returns Override key including static/instance kind.
*/
private methodOverrideKey;
/**
* Create the override identity used by MATLAB-like property resolution.
*
* @param property Property metadata.
* @returns Override key for inherited abstract properties.
*/
private propertyOverrideKey;
/**
* Reject direct methods that would override inherited sealed methods.
*
* MATLAB sealed methods remain callable from subclasses, but subclasses
* cannot provide a replacement with the same static/instance identity.
*
* @param throwEvalError Interpreter error callback.
*/
private validateSealedMethodOverrides;
/**
* Validate class and section attribute names before their values are used.
*
* @param throwEvalError Interpreter error callback.
*/
private validateSupportedAttributes;
/**
* Validate all names in an attribute table against an allow-list.
*
* @param table Attribute table to inspect.
* @param supportedNames Attribute names accepted for this owner.
* @param owner Description used in error messages.
* @param throwEvalError Interpreter error callback.
*/
private validateAttributeNames;
/**
* Validate that an attribute appears at most once in the same declaration.
*
* @param table Attribute table to inspect.
* @param owner Description used in error messages.
* @param throwEvalError Interpreter error callback.
*/
private validateDuplicateAttributes;
/**
* Validate boolean marker attributes and boolean-valued attributes.
*
* @param table Attribute table to inspect.
* @param booleanNames Attributes whose value must be boolean when present.
* @param owner Description used in error messages.
* @param throwEvalError Interpreter error callback.
*/
private validateBooleanAttributes;
/**
* Validate class-name-list attributes such as `InferiorClasses`.
*
* @param table Attribute table to inspect.
* @param listNames Attributes whose value must be a class-name list.
* @param owner Description used in error messages.
* @param throwEvalError Interpreter error callback.
*/
private validateClassNameListAttributes;
/**
* Validate positive-integer numeric attributes.
*
* @param table Attribute table to inspect.
* @param integerNames Attributes whose value must be a positive integer.
* @param owner Description used in error messages.
* @param throwEvalError Interpreter error callback.
*/
private validatePositiveIntegerAttributes;
/**
* Validate access attributes that affect class member visibility.
*
* @param throwEvalError Interpreter error callback.
*/
private validateAccessAttributes;
/**
* Reject direct or indirect inheritance cycles.
*
* @param throwEvalError Interpreter error callback.
*/
private validateInheritanceCycles;
/**
* Find a path from this class back to a target class.
*
* @param target Class that would close the cycle.
* @param path Names visited so far.
* @param visited Definitions already inspected.
* @returns Cycle path, when found.
*/
private inheritanceCyclePath;
/**
* Find a superclass-name path from this class back to a target class name.
*
* @param targetName Class name that would close the cycle.
* @param path Names visited so far.
* @param visited Names already inspected.
* @returns Cycle path, when found.
*/
private inheritanceNameCyclePath;
/**
* Validate MATLAB-style `get.Property` and `set.Property` accessor methods.
*
* @param throwEvalError Interpreter error callback.
*/
private validatePropertyAccessors;
/**
* Validate incompatible class and section attribute combinations.
*
* @param throwEvalError Interpreter error callback.
*/
private validateAttributeCombinations;
/**
* Validate direct duplicate member names before lookup tables are relied on.
*
* @param throwEvalError Interpreter error callback.
*/
private validateDuplicateMembers;
/**
* Validate direct member names that share the same class namespace.
*
* Property accessor methods (`get.Name` and `set.Name`) are intentionally
* excluded because they are tied to their target property by
* `validatePropertyAccessors`.
*
* @param throwEvalError Interpreter error callback.
*/
private validateCrossMemberNameConflicts;
/**
* Test whether a method name denotes this class constructor.
*
* @param name Method name to test.
* @returns `true` for canonical and package-local constructor spellings.
*/
private isConstructorMethodName;
/**
* Reject duplicate names in a direct member collection.
*
* @param names Names or keys to inspect.
* @param kind Member kind for diagnostics.
* @param throwEvalError Interpreter error callback.
* @param displayName Optional key-to-name mapper for diagnostics.
*/
private validateDuplicateNames;
/**
* Populate member tables from parsed class sections.
*/
private collectMembers;
/**
* Validate and return members collected from one concrete class section.
*/
private classSectionMembers;
/**
* Validate one method-header list before using it for class-special method rules.
*/
private checkedMethodHeaderList;
/**
* Return validated method parameters.
*/
private methodParameters;
/**
* Return validated method returns.
*/
private methodReturns;
/**
* Collect property metadata from one `properties` section.
*
* @param section Section to index.
*/
private collectProperties;
/**
* Collect method metadata from one `methods` section.
*
* @param section Section to index.
*/
private collectMethods;
/**
* Collect event metadata from one `events` section.
*
* @param section Section to index.
*/
private collectEvents;
/**
* Collect enumeration metadata from one `enumeration` section.
*
* @param section Section to index.
*/
private collectEnumerations;
}
export type { ClassMethodTable, ClassPropertyTable, ClassEnumerationTable };
export { ClassDefinition };
declare const _default: {
ClassDefinition: typeof ClassDefinition;
};
export default _default;