site/node_modules/mathjax-full/ts/input/tex/ams/AmsMethods.ts

/*************************************************************
 *
 *  Copyright (c) 2018-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 AMS Parse methods.
 *
 * @author v.sorge@mathjax.org (Volker Sorge)
 */


import {StackItem} from '../StackItem.js';
import {ParseMethod} from '../Types.js';
import ParseUtil from '../ParseUtil.js';
import ParseMethods from '../ParseMethods.js';
import NodeUtil from '../NodeUtil.js';
import {TexConstant} from '../TexConstants.js';
import TexParser from '../TexParser.js';
import TexError from '../TexError.js';
import {Macro} from '../Symbol.js';
import {CommandMap} from '../SymbolMap.js';
import {ArrayItem} from '../base/BaseItems.js';
import {FlalignItem} from './AmsItems.js';
import BaseMethods from '../base/BaseMethods.js';
import {TEXCLASS} from '../../../core/MmlTree/MmlNode.js';
import {MmlMunderover} from '../../../core/MmlTree/MmlNodes/munderover.js';
import {MmlNode, AbstractMmlTokenNode} from '../../../core/MmlTree/MmlNode.js';


// Namespace
export const AmsMethods: Record<string, ParseMethod> = {};


/**
 * Handle AMS array environments.
 * @param {TexParser} parser The calling parser.
 * @param {StackItem} begin The opening stackitem.
 * @param {boolean} numbered Environment numbered.
 * @param {boolean} taggable Environment taggable (e.g., align* is taggable,
 *     split is not).
 * @param {string} align Column alignment.
 * @param {string} spacing Column spacing.
 * @param {string} style Display style indicator.
 */
AmsMethods.AmsEqnArray = function(parser: TexParser, begin: StackItem,
                                      numbered: boolean, taggable: boolean,
                                      align: string, spacing: string,
                                      style: string) {
  // @test Aligned, Gathered
  const args = parser.GetBrackets('\\begin{' + begin.getName() + '}');
  const array = BaseMethods.EqnArray(parser, begin, numbered, taggable, align, spacing, style);
  return ParseUtil.setArrayAlign(array as ArrayItem, args);
};


/**
 * Handle AMS  alignat environments.
 * @param {TexParser} parser The calling parser.
 * @param {StackItem} begin The opening stackitem.
 * @param {boolean} numbered Environment numbered.
 * @param {boolean} taggable Environment taggable (e.g., align* is taggable,
 *     split is not).
 */
AmsMethods.AlignAt = function(parser: TexParser, begin: StackItem,
                              numbered: boolean, taggable: boolean) {
  const name = begin.getName();
  let n, valign, align = '', spacing = [];
  if (!taggable) {
    // @test Alignedat
    valign = parser.GetBrackets('\\begin{' + name + '}');
  }
  n = parser.GetArgument('\\begin{' + name + '}');
  if (n.match(/[^0-9]/)) {
    // @test PositiveIntegerArg
    throw new TexError('PositiveIntegerArg',
                        'Argument to %1 must me a positive integer',
                        '\\begin{' + name + '}');
  }
  let count = parseInt(n, 10);
  while (count > 0) {
    align  += 'rl';
    spacing.push('0em 0em');
    count--;
  }
  let spaceStr = spacing.join(' ');
  if (taggable) {
    // @test Alignat, Alignat Star
    return AmsMethods.EqnArray(parser, begin, numbered, taggable, align, spaceStr);
  }
  // @test Alignedat
  let array = AmsMethods.EqnArray(parser, begin, numbered, taggable, align, spaceStr);
  return ParseUtil.setArrayAlign(array as ArrayItem, valign);
};


/**
 * Implements multline environment (mostly handled through STACKITEM below)
 * @param {TexParser} parser The calling parser.
 * @param {StackItem} begin The opening stackitem.
 * @param {boolean} numbered Environment numbered.
 */
AmsMethods.Multline = function (parser: TexParser, begin: StackItem, numbered: boolean) {
  // @test Shove*, Multline
  parser.Push(begin);
  ParseUtil.checkEqnEnv(parser);
  const item = parser.itemFactory.create('multline', numbered, parser.stack) as ArrayItem;
  item.arraydef = {
    displaystyle: true,
    rowspacing: '.5em',
    columnspacing: '100%',
    width: parser.options.ams['multlineWidth'],
    side: parser.options['tagSide'],
    minlabelspacing: parser.options['tagIndent'],
    framespacing: parser.options.ams['multlineIndent'] + ' 0',
    frame: '',   // Use frame spacing with no actual frame
    'data-width-includes-label': true // take label space out of 100% width
  };
  return item;
};


