app/node_modules/mathjax-full/ts/input/tex/TexParser.ts

/*************************************************************
 *
 *  Copyright (c) 2017-2022 The MathJax Consortium
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */


/**
 * @fileoverview The TexParser. Implements the basic parsing functionality and
 *     administers the global stack and tree objects.
 *
 * @author v.sorge@mathjax.org (Volker Sorge)
 */

import ParseUtil from './ParseUtil.js';
import {HandlerType} from './MapHandler.js';
import Stack from './Stack.js';
import StackItemFactory from './StackItemFactory.js';
import {Tags} from './Tags.js';
import TexError from './TexError.js';
import {MmlNode, AbstractMmlNode} from '../../core/MmlTree/MmlNode.js';
import {ParseInput, ParseResult} from './Types.js';
import ParseOptions from './ParseOptions.js';
import {StackItem, EnvList} from './StackItem.js';
import {Symbol} from './Symbol.js';
import {OptionList} from '../../util/Options.js';


/**
 * The main Tex Parser class.
 */
export default class TexParser {

  /**
   * Counter for recursive macros.
   * @type {number}
   */
  public macroCount: number = 0;

  /**
   * The stack for items and created nodes.
   * @type {Stack}
   */
  public stack: Stack;

  /**
   * Current position in the string that is parsed.
   * @type {number}
   */
  public i: number = 0;

  /**
   * The last command sequence
   * @type {string}
   */
  public currentCS: string = '';

  /**
   * @constructor
   * @param {string} string The string to parse.
   * @param {EnvList} env The intial environment representing the current parse
   *     state of the overall expression translation.
   * @param {ParseOptions} configuration A parser configuration.
   */
  constructor(private _string: string, env: EnvList, public configuration: ParseOptions) {
    const inner = env.hasOwnProperty('isInner');
    const isInner = env['isInner'] as boolean;
    delete env['isInner'];
    let ENV: EnvList;
    if (env) {
      ENV = {};
      for (const id of Object.keys(env)) {
        ENV[id] = env[id];
      }
    }
    this.configuration.pushParser(this);
    this.stack = new Stack(this.itemFactory, ENV, inner ? isInner : true);
    this.Parse();
    this.Push(this.itemFactory.create('stop'));
  }

  /**
   * @return {OptionList} The configuration options.
   */
  get options(): OptionList {
    return this.configuration.options;
  }

  /**
   * @return {StackItemFactory} The factory for stack items.
   */
  get itemFactory(): StackItemFactory {
    return this.configuration.itemFactory;
  }

  /**
   * @return {Tags} The tags style of this configuration.
   */
  get tags(): Tags {
    return this.configuration.tags;
  }

  /**
   * Sets the string that should be parsed.
   * @param {string} str The new string to parse.
   */
  set string(str: string) {
    this._string = str;
  }

  /**
   * @return {string} The string that is currently parsed.
   */
  get string(): string {
    return this._string;
  }


  /**
   * Parses the input with the specified kind of map.
   * @param {HandlerType} kind Configuration name.
   * @param {ParseInput} input Input to be parsed.
   * @return {ParseResult} The output of the parsing function.
   */
  public parse(kind: HandlerType, input: ParseInput): ParseResult {
    return this.configuration.handlers.get(kind).parse(input);
  }


  /**
   * Maps a symbol to its "parse value" if it exists.
   * @param {HandlerType} kind Configuration name.
   * @param {string} symbol The symbol to parse.
   * @return {any} A boolean, Character, or Macro.
   */
  public lookup(kind: HandlerType, symbol: string): any {
    return this.configuration.handlers.get(kind).lookup(symbol);
  }


  /**
   * Checks if a symbol is contained in one of the symbol mappings of the
   * specified kind.
   * @param {HandlerType} kind Configuration name.
   * @param {string} symbol The symbol to parse.
   * @return {boolean} True if the symbol is contained in the given types of
   *     symbol mapping.
   */
  public contains(kind: HandlerType, symbol: string): boolean {
    return this.configuration.handlers.get(kind).contains(symbol);
  }


  /**
   * @override
   */
  public toString(): string {
    let str = '';
    for (const config of Array.from(this.configuration.handlers.keys())) {
      str += config + ': ' +
        this.configuration.handlers.get(config as HandlerType) + '\n';
    }
    return str;
  }


  /**
   * Parses the current input string.
   */
  public Parse() {
    let c: string;
    while (this.i < this.string.length) {
      c = this.getCodePoint();
      this.i += c.length;
      this.parse('character', [this, c]);
    }
  }


