latexmath 0.1.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3dd210bb97aa808bf1bee45d595148730fd1e324917a7fe402c05dcda243357e
-  data.tar.gz: 2bf325bde0a31dee92da668bd985d11cbc43424aeb1a3e94397ffbe7b6803a95
+  metadata.gz: a635c719d5f6d75f506de0542d17fba696d501cd9d1a80cf55e72477a6034a71
+  data.tar.gz: 2c7320734429e687c36964b3fb5a82aa75377ca82c594b565ff25c50b68d3e9d
 SHA512:
-  metadata.gz: d0ee9acb802192c32b47f22a8563964efd6640d8d606cd622e9f152dd46fd4f1fbe7d2c017aa8f1cc0e769e3b69d20b3e111946be67faed4420f45a519078053
-  data.tar.gz: e3cf465915d734f68290aecb7d9b1c9747b9b8202b5c673536899f97356e0fef341428950c31782b228209e4ea4eeb06cb5e87a2b925478a3e05fbee4261f6b9
+  metadata.gz: b401aa154dc56405a7aac319b044ec78e138a854421d993b368688a852cf7e1d60f0cef034bd98160ea7d5843d5284e15ca7527c436ed4b3c97a060c943e56ff
+  data.tar.gz: f42060ac13fce70b34ffa47e59ad6ed3a53660ff9cde08c2209d2be7b6f23c65dc506e11bd4b095bff4f64cb4d01509ea0407a03c7413853d632adf0b3072f33

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## 1.0.0
+
+Latexmath is now a LaTeX math parser that returns a typed model, built for
+Plurimath. It replaces the 0.1.x LaTeX-to-MathML converter, and is not
+backward compatible with it.
+
+### Breaking changes
+
+- `Latexmath.parse(input, decimal: ".", engine: :auto)` returns a
+  `Latexmath::Model::Document`, a typed model of the formula built with
+  LutaML Model. In 0.1.x it returned an equation object whose `to_mathml`
+  wrote MathML.
+- The 0.1.x converter is removed: `Latexmath.legacy_parse`, the
+  `Latexmath::Tokenizer`, `Aggregator`, `Converter`, `Equation`, `Symbol`
+  and `XML` classes, `Latexmath::Constants::SYMBOLS`, the `latexmath`
+  executable and the Opal build (`dist/latexmath.js`).
+- Invalid input raises `Latexmath::ParseError` with the position in the
+  caller's input (`char_offset`, `byte_offset`). Every error Latexmath
+  raises on purpose is a `Latexmath::Error`.
+- Ruby 3.2 or later is required. The runtime dependencies are Parsanol,
+  LutaML Model and HTMLEntities; Ox is no longer used. LaTeXML is no longer
+  needed, even for development.
+
+### Moving from 0.1.x
+
+Latexmath no longer writes MathML. To convert LaTeX math to MathML or
+another format, use Plurimath:
+
+```ruby
+require "plurimath"
+
+Plurimath::Math.parse("x^2", :latex).to_mathml
+```
+
+Code that only needs the structure of a formula can read the model from
+`Latexmath.parse` directly; see `docs/model-contract.adoc`. To keep the
+0.1.x converter, pin `gem "latexmath", "~> 0.1.5"`.
+
+### Other changes
+
+- The grammar is Plurimath's LaTeX grammar, compiled with Parsanol into a
+  checksummed artifact (`artifacts/latex.json`). It runs on Parsanol's
+  native engine where available and on its Ruby engine elsewhere, with the
+  same results.
+- CI replays the LaTeX generation of plurimath-testsuite pinned in
+  `spec/fixtures/testsuite-pin.yml` and compares the parse tree with the
+  pinned Plurimath release for every LaTeX case of the testsuite.
+- The gem is released by trusted publishing from the `release` workflow.

data/LICENSE.md

