@sdeverywhere/parse 0.1.1 → 0.1.3

package/dist/index.d.cts

@@ -1,3 +1,46 @@
+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. */
@@ -321,6 +364,13 @@ interface Equation {
 }
 /** 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. */
@@ -442,4 +492,116 @@ declare function parseVensimEquation(input: string): Equation;
  */
 declare function parseVensimModel(input: string, context?: VensimParseContext, sort?: boolean): Model;
 
-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 PrettyOpts, type ReduceExprOptions, type StringLiteral, type SubId, type SubName, type SubscriptMapping, type SubscriptRef, type UnaryOp, type UnaryOpExpr, type VariableDef, type VariableId, type VariableName, type VariableRef, type VensimParseContext, debugPrintExpr, parseVensimEquation, parseVensimExpr, parseVensimModel, parseVensimSubscriptRange, prettyPrintExpr, printExprStats, reduceConditionals, reduceExpr, toPrettyString };
+/**
+ * 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 };

package/dist/index.d.ts

@@ -1,3 +1,46 @@
+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. */
@@ -321,6 +364,13 @@ interface Equation {
 }
 /** 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. */
@@ -442,4 +492,116 @@ declare function parseVensimEquation(input: string): Equation;
  */
 declare function parseVensimModel(input: string, context?: VensimParseContext, sort?: boolean): Model;
 
-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 PrettyOpts, type ReduceExprOptions, type StringLiteral, type SubId, type SubName, type SubscriptMapping, type SubscriptRef, type UnaryOp, type UnaryOpExpr, type VariableDef, type VariableId, type VariableName, type VariableRef, type VensimParseContext, debugPrintExpr, parseVensimEquation, parseVensimExpr, parseVensimModel, parseVensimSubscriptRange, prettyPrintExpr, printExprStats, reduceConditionals, reduceExpr, toPrettyString };
+/**
+ * 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 };