@cortex-js/compute-engine 0.12.4 → 0.12.6

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

@@ -1,5 +1,5 @@
-/* 0.12.4 */
-import { IndexedLatexDictionary, IndexedInfixEntry, IndexedPostfixEntry, IndexedPrefixEntry, IndexedIdentifierEntry } from './dictionary/definitions';
+/* 0.12.6 */
+import { IndexedLatexDictionary, IndexedInfixEntry, IndexedPostfixEntry, IndexedPrefixEntry, IndexedSymbolEntry, IndexedExpressionEntry } from './dictionary/definitions';
 import { IComputeEngine } from '../public';
 import { Expression } from '../../math-json/math-json-format';
 export declare const DEFAULT_LATEX_NUMBER_OPTIONS: NumberFormattingOptions;
@@ -8,7 +8,7 @@ export declare class _Parser implements Parser {
     readonly computeEngine: IComputeEngine;
     readonly options: NumberFormattingOptions & ParseLatexOptions;
     index: number;
-    private readonly _tokens;
+    private _tokens;
     private _positiveInfinityTokens;
     private _negativeInfinityTokens;
     private _notANumberTokens;
@@ -29,7 +29,7 @@ export declare class _Parser implements Parser {
     updateOptions(opt: Partial<NumberFormattingOptions> & Partial<ParseLatexOptions>): void;
     get atEnd(): boolean;
     get peek(): LatexToken;
-    next(): LatexToken;
+    nextToken(): LatexToken;
     /**
      * Return true if
      * - at end of the token stream
@@ -44,12 +44,9 @@ export declare class _Parser implements Parser {
     matchBoundary(): boolean;
     boundaryError(msg: string | [string, ...Expression[]]): Expression;
     latex(start: number, end?: number): string;
-    latexAhead(n: number): string;
-    latexBefore(): string;
-    latexAfter(): string;
+    private latexAhead;
     /**
-     * Return at most `this._dictionary.lookahead` strings made from the tokens
-     * ahead.
+     * Return at most `this._dictionary.lookahead` LaTeX tokens.
      *
      * The index in the returned array correspond to the number of tokens.
      * Note that since a token can be longer than one char ('\\pi', but also
@@ -57,11 +54,16 @@ export declare class _Parser implements Parser {
      * does not match that index. However, knowing the index is important
      * to know by how many tokens to advance.
      *
+     * For example:
+     *
+     * `[empty, '\\sqrt', '\\sqrt{', '\\sqrt{2', '\\sqrt{2}']`
+     *
      */
     lookAhead(): string[];
     /** Return all the definitions that potentially match the tokens ahead */
+    peekDefinitions(kind: 'expression'): [IndexedExpressionEntry, number][] | null;
     peekDefinitions(kind: 'function'): [FunctionEntry, number][] | null;
-    peekDefinitions(kind: 'identifier'): [IndexedIdentifierEntry, number][] | null;
+    peekDefinitions(kind: 'symbol'): [IndexedSymbolEntry, number][] | null;
     peekDefinitions(kind: 'postfix'): [IndexedPostfixEntry, number][] | null;
     peekDefinitions(kind: 'infix'): [IndexedInfixEntry, number][] | null;
     peekDefinitions(kind: 'prefix'): [IndexedPrefixEntry, number][] | null;
@@ -77,23 +79,38 @@ export declare class _Parser implements Parser {
      */
     skipSpace(): boolean;
     skipVisualSpace(): void;
-    matchChar(): string | null;
-    matchColor(_background?: boolean): string | null;
-    matchLatexDimension(): string | null;
     match(token: LatexToken): boolean;
-    matchAll(tokens: LatexToken | LatexToken[]): boolean;
+    matchAll(tokens: LatexToken[]): boolean;
     matchAny(tokens: LatexToken[]): LatexToken;
-    matchSequence(tokens: LatexToken[]): LatexToken[];
-    matchOptionalSign(): string;
-    matchDecimalDigits(options?: {
-        withGrouping?: boolean;
-    }): string;
-    matchSignedInteger(options?: {
-        withGrouping?: boolean;
-    }): string;
-    matchExponent(): string;
-    matchRepeatingDecimal(): string;
-    matchNumber(): string;
+    matchChar(): string | null;
+    parseGroup(): Expression | null;
+    parseToken(): Expression | null;
+    parseOptionalGroup(): Expression | null;
+    /**
+     * Parse an expression in a tabular format, where rows are separated by `\\`
+     * and columns by `&`.
+     *
+     * Return rows of sparse columns: empty rows are indicated with `Nothing`,
+     * and empty cells are also indicated with `Nothing`.
+     */
+    parseTabular(): null | Expression[][];
+    /** Parse a group as a a string, for example for `\operatorname` or `\begin` */
+    parseStringGroup(): 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 */
+    private parseOptionalSign;
+    private parseDecimalDigits;
+    private parseSignedInteger;
+    private parseExponent;
+    parseRepeatingDecimal(): string;
+    /**
+     * Parse a number, with an optional sign, exponent, decimal marker,
+     * repeating decimals, etc...
+     */
+    private parseNumber;
     /**
      * A Latex number can be a decimal, hex or octal number.
      * It is used in some Latex commands, such as `\char`
@@ -106,25 +123,22 @@ export declare class _Parser implements Parser {
      * > an internal variable.
      */
     matchLatexNumber(isInteger?: boolean): null | number;
-    matchPrefixOperator(until?: Terminator): Expression | null;
-    matchInfixOperator(lhs: Expression, until?: Terminator): Expression | null;
+    private parsePrefixOperator;
+    private parseInfixOperator;
     /**
-     * - 'enclosure' : will look for an argument inside an enclosure (open/close fence)
+     * This returns an array of arguments (as in a function application),
+     * or null if there is no match.
+     *
+     * - 'enclosure' : will look for an argument inside an enclosure
+     *   (open/close fence)
      * - 'implicit': either an expression inside a pair of `()`, or just a product
      *  (i.e. we interpret `\cos 2x + 1` as `\cos(2x) + 1`)
+     *
      */
-    matchArguments(kind: undefined | '' | 'enclosure' | 'implicit', until?: Terminator): Expression[] | null;
-    /**
-     * A function can be followed by the following suffixes:
-     * - a `\prime`, `\doubleprime`, `'`, `(n)` to indicate a derivative
-     * - a subscript to indicate an argument
-     * - an argument, optionally inside an enclosure
-     */
-    matchFunctionSuffix(id: string): Expression;
+    parseArguments(kind?: 'enclosure' | 'implicit', until?: Terminator): Expression[] | null;
     /** A prime suffix is a sequence of `'`, `\prime` or `\doubleprime`
      * after a function or in a superscript.
      */
-    matchPrimeSuffix(): number;
     /** If matches the normalized open delimiter, return the
      * expected closing delimiter.
      *
@@ -133,55 +147,55 @@ export declare class _Parser implements Parser {
      *
      * If you need to match several tokens, use `matchAll()`
      */
-    matchOpenDelimiter(openDelim: Delimiter, closeDelim: Delimiter): LatexToken[] | null;
-    matchMiddleDelimiter(delimiter: '|' | ':' | LatexToken): boolean;
+    private matchOpenDelimiter;
     /** For error handling, when there is potentially a mismatched delimiter.
      * Return a LaTeX fragment of the expected closing delimiter
+     *
+     * @internal
      */
     matchEnclosureOpen(): string | null;
+    /**
+     * Used for error handling
+     * @internal */
     matchEnclosureClose(): string | null;
     /**
      * An enclosure is an opening matchfix operator, an optional expression,
      * optionally followed multiple times by a separator and another expression,
      * and finally a closing matching operator.
      */
-    matchEnclosure(): Expression | null;
-    matchIdentifier(): string | null;
+    private parseEnclosure;
     /**
-     * A function is an identifier followed by arguments
-     * - a single letter identifier with explicit arguments `f(x)`
-     * - a multiletter identifier with explicit arguments `\mathrm{floor}(x)`
-     * - an identifier: `\mathrm{floor}`
-     * - a command with implicit arguments: `\cos x` (via a  custom parser)
-     *
+     * A generic expression is used for dictionary entries that take 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).
+     */
+    private parseGenericExpression;
+    /**
+     * A function is an identifier followed by postfix operators
+     * (`\prime`...) and some arguments.
      */
-    matchFunction(until?: Partial<Terminator>): Expression | null;
+    private parseFunction;
+    parseSymbol(until?: Partial<Terminator>): Expression | null;
     /**
-     * A symbol is an identifier or a custom definition
+     * Parse a sequence superfix/subfix operator, e.g. `^{*}`
+     *
+     * Superfix and subfix need special handling:
+     *
+     * - they act mostly like an infix operator, but they are commutative, i.e.
+     * `x_a^b` should be parsed identically to `x^b_a`.
+     *
+     * - furthermore, in LaTeX `x^a^b` parses the same as `x^a{}^b`.
+     *
      */
-    matchSymbol(until?: Partial<Terminator>): Expression | null;
-    matchLatexOptionalGroup(): Expression | null;
-    matchSingleAtomArgument(): Expression | null;
-    matchLatexGroup(): Expression | null;
-    matchSupsub(lhs: Expression | null): Expression | null;
-    matchPostfix(lhs: Expression | null): Expression | null;
+    private parseSupsub;
+    parsePostfixOperator(lhs: Expression | null, until?: Partial<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.
      */
-    matchString(): string;
-    /** Match a string as an argument (in a `{}` pair) */
-    matchStringArgument(): string | null;
-    /**
-     * Match an expression in a tabular format, where rows are separated by `\\`
-     * and columns by `&`.
-     *
-     * Return rows of sparse columns: empty rows are indicated with `Nothing`,
-     * and empty cells are also indicated with `Nothing`.
-     */
-    matchTabular(): null | Expression[][];
-    matchEnvironment(): Expression | null;
+    private parseStringGroupContent;
     /**
      * Apply an invisible operator between two expressions.
      *
@@ -203,19 +217,30 @@ export declare class _Parser implements Parser {
      * - x2 -> no
      * => lhs is a number, rhs is a number, but not a literal
      */
-    applyInvisibleOperator(until: Terminator, lhs: Expression | null): Expression | null;
-    matchUnexpectedLatexCommand(): Expression | null;
+    private applyInvisibleOperator;
+    /**
+     * This is an error handling method. We've encountered a LaTeX command
+     * but were not able to match it to any entry in the LaTeX dictionary,
+     * or ran into it in an unexpected context (postfix operator lacking an
+     * argument, for example)
+     */
+    private parseUnexpectedLatexCommand;
     /**
      * <primary> :=
-     * (<number> | <symbol> | <environment> | <matchfix-expr>) <subsup>* <postfix-operator>*
+     *  (<number> | <symbol> | <environment> | <matchfix-expr>)
+     *    <subsup>* <postfix-operator>*
      *
-     * <symbol> ::= (<symbol-id> | (<latex-command><latex-arguments>)) <arguments>
+     * <symbol> ::=
+     *  (<symbol-id> | (<latex-command><latex-arguments>)) <arguments>
      *
      * <matchfix-expr> :=
-     *  <matchfix-op-open> <expression> [<matchfix-op-separator> <expression>] <matchfix-op-close>
+     *  <matchfix-op-open>
+     *  <expression>
+     *  (<matchfix-op-separator> <expression>)*
+     *  <matchfix-op-close>
      *
      */
-    matchPrimary(until?: Partial<Terminator>): Expression | null;
+    private parsePrimary;
     /**
      *  Parse an expression:
      *
@@ -224,12 +249,14 @@ export declare class _Parser implements Parser {
      *  | <prefix-op> <primary>
      *  | <primary> <infix-op> <expression>
      *
-     * Stop when an operator of precedence less than `until.minPrec` is encountered
+     * Stop when an operator of precedence less than `until.minPrec`
+     * is encountered
      */
-    matchExpression(until?: Partial<Terminator>): Expression | null;
+    parseExpression(until?: Partial<Terminator>): Expression | null;
     /**
      * Add LaTeX or other requested metadata to the expression
      */
     decorate(expr: Expression | null, start: number): Expression | null;
     error(code: string | [string, ...Expression[]], fromToken: number): Expression;
+    private isFunctionHead;
 }