/**
 * Generate an align at environment.
 * @param {TexParser} parser The current TeX parser.
 * @param {StackItem} begin The begin stackitem.
 * @param {boolean} numbered Is this a numbered array.
 * @param {boolean} padded Is it padded.
 */
AmsMethods.XalignAt = function(parser: TexParser, begin: StackItem,
                                  numbered: boolean, padded: boolean) {
  let n = parser.GetArgument('\\begin{' + begin.getName() + '}');
  if (n.match(/[^0-9]/)) {
    throw new TexError('PositiveIntegerArg',
                       'Argument to %1 must me a positive integer',
                       '\\begin{' + begin.getName() + '}');
  }
  const align = (padded ? 'crl' : 'rlc');
  const width = (padded ? 'fit auto auto' : 'auto auto fit');
  const item = AmsMethods.FlalignArray(parser, begin, numbered, padded, false, align, width, true) as FlalignItem;
  item.setProperty('xalignat', 2 * parseInt(n));
  return item;
};


/**
 * Generate an flalign environment.
 * @param {TexParser} parser The current TeX parser.
 * @param {StackItem} begin The begin stackitem.
 * @param {boolean} numbered Is this a numbered array.
 * @param {boolean} padded Is it padded.
 * @param {boolean} center Is it centered.
 * @param {string} align The horizontal alignment for columns
 * @param {string} width The column widths of the table
 * @param {boolean} zeroWidthLabel True if the label should be in llap/rlap
 */
AmsMethods.FlalignArray = function(parser: TexParser, begin: StackItem, numbered: boolean,
                                  padded: boolean, center: boolean, align: string,
                                  width: string, zeroWidthLabel: boolean = false) {
  parser.Push(begin);
  ParseUtil.checkEqnEnv(parser);
  align = align
    .split('')
    .join(' ')
    .replace(/r/g, 'right')
    .replace(/l/g, 'left')
    .replace(/c/g, 'center');
  const item = parser.itemFactory.create(
    'flalign', begin.getName(), numbered, padded, center, parser.stack) as FlalignItem;
  item.arraydef = {
    width: '100%',
    displaystyle: true,
    columnalign: align,
    columnspacing: '0em',
    columnwidth: width,
    rowspacing: '3pt',
    side: parser.options['tagSide'],
    minlabelspacing: (zeroWidthLabel ? '0' : parser.options['tagIndent']),
    'data-width-includes-label': true,
  };
  item.setProperty('zeroWidthLabel', zeroWidthLabel);
  return item;
};


export const NEW_OPS = 'ams-declare-ops';

/**
 * Handle DeclareMathOperator.
 * @param {TexParser} parser The calling parser.
 * @param {string} name The macro name.
 */
AmsMethods.HandleDeclareOp =  function (parser: TexParser, name: string) {
  let star = (parser.GetStar() ? '*' : '');
  let cs = ParseUtil.trimSpaces(parser.GetArgument(name));
  if (cs.charAt(0) === '\\') {
    cs = cs.substr(1);
  }
  let op = parser.GetArgument(name);
  (parser.configuration.handlers.retrieve(NEW_OPS) as CommandMap).
    add(cs, new Macro(cs, AmsMethods.Macro, [`\\operatorname${star}{${op}}`]));
};


/**
 * Handle operatorname.
 * @param {TexParser} parser The calling parser.
 * @param {string} name The macro name.
 */
AmsMethods.HandleOperatorName = function(parser: TexParser, name: string) {
  // @test Operatorname
  const star = parser.GetStar();
  //
  //  Parse the argument using operator letters and grouping multiple letters.
  //
  let op = ParseUtil.trimSpaces(parser.GetArgument(name));
  let mml = new TexParser(op, {
    ...parser.stack.env,
    font: TexConstant.Variant.NORMAL,
    multiLetterIdentifiers: /^[-*a-z]+/i as any,
    operatorLetters: true
  }, parser.configuration).mml();
  //
  //  If we get something other than a single mi, wrap in a TeXAtom.
  //
  if (!mml.isKind('mi')) {
    mml = parser.create('node', 'TeXAtom', [mml]);
  }
  //
  //  Mark the limit properties and the TeX class.
  //
  NodeUtil.setProperties(mml, {movesupsub: star, movablelimits: true, texClass: TEXCLASS.OP});
  //
  //  Skip a following \limits macro if not a starred operator
  //
  if (!star) {
    const c = parser.GetNext(), i = parser.i;
    if (c === '\\' && ++parser.i && parser.GetCS() !== 'limits') {
      parser.i = i;
    }
  }
  //
  parser.Push(mml);
};

