katex 0.13.24 → 0.15.1

package/src/Parser.js

@@ -150,6 +150,27 @@ export default class Parser {
         }
     }
 
+    /**
+     * Fully parse a separate sequence of tokens as a separate job.
+     * Tokens should be specified in reverse order, as in a MacroDefinition.
+     */
+    subparse(tokens: Token[]): AnyParseNode[] {
+        // Save the next token from the current job.
+        const oldToken = this.nextToken;
+        this.consume();
+
+        // Run the new job, terminating it with an excess '}'
+        this.gullet.pushToken(new Token("}"));
+        this.gullet.pushTokens(tokens);
+        const parse = this.parseExpression(false);
+        this.expect("}");
+
+        // Restore the next token from the current job.
+        this.nextToken = oldToken;
+
+        return parse;
+    }
+
     static endOfExpression: string[] = ["}", "\\endgroup", "\\end", "\\right", "&"];
 
     /**

package/src/Settings.js

@@ -52,23 +52,180 @@ export type TrustContextTypes = {
 export type AnyTrustContext = $Values<TrustContextTypes>;
 export type TrustFunction = (context: AnyTrustContext) => ?boolean;
 
-export type SettingsOptions = {
-    displayMode?: boolean;
-    output?: "html" | "mathml" | "htmlAndMathml";
-    leqno?: boolean;
-    fleqn?: boolean;
-    throwOnError?: boolean;
-    errorColor?: string;
-    macros?: MacroMap;
-    minRuleThickness?: number;
-    colorIsTextColor?: boolean;
-    strict?: boolean | "ignore" | "warn" | "error" | StrictFunction;
-    trust?: boolean | TrustFunction;
-    maxSize?: number;
-    maxExpand?: number;
-    globalGroup?: boolean;
+export type SettingsOptions = $Shape<Settings>;
+
+type EnumType = {| enum: string[] |};
+type Type = "boolean" | "string" | "number" | "object" | "function" | EnumType;
+type Schema = {
+    [$Keys<SettingsOptions>]: {
+        /**
+         * Allowed type(s) of the value.
+         */
+        type: Type | Type[];
+        /**
+         * The default value. If not specified, false for boolean, an empty string
+         * for string, 0 for number, an empty object for object, or the first item
+         * for enum will be used. If multiple types are allowed, the first allowed
+         * type will be used for determining the default value.
+         */
+        default?: any;
+        /**
+         * The description.
+         */
+        description?: string;
+        /**
+         * The function to process the option.
+         */
+        processor?: (any) => any,
+        /**
+         * The command line argument. See Commander.js docs for more information.
+         * If not specified, the name prefixed with -- will be used. Set false not
+         * to add to the CLI.
+         */
+        cli?: string | false;
+        /**
+         * The default value for the CLI.
+         */
+        cliDefault?: any;
+        /**
+         * The description for the CLI. If not specified, the description for the
+         * option will be used.
+         */
+        cliDescription?: string;
+        /**
+         * The custom argument processor for the CLI. See Commander.js docs for
+         * more information.
+         */
+        cliProcessor?: (any, any) => any;
+    };
+};
+
+// TODO: automatically generate documentation
+// TODO: check all properties on Settings exist
+// TODO: check the type of a property on Settings matches
+export const SETTINGS_SCHEMA: Schema = {
+    displayMode: {
+        type: "boolean",
+        description: "Render math in display mode, which puts the math in " +
+            "display style (so \\int and \\sum are large, for example), and " +
+            "centers the math on the page on its own line.",
+        cli: "-d, --display-mode",
+    },
+    output: {
+        type: {enum: ["htmlAndMathml", "html", "mathml"]},
+        description: "Determines the markup language of the output.",
+        cli: "-F, --format <type>",
+    },
+    leqno: {
+        type: "boolean",
+        description: "Render display math in leqno style (left-justified tags).",
+    },
+    fleqn: {
+        type: "boolean",
+        description: "Render display math flush left.",
+    },
+    throwOnError: {
+        type: "boolean",
+        default: true,
+        cli: "-t, --no-throw-on-error",
+        cliDescription: "Render errors (in the color given by --error-color) ins" +
+            "tead of throwing a ParseError exception when encountering an error.",
+    },
+    errorColor: {
+        type: "string",
+        default: "#cc0000",
+        cli: "-c, --error-color <color>",
+        cliDescription: "A color string given in the format 'rgb' or 'rrggbb' " +
+            "(no #). This option determines the color of errors rendered by the " +
+            "-t option.",
+        cliProcessor: (color) => "#" + color,
+    },
+    macros: {
+        type: "object",
+        cli: "-m, --macro <def>",
+        cliDescription: "Define custom macro of the form '\\foo:expansion' (use " +
+            "multiple -m arguments for multiple macros).",
+        cliDefault: [],
+        cliProcessor: (def, defs) => {
+            defs.push(def);
+            return defs;
+        },
+    },
+    minRuleThickness: {
+        type: "number",
+        description: "Specifies a minimum thickness, in ems, for fraction lines," +
+            " `\\sqrt` top lines, `{array}` vertical lines, `\\hline`, " +
+            "`\\hdashline`, `\\underline`, `\\overline`, and the borders of " +
+            "`\\fbox`, `\\boxed`, and `\\fcolorbox`.",
+        processor: (t) => Math.max(0, t),
+        cli: "--min-rule-thickness <size>",
+        cliProcessor: parseFloat,
+    },
+    colorIsTextColor: {
+        type: "boolean",
+        description: "Makes \\color behave like LaTeX's 2-argument \\textcolor, " +
+            "instead of LaTeX's one-argument \\color mode change.",
+        cli: "-b, --color-is-text-color",
+    },
+    strict: {
+        type: [{enum: ["warn", "ignore", "error"]}, "boolean", "function"],
+        description: "Turn on strict / LaTeX faithfulness mode, which throws an " +
+            "error if the input uses features that are not supported by LaTeX.",
+        cli: "-S, --strict",
+        cliDefault: false,
+    },
+    trust: {
+        type: ["boolean", "function"],
+        description: "Trust the input, enabling all HTML features such as \\url.",
+        cli: "-T, --trust",
+    },
+    maxSize: {
+        type: "number",
+        default: Infinity,
+        description: "If non-zero, all user-specified sizes, e.g. in " +
+            "\\rule{500em}{500em}, will be capped to maxSize ems. Otherwise, " +
+            "elements and spaces can be arbitrarily large",
+        processor: (s) => Math.max(0, s),
+        cli: "-s, --max-size <n>",
+        cliProcessor: parseInt,
+    },
+    maxExpand: {
+        type: "number",
+        default: 1000,
+        description: "Limit the number of macro expansions to the specified " +
+            "number, to prevent e.g. infinite macro loops. If set to Infinity, " +
+            "the macro expander will try to fully expand as in LaTeX.",
+        processor: (n) => Math.max(0, n),
+        cli: "-e, --max-expand <n>",
+        cliProcessor: (n) => (n === "Infinity" ? Infinity : parseInt(n)),
+    },
+    globalGroup: {
+        type: "boolean",
+        cli: false,
+    },
 };
 