  /**
   * Pushes a new item onto the stack. The item can also be a Mml node,
   *   but if the mml item is an inferred row, push its children instead.
   * @param {StackItem|MmlNode} arg The new item.
   */
  public Push(arg: StackItem | MmlNode) {
    if (arg instanceof AbstractMmlNode && arg.isInferred) {
      this.PushAll(arg.childNodes);
    } else {
      this.stack.Push(arg);
    }
  }


  /**
   * Pushes a list of new items onto the stack.
   * @param {StackItem|MmlNode[]} args The new items.
   */
  public PushAll(args: (StackItem | MmlNode)[]) {
    for (const arg of args) {
      this.stack.Push(arg);
    }
  }


  /**
   * @return {MmlNode} The internal Mathml structure.
   */
  public mml(): MmlNode {
    if (!this.stack.Top().isKind('mml')) {
      return null;
    }
    let node = this.stack.Top().First;
    this.configuration.popParser();
    return node;
  }

  /************************************************************************
   *
   *   String handling routines
   */

  /**
   * Convert delimiter to character.
   * @param {string} c The delimiter name.
   * @return {string} The corresponding character.
   */
  public convertDelimiter(c: string): string {
    const symbol = this.lookup('delimiter', c) as Symbol;
    return symbol ? symbol.char : null;
  }

  /**
   * @return {string}   Get the next unicode character in the string
   */
  public getCodePoint(): string {
    const code = this.string.codePointAt(this.i);
    return code === undefined ? '' : String.fromCodePoint(code);
  }

  /**
   * @return {boolean} True if the next character to parse is a space.
   */
  public nextIsSpace(): boolean {
    return !!this.string.charAt(this.i).match(/\s/);
  }

  /**
   * @return {string} Get the next non-space character.
   */
  public GetNext(): string {
    while (this.nextIsSpace()) {
      this.i++;
    }
    return this.getCodePoint();
  }

  /**
   * @return {string} Get and return a control-sequence name
   */
  public GetCS(): string {
    let CS = this.string.slice(this.i).match(/^(([a-z]+) ?|[\uD800-\uDBFF].|.)/i);
    if (CS) {
      this.i += CS[0].length;
      return CS[2] || CS[1];
    } else {
      this.i++;
      return ' ';
    }
  }

  /**
   * Get and return a TeX argument (either a single character or control
   *     sequence, or the contents of the next set of braces).
   * @param {string} name Name of the current control sequence.
   * @param {boolean} noneOK? True if no argument is OK.
   * @return {string} The next argument.
   */
  public GetArgument(_name: string, noneOK?: boolean): string {
    switch (this.GetNext()) {
    case '':
      if (!noneOK) {
        // @test MissingArgFor
        throw new TexError('MissingArgFor', 'Missing argument for %1', this.currentCS);
      }
      return null;
    case '}':
      if (!noneOK) {
        // @test ExtraCloseMissingOpen
        throw new TexError('ExtraCloseMissingOpen',
                            'Extra close brace or missing open brace');
      }
      return null;
    case '\\':
      this.i++;
      return '\\' + this.GetCS();
    case '{':
      let j = ++this.i, parens = 1;
      while (this.i < this.string.length) {
        switch (this.string.charAt(this.i++)) {
        case '\\':  this.i++; break;
        case '{':   parens++; break;
        case '}':
          if (--parens === 0) {
            return this.string.slice(j, this.i - 1);
          }
          break;
        }
      }
      // @test MissingCloseBrace
      throw new TexError('MissingCloseBrace', 'Missing close brace');
    }
    const c = this.getCodePoint();
    this.i += c.length;
    return c;
  }


  /**
   * Get an optional LaTeX argument in brackets.
   * @param {string} name Name of the current control sequence.
   * @param {string} def? The default value for the optional argument.
   * @return {string} The optional argument.
   */
  public GetBrackets(_name: string, def?: string): string {
    if (this.GetNext() !== '[') {
      return def;
    }
    let j = ++this.i, parens = 0;
    while (this.i < this.string.length) {
      switch (this.string.charAt(this.i++)) {
      case '{':   parens++; break;
      case '\\':  this.i++; break;
      case '}':
        if (parens-- <= 0) {
          // @test ExtraCloseLooking1
          throw new TexError('ExtraCloseLooking',
                              'Extra close brace while looking for %1', '\']\'');
        }
        break;
      case ']':
        if (parens === 0) {
          return this.string.slice(j, this.i - 1);
        }
        break;
      }
    }
    // @test MissingCloseBracket
    throw new TexError('MissingCloseBracket',
                        'Could not find closing \']\' for argument to %1', this.currentCS);
  }