@@ -0,0 +1,33 @@
+Licenses & Copyright
+====================
+
+This license file adheres to the formatting guidelines of
+[readable-licenses](https://github.com/nevir/readable-licenses).
+
+
+Ribose's BSD 2-Clause License
+-----------------------------
+
+Copyright (c) 2026, [Ribose Inc](https://www.ribose.com).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1.  Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -1,28 +1,147 @@
-= latexmath
+= Latexmath: LaTeX math parser for Ruby
 
 image:https://img.shields.io/gem/v/latexmath.svg["Gem Version", link="https://rubygems.org/gems/latexmath"]
-image:https://github.com/metanorma/latexmath/workflows/test/badge.svg["Build Status", link="https://github.com/metanorma/latexmath/actions?workflow=test"]
-image:https://codeclimate.com/github/metanorma/latexmath/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/latexmath"]
-image:https://img.shields.io/github/issues-pr-raw/metanorma/latexmath.svg["Pull Requests", link="https://github.com/metanorma/latexmath/pulls"]
-image:https://img.shields.io/github/commits-since/metanorma/latexmath/latest.svg["Commits since latest",link="https://github.com/metanorma/latexmath/releases"]
+image:https://github.com/plurimath/latexmath/actions/workflows/test.yml/badge.svg["Build Status", link="https://github.com/plurimath/latexmath/actions/workflows/test.yml"]
 
 == Purpose
 
-Ruby gem to translate LaTeX math into MathML.
-The MathML is supposed to be compliant with output of LaTeXML.
+Latexmath parses LaTeX math, the notation inside `$...$` or a `\[...\]`
+display, into a typed model of the formula. It reads the LaTeX that
+https://github.com/plurimath/plurimath[Plurimath] reads, with the same
+grammar, and is built for Plurimath to use for LaTeX input
+(https://github.com/plurimath/plurimath/issues/531[plurimath/plurimath#531]).
 
-It also works in reverse by translating MathML into LaTeX code.
+The model records the structure of the formula: which symbols, fractions,
+roots, sub- and superscripts, matrices, environments and brackets it
+contains, and how they nest. Your code decides what to do with it, such as
+rendering, converting or analysing it. Latexmath does not write MathML or any
+other output format; Plurimath does that.
 
-The LaTeX math syntax supports `amsmath`, `array`, `split` and `pmatrix` packages.
+Version 1.0.0 replaces the 0.1.x gem, which converted LaTeX to MathML. See
+link:CHANGELOG.md[the changelog] for what changed and how to move.
 
-NOTE: Bolding, symbols like `\backepsilon`, equation alignment, are all supported.
+== Installation
+
+Add it to your `Gemfile`:
+
+[source,ruby]
+----
+gem "latexmath", "~> 1.0"
+----
+
+Latexmath needs Ruby 3.2 or later. Its runtime dependencies are
+https://github.com/parsanol/parsanol-ruby[Parsanol],
+https://github.com/lutaml/lutaml-model[LutaML Model] and HTMLEntities. It
+does not load Plurimath.
 
 == Usage
 
 [source,ruby]
--------------
+----
 require "latexmath"
 
-latex = "$$f_i =  \sum_{j=1}^2 s_{ij} n_j \quad {\rm for} \quad i = 1,2$$"
-mathml = Latexmath.parse(latex).to_mathml
--------------
+doc = Latexmath.parse("x^2")
+power = doc.expression.power
+power.symbols.spelling   # => "x"
+power.supscript.number   # => "2"
+----
+
+`Latexmath.parse` returns a `Latexmath::Model::Document`. Its `expression`
+holds the formula and `decimal` the decimal marker it was parsed with. Input
+with no formula, such as an empty string, gives a document whose `expression`
+is nil.
+
+The model classes are plain LutaML Model classes, generated from the grammar:
+each named part of the grammar is a class with one attribute per part it can
+contain. Symbols such as `\alpha` are `Latexmath::Model::MathSymbol` objects.
+A symbol keeps the text the grammar matched as `spelling` and gives its
+Unicode text and kind (`symbol`, `open` or `close`):
+
+[source,ruby]
+----
+symbol = Latexmath.parse("\\alpha").expression.symbols
+symbol.spelling # => "alpha"
+symbol.value    # => "α"
+symbol.kind     # => "symbol"
+----
+
+Numbers keep their digits and decimal marker as written. A dot is the
+decimal marker unless you say otherwise; a comma and the Arabic decimal
+separator are also supported:
+
+[source,ruby]
+----
+Latexmath.parse("1,5", decimal: ",")
+Latexmath.parse("1٫5", decimal: "٫")
+----
+
+The rules for each model class are in link:docs/model-contract.adoc[the
+model contract], and the accepted syntax and the preprocessing of the input
+in link:docs/parser-contract.adoc[the parser contract].
+
+== Errors
+
+Input that is not valid LaTeX math raises `Latexmath::ParseError`, which
+tells you where the parser gave up, as a position in the text you passed:
+
+[source,ruby]
+----
+begin
+  Latexmath.parse("é}")
+rescue Latexmath::ParseError => e
+  e.char_offset # => 1, position in characters
+  e.byte_offset # => 2, position in UTF-8 bytes
+end
+----
+
+The parser first rewrites the input as Plurimath does: it removes spaces and
+newlines and writes non-ASCII characters as HTML entities. The place the
+grammar stops is therefore a position in text you did not write. The offsets are mapped back to your input; a position
+inside rewritten text points at the start of the text it came from. The
+position in the rewritten text is also available, as `grammar_char_offset`
+and `grammar_byte_offset`.
+
+Every error Latexmath raises on purpose is a `Latexmath::Error`, except
+`ArgumentError` for an invalid argument such as an unknown engine or decimal
+marker.
+
+== Engines
+
+Latexmath runs on Parsanol's native engine where its extension is available,
+and on its pure Ruby engine elsewhere. Both give the same results. You can
+choose one with `engine: :native` or `engine: :ruby`. Asking for the native
+engine where it cannot run raises `Latexmath::EngineUnavailable` instead of
+quietly using Ruby. `Latexmath.last_engine` tells you which engine handled
+the last call on the current thread.
+
+The native engine has a recursion limit. With the default `engine: :auto`,
+input that nests deeper than that is parsed with the Ruby engine; with
+`engine: :native` it raises `Latexmath::NestingTooDeep`, a kind of
+`Latexmath::ParseError` that has no offsets, because the input may well be
+valid.
+
+== Testing against the Plurimath testsuite
+
+The LaTeX cases of
+https://github.com/plurimath/plurimath-testsuite[plurimath-testsuite] are
+kept there as numbered, immutable generations. `spec/fixtures/testsuite-pin.yml`
+names the exact commit, generation and digest this gem is tested against, and
+CI replays every raw-tree row of that generation on both engines. CI also
+compares the parse tree with the one the pinned Plurimath release produces
+for every LaTeX case of the testsuite. See
+link:docs/testsuite-pin.adoc[the testsuite pin].
+
+== Relation to Plurimath
+
+Latexmath is one of the language gems split out of Plurimath, with
+https://github.com/plurimath/amath[amath] for AsciiMath and
+https://github.com/plurimath/unicodemath[unicodemath] for UnicodeMath. The
+plan and its progress are tracked in
+https://github.com/plurimath/plurimath/issues/541[plurimath/plurimath#541].
+Plurimath is to turn the model into its own formula objects and write the
+output formats.
+
+== License
+
+Copyright Ribose Inc. Licensed under the BSD 2-Clause License; see
+link:LICENSE.md[].

data/artifacts/latex.bindings.python.json

@@ -0,0 +1 @@
+{"artifact_kind":"parg-bindings","target":"python","binding_version":1,"grammar":"Latex","grammar_version":"0.1.0","grammar_source_hash":"f0694ce57b0f3e99e536b3749eb6b9c56570e4311b1d7aca0047c9e25a668cbf","shape":"parsanol-tree/v2","entries":{"dot":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]},"comma":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]},"arabic":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]}},"checksum":"sha256:74c9d54e22cb43fb1667bab1a6f1c3fecf177cf998756902355bd946f4142380"}

