@cortex-js/compute-engine 0.24.0 → 0.25.0

package/dist/types/compute-engine/latex-syntax/parse.d.ts

@@ -1,37 +1,71 @@
-/* 0.24.0 */
-import { IndexedLatexDictionary, IndexedLatexDictionaryEntry, IndexedInfixEntry, IndexedPostfixEntry, IndexedPrefixEntry, IndexedSymbolEntry, IndexedExpressionEntry, IndexedFunctionEntry } from './dictionary/definitions';
-import { IComputeEngine } from '../public';
-import { Expression } from '../../math-json/math-json-format';
-export declare const DEFAULT_LATEX_NUMBER_OPTIONS: NumberFormattingOptions;
-export declare const DEFAULT_PARSE_LATEX_OPTIONS: ParseLatexOptions;
+/* 0.25.0 */
+import { ParseLatexOptions, LatexToken, Terminator, Parser, SymbolTable, SymbolType } from './public';
+import type { IndexedLatexDictionary, IndexedLatexDictionaryEntry, IndexedInfixEntry, IndexedPostfixEntry, IndexedPrefixEntry, IndexedSymbolEntry, IndexedExpressionEntry, IndexedFunctionEntry } from './dictionary/definitions';
+/**
+ * ## THEORY OF OPERATIONS
+ *
+ * The parser is a recursive descent parser that uses a dictionary of
+ * LaTeX commands to parse a LaTeX string into a MathJSON expression.
+ *
+ * The parser is a stateful object that keeps track of the current position
+ * in the token stream, and the boundaries of the current parsing operation.
+ *
+ * To parse correctly some constructs, the parser needs to know the context
+ * in which it is parsing. For example, parsing `k(2+x)` can be interpreted
+ * as a function `k` applied to the sum of `2` and `x`, or as the product
+ * of `k` and the sum of `2` and `x`. The parser needs to know that `k` is
+ * a function to interpret the expression as a function application.
+ *
+ * The parser uses the current state of the compute engine, and any
+ * identifier that may have been declared, to determine the correct
+ * interpretation.
+ *
+ * Some constructs declare variables or functions while parsing. For example,
+ * `\sum_{i=1}^n i` declares the variable `i` as the index of the sum.
+ *
+ * The parser keeps track of the parsing state with a stack of symbol tables.
+ *
+ * In addition, the handler `getIdentifierType()` is called when the parser
+ * encounters an unknown identifier. This handler can be used to declare the
+ * identifier, or to return `unknown` if the identifier is not known.
+ *
+ * Some functions affect the state of the parser:
+ * - `Declare`, `Assign` modify the symbol table
+ * - `Block` create a new symbol table (local scope)
+ * - `Function` create a new symbol table with named arguments
+ *
+ *
+ */
 export declare class _Parser implements Parser {
-    readonly computeEngine: IComputeEngine;
-    readonly options: NumberFormattingOptions & ParseLatexOptions;
+    readonly options: Readonly<ParseLatexOptions>;
     _index: number;
+    symbolTable: SymbolTable;
+    pushSymbolTable(): void;
+    popSymbolTable(): void;
+    addSymbol(id: string, type: SymbolType): void;
     get index(): number;
     set index(val: number);
     private _tokens;
     private _positiveInfinityTokens;
     private _negativeInfinityTokens;
     private _notANumberTokens;
-    private _decimalMarkerTokens;
-    private _groupSeparatorTokens;
+    private _decimalSeparatorTokens;
+    private _wholeDigitGroupSeparatorTokens;
+    private _fractionalDigitGroupSeparatorTokens;
     private _exponentProductTokens;
     private _beginExponentMarkerTokens;
     private _endExponentMarkerTokens;
     private _truncationMarkerTokens;
-    private _beginRepeatingDigitsTokens;
-    private _endRepeatingDigitsTokens;
-    private _imaginaryNumberTokens;
+    private _imaginaryUnitTokens;
     private readonly _dictionary;
     private _boundaries;
     private _lastPeek;
     private _peekCounter;
-    constructor(tokens: LatexToken[], options: NumberFormattingOptions & ParseLatexOptions, dictionary: IndexedLatexDictionary, computeEngine: IComputeEngine);
-    updateOptions(opt: Partial<NumberFormattingOptions> & Partial<ParseLatexOptions>): void;
-    get atEnd(): boolean;
+    constructor(tokens: LatexToken[], dictionary: IndexedLatexDictionary, options: Readonly<ParseLatexOptions>);
+    getIdentifierType(id: string): SymbolType;
     get peek(): LatexToken;
     nextToken(): LatexToken;
+    get atEnd(): boolean;
     /**
      * Return true if
      * - at end of the token stream
@@ -111,8 +145,8 @@ export declare class _Parser implements Parser {
      */
     private matchDelimiter;
     parseGroup(): Expression | null;
-    parseToken(): Expression | null;
     parseOptionalGroup(): Expression | null;
+    parseToken(): Expression | null;
     /**
      * Parse an expression in a tabular format, where rows are separated by `\\`
      * and columns by `&`.
@@ -121,15 +155,28 @@ export declare class _Parser implements Parser {
      * and empty cells are also indicated with `Nothing`.
      */
     parseTabular(): null | Expression[][];
+    /** Match a string used as a LaTeX identifier, for example an environment
+     * name.
+     * Not suitable for general purpose text, e.g. argument of a `\text{}
+     * command. See `matchChar()` instead.
+     */
+    private parseStringGroupContent;
     /** Parse a group as a a string, for example for `\operatorname` or `\begin` */
     parseStringGroup(optional?: boolean): string | null;
     /** Parse an environment: `\begin{env}...\end{end}`
      */
     private parseEnvironment;
-    /** If the next token matches a `+` or `-` sign, return it and advance the index.
-     * Otherwise return `''` and do not advance */
+    /** If the next token matches a `-` sign, return '-', otherwise return '+'
+     *
+     */
     private parseOptionalSign;
+    /** Parse a sequence of decimal digits. The part indicates which
+     * grouping separator should be expected.
+     */
     private parseDecimalDigits;
+    /** The 'part' argument is used to dermine what grouping separator
+     *  should be expected.
+     */
     private parseSignedInteger;
     private parseExponent;
     parseRepeatingDecimal(): string;
@@ -173,7 +220,6 @@ export declare class _Parser implements Parser {
      *
      * @internal
      */
-    private matchOpenDelimiter;
     /**
      * An enclosure is an opening matchfix operator, an optional expression,
      * optionally followed multiple times by a separator and another expression,
@@ -181,7 +227,7 @@ export declare class _Parser implements Parser {
      */
     private parseEnclosure;
     /**
-     * A generic expression is used for dictionary entries that take do
+     * A generic expression is used for dictionary entries that do
      * some complex (non-standard) parsing. This includes trig functions (to
      * parse implicit arguments), and integrals (to parse the integrand and
      * limits and the "dx" terminator).
@@ -206,18 +252,13 @@ export declare class _Parser implements Parser {
      */
     private parseSupsub;
     parsePostfixOperator(lhs: Expression | null, until?: Readonly<Terminator>): Expression | null;
-    /** Match a string used as a LaTeX identifier, for example an environment
-     * name.
-     * Not suitable for general purpose text, e.g. argument of a `\text{}
-     * command. See `matchChar()` instead.
-     */
-    private parseStringGroupContent;
     /**
-     * This method can be invoked when we know we're in an error situation.
+     * This method can be invoked when we know we're in an error situation,
+     * for example when there are tokens remaining after we've finished parsing.
      *
      * In general, if a context does not apply, we return `null` to give
      * the chance to some other option to be considered. However, in some cases
-     * we know we've exhausted all posibilities, and in this case this method
+     * we know we've exhausted all possibilities, and in this case this method
      * will return an error expression as informative as possible.
      *
      * We've encountered a LaTeX command or symbol but were not able to match it
@@ -262,3 +303,4 @@ export declare class _Parser implements Parser {
     /** Return all defs of the specified kind */
     getDefs(kind: string): Iterable<IndexedLatexDictionaryEntry>;
 }
+export declare function parse(latex: string, dictionary: IndexedLatexDictionary, options: Readonly<ParseLatexOptions>): Expression | null;