katex 0.12.0 → 0.13.3

package/src/environments/array.js

@@ -2,6 +2,7 @@
 import buildCommon from "../buildCommon";
 import Style from "../Style";
 import defineEnvironment from "../defineEnvironment";
+import {parseCD} from "./cd";
 import defineFunction from "../defineFunction";
 import mathMLTree from "../mathMLTree";
 import ParseError from "../ParseError";
@@ -27,8 +28,9 @@ export type AlignSpec = { type: "separator", separator: string } | {
 };
 
 // Type to indicate column separation in MathML
-export type ColSeparationType = "align" | "alignat" | "small";
+export type ColSeparationType = "align" | "alignat" | "gather" | "small" | "CD";
 
+// Helper functions
 function getHLines(parser: Parser): boolean[] {
     // Return an array. The array length = number of hlines.
     // Each element in the array tells if the line is dashed.
@@ -44,6 +46,14 @@ function getHLines(parser: Parser): boolean[] {
     return hlineInfo;
 }
 
+const validateAmsEnvironmentContext = context => {
+    const settings = context.parser.settings;
+    if (!settings.displayMode) {
+        throw new ParseError(`{${context.envName}} can be used only in` +
+            ` display mode.`);
+    }
+};
+
 /**
  * Parse the body of the environment, with rows delimited by \\ and
  * columns delimited by &, and create a nested list in row-major order
@@ -52,18 +62,37 @@ function getHLines(parser: Parser): boolean[] {
  */
 function parseArray(
     parser: Parser,
-    {hskipBeforeAndAfter, addJot, cols, arraystretch, colSeparationType}: {|
+    {
+        hskipBeforeAndAfter,
+        addJot,
+        cols,
+        arraystretch,
+        colSeparationType,
+        addEqnNum,
+        singleRow,
+        emptySingleRow,
+        maxNumCols,
+        leqno,
+    }: {|
         hskipBeforeAndAfter?: boolean,
         addJot?: boolean,
         cols?: AlignSpec[],
         arraystretch?: number,
         colSeparationType?: ColSeparationType,
+        addEqnNum?: boolean,
+        singleRow?: boolean,
+        emptySingleRow?: boolean,
+        maxNumCols?: number,
+        leqno?: boolean,
     |},
     style: StyleStr,
 ): ParseNode<"array"> {
-    // Parse body of array with \\ temporarily mapped to \cr
     parser.gullet.beginGroup();
-    parser.gullet.macros.set("\\\\", "\\cr");
+    if (!singleRow) {
+        // \cr is equivalent to \\ without the optional size argument (see below)
+        // TODO: provide helpful error when \cr is used outside array environment
+        parser.gullet.macros.set("\\cr", "\\\\\\relax");
+    }
 
     // Get current arraystretch if it's not set by the environment
     if (!arraystretch) {
@@ -92,7 +121,7 @@ function parseArray(
 
     while (true) {  // eslint-disable-line no-constant-condition
         // Parse each cell in its own group (namespace)
-        let cell = parser.parseExpression(false, "\\cr");
+        let cell = parser.parseExpression(false, singleRow ? "\\end" : "\\\\");
         parser.gullet.endGroup();
         parser.gullet.beginGroup();
 
@@ -112,22 +141,44 @@ function parseArray(
         row.push(cell);
         const next = parser.fetch().text;
         if (next === "&") {
+            if (maxNumCols && row.length === maxNumCols) {
+                if (singleRow || colSeparationType) {
+                    // {equation} or {split}
+                    throw new ParseError("Too many tab characters: &",
+                                        parser.nextToken);
+                } else {
+                    // {array} environment
+                    parser.settings.reportNonstrict("textEnv", "Too few columns " +
+                    "specified in the {array} column argument.");
+                }
+            }
             parser.consume();
         } else if (next === "\\end") {
             // Arrays terminate newlines with `\crcr` which consumes a `\cr` if
-            // the last line is empty.
+            // the last line is empty.  However, AMS environments keep the
+            // empty row if it's the only one.
             // NOTE: Currently, `cell` is the last item added into `row`.
             if (row.length === 1 && cell.type === "styling" &&
-                cell.body[0].body.length === 0) {
+                cell.body[0].body.length === 0 &&
+                (body.length > 1 || !emptySingleRow)) {
                 body.pop();
             }
             if (hLinesBeforeRow.length < body.length + 1) {
                 hLinesBeforeRow.push([]);
             }
             break;
-        } else if (next === "\\cr") {
-            const cr = assertNodeType(parser.parseFunction(), "cr");
-            rowGaps.push(cr.size);
+        } else if (next === "\\\\") {
+            parser.consume();
+            let size;
+            // \def\Let@{\let\\\math@cr}
+            // \def\math@cr{...\math@cr@}
+            // \def\math@cr@{\new@ifnextchar[\math@cr@@{\math@cr@@[\z@]}}
+            // \def\math@cr@@[#1]{...\math@cr@@@...}
+            // \def\math@cr@@@{\cr}
+            if (parser.gullet.future().text !== " ") {
+                size = parser.parseSizeGroup(true);
+            }
+            rowGaps.push(size ? size.value : null);
 
             // check for \hline(s) following the row separator
             hLinesBeforeRow.push(getHLines(parser));
@@ -142,7 +193,7 @@ function parseArray(
 
     // End cell group
     parser.gullet.endGroup();
-    // End array group defining \\
+    // End array group defining \cr
     parser.gullet.endGroup();
 
     return {
@@ -156,6 +207,8 @@ function parseArray(
         hskipBeforeAndAfter,
         hLinesBeforeRow,
         colSeparationType,
+        addEqnNum,
+        leqno,
     };
 }
 
@@ -206,7 +259,9 @@ const htmlBuilder: HtmlBuilder<"array"> = function(group, options) {
     }
 
     // Vertical spacing
-    const baselineskip = 12 * pt; // see size10.clo
+    const baselineskip = group.colSeparationType === "CD"
+      ? calculateSize({number: 3, unit: "ex"}, options)
+      : 12 * pt; // see size10.clo
     // Default \jot from ltmath.dtx
     // TODO(edemaine): allow overriding \jot via \setlength (#687)
     const jot = 3 * pt;
@@ -283,6 +338,21 @@ const htmlBuilder: HtmlBuilder<"array"> = function(group, options) {
     const cols = [];
     let colSep;
     let colDescrNum;
+
+    const eqnNumSpans = [];
+    if (group.addEqnNum) {
+        // An environment with automatic equation numbers.
+        // Create node(s) that will trigger CSS counter increment.
+        for (r = 0; r < nr; ++r) {
+            const rw = body[r];
+            const shift = rw.pos - offset;
+            const eqnTag = buildCommon.makeSpan(["eqn-num"], [], options);
+            eqnTag.depth = rw.depth;
+            eqnTag.height = rw.height;
+            eqnNumSpans.push({type: "elem", elem: eqnTag, shift});
+        }
+    }
+
     for (c = 0, colDescrNum = 0;
          // Continue while either there are more columns or more column
          // descriptions, so trailing separators don't get lost.
@@ -393,7 +463,16 @@ const htmlBuilder: HtmlBuilder<"array"> = function(group, options) {
         }, options);
     }
 
-    return buildCommon.makeSpan(["mord"], [body], options);
+    if (!group.addEqnNum) {
+        return buildCommon.makeSpan(["mord"], [body], options);
+    } else {
+        let eqnNumCol = buildCommon.makeVList({
+            positionType: "individualShift",
+            children: eqnNumSpans,
+        }, options);
+        eqnNumCol = buildCommon.makeSpan(["tag"], [eqnNumCol], options);
+        return buildCommon.makeFragment([body, eqnNumCol]);
+    }
 };
 
 const alignMap = {
@@ -403,14 +482,28 @@ const alignMap = {
 };
 
 const mathmlBuilder: MathMLBuilder<"array"> = function(group, options) {
-    let table = new mathMLTree.MathNode(
-        "mtable", group.body.map(function(row) {
-            return new mathMLTree.MathNode(
-                "mtr", row.map(function(cell) {
-                    return new mathMLTree.MathNode(
-                        "mtd", [mml.buildGroup(cell, options)]);
-                }));
-        }));
+    const tbl = [];
+    const glue = new mathMLTree.MathNode("mtd", [], ["mtr-glue"]);
+    const tag = new mathMLTree.MathNode("mtd", [], ["mml-eqn-num"]);
+    for (let i = 0; i < group.body.length; i++) {
+        const rw = group.body[i];
+        const row = [];
+        for (let j = 0; j < rw.length; j++) {
+            row.push(new mathMLTree.MathNode("mtd",
+                [mml.buildGroup(rw[j], options)]));
+        }
+        if (group.addEqnNum) {
+            row.unshift(glue);
+            row.push(glue);
+            if (group.leqno) {
+                row.unshift(tag);
+            } else {
+                row.push(tag);
+            }
+        }
+        tbl.push(new mathMLTree.MathNode("mtr", row));
+    }
+    let table = new mathMLTree.MathNode("mtable", tbl);
 
     // Set column alignment, row spacing, column spacing, and
     // array lines by setting attributes on the table element.
@@ -428,7 +521,7 @@ const mathmlBuilder: MathMLBuilder<"array"> = function(group, options) {
     const gap = (group.arraystretch === 0.5)
         ? 0.1  // {smallmatrix}, {subarray}
         : 0.16 + group.arraystretch - 1 + (group.addJot ? 0.09 : 0);
-    table.setAttribute("rowspacing", gap + "em");
+    table.setAttribute("rowspacing", gap.toFixed(4) + "em");
 
     // MathML table lines go only between cells.
     // To place a line on an edge we'll use <menclose>, if necessary.
@@ -487,10 +580,13 @@ const mathmlBuilder: MathMLBuilder<"array"> = function(group, options) {
             spacing += i % 2 ? "0em " : "1em ";
         }
         table.setAttribute("columnspacing", spacing.trim());
-    } else if (group.colSeparationType === "alignat") {
+    } else if (group.colSeparationType === "alignat" ||
+        group.colSeparationType === "gather") {
         table.setAttribute("columnspacing", "0em");
     } else if (group.colSeparationType === "small") {
         table.setAttribute("columnspacing", "0.2778em");
+    } else if (group.colSeparationType === "CD") {
+        table.setAttribute("columnspacing", "0.5em");
     } else {
         table.setAttribute("columnspacing", "1em");
     }
@@ -526,10 +622,25 @@ const mathmlBuilder: MathMLBuilder<"array"> = function(group, options) {
     return table;
 };
 
-// Convenience function for aligned and alignedat environments.
+// Convenience function for align, align*, aligned, alignat, alignat*, alignedat.
 const alignedHandler = function(context, args) {
+    if (context.envName.indexOf("ed") === -1) {
+        validateAmsEnvironmentContext(context);
+    }
     const cols = [];
-    const res = parseArray(context.parser, {cols, addJot: true}, "display");
+    const separationType = context.envName.indexOf("at") > -1 ? "alignat" : "align";
+    const res = parseArray(context.parser,
+        {
+            cols,
+            addJot: true,
+            addEqnNum: context.envName === "align" || context.envName === "alignat",
+            emptySingleRow: true,
+            colSeparationType: separationType,
+            maxNumCols: context.envName === "split" ? 2 : undefined,
+            leqno: context.parser.settings.leqno,
+        },
+        "display"
+    );
 
     // Determining number of columns.
     // 1. If the first argument is given, we use it as a number of columns,
@@ -641,6 +752,7 @@ defineEnvironment({
         const res = {
             cols,
             hskipBeforeAndAfter: true, // \@preamble in lttab.dtx
+            maxNumCols: cols.length,
         };
         return parseArray(context.parser, res, dCellStyle(context.envName));
     },
@@ -650,6 +762,8 @@ defineEnvironment({
 
 // The matrix environments of amsmath builds on the array environment
 // of LaTeX, which is discussed above.
+// The mathtools package adds starred versions of the same environments.
+// These have an optional argument to choose left|center|right justification.
 defineEnvironment({
     type: "array",
     names: [
@@ -659,6 +773,12 @@ defineEnvironment({
         "Bmatrix",
         "vmatrix",
         "Vmatrix",
+        "matrix*",
+        "pmatrix*",
+        "bmatrix*",
+        "Bmatrix*",
+        "vmatrix*",
+        "Vmatrix*",
     ],
     props: {
         numArgs: 0,
@@ -671,11 +791,38 @@ defineEnvironment({
             "Bmatrix": ["\\{", "\\}"],
             "vmatrix": ["|", "|"],
             "Vmatrix": ["\\Vert", "\\Vert"],
-        }[context.envName];
+        }[context.envName.replace("*", "")];
         // \hskip -\arraycolsep in amsmath
-        const payload = {hskipBeforeAndAfter: false};
+        let colAlign = "c";
+        const payload = {
+            hskipBeforeAndAfter: false,
+            cols: [{type: "align", align: colAlign}],
+        };
+        if (context.envName.charAt(context.envName.length - 1) === "*") {
+            // It's one of the mathtools starred functions.
+            // Parse the optional alignment argument.
+            const parser = context.parser;
+            parser.consumeSpaces();
+            if (parser.fetch().text === "[") {
+                parser.consume();
+                parser.consumeSpaces();
+                colAlign = parser.fetch().text;
+                if ("lcr".indexOf(colAlign) === -1) {
+                    throw new ParseError("Expected l or c or r", parser.nextToken);
+                }
+                parser.consume();
+                parser.consumeSpaces();
+                parser.expect("]");
+                parser.consume();
+                payload.cols = [{type: "align", align: colAlign}];
+            }
+        }
         const res: ParseNode<"array"> =
             parseArray(context.parser, payload, dCellStyle(context.envName));
+        // Populate cols with the correct number of column alignment specs.
+        res.cols = new Array(res.body[0].length).fill(
+            {type: "align", align: colAlign}
+        );
         return delimiters ? {
             type: "leftright",
             mode: context.mode,
@@ -797,13 +944,15 @@ defineEnvironment({
     mathmlBuilder,
 });
 
-// An aligned environment is like the align* environment
-// except it operates within math mode.
+// In the align environment, one uses ampersands, &, to specify number of
+// columns in each row, and to locate spacing between each column.
+// align gets automatic numbering. align* and aligned do not.
+// The alignedat environment can be used in math mode.
 // Note that we assume \nomallineskiplimit to be zero,
 // so that \strut@ is the same as \strut.
 defineEnvironment({
     type: "array",
-    names: ["aligned"],
+    names: ["align", "align*", "aligned", "split"],
     props: {
         numArgs: 0,
     },
@@ -817,17 +966,24 @@ defineEnvironment({
 // and contents are set in \displaystyle.
 defineEnvironment({
     type: "array",
-    names: ["gathered"],
+    names: ["gathered", "gather", "gather*"],
     props: {
         numArgs: 0,
     },
     handler(context) {
+        if (utils.contains(["gather", "gather*"], context.envName)) {
+            validateAmsEnvironmentContext(context);
+        }
         const res = {
             cols: [{
                 type: "align",
                 align: "c",
             }],
             addJot: true,
+            colSeparationType: "gather",
+            addEqnNum: context.envName === "gather",
+            emptySingleRow: true,
+            leqno: context.parser.settings.leqno,
         };
         return parseArray(context.parser, res, "display");
     },
@@ -840,10 +996,7 @@ defineEnvironment({
 // each columns.
 defineEnvironment({
     type: "array",
-    names: ["alignedat"],
-    // One for numbered and for unnumbered;
-    // but, KaTeX doesn't supports math numbering yet,
-    // they make no difference for now.
+    names: ["alignat", "alignat*", "alignedat"],
     props: {
         numArgs: 1,
     },
@@ -852,6 +1005,41 @@ defineEnvironment({
     mathmlBuilder,
 });
 
+defineEnvironment({
+    type: "array",
+    names: ["equation", "equation*"],
+    props: {
+        numArgs: 0,
+    },
+    handler(context) {
+        validateAmsEnvironmentContext(context);
+        const res = {
+            addEqnNum: context.envName === "equation",
+            emptySingleRow: true,
+            singleRow: true,
+            maxNumCols: 1,
+            leqno: context.parser.settings.leqno,
+        };
+        return parseArray(context.parser, res, "display");
+    },
+    htmlBuilder,
+    mathmlBuilder,
+});
+
+defineEnvironment({
+    type: "array",
+    names: ["CD"],
+    props: {
+        numArgs: 0,
+    },
+    handler(context) {
+        validateAmsEnvironmentContext(context);
+        return parseCD(context.parser);
+    },
+    htmlBuilder,
+    mathmlBuilder,
+});
+
 // Catch \hline outside array environment
 defineFunction({
     type: "text", // Doesn't matter what this is.