Default arguments support #24

package.json

@@ -25,6 +25,7 @@
     "devDependencies": {
         "@types/node": "^20.5.9",
         "@types/prettier": "^2.7.3",
+        "@typescript-eslint/eslint-plugin": "^6.16.0",
         "esbuild": "^0.19.2",
         "esbuild-runner": "^2.2.2",
         "lerna": "^7.2.0",

packages/unified-latex-builder/libs/builders.ts

@@ -181,6 +181,16 @@ export function arg(
     return { type: "argument", content: args, openMark, closeMark };
 }
 
+/**
+ * Creates an empty argument. This can only present in Ast as a result of -NoValue-.
+ */
+export function emptyArg() {
+    return arg([], {
+        openMark: "",
+        closeMark: "",
+    });
+}
+
 /**
  * Create a Macro with the given `name`. The macro
  * may be followed by any number of arguments.

packages/unified-latex-cli/libs/macros/expand-document-macros-plugin.ts

@@ -1,11 +1,10 @@
 import * as Ast from "@unified-latex/unified-latex-types";
+import { attachMacroArgs } from "@unified-latex/unified-latex-util-arguments";
 import {
-    expandMacros,
     expandMacrosExcludingDefinitions,
     listNewcommands,
 } from "@unified-latex/unified-latex-util-macros";
 import { Plugin } from "unified";
-import { attachMacroArgs } from "@unified-latex/unified-latex-util-arguments";
 
 type PluginOptions = {
     macros?: string[];

packages/unified-latex-cli/tests/__snapshots__/cli.test.ts.snap

@@ -45,6 +45,12 @@ hi $\\\\x fooArg$ and baz!
 "
 `;
 
+exports[`unified-latex-cli > can expand macro 3`] = `
+"% Expand via> tests/needs-expanding.tex --stats -e \\"\\\\\\\\newcommand{foo}[1]{FOO(#1)}\\" -e '{name: \\"bar\\", body: \\"baz\\"}'
+hi FOO(fooArg) and baz!
+"
+`;
+
 exports[`unified-latex-cli > can expand macros defined in document 1`] = `
 "\\\\newcommand{\\\\foo}[1]{$BAR #1$}
 \\\\DeclareDocumentCommand{\\\\baz}{m}{\\\\foo{xxx} .#1.}

packages/unified-latex-cli/tests/cli.test.ts

@@ -67,6 +67,16 @@ describe(
                 ]);
                 expect(stdout).toMatchSnapshot();
             }
+            {
+                let stdout = await execCLI([
+                    `${examplesPath}/needs-expanding.tex`,
+                    `-e`,
+                    "\\newcommand{foo}[2][FOO]{#1(#2)}",
+                    `-e`,
+                    '{name: "bar", signature: "O{baz}", body: "#1"}',
+                ]);
+                expect(stdout).toMatchSnapshot();
+            }
         });
         it("can expand macros defined in document", async () => {
             const stdout = await execCLI([

packages/unified-latex-prettier/libs/printer/argument.ts

@@ -19,11 +19,7 @@ export function printArgument(
     );
 
     // We can return early for empty arguments (this is common for omitted optional arguments)
-    if (
-        node.openMark === "" &&
-        node.closeMark === "" &&
-        node.content.length === 0
-    ) {
+    if (match.blankArgument(node)) {
         return [];
     }
     const parentNode = path.getParentNode();

packages/unified-latex-prettier/libs/printer/printer.ts

@@ -83,6 +83,8 @@ export function printLatexAst(
             return printVerbatimEnvironment(path, print, options);
         case "whitespace":
             return line;
+        case "hash_number":
+            return `#${node.number}`;
         default:
             console.warn("Printing unknown type", node);
             return printRaw(node);

packages/unified-latex-to-hast/libs/html-subs/to-hast-direct.ts

@@ -69,6 +69,11 @@ export function toHastDirect(
             );
         case "root":
             return h("root");
+        case "hash_number":
+            return {
+                type: "text",
+                value: `#${node.number}`,
+            };
         default: {
             const _exhaustiveCheck: never = node;
             throw new Error(

packages/unified-latex-to-hast/libs/html-subs/to-hast.ts

@@ -114,6 +114,11 @@ export function toHastWithLoggerFactory(
                 );
             case "root":
                 return node.content.flatMap(toHast);
+            case "hash_number":
+                return {
+                    type: "text",
+                    value: `#${node.number}`,
+                };
             default: {
                 const _exhaustiveCheck: never = node;
                 throw new Error(

packages/unified-latex-types/libs/ast-types.ts

@@ -92,6 +92,12 @@ export interface Argument extends ContentNode {
     closeMark: string;
 }
 
+// Only available during macro expansion
+export interface HashNumber extends BaseNode {
+    type: "hash_number";
+    number: number;
+}
+
 export type Node =
     | Root
     | String
@@ -104,6 +110,7 @@ export type Node =
     | InlineMath
     | DisplayMath
     | Group
-    | Verb;
+    | Verb
+    | HashNumber;
 
 export type Ast = Node | Argument | Node[];

packages/unified-latex-util-argspec/libs/argspec-parser.ts

@@ -7,7 +7,7 @@ import * as ArgSpec from "./argspec-types";
  */
 function getDecorators(node: ArgSpec.Node): string {
     let ret = "";
-    if ((node as ArgSpec.LeadingWhitespace).noLeadingWhitespace) {
+    if (node.noLeadingWhitespace) {
         ret += "!";
     }
     return ret;
@@ -29,13 +29,11 @@ export function printRaw(
         const sepToken = root ? " " : "";
         return node.map((tok) => printRaw(tok)).join(sepToken);
     }
-
+    return printRawInner(node);
+}
+function printRawInner(node: ArgSpec.Node) {
     const decorators = getDecorators(node);
-    const defaultArg = (node as ArgSpec.DefaultArgument).defaultArg
-        ? printRaw((node as ArgSpec.DefaultArgument).defaultArg!)
-        : "";
     let spec = decorators;
-
     const type = node.type;
     switch (type) {
         case "body":
@@ -52,7 +50,10 @@ export function printRaw(
                 spec += node.defaultArg ? "D" : "d";
                 spec += node.openBrace + node.closeBrace;
             }
-            return spec + defaultArg;
+            if (node.defaultArg) {
+                spec = appendTokenOrGroup(spec, node.defaultArg);
+            }
+            return spec;
         case "mandatory":
             // {...} is the default enclosure for mandatory arguments
             if (node.openBrace === "{" && node.closeBrace === "}") {
@@ -61,32 +62,94 @@ export function printRaw(
                 spec += node.defaultArg ? "R" : "r";
                 spec += node.openBrace + node.closeBrace;
             }
-            return spec + defaultArg;
+            if (node.defaultArg) {
+                spec = appendTokenOrGroup(spec, node.defaultArg);
+            }
+            return spec;
         case "embellishment":
-            spec += node.defaultArg ? "E" : "e";
-            return (
-                spec +
-                "{" +
-                printRaw(node.embellishmentTokens) +
-                "}" +
-                defaultArg
-            );
+            spec += node.defaultArgs ? "E" : "e";
+            spec += printTokenOrCollection(node.tokens);
+            if (node.defaultArgs) {
+                spec += printTokenOrCollection(node.defaultArgs);
+            }
+            return spec;
         case "verbatim":
             return spec + "v" + node.openBrace;
-        case "group":
-            return spec + "{" + printRaw(node.content) + "}";
         case "until": {
-            const stopTokens = printRaw(node.stopTokens);
-            return stopTokens.length > 1 || stopTokens[0] === " "
-                ? `u{${stopTokens}}`
-                : `u${stopTokens}`;
+            spec += "u";
+            spec += printTokenOrCollection(node.stopTokens);
+            return spec;
         }
         default:
             const neverType: never = type;
             console.warn(`Unknown node type "${neverType}" for node`, node);
             return "";
     }
 }
+/**
+ * See xparse-argspec.pegjs - token_or_group is parsed to an array of strings.
+ * This function will reconstruct a representative in an inverse image of token_or_group
+ * for a given array of strings, and append it to a given string.
+ * In order to avoid parsing ambiguity, we force enclose the representative with braces in some case.
+ *
+ * Examples)
+ * Appending a `token_or_group` representing an embellishment tokens, with existingString `e`.
+ * token of several chars "ab" --> {ab} will be appended, so the result will be `e{ab}`.
+ * token of single char "^" ---> ^ will be appended, so the result will be `e^`.
+ * token of single char " " ---> { } will be appended, so the result will be `e{ }`.
+ *
+ * Appending a `token_or_group` representing a bracespec of a delimited argument spec.
+ * Already constructed a string until the opening brace, existingString = "r\open".
+ * If the bracespec is a single alphabetric char "a", then we need to append it with braces, so the result will be "r\open{a}".
+ *
+ * Appending an embellishment token, with existingString = "e{a\token".
+ * If a next token is again a control world, say \anotherToken, we can append it as-is. "e{a\token\anotherToken".
+ * If a next token is a single char, say "b", we may either enclose it with braces or separate it with a space,
+ * because in this circumstance, space can be used to separate tokens (as conveyed by allowWhitespace = true).
+ * Then the result will be "e{a\token b".
+ */
+function appendTokenOrGroup(
+    existingString: string,
+    tokenOrGroup: string,
+    allowWhitespace = false
+) {
+    // If a previous token consists of more than one chars and ends with letters,
+    // then we need to separate the next token by enclosing it with braces.
+    // This can happen with control words such as \asdf.
+    const followsControlWord = /\\[a-zA-Z]+$/.test(existingString);
+    if (
+        (!followsControlWord &&
+            tokenOrGroup.length === 1 &&
+            (allowWhitespace || tokenOrGroup !== " ")) ||
+        tokenOrGroup.startsWith("\\")
+    ) {
+        return existingString + tokenOrGroup;
+    }
+    // In normalization, prefer whitespace because it occupies less space.
+    return (
+        existingString +
+        (allowWhitespace && tokenOrGroup.length === 1
+            ? " " + tokenOrGroup
+            : "{" + tokenOrGroup + "}")
+    );
+}
+/**
+ * See xparse-argspec.pegjs, token_or_collection is used by embellishment tokens, embellishment default arguments,
+ * and stop tokens for `until`.
+ */
+function printTokenOrCollection(tokenOrCollection: string[]) {
+    if (tokenOrCollection.length <= 1) {
+        const token = tokenOrCollection[0];
+        if (token.length === 1 && token !== " ") {
+            return token;
+        }
+    }
+    let out = "";
+    for (let token of tokenOrCollection) {
+        out = appendTokenOrGroup(out, token, true);
+    }
+    return "{" + out + "}";
+}
 
 const parseCache: { [argStr: string]: ArgSpec.Node[] } = {};
 

packages/unified-latex-util-argspec/libs/argspec-types.ts

@@ -1,42 +1,60 @@
 export type Ast = Node[] | Node;
-export type Node = Optional | Mandatory | Verbatim | Body | Group | Until;
+export type Node = Optional | Mandatory | Verbatim | Body | Until;
 type Optional = OptionalArg | OptionalStar | OptionalToken | Embellishment;
-interface AstNode {
+
+// Make several optional properties available in all `AstNode`s
+interface AstNode
+    extends Partial<Arg>,
+        Partial<LeadingWhitespace>,
+        DefaultArgument {
     type: string;
 }
-interface Arg extends AstNode {
+
+// Mixins
+interface Arg {
     openBrace: string;
     closeBrace: string;
 }
-export interface LeadingWhitespace {
+interface LeadingWhitespace {
     noLeadingWhitespace: boolean | undefined;
 }
-export interface DefaultArgument {
-    defaultArg?: Group;
+interface DefaultArgument {
+    defaultArg?: string;
 }
-interface Verbatim extends Arg {
+
+// Make `openBrace` and `closeBrace` required by extending both.
+// Typescript requires specifying those properties to be specified in interface body,
+// otherwise the compilation will error out.
+interface Verbatim extends AstNode, Arg {
     type: "verbatim";
+    openBrace: string;
+    closeBrace: string;
 }
-interface OptionalArg extends LeadingWhitespace, DefaultArgument, Arg {
+interface OptionalArg extends LeadingWhitespace, DefaultArgument, AstNode, Arg {
     type: "optional";
+    openBrace: string;
+    closeBrace: string;
+    noLeadingWhitespace: boolean | undefined;
+    defaultArg?: string;
 }
 interface OptionalStar extends LeadingWhitespace, AstNode {
     type: "optionalStar";
+    noLeadingWhitespace: boolean | undefined;
 }
 interface OptionalToken extends LeadingWhitespace, AstNode {
     type: "optionalToken";
     token: string;
+    noLeadingWhitespace: boolean | undefined;
 }
-export interface Embellishment extends DefaultArgument, AstNode {
+export interface Embellishment extends AstNode {
     type: "embellishment";
-    embellishmentTokens: string[];
+    tokens: string[];
+    defaultArgs?: string[]; // Embellishment default arguments are always a collection of arguments
 }
-interface Mandatory extends LeadingWhitespace, DefaultArgument, Arg {
+interface Mandatory extends DefaultArgument, AstNode, Arg {
     type: "mandatory";
-}
-export interface Group extends AstNode {
-    type: "group";
-    content: (Group | string)[];
+    openBrace: string;
+    closeBrace: string;
 }
 interface Body extends AstNode {
     type: "body";