/**
 * Handle sideset.
 * @param {TexParser} parser The calling parser.
 * @param {string} name The macro name.
 */
AmsMethods.SideSet = function (parser: TexParser, name: string) {
  //
  //  Get the pre- and post-scripts, and any extra material from the arguments
  //
  const [preScripts, preRest] = splitSideSet(parser.ParseArg(name));
  const [postScripts, postRest] = splitSideSet(parser.ParseArg(name));
  const base = parser.ParseArg(name);
  let mml = base;
  //
  //  If there are pre-scripts...
  //
  if (preScripts) {
    //
    //  If there is other material...
    //
    if (preRest) {
      //
      //  Replace the empty base of the prescripts with a phantom element of the
      //    original base, with width 0 (but still of the correct height and depth).
      //    so the scripts will be at the right heights.
      //
      preScripts.replaceChild(
        parser.create('node', 'mphantom', [
          parser.create('node', 'mpadded', [ParseUtil.copyNode(base, parser)], {width: 0})
        ]),
        NodeUtil.getChildAt(preScripts, 0)
      );
    } else {
      //
      //  If there is no extra meterial, make a mmultiscripts element
      //
      mml = parser.create('node', 'mmultiscripts', [base]);
      //
      //  Add any postscripts
      //
      if (postScripts) {
        NodeUtil.appendChildren(mml, [
          NodeUtil.getChildAt(postScripts, 1) || parser.create('node', 'none'),
          NodeUtil.getChildAt(postScripts, 2) || parser.create('node', 'none')
        ]);
      }
      //
      //  Add the prescripts (left aligned)
      //
      NodeUtil.setProperty(mml, 'scriptalign', 'left');
      NodeUtil.appendChildren(mml, [
        parser.create('node', 'mprescripts'),
        NodeUtil.getChildAt(preScripts, 1) || parser.create('node', 'none'),
        NodeUtil.getChildAt(preScripts, 2) || parser.create('node', 'none')
      ]);
    }
  }
  //
  //  If there are postscripts and we didn't make a mmultiscript element above...
  //
  if (postScripts && mml === base) {
    //
    //  Replace the emtpy base with actual base, and use that as the mml
    //
    postScripts.replaceChild(base, NodeUtil.getChildAt(postScripts, 0));
    mml = postScripts;
  }
  //
  //  Put the needed pieces into a TeXAtom of class OP.
  //  Note that the postScripts are in the mml element,
  //    either as part of the mmultiscripts node, or the
  //    msubsup with the base inserted into it.
  //
  const mrow = parser.create('node', 'TeXAtom', [], {texClass: TEXCLASS.OP, movesupsub: true, movablelimits: true});
  if (preRest) {
    preScripts && mrow.appendChild(preScripts);
    mrow.appendChild(preRest);
  }
  mrow.appendChild(mml);
  postRest && mrow.appendChild(postRest);
  parser.Push(mrow);
};

/**
 * Utility for breaking the \sideset scripts from any other material.
 * @param {MmlNode} mml The node to check.
 * @return {[MmlNode, MmlNode]} The msubsup with the scripts together with any extra nodes.
 */
function splitSideSet(mml: MmlNode): [MmlNode, MmlNode] {
    if (!mml || (mml.isInferred && mml.childNodes.length === 0)) return [null, null];
    if (mml.isKind('msubsup') && checkSideSetBase(mml)) return [mml, null];
    const child = NodeUtil.getChildAt(mml, 0);
    if (!(mml.isInferred && child && checkSideSetBase(child))) return [null, mml];
    mml.childNodes.splice(0, 1); // remove first child
    return [child, mml];
}

/**
 * Utility for checking if a \sideset argument has scripts with an empty base.
 * @param {MmlNode} mml The node to check.
 * @return {boolean} True if the base is not and empty mi element.
 */
function checkSideSetBase(mml: MmlNode): boolean {
  const base = mml.childNodes[0];
  return base && base.isKind('mi') && (base as AbstractMmlTokenNode).getText() === '';
}


/**
 * Handle extra letters in \operatorname (- and *), default to normal otherwise.
 * @param {TexParser} parser The calling parser.
 * @param {string} c The letter being checked
 */
AmsMethods.operatorLetter = function (parser: TexParser, c: string) {
  return parser.stack.env.operatorLetters ? ParseMethods.variable(parser, c) : false;
};


