umath 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29cd6743561f1b47beec9dbd77d4afa5cad6b109b8ca1be39f48d7a24d0f5dad
+  data.tar.gz: 3d92b72dbb72d885024387869ac7db8be1f4adcb7e0a6397c264245fd02128b6
+SHA512:
+  metadata.gz: f4e0eb27a7ee0f12455eff207ef4a3d3e58b136786053c6cf633dfcb4767ef58ce4d6fd8ede5f6eb3931850afe2116e709415377be73aca98f395cbfb1d39126
+  data.tar.gz: cdfd7bde07ce5f5a73883ae6daa5bba759dd0d69f303f6447f7e25ec181ad89c3f6bc5c3c60e00ef48c2be59e90632dd04ceeafa101810482266a3d7522aeab8

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.1.0
+
+First release. Umath is the UnicodeMath parser split out of
+Plurimath, as planned in plurimath/plurimath#530 and plurimath/plurimath#541.
+
+- `Umath.parse(input, decimal: ".", engine: :ruby)` returns a
+  `Umath::Model::Document`, a typed model of the formula declared with
+  LutaML Model. Symbols are `Umath::Model::MathSymbol` objects with
+  their spelling, Unicode value and kind, read from the symbol catalog in
+  `data/umath-symbols.json`.
+- Invalid input raises `Umath::ParseError` with the position in the
+  caller's input (`char_offset`, `byte_offset`). Every error Umath
+  raises on purpose is a `Umath::Error`.
+- The grammar is Plurimath's UnicodeMath grammar, compiled with Parsanol
+  into a checksummed artifact (`artifacts/umath.json`). It runs on
+  Parsanol's Ruby engine by default. Parsanol's native engine is an opt-in
+  with `engine: :native` (or `engine: :auto`, which uses native where it is
+  available): for 18 inputs of the testsuite's UnicodeMath fixtures it gives
+  a different tree from the Ruby engine and legacy Plurimath; see the
+  README's section on engines.
+- CI replays the unicode generation of plurimath-testsuite pinned in
+  `spec/fixtures/testsuite-pin.yml`, and compares the parse tree with the
+  pinned Plurimath commit for every UnicodeMath case of the testsuite.
+- Requires Ruby 3.2 or later. The runtime dependencies are Parsanol and
+  LutaML Model.

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

@@ -0,0 +1,155 @@
+= Umath: UnicodeMath parser for Ruby
+
+image:https://img.shields.io/gem/v/umath.svg["Gem Version", link="https://rubygems.org/gems/umath"]
+image:https://github.com/plurimath/umath/actions/workflows/test.yml/badge.svg["Build Status", link="https://github.com/plurimath/umath/actions/workflows/test.yml"]
+
+== Purpose
+
+Umath parses https://www.unicode.org/notes/tn28/[UnicodeMath], the
+linear format for mathematics described in Unicode Technical Note 28, into a
+typed model of the formula. It reads the UnicodeMath that
+https://github.com/plurimath/plurimath[Plurimath] reads, with the same
+grammar, and is built for Plurimath to use for UnicodeMath input
+(https://github.com/plurimath/plurimath/issues/530[plurimath/plurimath#530]).
+
+The model records the structure of the formula: which symbols, fractions,
+scripts, roots, matrices and brackets it contains, and how they nest. Your
+code decides what to do with it, such as rendering, converting or analysing
+it. Umath does not write MathML or any other output format; Plurimath
+does that.
+
+== Installation
+
+Add it to your `Gemfile`:
+
+[source,ruby]
+----
+gem "umath", "~> 0.1.0"
+----
+
+Umath needs Ruby 3.2 or later. Its runtime dependencies are
+https://github.com/parsanol/parsanol-ruby[Parsanol] and
+https://github.com/lutaml/lutaml-model[LutaML Model]. It does not load
+Plurimath.
+
+== Usage
+
+[source,ruby]
+----
+require "umath"
+
+doc = Umath.parse("a/b")
+frac = doc.expression.frac
+frac.numerator.atom.alphanumeric.spelling   # => "a"
+doc.to_hash
+# => {"expression" => {"frac" => {"denominator" => {...}, "numerator" => {...}}}, "decimal" => "."}
+----
+
+`Umath.parse` returns a `Umath::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. Parts that can hold a whole expression, such as a numerator or a
+subscript, share the class `Umath::Model::Expression`. Symbols are
+`Umath::Model::MathSymbol` objects with the text the grammar matched
+(`spelling`), its Unicode text (`value`) and its kind:
+
+[source,ruby]
+----
+symbol = Umath.parse("α").expression.factor.ordinary_symbols
+symbol.spelling # => "α"
+symbol.value    # => "α"
+symbol.kind     # => "symbol"
+----
+
+The spelling is the text after the input has been rewritten as Plurimath
+does (non-ASCII characters become HTML entities), so `value` is usually the
+field you want.
+
+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]
+----
+Umath.parse("1,5", decimal: ",")
+Umath.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 UnicodeMath raises `Umath::ParseError`, which
+tells you where the parser gave up, as a position in the text you passed:
+
+[source,ruby]
+----
+begin
+  Umath.parse("α)")
+rescue Umath::ParseError => e
+  e.char_offset # => 1, position in characters
+  e.byte_offset # => 2, position in UTF-8 bytes
+end
+----
+
+Every error Umath raises on purpose is a `Umath::Error`, except
+`ArgumentError` for an invalid argument, such as input that is not a valid
+UTF-8 string, an unknown engine or an unsupported decimal marker.
+`Umath::NestingTooDeep`, a kind of `ParseError` with no offsets, means
+the engine could not handle how deeply the input nests, not that the input
+is invalid.
+
+== Engines
+
+Umath runs its grammar on Parsanol's pure Ruby engine or on its native
+engine. The default is `engine: :ruby`. You can opt into the native engine
+with `engine: :native`, or with `engine: :auto`, which uses the native
+engine where its extension is available and the Ruby engine elsewhere.
+Asking for `engine: :native` where it cannot run raises
+`Umath::EngineUnavailable` instead of quietly using Ruby.
+`Umath.last_engine` tells you which engine handled the last call on
+the current thread.
+
+Ruby is the default because it is the engine that matches legacy Plurimath.
+For 18 of the inputs in the testsuite's `fixtures/unicode-expectations.yaml`
+that legacy Plurimath accepts, the native engine takes another alternative
+of the same grammar and returns a different tree from the Ruby engine; the
+Ruby engine returns the legacy tree for all of them. These inputs are listed
+in
+link:spec/parser/fixtures/oracle/native-divergences.yml[`spec/parser/fixtures/oracle/native-divergences.yml`],
+and CI checks that they still differ, so the list shrinks when the native
+engine changes. The native engine is faster, and the Ruby engine is slower,
+especially on input it refuses. Choose `engine: :native` when speed matters
+more to you than the legacy tree for those inputs.
+
+== Testing against the Plurimath testsuite
+
+The UnicodeMath 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 commit produces for every UnicodeMath case of the testsuite.
+See link:docs/testsuite-pin.adoc[the testsuite pin].
+
+== Relation to Plurimath
+
+Umath is one of the language gems split out of Plurimath, with
+https://github.com/plurimath/amath[amath] for AsciiMath and
+https://github.com/plurimath/latexmath[latexmath] for LaTeX. 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/umath.bindings.ruby.json

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