+function getDefaultValue(schema): any {
+    if (schema.default) {
+        return schema.default;
+    }
+    const type = schema.type;
+    const defaultType = Array.isArray(type) ? type[0] : type;
+    if (typeof defaultType !== 'string') {
+        return defaultType.enum[0];
+    }
+    switch (defaultType) {
+        case 'boolean':
+            return false;
+        case 'string':
+            return '';
+        case 'number':
+            return 0;
+        case 'object':
+            return {};
+    }
+}
+
 /**
  * The main Settings object
  *
@@ -98,23 +255,17 @@ export default class Settings {
     constructor(options: SettingsOptions) {
         // allow null options
         options = options || {};
-        this.displayMode = utils.deflt(options.displayMode, false);
-        this.output = utils.deflt(options.output, "htmlAndMathml");
-        this.leqno = utils.deflt(options.leqno, false);
-        this.fleqn = utils.deflt(options.fleqn, false);
-        this.throwOnError = utils.deflt(options.throwOnError, true);
-        this.errorColor = utils.deflt(options.errorColor, "#cc0000");
-        this.macros = options.macros || {};
-        this.minRuleThickness = Math.max(
-            0,
-            utils.deflt(options.minRuleThickness, 0)
-        );
-        this.colorIsTextColor = utils.deflt(options.colorIsTextColor, false);
-        this.strict = utils.deflt(options.strict, "warn");
-        this.trust = utils.deflt(options.trust, false);
-        this.maxSize = Math.max(0, utils.deflt(options.maxSize, Infinity));
-        this.maxExpand = Math.max(0, utils.deflt(options.maxExpand, 1000));
-        this.globalGroup = utils.deflt(options.globalGroup, false);
+        for (const prop in SETTINGS_SCHEMA) {
+            if (SETTINGS_SCHEMA.hasOwnProperty(prop)) {
+                // $FlowFixMe
+                const schema = SETTINGS_SCHEMA[prop];
+                // TODO: validate options
+                // $FlowFixMe
+                this[prop] = options[prop] !== undefined ? (schema.processor
+                        ? schema.processor(options[prop]) : options[prop])
+                    : getDefaultValue(schema);
+            }
+        }
     }
 
     /**

package/src/environments/array.js

@@ -4,10 +4,12 @@ import Style from "../Style";
 import defineEnvironment from "../defineEnvironment";
 import {parseCD} from "./cd";
 import defineFunction from "../defineFunction";
+import defineMacro from "../defineMacro";
 import mathMLTree from "../mathMLTree";
 import ParseError from "../ParseError";
 import {assertNodeType, assertSymbolNodeType} from "../parseNode";
 import {checkSymbolNodeType} from "../parseNode";
+import {Token} from "../Token";
 import {calculateSize, makeEm} from "../units";
 import utils from "../utils";
 
@@ -54,6 +56,18 @@ const validateAmsEnvironmentContext = context => {
     }
 };
 
+// autoTag (an argument to parseArray) can be one of three values:
+// * undefined: Regular (not-top-level) array; no tags on each row
+// * true: Automatic equation numbering, overridable by \tag
+// * false: Tags allowed on each row, but no automatic numbering
+// This function *doesn't* work with the "split" environment name.
+function getAutoTag(name): ?boolean {
+    if (name.indexOf("ed") === -1) {
+        return name.indexOf("*") === -1;
+    }
+    // return undefined;
+}
+
 /**
  * Parse the body of the environment, with rows delimited by \\ and
  * columns delimited by &, and create a nested list in row-major order
@@ -68,7 +82,7 @@ function parseArray(
         cols,
         arraystretch,
         colSeparationType,
-        addEqnNum,
+        autoTag,
         singleRow,
         emptySingleRow,
         maxNumCols,
@@ -79,7 +93,7 @@ function parseArray(
         cols?: AlignSpec[],
         arraystretch?: number,
         colSeparationType?: ColSeparationType,
-        addEqnNum?: boolean,
+        autoTag?: ?boolean,
         singleRow?: boolean,
         emptySingleRow?: boolean,
         maxNumCols?: number,
@@ -116,6 +130,29 @@ function parseArray(
     const rowGaps = [];
     const hLinesBeforeRow = [];
 
+    const tags = (autoTag != null ? [] : undefined);
+
+    // amsmath uses \global\@eqnswtrue and \global\@eqnswfalse to represent
+    // whether this row should have an equation number.  Simulate this with
+    // a \@eqnsw macro set to 1 or 0.
+    function beginRow() {
+        if (autoTag) {
+            parser.gullet.macros.set("\\@eqnsw", "1", true);
+        }
+    }
+    function endRow() {
+        if (tags) {
+            if (parser.gullet.macros.get("\\df@tag")) {
+                tags.push(parser.subparse([new Token("\\df@tag")]));
+                parser.gullet.macros.set("\\df@tag", undefined, true);
+            } else {
+                tags.push(Boolean(autoTag) &&
+                    parser.gullet.macros.get("\\@eqnsw") === "1");
+            }
+        }
+    }
+    beginRow();
+
     // Test for \hline at the top of the array.
     hLinesBeforeRow.push(getHLines(parser));
 
@@ -154,6 +191,7 @@ function parseArray(
             }
             parser.consume();
         } else if (next === "\\end") {
+            endRow();
             // Arrays terminate newlines with `\crcr` which consumes a `\cr` if
             // the last line is empty.  However, AMS environments keep the
             // empty row if it's the only one.
@@ -179,12 +217,14 @@ function parseArray(
                 size = parser.parseSizeGroup(true);
             }
             rowGaps.push(size ? size.value : null);
+            endRow();
 
             // check for \hline(s) following the row separator
             hLinesBeforeRow.push(getHLines(parser));
 
             row = [];
             body.push(row);
+            beginRow();
         } else {
             throw new ParseError("Expected & or \\\\ or \\cr or \\end",
                                  parser.nextToken);
@@ -207,7 +247,7 @@ function parseArray(
         hskipBeforeAndAfter,
         hLinesBeforeRow,
         colSeparationType,
-        addEqnNum,
+        tags,
         leqno,
     };
 }
@@ -339,17 +379,27 @@ const htmlBuilder: HtmlBuilder<"array"> = function(group, options) {
     let colSep;
     let colDescrNum;
 
-    const eqnNumSpans = [];
-    if (group.addEqnNum) {
-        // An environment with automatic equation numbers.
-        // Create node(s) that will trigger CSS counter increment.
+    const tagSpans = [];
+    if (group.tags && group.tags.some((tag) => tag)) {
+        // An environment with manual tags and/or automatic equation numbers.
+        // Create node(s), the latter of which 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});
+            const tag = group.tags[r];
+            let tagSpan;
+            if (tag === true) {  // automatic numbering
+                tagSpan = buildCommon.makeSpan(["eqn-num"], [], options);
+            } else if (tag === false) {
+                // \nonumber/\notag or starred environment
+                tagSpan = buildCommon.makeSpan([], [], options);
+            } else {  // manual \tag
+                tagSpan = buildCommon.makeSpan([],
+                    html.buildExpression(tag, options, true), options);
+            }
+            tagSpan.depth = rw.depth;
+            tagSpan.height = rw.height;
+            tagSpans.push({type: "elem", elem: tagSpan, shift});
         }
     }
 
@@ -465,12 +515,12 @@ const htmlBuilder: HtmlBuilder<"array"> = function(group, options) {
         }, options);
     }
 
-    if (!group.addEqnNum) {
+    if (tagSpans.length === 0) {
         return buildCommon.makeSpan(["mord"], [body], options);
     } else {
         let eqnNumCol = buildCommon.makeVList({
             positionType: "individualShift",
-            children: eqnNumSpans,
+            children: tagSpans,
         }, options);
         eqnNumCol = buildCommon.makeSpan(["tag"], [eqnNumCol], options);
         return buildCommon.makeFragment([body, eqnNumCol]);
@@ -494,7 +544,7 @@ const mathmlBuilder: MathMLBuilder<"array"> = function(group, options) {
             row.push(new mathMLTree.MathNode("mtd",
                 [mml.buildGroup(rw[j], options)]));
         }
-        if (group.addEqnNum) {
+        if (group.tags && group.tags[i]) {
             row.unshift(glue);
             row.push(glue);
             if (group.leqno) {
@@ -631,14 +681,15 @@ const alignedHandler = function(context, args) {
     }
     const cols = [];
     const separationType = context.envName.indexOf("at") > -1 ? "alignat" : "align";
+    const isSplit = context.envName === "split";
     const res = parseArray(context.parser,
         {
             cols,
             addJot: true,
-            addEqnNum: context.envName === "align" || context.envName === "alignat",
+            autoTag: isSplit ? undefined : getAutoTag(context.envName),
             emptySingleRow: true,
             colSeparationType: separationType,
-            maxNumCols: context.envName === "split" ? 2 : undefined,
+            maxNumCols: isSplit ? 2 : undefined,
             leqno: context.parser.settings.leqno,
         },
         "display"
@@ -984,7 +1035,7 @@ defineEnvironment({
             }],
             addJot: true,
             colSeparationType: "gather",
-            addEqnNum: context.envName === "gather",
+            autoTag: getAutoTag(context.envName),
             emptySingleRow: true,
             leqno: context.parser.settings.leqno,
         };
@@ -1017,7 +1068,7 @@ defineEnvironment({
     handler(context) {
         validateAmsEnvironmentContext(context);
         const res = {
-            addEqnNum: context.envName === "equation",
+            autoTag: getAutoTag(context.envName),
             emptySingleRow: true,
             singleRow: true,
             maxNumCols: 1,
@@ -1043,6 +1094,9 @@ defineEnvironment({
     mathmlBuilder,
 });
 
+defineMacro("\\nonumber", "\\gdef\\@eqnsw{0}");
+defineMacro("\\notag", "\\nonumber");
+
 // Catch \hline outside array environment
 defineFunction({
     type: "text", // Doesn't matter what this is.

package/src/functions/relax.js

@@ -0,0 +1,17 @@
+//@flow
+import defineFunction from "../defineFunction";
+
+defineFunction({
+    type: "internal",
+    names: ["\\relax"],
+    props: {
+        numArgs: 0,
+        allowedInText: true,
+    },
+    handler({parser}) {
+        return {
+            type: "internal",
+            mode: parser.mode,
+        };
+    },
+});

package/src/functions.js

@@ -37,6 +37,7 @@ import "./functions/ordgroup";
 import "./functions/overline";
 import "./functions/phantom";
 import "./functions/raisebox";
+import "./functions/relax";
 import "./functions/rule";
 import "./functions/sizing";
 import "./functions/smash";

package/src/macros.js

@@ -368,7 +368,7 @@ defineMacro("\\substack", "\\begin{subarray}{c}#1\\end{subarray}");
 // \renewcommand{\colon}{\nobreak\mskip2mu\mathpunct{}\nonscript
 // \mkern-\thinmuskip{:}\mskip6muplus1mu\relax}
 defineMacro("\\colon", "\\nobreak\\mskip2mu\\mathpunct{}" +
-    "\\mathchoice{\\mkern-3mu}{\\mkern-3mu}{}{}{:}\\mskip6mu");
+    "\\mathchoice{\\mkern-3mu}{\\mkern-3mu}{}{}{:}\\mskip6mu\\relax");
 
 // \newcommand{\boxed}[1]{\fbox{\m@th$\displaystyle#1$}}
 defineMacro("\\boxed", "\\fbox{$\\displaystyle{#1}$}");

package/src/parseNode.js

@@ -39,7 +39,8 @@ type ParseNodeTypes = {
         body: AnyParseNode[][], // List of rows in the (2D) array.
         rowGaps: (?Measurement)[],
         hLinesBeforeRow: Array<boolean[]>,
-        addEqnNum?: boolean,
+        // Whether each row should be automatically numbered, or an explicit tag
+        tags?: (boolean | AnyParseNode[])[],
         leqno?: boolean,
         isCD?: boolean,
     |},

package/src/parseTree.js

@@ -6,6 +6,7 @@
 
 import Parser from "./Parser";
 import ParseError from "./ParseError";
+import {Token} from "./Token";
 
 import type Settings from "./Settings";
 import type {AnyParseNode} from "./parseNode";
@@ -34,12 +35,11 @@ const parseTree = function(toParse: string, settings: Settings): AnyParseNode[]
         if (!settings.displayMode) {
             throw new ParseError("\\tag works only in display equations");
         }
-        parser.gullet.feed("\\df@tag");
         tree = [{
             type: "tag",
             mode: "text",
             body: tree,
-            tag: parser.parse(),
+            tag: parser.subparse([new Token("\\df@tag")]),
         }];
     }