/**
 * Handle multi integral signs.
 * @param {TexParser} parser The calling parser.
 * @param {string} name The macro name.
 * @param {string} integral The actual integral sign.
 */
AmsMethods.MultiIntegral = function(parser: TexParser, name: string,
                                    integral: string) {
  let next = parser.GetNext();
  if (next === '\\') {
    // @test MultiInt with Command
    let i = parser.i;
    next = parser.GetArgument(name);
    parser.i = i;
    if (next === '\\limits') {
      if (name === '\\idotsint') {
       // @test MultiInt with Limits
        integral = '\\!\\!\\mathop{\\,\\,' + integral + '}';
      }
      else {
        // Question: This is not used anymore?
        integral = '\\!\\!\\!\\mathop{\\,\\,\\,' + integral + '}';
      }
    }
  }
  // @test MultiInt, MultiInt in Context
  parser.string = integral + ' ' + parser.string.slice(parser.i);
  parser.i = 0;
};


/**
 *  Handle stretchable arrows.
 * @param {TexParser} parser The calling parser.
 * @param {string} name The macro name.
 * @param {number} chr The arrow character in hex code.
 * @param {number} l Left width.
 * @param {number} r Right width.
 */
AmsMethods.xArrow = function(parser: TexParser, name: string,
                             chr: number, l: number, r: number) {
  let def = {width: '+' + ParseUtil.Em((l + r) / 18), lspace: ParseUtil.Em(l / 18)};
  let bot = parser.GetBrackets(name);
  let first = parser.ParseArg(name);
  let dstrut = parser.create('node', 'mspace', [], {depth: '.25em'});
  let arrow = parser.create('token',
    'mo', {stretchy: true, texClass: TEXCLASS.REL}, String.fromCodePoint(chr));
  arrow = parser.create('node', 'mstyle', [arrow], {scriptlevel: 0});
  let mml = parser.create('node', 'munderover', [arrow]) as MmlMunderover;
  let mpadded = parser.create('node', 'mpadded', [first, dstrut], def);
  NodeUtil.setAttribute(mpadded, 'voffset', '-.2em');
  NodeUtil.setAttribute(mpadded, 'height', '-.2em');
  NodeUtil.setChild(mml, mml.over, mpadded);
  if (bot) {
    // @test Above Below Left Arrow, Above Below Right Arrow
    let bottom = new TexParser(bot, parser.stack.env, parser.configuration).mml();
    let bstrut = parser.create('node', 'mspace', [], {height: '.75em'});
    mpadded = parser.create('node', 'mpadded', [bottom, bstrut], def);
    NodeUtil.setAttribute(mpadded, 'voffset', '.15em');
    NodeUtil.setAttribute(mpadded, 'depth', '-.15em');
    NodeUtil.setChild(mml, mml.under, mpadded);
  }
  // @test Above Left Arrow, Above Right Arrow, Above Left Arrow in Context,
  //       Above Right Arrow in Context
  NodeUtil.setProperty(mml, 'subsupOK', true);
  parser.Push(mml);
};


/**
 * Record presence of \shoveleft and \shoveright
 * @param {TexParser} parser The calling parser.
 * @param {string} name The macro name.
 * @param {string} shove The shove value.
 */
AmsMethods.HandleShove = function(parser: TexParser, _name: string,
                                  shove: string) {
  let top = parser.stack.Top();
  // @test Shove (Left|Right) (Top|Middle|Bottom)
  if (top.kind !== 'multline') {
    // @test Shove Error Environment
    throw new TexError('CommandOnlyAllowedInEnv',
                        '%1 only allowed in %2 environment',
                        parser.currentCS, 'multline');
  }
  if (top.Size()) {
    // @test Shove Error (Top|Middle|Bottom)
    throw new TexError('CommandAtTheBeginingOfLine',
                        '%1 must come at the beginning of the line', parser.currentCS);
  }
  top.setProperty('shove', shove);
};


/**
 * Handle \cfrac
 * @param {TexParser} parser The calling parser.
 * @param {string} name The macro name.
 */