data/artifacts/latex.bindings.rs.json

@@ -0,0 +1 @@
+{"artifact_kind":"parg-bindings","target":"rs","binding_version":1,"grammar":"Latex","grammar_version":"0.1.0","grammar_source_hash":"f0694ce57b0f3e99e536b3749eb6b9c56570e4311b1d7aca0047c9e25a668cbf","shape":"parsanol-tree/v2","entries":{"dot":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]},"comma":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]},"arabic":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]}},"checksum":"sha256:7140c6478d723a74e8363ed1fb64619072cb94e1fee27ae999d4095d0094bacc"}

data/artifacts/latex.bindings.ruby.json

@@ -0,0 +1 @@
+{"artifact_kind":"parg-bindings","target":"ruby","binding_version":1,"grammar":"Latex","grammar_version":"0.1.0","grammar_source_hash":"f0694ce57b0f3e99e536b3749eb6b9c56570e4311b1d7aca0047c9e25a668cbf","shape":"parsanol-tree/v2","entries":{"dot":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]},"comma":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]},"arabic":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]}},"checksum":"sha256:35d47a16342a91651ca9be16bb0436f02c8b4528afd0a3757b415366f29a6b3f"}

data/artifacts/latex.bindings.ts.json

@@ -0,0 +1 @@
+{"artifact_kind":"parg-bindings","target":"ts","binding_version":1,"grammar":"Latex","grammar_version":"0.1.0","grammar_source_hash":"f0694ce57b0f3e99e536b3749eb6b9c56570e4311b1d7aca0047c9e25a668cbf","shape":"parsanol-tree/v2","entries":{"dot":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]},"comma":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]},"arabic":{"bindings":[{"capture":"latex_tree","path":"latex_tree","type":"raw","card":null,"preprocess":null},{"capture":"latex_tree","path":"model","type":"any","card":null,"preprocess":null}]}},"checksum":"sha256:ecff4bfe9a7c8eed7b9df7ca833ecec5ff6425b837278de96a88374b4d654b78"}