  /**
   *  Get the name of a delimiter (check it in the delimiter list).
   * @param {string} name Name of the current control sequence.
   * @param {boolean} braceOK? Are braces around the delimiter OK.
   * @return {string} The delimiter name.
   */
  public GetDelimiter(name: string, braceOK?: boolean): string {
    let c = this.GetNext(); this.i += c.length;
    if (this.i <= this.string.length) {
      if (c === '\\') {
        c += this.GetCS();
      } else if (c === '{' && braceOK) {
        this.i--;
        c = this.GetArgument(name).trim();
      }
      if (this.contains('delimiter', c)) {
        return this.convertDelimiter(c);
      }
    }
    // @test MissingOrUnrecognizedDelim1, MissingOrUnrecognizedDelim2
    throw new TexError('MissingOrUnrecognizedDelim',
                        'Missing or unrecognized delimiter for %1', this.currentCS);
  }

  /**
   * Get a dimension (including its units).
   * @param {string} name Name of the current control sequence.
   * @return {string} The dimension string.
   */
  public GetDimen(name: string): string {
    if (this.GetNext() === '{') {
      let dimen = this.GetArgument(name);
      let [value, unit] = ParseUtil.matchDimen(dimen);
      if (value) {
        // @test Raise In Line, Lower 2, (Raise|Lower) Negative
        return value + unit;
      }
    } else {
      // @test Above, Raise, Lower, Modulo, Above With Delims
      let dimen = this.string.slice(this.i);
      let [value, unit, length] = ParseUtil.matchDimen(dimen, true);
      if (value) {
        this.i += length;
        return value + unit;
      }
    }
    // @test MissingDimOrUnits
    throw new TexError('MissingDimOrUnits',
                        'Missing dimension or its units for %1', this.currentCS);
  }

  /**
   *  Get everything up to the given control sequence (token)
   * @param {string} name Name of the current control sequence.
   * @param {string} token The element until where to parse.
   * @return {string} The text between the current position and the given token.
   */
  public GetUpTo(_name: string, token: string): string {
    while (this.nextIsSpace()) {
      this.i++;
    }
    let j = this.i;
    let parens = 0;
    while (this.i < this.string.length) {
      let k = this.i;
      let c = this.GetNext(); this.i += c.length;
      switch (c) {
      case '\\':  c += this.GetCS(); break;
      case '{':   parens++; break;
      case '}':
        if (parens === 0) {
          // @test ExtraCloseLooking2
          throw new TexError('ExtraCloseLooking',
                              'Extra close brace while looking for %1', token);
        }
        parens--;
        break;
      }
      if (parens === 0 && c === token) {
        return this.string.slice(j, k);
      }
    }
    // @test TokenNotFoundForCommand
    throw new TexError('TokenNotFoundForCommand',
                        'Could not find %1 for %2', token, this.currentCS);
  }

  /**
   * Parse the arguments of a control sequence in a new parser instance.
   * @param {string} name Name of the current control sequence.
   * @return {MmlNode} The parsed node.
   */
  public ParseArg(name: string): MmlNode  {
    return new TexParser(this.GetArgument(name), this.stack.env,
                         this.configuration).mml();
  }

  /**
   * Parses a given string up to a given token in a new parser instance.
   * @param {string} name Name of the current control sequence.
   * @param {string} token A Token at which to end parsing.
   * @return {MmlNode} The parsed node.
   */
  public ParseUpTo(name: string, token: string): MmlNode {
    return new TexParser(this.GetUpTo(name, token), this.stack.env,
                         this.configuration).mml();
  }


  /**
   * Get a delimiter or empty argument
   * @param {string} name Name of the current control sequence.
   * @return {string} The delimiter.
   */
  public GetDelimiterArg(name: string): string {
    let c = ParseUtil.trimSpaces(this.GetArgument(name));
    if (c === '') {
      return null;
    }
    if (this.contains('delimiter', c)) {
      return c;
    }
    // @test MissingOrUnrecognizedDelim
    throw new TexError('MissingOrUnrecognizedDelim',
                        'Missing or unrecognized delimiter for %1', this.currentCS);
  }

  /**
   * @return {boolean} True if a star follows the control sequence name.
   */
  public GetStar(): boolean {
    let star = (this.GetNext() === '*');
    if (star) {
      this.i++;
    }
    return star;
  }


  /**
   * Convenience method to create nodes with the node factory of the current
   * configuration.
   * @param {string} kind The kind of node to create.
   * @param {any[]} ...rest The remaining arguments for the creation method.
   * @return {MmlNode} The newly created node.
   */
  public create(kind: string, ...rest: any[]): MmlNode {
    return this.configuration.nodeFactory.create(kind, ...rest);
  }


}