AmsMethods.CFrac = function(parser: TexParser, name: string) {
  let lr  = ParseUtil.trimSpaces(parser.GetBrackets(name, ''));
  let num = parser.GetArgument(name);
  let den = parser.GetArgument(name);
  let lrMap: {[key: string]: string} = {
    l: TexConstant.Align.LEFT, r: TexConstant.Align.RIGHT, '': ''};
  let numNode = new TexParser('\\strut\\textstyle{' + num + '}',
                              parser.stack.env, parser.configuration).mml();
  let denNode = new TexParser('\\strut\\textstyle{' + den + '}',
                              parser.stack.env, parser.configuration).mml();
  let frac = parser.create('node', 'mfrac', [numNode, denNode]);
  lr = lrMap[lr];
  if (lr == null) {
    // @test Center Fraction Error
    throw new TexError('IllegalAlign', 'Illegal alignment specified in %1', parser.currentCS);
  }
  if (lr) {
    // @test Right Fraction, Left Fraction
    NodeUtil.setProperties(frac, {numalign: lr, denomalign: lr});
  }
  // @test Center Fraction
  parser.Push(frac);
};


/**
 * Implement AMS generalized fraction.
 * @param {TexParser} parser The calling parser.
 * @param {string} name The macro name.
 * @param {string} left Left delimiter.
 * @param {string} right Right delimiter.
 * @param {string} thick Line thickness.
 * @param {string} style Math style.
 */
AmsMethods.Genfrac = function(parser: TexParser, name: string, left: string,
                              right: string, thick: string, style: string) {
  if (left  == null) { // @test Genfrac
    left = parser.GetDelimiterArg(name);
  }
  if (right == null) { // @test Genfrac
    right = parser.GetDelimiterArg(name);
  }
  if (thick == null) { // @test Genfrac
    thick = parser.GetArgument(name);
  }
  if (style == null) { // @test Genfrac
    style = ParseUtil.trimSpaces(parser.GetArgument(name));
  }
  let num = parser.ParseArg(name);
  let den = parser.ParseArg(name);
  let frac = parser.create('node', 'mfrac', [num, den]);
  if (thick !== '') {
    // @test Normal Binomial, Text Binomial, Display Binomial
    NodeUtil.setAttribute(frac, 'linethickness', thick);
  }
  if (left || right) {
    // @test Normal Binomial, Text Binomial, Display Binomial
    NodeUtil.setProperty(frac, 'withDelims', true);
    frac = ParseUtil.fixedFence(parser.configuration, left, frac, right);
  }
  if (style !== '') {
    let styleDigit = parseInt(style, 10);
    let styleAlpha = ['D', 'T', 'S', 'SS'][styleDigit];
    if (styleAlpha == null) {
      // @test Genfrac Error
      throw new TexError('BadMathStyleFor', 'Bad math style for %1', parser.currentCS);
    }
    frac = parser.create('node', 'mstyle', [frac]);
    if (styleAlpha === 'D') {
      // @test Display Fraction, Display Sub Fraction, Display Binomial,
      //       Display Sub Binomial
      NodeUtil.setProperties(frac, {displaystyle: true, scriptlevel: 0});
    }
    else {
      // @test Text Fraction, Text Sub Fraction, Text Binomial,
      //       Text Sub Binomial
      NodeUtil.setProperties(frac, {displaystyle: false,
                                      scriptlevel: styleDigit - 1});
    }
  }
  // @test Text Fraction, Normal Sub Binomial, Normal Binomial
  parser.Push(frac);
};



/**
 * Add the tag to the environment (to be added to the table row later).
 * @param {TexParser} parser The calling parser.
 * @param {string} name The macro name.
 */
AmsMethods.HandleTag = function(parser: TexParser, name: string) {
  if (!parser.tags.currentTag.taggable && parser.tags.env) {
    // @test Illegal Tag Error
    throw new TexError('CommandNotAllowedInEnv',
                        '%1 not allowed in %2 environment',
                        parser.currentCS, parser.tags.env);
  }
  if (parser.tags.currentTag.tag) {
    // @test Double Tag Error
    throw new TexError('MultipleCommand', 'Multiple %1', parser.currentCS);
  }
  let star = parser.GetStar();
  let tagId = ParseUtil.trimSpaces(parser.GetArgument(name));
  parser.tags.tag(tagId, star);
};


AmsMethods.HandleNoTag = BaseMethods.HandleNoTag;

AmsMethods.HandleRef = BaseMethods.HandleRef;

AmsMethods.Macro = BaseMethods.Macro;

AmsMethods.Accent = BaseMethods.Accent;

AmsMethods.Tilde = BaseMethods.Tilde;

AmsMethods.Array = BaseMethods.Array;

AmsMethods.Spacer = BaseMethods.Spacer;

AmsMethods.NamedOp = BaseMethods.NamedOp;

AmsMethods.EqnArray = BaseMethods.EqnArray;

AmsMethods.Equation = BaseMethods.Equation;