math-core 0.7.0 → 0.8.2

package/README.md

@@ -12,6 +12,7 @@ A Node.js library for converting LaTeX math expressions to MathML Core.
 - Support for both inline and display (block) math
 - Define custom LaTeX macros for extended functionality
 - Global and local counter for numbered equations
+- Batch conversion which resolves forward references between snippets
 - Pretty-printing option for readable MathML output
 - Comprehensive error handling with descriptive error messages
 
@@ -120,6 +121,28 @@ const doc2 = converter.convert_with_local_state(
 ); // Also contains (1) and (2)
 ```
 
+### Converting a Whole Document at Once
+
+`convert_all` converts a collection of snippets in one go, which is the only way to get
+*forward references* right: a snippet may refer to an equation which is only defined in a later
+snippet.
+
+```javascript
+const converter = new LatexToMathML({});
+
+const [reference, equation] = converter.convert_all([
+  { latex: "\\eqref{eq:euler}", displayStyle: false },
+  {
+    latex: "\\begin{align}e^{i\\pi} + 1 = 0\\label{eq:euler}\\end{align}",
+    displayStyle: true,
+  },
+]);
+// `reference` refers to equation (1), even though it comes first.
+```
+
+Equation numbering restarts with every call to `convert_all`; the state of
+`convert_with_global_state` is neither used nor modified.
+
 ### Error Handling
 
 By default, conversion errors throw a `LatexError` with detailed diagnostics:
@@ -168,11 +191,17 @@ new LatexToMathML(options: MathCoreOptions)
 | `throwOnError` | `boolean` | `true` | Throw `LatexError` on conversion errors. If `false`, returns an HTML error snippet instead. |
 | `ignoreUnknownCommands` | `boolean` | `false` | Render unknown commands as red text instead of erroring. |
 | `annotation` | `boolean` | `false` | Include the original LaTeX as an annotation in the MathML output. |
+| `allowUnreliableRendering` | `boolean` | `false` | Enable commands whose MathML Core output is rendered unreliably across browsers, such as `\widetilde`, `\widecheck` and `\utilde`. If `false`, these commands are treated as unknown. |
+| `globalGroup` | `boolean` | `false` | Run the conversion in the global group, so that commands defined with `\newcommand` stay defined for subsequent calls to `convert_with_global_state`. If `false`, such definitions are local to the snippet which contains them. |
+| `unicodeSubstitution` | `"never" \| "conventional"` | `"conventional"` | Whether commands like `\coloneqq` are rendered with a dedicated Unicode symbol (`≔`) or as a combination of more basic symbols (`:` and `=`). `"conventional"` substitutes wherever the LaTeX package `unicode-math` would, which is a good middle ground between semantics and faithfulness to the LaTeX output; `"never"` disables the substitutions. |
+| `maxExpansions` | `number` | `1000` | How many custom commands may be expanded in one snippet before the conversion gives up. The limit exists because a macro may expand to itself, directly or indirectly. |
+| `idPrefix`      | `string` | `""`   | Added to the beginning of every `id` and anchor reference. Use this to avoid conflicts when embedding the output. |
 
 **Methods:**
 
 - `convert_with_global_state(latex: string, displaystyle: boolean): string` — Convert LaTeX to MathML using global state.
 - `convert_with_local_state(latex: string, displaystyle: boolean): string` — Convert LaTeX to MathML using local state.
+- `convert_all(snippets: MathSnippet[]): string[]` — Convert all snippets of a document at once, resolving forward references between them. A `MathSnippet` is `{ latex: string, displayStyle: boolean }`. Uses a fresh state for the batch, independent of the global state.
 - `reset_global_state(): void` — Reset the global state (e.g., set the equation counter to zero).
 
 ### `LatexError`
@@ -188,6 +217,7 @@ Error thrown when LaTeX parsing or conversion fails.
 | `context` | `string \| undefined` | The relevant LaTeX source. |
 | `start` | `number` | Start offset of the error in the source. |
 | `end` | `number` | End offset of the error in the source. |
+| `index` | `number \| undefined` | Index of the failing snippet; only set by `convert_all`. |
 
 ## Why MathML Core?
 

package/dist/math_core.d.ts

@@ -9,7 +9,15 @@ interface MathCoreOptions {
     ignoreUnknownCommands?: boolean;
     annotation?: boolean;
     allowUnreliableRendering?: boolean;
+    globalGroup?: boolean;
     unicodeSubstitution?: "never" | "conventional";
+    maxExpansions?: number;
+    idPrefix?: string;
+}
+
+interface MathSnippet {
+    latex: string;
+    displayStyle: boolean;
 }
 
 
@@ -26,6 +34,14 @@ export class LatexError {
     free(): void;
     [Symbol.dispose](): void;
     end: number;
+    /**
+     * The index of the snippet that caused the error; only set by `convert_all`.
+     */
+    get index(): number | undefined;
+    /**
+     * The index of the snippet that caused the error; only set by `convert_all`.
+     */
+    set index(value: number | null | undefined);
     start: number;
     readonly context: string | undefined;
     readonly label: string;
@@ -36,6 +52,16 @@ export class LatexError {
 export class LatexToMathML {
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Convert a collection of LaTeX snippets to MathML.
+     *
+     * In contrast to the other conversion methods, this one resolves *forward references*
+     * correctly, meaning that a snippet can refer to an equation which is only defined in a
+     * later snippet. This is why all snippets of a document have to be passed in at once.
+     *
+     * The conversion does not touch the global state; it uses a fresh state for the whole batch.
+     */
+    convert_all(snippets: MathSnippet[]): string[];
     convert_with_global_state(content: string, displaystyle: boolean): string;
     convert_with_local_state(content: string, displaystyle: boolean): string;
     constructor(js_config: MathCoreOptions);

package/dist/math_core.js

@@ -53,6 +53,14 @@ export class LatexError {
         const ret = wasm.__wbg_get_latexerror_end(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * The index of the snippet that caused the error; only set by `convert_all`.
+     * @returns {number | undefined}
+     */
+    get index() {
+        const ret = wasm.__wbg_get_latexerror_index(this.__wbg_ptr);
+        return ret === Number.MAX_SAFE_INTEGER ? undefined : ret;
+    }
     /**
      * @returns {number}
      */
@@ -94,6 +102,13 @@ export class LatexError {
     set end(arg0) {
         wasm.__wbg_set_latexerror_end(this.__wbg_ptr, arg0);
     }
+    /**
+     * The index of the snippet that caused the error; only set by `convert_all`.
+     * @param {number | null} [arg0]
+     */
+    set index(arg0) {
+        wasm.__wbg_set_latexerror_index(this.__wbg_ptr, isLikeNone(arg0) ? Number.MAX_SAFE_INTEGER : (arg0) >>> 0);
+    }
     /**
      * @param {number} arg0
      */
@@ -114,6 +129,26 @@ export class LatexToMathML {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_latextomathml_free(ptr, 0);
     }
+    /**
+     * Convert a collection of LaTeX snippets to MathML.
+     *
+     * In contrast to the other conversion methods, this one resolves *forward references*
+     * correctly, meaning that a snippet can refer to an equation which is only defined in a
+     * later snippet. This is why all snippets of a document have to be passed in at once.
+     *
+     * The conversion does not touch the global state; it uses a fresh state for the whole batch.
+     * @param {MathSnippet[]} snippets
+     * @returns {string[]}
+     */
+    convert_all(snippets) {
+        const ptr0 = passArrayJsValueToWasm0(snippets, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.latextomathml_convert_all(this.__wbg_ptr, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @param {string} content
      * @param {boolean} displaystyle
@@ -162,7 +197,7 @@ if (Symbol.dispose) LatexToMathML.prototype[Symbol.dispose] = LatexToMathML.prot
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbg___wbindgen_string_get_b0ca35b86a603356: function(arg0, arg1) {
+        __wbg___wbindgen_string_get_d154f1e671052120: function(arg0, arg1) {
             const obj = arg1;
             const ret = typeof(obj) === 'string' ? obj : undefined;
             var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -170,14 +205,14 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg___wbindgen_throw_344f42d3211c4765: function(arg0, arg1) {
+        __wbg___wbindgen_throw_bb96b2010945f0bc: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_allowUnreliableRendering_09ef135275eede85: function(arg0) {
+        __wbg_allowUnreliableRendering_0c688f2e673263ef: function(arg0) {
             const ret = arg0.allowUnreliableRendering;
             return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
         },
-        __wbg_annotation_363d3c8394162f0f: function(arg0) {
+        __wbg_annotation_21d23c44ed560264: function(arg0) {
             const ret = arg0.annotation;
             return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
         },
@@ -185,65 +220,91 @@ function __wbg_get_imports() {
             const ret = ConfigParseError.__wrap(arg0);
             return ret;
         },
-        __wbg_done_89b2b13e91a60321: function(arg0) {
+        __wbg_displayStyle_8f34f8466c68c3e6: function(arg0) {
+            const ret = arg0.displayStyle;
+            return ret;
+        },
+        __wbg_done_669171204c3dcae2: function(arg0) {
             const ret = arg0.done;
             return ret;
         },
-        __wbg_entries_00d7283394649868: function(arg0) {
+        __wbg_entries_71601bcb707d5078: function(arg0) {
             const ret = arg0.entries();
             return ret;
         },
-        __wbg_get_507a50627bffa49b: function(arg0, arg1) {
+        __wbg_get_c0c8f8d7da0c03dd: function(arg0, arg1) {
             const ret = arg0[arg1 >>> 0];
             return ret;
         },
-        __wbg_ignoreUnknownCommands_fbafb7b34d6e9764: function(arg0) {
+        __wbg_globalGroup_e6cfdf49a72c6ace: function(arg0) {
+            const ret = arg0.globalGroup;
+            return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
+        },
+        __wbg_idPrefix_74c8aab65e9f7cb8: function(arg0, arg1) {
+            const ret = arg1.idPrefix;
+            var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            var len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg_ignoreUnknownCommands_6a05fe2fbcdaf5cb: function(arg0) {
             const ret = arg0.ignoreUnknownCommands;
             return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
         },
-        __wbg_isArray_0677c962b281d01a: function(arg0) {
+        __wbg_isArray_6339f732981044bf: function(arg0) {
             const ret = Array.isArray(arg0);
             return ret;
         },
+        __wbg_latex_7b59333697348341: function(arg0, arg1) {
+            const ret = arg1.latex;
+            const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
         __wbg_latexerror_new: function(arg0) {
             const ret = LatexError.__wrap(arg0);
             return ret;
         },
-        __wbg_macros_03715a0e353a948d: function(arg0) {
+        __wbg_macros_980bab7dcab4497a: function(arg0) {
             const ret = arg0.macros;
             return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
         },
-        __wbg_next_71f2aa1cb3d1e37e: function() { return handleError(function (arg0) {
+        __wbg_maxExpansions_a488622f8ecb93ad: function(arg0) {
+            const ret = arg0.maxExpansions;
+            return isLikeNone(ret) ? Number.MAX_SAFE_INTEGER : (ret) >>> 0;
+        },
+        __wbg_next_42cf16ee0dafc9e2: function() { return handleError(function (arg0) {
             const ret = arg0.next();
             return ret;
         }, arguments); },
-        __wbg_prettyPrint_53b1abd5bf18c3d9: function(arg0, arg1) {
+        __wbg_prettyPrint_f6868ca7e4b2ac12: function(arg0, arg1) {
             const ret = arg1.prettyPrint;
             var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
             var len1 = WASM_VECTOR_LEN;
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg_size_56cb46b36f9b2664: function(arg0) {
+        __wbg_size_7c5f5d6c17503441: function(arg0) {
             const ret = arg0.size;
             return ret;
         },
-        __wbg_throwOnError_b6c73f7b5c7ff297: function(arg0) {
+        __wbg_throwOnError_271d79a0e89a8c82: function(arg0) {
             const ret = arg0.throwOnError;
             return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
         },
-        __wbg_unicodeSubstitution_0308f153a7409367: function(arg0, arg1) {
+        __wbg_unicodeSubstitution_1eb49d99cb177b14: function(arg0, arg1) {
             const ret = arg1.unicodeSubstitution;
             var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
             var len1 = WASM_VECTOR_LEN;
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg_value_a5d5488a9589444a: function(arg0) {
+        __wbg_value_1e2369fab29b420e: function(arg0) {
             const ret = arg0.value;
             return ret;
         },
-        __wbg_xmlNamespace_28171b05853d5a2e: function(arg0) {
+        __wbg_xmlNamespace_90ec7bce1e2fb4b9: function(arg0) {
             const ret = arg0.xmlNamespace;
             return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
         },
@@ -252,6 +313,13 @@ function __wbg_get_imports() {
             const ret = getStringFromWasm0(arg0, arg1);
             return ret;
         },
+        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
+            var v0 = getArrayJsValueFromWasm0(arg0, arg1);
+            wasm.__wbindgen_free(arg0, arg1 * 4, 4);
+            // Cast intrinsic for `Vector(Externref) -> Externref`.
+            const ret = v0;
+            return ret;
+        },
         __wbindgen_init_externref_table: function() {
             const table = wasm.__wbindgen_externrefs;
             const offset = table.grow(4);
@@ -284,6 +352,17 @@ function addToExternrefTable0(obj) {
     return idx;
 }
 
+function getArrayJsValueFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    const mem = getDataViewMemory0();
+    const result = [];
+    for (let i = ptr; i < ptr + 4 * len; i += 4) {
+        result.push(wasm.__wbindgen_externrefs.get(mem.getUint32(i, true)));
+    }
+    wasm.__externref_drop_slice(ptr, len);
+    return result;
+}
+
 let cachedDataViewMemory0 = null;
 function getDataViewMemory0() {
     if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
@@ -317,6 +396,16 @@ function isLikeNone(x) {
     return x === undefined || x === null;
 }
 
+function passArrayJsValueToWasm0(array, malloc) {
+    const ptr = malloc(array.length * 4, 4) >>> 0;
+    for (let i = 0; i < array.length; i++) {
+        const add = addToExternrefTable0(array[i]);
+        getDataViewMemory0().setUint32(ptr + 4 * i, add, true);
+    }
+    WASM_VECTOR_LEN = array.length;
+    return ptr;
+}
+
 function passStringToWasm0(arg, malloc, realloc) {
     if (realloc === undefined) {
         const buf = cachedTextEncoder.encode(arg);

package/dist/math_core_bg.wasm.d.ts

@@ -3,16 +3,19 @@
 export const memory: WebAssembly.Memory;
 export const __wbg_configparseerror_free: (a: number, b: number) => void;
 export const __wbg_get_latexerror_end: (a: number) => number;
+export const __wbg_get_latexerror_index: (a: number) => number;
 export const __wbg_get_latexerror_start: (a: number) => number;
 export const __wbg_latexerror_free: (a: number, b: number) => void;
 export const __wbg_latextomathml_free: (a: number, b: number) => void;
 export const __wbg_set_latexerror_end: (a: number, b: number) => void;
+export const __wbg_set_latexerror_index: (a: number, b: number) => void;
 export const __wbg_set_latexerror_start: (a: number, b: number) => void;
 export const configparseerror_message: (a: number) => any;
 export const latexerror_context: (a: number) => any;
 export const latexerror_label: (a: number) => any;
 export const latexerror_message: (a: number) => any;
 export const latexerror_report: (a: number) => any;
+export const latextomathml_convert_all: (a: number, b: number, c: number) => [number, number, number];
 export const latextomathml_convert_with_global_state: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const latextomathml_convert_with_local_state: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const latextomathml_new: (a: any) => [number, number, number];
@@ -22,5 +25,7 @@ export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) =>
 export const __externref_table_alloc: () => number;
 export const __wbindgen_externrefs: WebAssembly.Table;
 export const __wbindgen_exn_store: (a: number) => void;
+export const __externref_drop_slice: (a: number, b: number) => void;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
 export const __externref_table_dealloc: (a: number) => void;
 export const __wbindgen_start: () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "math-core",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "description": "Convert LaTeX to MathML Core",
   "homepage": "https://github.com/tmke8/math-core#readme",
   "bugs": {