data/artifacts/latex.checksums.txt

@@ -0,0 +1,19 @@
+# Written by scripts/compile.rb. Envelope checksums are Parsanol's own;
+# the sha256 lines are of the files' bytes.
+artifact_checksum sha256:5639a6ca46058450f500d340649c95510b2a880ce0e4ce1a8d50e95eabad465f
+compiler_version 1.3.132
+edition 2
+source_hash sha256:f0694ce57b0f3e99e536b3749eb6b9c56570e4311b1d7aca0047c9e25a668cbf
+artifacts/latex.json sha256:f1f2e5d8328be8686b2c85907d23327a5081de0fa765c1b04b5de2a20d96f84b
+bindings ruby checksum sha256:35d47a16342a91651ca9be16bb0436f02c8b4528afd0a3757b415366f29a6b3f
+artifacts/latex.bindings.ruby.json sha256:6aec2810d9d52ea12bd1f65a8bc06c3074a866257f6a0fdd10948a8927f3720b
+bindings rs checksum sha256:7140c6478d723a74e8363ed1fb64619072cb94e1fee27ae999d4095d0094bacc
+artifacts/latex.bindings.rs.json sha256:55c9e24177b459a313b8990bba111b7769875a02cc9476909f1383da66e3bcc5
+bindings ts checksum sha256:ecff4bfe9a7c8eed7b9df7ca833ecec5ff6425b837278de96a88374b4d654b78
+artifacts/latex.bindings.ts.json sha256:94184309e07268d41cafae75b700ebad7f61d16ef83f3aac4b0f775961916441
+bindings python checksum sha256:74c9d54e22cb43fb1667bab1a6f1c3fecf177cf998756902355bd946f4142380
+artifacts/latex.bindings.python.json sha256:cbdff4ef98335a187bd4a1d3dda2d34af61cfb5d3d0b6c411385ccb3987f0ef8
+grammars/latex.parg sha256:f0694ce57b0f3e99e536b3749eb6b9c56570e4311b1d7aca0047c9e25a668cbf
+data/latex-atoms.json sha256:405440c7f5e90a866e5b36d8145e547572c8c67779984726bcc52c38972950c9
+entries dot comma arabic
+order_warnings 31906