@sdeverywhere/parse 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,445 @@
+/** 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 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;
+
+export { BinaryOp, BinaryOpExpr, DimId, DimName, DimOrSubId, DimOrSubName, DimensionDef, Equation, EquationLhs, EquationRhs, EquationRhsConstList, EquationRhsData, EquationRhsExpr, EquationRhsLookup, Expr, FormatVariableRefFunc, FunctionCall, FunctionId, FunctionName, Keyword, LookupCall, LookupDef, LookupPoint, LookupRange, Model, NumberLiteral, ParensExpr, PrettyOpts, ReduceExprOptions, StringLiteral, SubId, SubName, SubscriptMapping, SubscriptRef, UnaryOp, UnaryOpExpr, VariableDef, VariableId, VariableName, VariableRef, VensimParseContext, debugPrintExpr, parseVensimEquation, parseVensimExpr, parseVensimModel, parseVensimSubscriptRange, prettyPrintExpr, printExprStats, reduceConditionals, reduceExpr, toPrettyString };