@sdeverywhere/parse 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -1,607 +0,0 @@
-import { XmlElement } from '@rgrove/parse-xml';
-
-/**
- * Format a model variable or subscript/dimension name into a valid C identifier (with
- * special characters converted to underscore).
- *
- * Note that this should only be called with an individual variable base name (e.g.,
- * 'Variable name') or a subscript/dimension name (e.g., 'DimA').  In the case where
- * you have a full variable name that includes subscripts/dimensions (e.g.,
- * 'Variable name[DimA,B2]'), use `canonicalVarId` to convert the base variable name
- * and subscript/dimension parts to canonical form indepdendently.
- *
- * @param {string} name The name of the variable in the source model, e.g., "Variable name".
- * @returns {string} The C identifier for the given name, e.g., "_variable_name".
- */
-declare function canonicalId(name: string): string;
-/**
- * Format a (subscripted or non-subscripted) model variable name into a canonical identifier,
- * (with special characters converted to underscore, and subscript/dimension parts separated
- * by commas).
- *
- * @param {string} name The name of the variable in the source model, e.g., "Variable name[DimA, B2]".
- * @returns {string} The canonical identifier for the given name, e.g., "_variable_name[_dima,_b2]".
- */
-declare function canonicalVarId(name: string): string;
-/**
- * Format a model function name into a valid C identifier (with special characters
- * converted to underscore, and the ID converted to uppercase).
- *
- * @param {string} name The name of the variable in the source model, e.g., "FUNCTION name".
- * @returns {string} The C identifier for the given name, e.g., "_FUNCTION_NAME".
- */
-declare function canonicalFunctionId(name: string): string;
-
-/** The simulation parameters, such as start time, end time, and time step. */
-interface SimulationSpec {
-    /** The start time of the simulation. */
-    startTime: number;
-    /** The end time of the simulation. */
-    endTime: number;
-    /** The time step of the simulation. */
-    timeStep: number;
-}
-/** The original name of a dimension, as it appears in the model. */
-type DimName = string;
-/** The canonical identifier of a dimension, as it appears in generated code. */
-type DimId = string;
-/** The original name of a subscript/index, as it appears in the model. */
-type SubName = string;
-/** The canonical identifier of a subscript/index, as it appears in generated code. */
-type SubId = string;
-/**
- * The original name of a dimension or subscript/index, as it appears in the model.
- *
- * This type is used in cases where either a dimension or an individual subscript/index
- * can appear, and more analysis is needed to resolve the reference.
- */
-type DimOrSubName = string;
-/**
- * The canonical identifier of a dimension or subscript/index, as it appears in
- * generated code.
- *
- * This type is used in cases where either a dimension or an individual subscript/index
- * can appear, and more analysis is needed to resolve the reference.
- */
-type DimOrSubId = string;
-/**
- * A reference to a dimension or an individual subscript/index, as used in a dimension
- * definition or in a variable reference inside an equation definition.
- *
- * This type can be used in cases where either a dimension or an individual subscript/index
- * can appear, and more analysis is needed to resolve the reference.
- */
-interface SubscriptRef {
-    /**
-     * The original name of the dimension or subscript/index, as it appears in the model.
-     */
-    subName: DimOrSubName;
-    /**
-     * The canonical identifier of the dimension or subscript/index, as it appears in
-     * generated code.
-     */
-    subId: DimOrSubId;
-}
-/**
- * A subscript mapping, as used in a dimension definition.
- */
-interface SubscriptMapping {
-    /**
-     * The original name of the "target" dimension for the mapping, as it appears in
-     * the model.
-     */
-    toDimName: DimName;
-    /**
-     * The canonical identifier of the "target" dimension for the mapping, as it appears
-     * in generated code.
-     */
-    toDimId: DimId;
-    /**
-     * The mapped subscripts.
-     */
-    subscriptRefs: SubscriptRef[];
-}
-/**
- * A definition of a dimension (aka "subscript range" in Vensim).
- */
-interface DimensionDef {
-    /**
-     * The original name of the dimension being defined, as it appears in the model.
-     */
-    dimName: DimName;
-    /**
-     * The canonical identifier of the dimension being defined, as it appears in generated code.
-     */
-    dimId: DimId;
-    /**
-     * The original name of the family associated with the dimension being defined, as it
-     * appears in the model.
-     *
-     * For a typical dimension, the family name is the same as the dimension name, but in the
-     * case of an alias (e.g., in Vensim, `DimA <-> DimB`), this will be the name used on the
-     * right side (e.g., `DimB`).
-     */
-    familyName: DimName;
-    /**
-     * The canonical identifier of the family associated with the dimension being defined, as
-     * it appears in generated code.
-     *
-     * For a typical dimension, the family name is the same as the dimension name, but in the
-     * case of an alias (e.g., in Vensim, `DimA <-> DimB`), this will be the ID used on the
-     * right side (e.g., `_dimb`).
-     */
-    familyId: DimId;
-    /**
-     * The array of subscripts/indices that make up this dimension.
-     */
-    subscriptRefs: SubscriptRef[];
-    /**
-     * The array of subscript mappings, if defined for this dimension.
-     */
-    subscriptMappings: SubscriptMapping[];
-    /**
-     * The optional comment text that accompanies the dimension definition in the model.
-     */
-    comment?: string;
-    /**
-     * The optional group name, if this dimension definition is contained within a group.
-     */
-    group?: string;
-}
-/** A number literal that appears in an expression. */
-interface NumberLiteral {
-    kind: 'number';
-    /** The numeric value. */
-    value: number;
-    /** The original string representation from the model. */
-    text: string;
-}
-/** A string literal that appears in an expression. */
-interface StringLiteral {
-    kind: 'string';
-    /** The string value without quotes. */
-    text: string;
-}
-/** A keyword (e.g., ":NA:") that appears in an expression. */
-interface Keyword {
-    kind: 'keyword';
-    /** The original string representation from the model. */
-    text: string;
-}
-/** The original name of a variable, as it appears in the model. */
-type VariableName = string;
-/** The canonical identifier of a variable, as it appears in generated code. */
-type VariableId = string;
-/**
- * A reference to a variable that appears in an expression.
- */
-interface VariableRef {
-    kind: 'variable-ref';
-    /**
-     * The original name of the variable, as it appears in the model.
-     */
-    varName: VariableName;
-    /**
-     * The canonical identifier of the variable, as it appears in generated code.
-     */
-    varId: VariableId;
-    /**
-     * The optional array of subscript/dimension references, if the referenced variable
-     * is subscripted.
-     */
-    subscriptRefs?: SubscriptRef[];
-}
-/** An operator used in a unary expression. */
-type UnaryOp = '+' | '-' | ':NOT:';
-/** A unary expression. */
-interface UnaryOpExpr {
-    kind: 'unary-op';
-    /** The operator. */
-    op: UnaryOp;
-    /** The child expression that the operator applies to. */
-    expr: Expr;
-}
-/** An operator used in a binary expression. */
-type BinaryOp = '+' | '-' | '*' | '/' | '^' | '=' | '<>' | '<' | '>' | '<=' | '>=' | ':AND:' | ':OR:';
-/** A binary expression. */
-interface BinaryOpExpr {
-    kind: 'binary-op';
-    /** The left-hand side child expression. */
-    lhs: Expr;
-    /** The operator. */
-    op: BinaryOp;
-    /** The right-hand side child expression. */
-    rhs: Expr;
-}
-/** An expression that was contained within parentheses in the original model. */
-interface ParensExpr {
-    kind: 'parens';
-    /** The child expression that was defined within parentheses. */
-    expr: Expr;
-}
-/** A single (x,y) point in a lookup definition. */
-type LookupPoint = [number, number];
-/** The range for a lookup definition. */
-interface LookupRange {
-    min: LookupPoint;
-    max: LookupPoint;
-}
-/** A lookup definition. */
-interface LookupDef {
-    kind: 'lookup-def';
-    /** The optional range that declares the minimum and maximum points for this lookup. */
-    range?: LookupRange;
-    /** The array of points that define this lookup. */
-    points: LookupPoint[];
-}
-/**
- * A lookup call, as used in an expression.  This is similar to a `FunctionCall`, except
- * that instead of a function name, there is a reference to a lookup variable, and the
- * single argument determines the x coordinate for the lookup.
- */
-interface LookupCall {
-    kind: 'lookup-call';
-    /** The reference to a lookup variable. */
-    varRef: VariableRef;
-    /** The single argument that determines the x coordinate for the lookup. */
-    arg: Expr;
-}
-/** The original name of a function, as it appears in the model. */
-type FunctionName = string;
-/** The canonical identifier of a function, as it appears in generated code. */
-type FunctionId = string;
-/** A function call, as used in an expression. */
-interface FunctionCall {
-    kind: 'function-call';
-    /**
-     * The original name of the function, as it appears in the model.
-     */
-    fnName: FunctionName;
-    /**
-     * The canonical identifier of the function, as it appears in generated code.
-     */
-    fnId: FunctionId;
-    /**
-     * The array of argument expressions that are passed to the function.
-     */
-    args: Expr[];
-}
-/**
- * A union type that includes all possible expression types.  Each expression type includes
- * a unique `kind` property that can be used to identify the type of the expression.
- */
-type Expr = NumberLiteral | StringLiteral | Keyword | VariableRef | UnaryOpExpr | BinaryOpExpr | ParensExpr | LookupDef | LookupCall | FunctionCall;
-/**
- * A variable definition that appears on the LHS of an equation definition.  Note that
- * this is mostly the same as `VariableRef` that is used in an expression; the difference
- * is that a `VariableDef` may contain an "except" clause whereas a `VariableRef` will not.
- */
-interface VariableDef {
-    kind: 'variable-def';
-    /**
-     * The original name of the variable, as it appears in the model.
-     */
-    varName: VariableName;
-    /**
-     * The canonical identifier of the variable, as it appears in generated code.
-     */
-    varId: VariableId;
-    /**
-     * The optional array of subscript/dimension references, if the variable is subscripted.
-     */
-    subscriptRefs?: SubscriptRef[];
-    /**
-     * The optional array of "exceptions".  For example, in Vensim it is possible to express
-     * that an equation to applies to all subscripts in a dimension except for one (or a subset),
-     * e.g., `x[DimA] :EXCEPT: [A1] = 5`.
-     */
-    exceptSubscriptRefSets?: SubscriptRef[][];
-}
-/**
- * The left-hand side of an equation definition.
- */
-interface EquationLhs {
-    /** The variable definition that appears on the LHS. */
-    varDef: VariableDef;
-}
-/** The right-hand side of a typical equation that is defined with an expression. */
-interface EquationRhsExpr {
-    kind: 'expr';
-    /** The expression that appears on the right-hand side of the equation. */
-    expr: Expr;
-}
-/** The right-hand side of a constant list definition. */
-interface EquationRhsConstList {
-    kind: 'const-list';
-    /** The array of constant values. */
-    constants: NumberLiteral[];
-    /**
-     * @hidden The original string representation from the model.  This is only needed for
-     * compatibility with the legacy parser, which includes the original string representation
-     * including semicolons, which is used for the `modelFormula`.  Ideally we could remove this
-     * field if we fix antlr4-vensim to preserve the groupings as described above.
-     */
-    text: string;
-}
-/** The right-hand side of a "lookup variable" definition. */
-interface EquationRhsLookup {
-    kind: 'lookup';
-    /** The lookup definition that appears on the right-hand side of the variable definition. */
-    lookupDef: LookupDef;
-}
-/**
- * The right-hand side of a "data variable" definition.  In Vensim, a data variable does
- * not contain any information in the model file, and the data is read from an external
- * file, so this type is merely used to indicate the equation kind (to differentiate it
- * from other kinds of equations).
- */
-interface EquationRhsData {
-    kind: 'data';
-}
-/**
- * A union type that includes all possible equation right-hand side types.  Each type includes
- * a unique `kind` property that can be used to identify the type of the equation.
- */
-type EquationRhs = EquationRhsExpr | EquationRhsConstList | EquationRhsLookup | EquationRhsData;
-/** An equation definition. */
-interface Equation {
-    /** The left-hand side of the equation. */
-    lhs: EquationLhs;
-    /** The right-hand side of the equation. */
-    rhs: EquationRhs;
-    /**
-     * The optional units text that accompanies the equation definition in the model.
-     */
-    units?: string;
-    /**
-     * The optional comment text that accompanies the equation definition in the model.
-     */
-    comment?: string;
-    /**
-     * The optional group name, if this equation definition is contained within a group.
-     */
-    group?: string;
-}
-/** A complete model definition, including all defined dimensions and equations. */
-interface Model {
-    /**
-     * The simulation parameters, such as start time, end time, and time step.
-     *
-     * NOTE: This will be defined for XMILE models, but may be undefined for Vensim models
-     * for which the parameters are not compile-time constants.
-     */
-    simulationSpec?: SimulationSpec;
-    /** The array of all dimension definitions in the model. */
-    dimensions: DimensionDef[];
-    /** The array of all variable/equation definitions in the model. */
-    equations: Equation[];
-}
-
-/**
- * @hidden This is not yet part of the public API.
- */
-declare function debugPrintExpr(expr: Expr, indent?: number): void;
-/**
- * @hidden This is not yet part of the public API.
- */
-type FormatVariableRefFunc = (varRef: VariableRef) => string;
-/**
- * @hidden This is not yet part of the public API.
- */
-interface PrettyOpts {
-    /**
-     * Whether to use a compact representation without additional spaces.  (The compact form mimics
-     * the behavior of the legacy parser.
-     */
-    compact?: boolean;
-    html?: boolean;
-    formatVariableRef?: FormatVariableRefFunc;
-}
-/**
- * @hidden This is not yet part of the public API.
- */
-declare function toPrettyString(expr: Expr, opts?: PrettyOpts): string;
-/**
- * @hidden This is not yet part of the public API.
- */
-declare function prettyPrintExpr(expr: Expr, indent?: number): void;
-/**
- * @hidden This is not yet part of the public API.
- */
-declare function printExprStats(exprs: Expr[]): void;
-
-/**
- * @hidden This is not yet part of the public API.
- */
-interface ReduceExprOptions {
-    /** A callback that returns the possibly reduced expression for the referenced variable. */
-    resolveVarRef?: (varRef: VariableRef) => Expr | undefined;
-}
-/**
- * @hidden This is not yet part of the public API.
- */
-declare function reduceExpr(expr: Expr, opts?: ReduceExprOptions): Expr;
-/**
- * A variant of `reduceExpr` that does not aggressively reduce the expression, but only
- * tries to eliminate the unused branch if a conditional (`IF THEN ELSE`) has a condition
- * that resolves to a constant.
- *
- * @hidden This is not yet part of the public API.
- *
- * @param expr The expression to reduce.
- * @param opts The reduce options.
- * @returns A possibly reduced expression.
- */
-declare function reduceConditionals(expr: Expr, opts?: ReduceExprOptions): Expr;
-
-/**
- * Context interface that provides access to file system resources (such as external
- * data files) that are needed when parsing a Vensim model.
- */
-interface VensimParseContext {
-    /**
-     * Called when a `GET DIRECT SUBSCRIPTS` function call is encountered when parsing a
-     * Vensim subscript range definition.  The arguments are the same as those passed
-     * to `GET DIRECT SUBSCRIPTS` in the model, except that the enclosing quotes have
-     * already been removed.
-     *
-     * @param fileName The CSV or XLS[X] file path, or an indirect tag (e.g., '?data').
-     * @param tabOrDelimiter The tab name (for XLS[X] files) or the delimiter (for CSV files).
-     * @param firstCell The location of the first subscript element.
-     * @param lastCell The location of the last subscript element.
-     * @param prefix A string that is prepended to every subscript element.
-     * @returns An array of subscript names read from the external data file.
-     */
-    getDirectSubscripts(fileName: string, tabOrDelimiter: string, firstCell: string, lastCell: string, prefix: string): SubName[];
-}
-
-/**
- * Parse the given Vensim subscript range definition and return a `DimensionDef` AST node.
- *
- * @param input A string containing the Vensim subscript range definition.
- * @param context An object that provides access to file system resources (such as
- * external data files) that are referenced during the parse phase.
- * @returns A `DimensionDef` AST node.
- */
-declare function parseVensimSubscriptRange(input: string, context?: VensimParseContext): DimensionDef;
-
-/**
- * Parse the given Vensim expression definition and return an `Expr` AST node.
- *
- * @param input A string containing the Vensim expression.
- * @returns An `Expr` AST node.
- */
-declare function parseVensimExpr(input: string): Expr;
-
-/**
- * Parse the given Vensim equation definition and return an `Equation` AST node.
- *
- * @param input A string containing the Vensim equation definition.
- * @returns An `Equation` AST node.
- */
-declare function parseVensimEquation(input: string): Equation;
-
-/**
- * Parse the given Vensim model definition and return a `Model` AST node.
- *
- * @param input A string containing the Vensim model.
- * @param context An object that provides access to file system resources (such as
- * external data files) that are referenced during the parse phase.
- * @param sort Whether to sort definitions alphabetically during the preprocessing phase.
- * @returns A `Model` AST node.
- */
-declare function parseVensimModel(input: string, context?: VensimParseContext, sort?: boolean): Model;
-
-/**
- * A single Vensim definition (either a subscript range definition or an
- * equation definition).  This contains the definition's text and metadata
- * that was extracted during preprocessing.
- */
-interface VensimDef {
-    /**
-     * A simplified key for the LHS of the definition, used for sorting
-     * and/or flattening.
-     */
-    key: string;
-    /**
-     * The preprocessed equation or subscript range definition (with
-     * units and comment replaced with `~~|`).
-     */
-    def: string;
-    /**
-     * The kind of definition; either 'eqn' for an equation containing an equals
-     * sign, 'dim' for a dimension (subscript range) definition, or 'decl' for
-     * all other declarations (e.g., a lookup or data variable definition).
-     */
-    kind: 'eqn' | 'dim' | 'decl';
-    /**
-     * The (1-based) line number where the definition begins.
-     */
-    line: number;
-    /**
-     * The units text.
-     */
-    units: string;
-    /**
-     * The comment text.
-     */
-    comment: string;
-    /**
-     * The optional group name, if the definition is contained within a group.
-     */
-    group?: string;
-}
-/**
- * Result type for the `preprocessVensimModel` function.
- */
-interface PreprocessedVensimModel {
-    /**
-     * The preprocessed definitions that were preserved.
-     */
-    defs: VensimDef[];
-    /**
-     * The macros that were removed by the preprocessor.
-     */
-    removedMacros: string[];
-    /**
-     * The text blocks that were removed by the preprocessor.  These include
-     * unsupported functions (such as `TABBED ARRAY`) and other definitions
-     * that were requested for removal.
-     */
-    removedBlocks: string[];
-}
-/**
- * Process the given Vensim model content so that it can be parsed
- * by `antlr4-vensim`.  This will:
- *   - strip out group markers
- *   - remove macro definitions, which are currently unsupported
- *   - remove equations that reference certain unsupported functions
- *     (e.g., `TABBED ARRAY`)
- *   - remove everything in the private Vensim sketch section
- *   - join lines that are separated by a continuation (backslash)
- *   - split the input into distinct definitions (equations and
- *     subscript ranges)
- *
- * The definitions are further processed to preserve the units and
- * comment text in separate properties, but strips them from the
- * equation string (replaced with `~~`) to make it easier for
- * `antlr4-vensim` to process.
- *
- * @param input The original Vensim mdl file content.
- * @param options The options that control preprocessing.
- * @return A `PreprocessedVensimModel` instance containing the preprocessed
- * Vensim definitions.
- */
-declare function preprocessVensimModel(input: string, options?: {
-    removalKeys?: string[];
-}): PreprocessedVensimModel;
-
-/**
- * Parse the given XMILE dimension (`<dim>`) definition and return a `DimensionDef` AST node.
- *
- * @param input A string containing the XMILE `<dim>` definition.
- * @returns A `DimensionDef` AST node.
- */
-declare function parseXmileDimensionDef(dimElem: XmlElement): DimensionDef;
-
-/**
- * Parse the given XMILE model definition and return a `Model` AST node.
- *
- * @param input A string containing the XMILE model.
- * @param context An object that provides access to file system resources (such as
- * external data files) that are referenced during the parse phase.
- * @returns A `Model` AST node.
- */
-declare function parseXmileModel(input: string): Model;
-
-/**
- * Parse the given XMILE variable definition and return an array of `Equation` AST nodes
- * corresponding to the variable definition (or definitions, in the case of a
- * non-apply-to-all variable that is defined with an `<element>` for each subscript).
- *
- * @param input A string containing the XMILE equation definition.
- * @returns An `Equation` AST node.
- */
-declare function parseXmileVariableDef(varElem: XmlElement): Equation[];
-
-export { type BinaryOp, type BinaryOpExpr, type DimId, type DimName, type DimOrSubId, type DimOrSubName, type DimensionDef, type Equation, type EquationLhs, type EquationRhs, type EquationRhsConstList, type EquationRhsData, type EquationRhsExpr, type EquationRhsLookup, type Expr, type FormatVariableRefFunc, type FunctionCall, type FunctionId, type FunctionName, type Keyword, type LookupCall, type LookupDef, type LookupPoint, type LookupRange, type Model, type NumberLiteral, type ParensExpr, type PreprocessedVensimModel, type PrettyOpts, type ReduceExprOptions, type SimulationSpec, type StringLiteral, type SubId, type SubName, type SubscriptMapping, type SubscriptRef, type UnaryOp, type UnaryOpExpr, type VariableDef, type VariableId, type VariableName, type VariableRef, type VensimDef, type VensimParseContext, canonicalFunctionId, canonicalId, canonicalVarId, debugPrintExpr, parseVensimEquation, parseVensimExpr, parseVensimModel, parseVensimSubscriptRange, parseXmileDimensionDef, parseXmileModel, parseXmileVariableDef, preprocessVensimModel, prettyPrintExpr, printExprStats, reduceConditionals, reduceExpr, toPrettyString };