mml 2.0.3 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4534e22a8c030145f41918044bbfb90390f9dc769cb6cc6c00494bfd308f959
-  data.tar.gz: 935e60485c754b7c5cc9d0a3a7e7a07e4674ba584f5f439de2d77f2428b0a406
+  metadata.gz: efbc2e4b8156916d34e524d2f7b6456168f8ef4a0c0c2ade8fbfb2b02bdc2efb
+  data.tar.gz: 8f826d13adfc7f0b556aa5ab6f32f8e8390bf06002a76570845605af7282058a
 SHA512:
-  metadata.gz: e535b06933158eed3b043dc21464c2b2f1d199a7b3f8d563bf4065173e28219dd76dbd5c8d874f5e7f6617d5ffa13140befe1c4d92c5bbe79b8603c16245d5bb
-  data.tar.gz: d45a10ba72fe8c6830cfc4d7e481837e8035807a22f7f4e16f7c117e99d967fd014bea1b5d0eb778fca11daa1754ba7443891729a89d74b7e6f1db09125a1c0d
+  metadata.gz: 694df3fcc6b3611d6bac5b5c380b420b91823e697b219ba93a5d9ec22c70d910f8ecef6fef6c419b1acf80660d726259056717380faf8e77d235879b056e3c85
+  data.tar.gz: 72b8f2d1960adec6a3777e43c792cf3d1d3aa4658be47e5bdbf9f7e5cd428ac1dbd3990d7c1685ae4f6ed1a90566b80932046c15424bf4b6a94efa4e39360a29

data/.github/workflows/release.yml

@@ -2,20 +2,26 @@
 # See https://github.com/metanorma/cimas
 name: release
 
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
 on:
   workflow_dispatch:
     inputs:
       next_version:
         description: |
-          Next release version. Possible values: x.y.z, major, minor, patch or pre|rc|etc
+          Next release version. Possible values: x.y.z, major, minor, patch (or pre|rc|etc).
+          Also, you can pass 'skip' to skip 'git tag' and do 'gem push' for the current version
         required: true
         default: 'skip'
-  push:
-    tags: [ v* ]
+  repository_dispatch:
+    types: [ do-release ]
 
 jobs:
   release:
-    uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
+    uses: relaton/support/.github/workflows/release.yml@main
     with:
       next_version: ${{ github.event.inputs.next_version }}
     secrets:

data/.gitignore

@@ -9,3 +9,5 @@
 
 # rspec failure tracking
 .rspec_status
+
+Gemfile.lock

data/.rubocop.yml

@@ -2,7 +2,7 @@ inherit_from:
   - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
   - .rubocop_todo.yml
 
-require:
+plugins:
 - rubocop-performance
 - rubocop-rake
 - rubocop-rspec

data/.rubocop_todo.yml

@@ -1,115 +1,44 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-03-29 09:22:55 UTC using RuboCop version 1.75.1.
+# on 2026-03-31 03:44:08 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 2
+# Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Include.
-# Include: **/*.gemspec
-Gemspec/AddRuntimeDependency:
-  Exclude:
-    - 'mml.gemspec'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Severity, Include.
-# Include: **/*.gemspec
-Gemspec/DeprecatedAttributeAssignment:
-  Exclude:
-    - 'mml.gemspec'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Severity, Include.
-# Include: **/*.gemspec
-Gemspec/RequireMFA:
-  Exclude:
-    - 'mml.gemspec'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'lib/mml/common_attributes.rb'
-
-# Offense count: 6
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
-# SupportedHashRocketStyles: key, separator, table
-# SupportedColonStyles: key, separator, table
-# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
-Layout/HashAlignment:
-  Exclude:
-    - 'lib/mml/mscarries.rb'
-    - 'lib/mml/mstyle.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: normal, indented_internal_methods
-Layout/IndentationConsistency:
-  Exclude:
-    - 'mml.gemspec'
-
-# Offense count: 8
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Max, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Exclude:
-    - 'lib/mml/common_attributes.rb'
-    - 'lib/mml/mscarries.rb'
-    - 'lib/mml/mstyle.rb'
     - 'mml.gemspec'
-
-# Offense count: 7
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'lib/mml/common_attributes.rb'
-    - 'lib/mml/mscarries.rb'
-    - 'lib/mml/mstyle.rb'
+    - 'spec/mml_spec.rb'
+    - 'spec/spec_helper.rb'
 
 # Offense count: 1
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 27
+
+# Offense count: 3
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
   Exclude:
+    - 'spec/mml4_spec.rb'
     - 'spec/mml_spec.rb'
 
-# Offense count: 5
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: SkipBlocks, EnforcedStyle, OnlyStaticConstants.
-# SupportedStyles: described_class, explicit
-RSpec/DescribedClass:
-  Exclude:
-    - 'spec/mml_spec.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-Style/FileRead:
+# Offense count: 1
+RSpec/MultipleDescribes:
   Exclude:
     - 'spec/mml_spec.rb'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
-# SupportedStyles: single_quotes, double_quotes
-Style/StringLiterals:
-  Exclude:
-    - 'mml.gemspec'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: single_quotes, double_quotes
-Style/StringLiteralsInInterpolation:
+# Offense count: 1
+# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
+# SupportedInflectors: default, active_support
+RSpec/SpecFilePathFormat:
   Exclude:
-    - 'spec/mml_spec.rb'
+    - '**/spec/routing/**/*'
+    - 'spec/mml4_spec.rb'

data/Gemfile

@@ -5,7 +5,8 @@ source "https://rubygems.org"
 gemspec
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-gem "equivalent-xml"
+gem "canon"
+gem "lutaml-model", github: "lutaml/lutaml-model", branch: "main"
 gem "ox"
 gem "pry"
 gem "rake", "~> 12.0"

data/README.adoc

@@ -1,9 +1,370 @@
-= Plurimath MathML library
+= Mml: MathML parser and builder
+
+:toc:
+:toclevels: 2
 
 == Purpose
 
-Mml is the MathML library used by Plurimath.
+Mml provides MathML 3 and MathML 4 XML parsing and serialization for Ruby. It maps
+the full MathML element set into Ruby model classes using the
+https://github.com/lutaml/lutaml-model[lutaml-model] framework and is used by
+https://github.com/plurimath/plurimath[Plurimath] for mathematical formula
+representation.
+
+Key features:
+
+* **Dual MathML version support**: Separate class hierarchies for MathML 3 and
+  MathML 4 with explicit version selection
+* **Round-trip fidelity**: Parse XML to an object graph, modify, and serialize back
+* **Namespace handling**: Default `xmlns`, prefixed `mml:`, and namespace-less input
+* **Opal support**: Runs in the browser via Ruby-to-JavaScript compilation
+
+== Installation
+
+[source,ruby]
+----
+gem 'mml'
+----
+
+[source,bash]
+----
+$ bundle install
+# or
+$ gem install mml
+----
+
+== Quick start
+
+[source,ruby]
+----
+require "mml"
+
+# Parse MathML (defaults to MathML 3)
+math = Mml.parse('<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>')
+
+# Serialize back to XML
+math.to_xml
+# => "<math xmlns=\"http://www.w3.org/1998/Math/MathML\"><mi>x</mi></math>"
+
+# Parse with explicit version
+math4 = Mml.parse(input, version: 4)
+----
+
+== MathML version architecture
+
+Mml maintains two parallel class hierarchies under `Mml::V3` and `Mml::V4`.
+Both versions share the same namespace URI (`http://www.w3.org/1998/Math/MathML`)
+for backward compatibility.
+
+[source]
+----
+                   ┌───────────────────────────────────────────┐
+                   │                   Mml                     │
+                   │  (aliases Mml::V3 for backward compat)    │
+                   └────────────────────┬──────────────────────┘
+                                        │
+                    ┌───────────────────┴────────────────────┐
+                    │                                        │
+               ┌────┴────┐                              ┌────┴────┐
+               │ Mml::V3 │                              │ Mml::V4 │
+               └────┬────┘                              └────┬────┘
+                    │                                        │
+    ┌───────────────┼─────────────────────┐  ┌───────────────┼───────────────┐
+    │  ┌────────────┴───────────────┐     │  │  ┌────────────┴────────────┐  │
+    │  │ Element classes            │     │  │  │ Element classes         │  │
+    │  │ (Mi, Mn, Mo, Mrow, ...)    │     │  │  │ (Mi, Mn, Mo, Mrow, ...) │  │
+    │  │                            │     │  │  │ + intent, arg,          │  │
+    │  │ Inherits from              │     │  │  │   displaystyle,         │  │
+    │  │ Lutaml::Model::Serializable│     │  │  │   scriptlevel           │  │
+    │  └────────────┬───────────────┘     │  │  │  + <a> element          │  │
+    │               │                     │  │  └────────────┬────────────┘  │
+    │  ┌────────────┴────────────┐        │  │  ┌────────────┴────────────┐  │
+    │  │ CommonAttributes        │        │  │  │ CommonAttributes        │  │
+    │  │ (child element mixin)   │        │  │  │ (v4 version)            │  │
+    │  └─────────────────────────┘        │  |  └─────────────────────────┘  |
+    └─────────────────────────────────────┘  └───────────────────────────────┘
+                                           │
+                        ┌──────────────────┴──────────────────────┐
+                        │         Lutaml::Model::Serializable     │
+                        │         (XML mapping framework)         │
+                        └─────────────────────────────────────────┘
+----
+
+=== Version selection
+
+[source,ruby]
+----
+Mml.parse(input)              # Default: MathML 3 (Mml::V3)
+Mml.parse(input, version: 3)  # Explicit MathML 3
+Mml.parse(input, version: 4)  # MathML 4 with intent/arg attributes
+Mml::V4.parse(input)          # Direct v4 parsing (no default fallback)
+----
+
+=== Key differences between MathML 3 and MathML 4
+
+[cols="1,2",options="header"]
+|===
+|Feature |MathML 4 additions
+|Universal attributes |`intent`, `arg`, `displaystyle`, `scriptlevel` available on all presentation elements
+|New element |`<a>` hyperlink element with `href`, `hreflang`
+|Deprecated (not serialized) a|
+* `fontfamily`, `fontweight`, `fontstyle`, `fontsize`, `color`, `background` on `mstyle`, `mglyph`, `mspace`
+* `groupalign` on `mtable`, `mtr`, `mlabeledtr`
+* `fence`, `separator` on `mo`
+|Deprecated (recognized but hidden) |`<mlabeledtr>`, `<none>` removed from `CommonAttributes` but classes still exist
+|===
+
+=== Migration from MathML 3 to MathML 4
+
+==== For gem users (upgrading parsing)
+
+If you currently parse MathML and want to use MathML 4 features:
+
+[source,ruby]
+----
+# Change this:
+math = Mml.parse(input)
+
+# To this:
+math = Mml.parse(input, version: 4)
+----
+
+==== For gem users (upgrading serialized output)
+
+If you serialize MathML 4 documents and want to ensure compatibility:
+
+[source,ruby]
+----
+# MathML 4 serialization removes deprecated attributes from XML output
+math = Mml.parse(input, version: 4)
+math.to_xml  # No fontfamily, fontweight, color, groupalign, etc. in output
+----
+
+==== For gem extenders (adding custom elements)
+
+Custom elements registered via `Configuration.custom_models` are version-specific:
+
+[source,ruby]
+----
+# Register a custom element for MathML 4 only
+Mml::V4::Configuration.custom_models = { Mi => MyCustomMiV4 }
+----
+
+CommonAttributes is version-specific. Elements that exist only in v4 (like `<a>`)
+are automatically handled:
+
+[source,ruby]
+----
+# The <a> element is only in v4 CommonAttributes
+Mml::V4::Mrow.new(a_value: [Mml::V4::A.new(href: "https://...")])
+----
+
+== Parsing and serialization
+
+=== Parsing
+
+[source,ruby]
+----
+# Default namespace
+Mml.parse('<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>')
+
+# Prefixed namespace
+Mml.parse('<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"><mml:mi>x</mml:mi></mml:math>')
+
+# No namespace (namespace injected internally)
+Mml.parse("<math><mi>x</mi></math>", namespace_exist: false)
+----
+
+=== Serialization
+
+[source,ruby]
+----
+math.to_xml
+# => "<math xmlns=\"http://www.w3.org/1998/Math/MathML\"><mi>x</mi></math>"
+
+math.to_xml(prefix: true)
+# => "<mml:math xmlns:mml=\"http://www.w3.org/1998/Math/MathML\"><mml:mi>x</mml:mi></mml:math>"
+
+math.to_xml(declaration: false)
+# => "<math xmlns=\"...\"><mi>x</mi></math>"
+----
+
+=== Round-trip (parse, modify, serialize)
+
+[source,ruby]
+----
+math = Mml.parse('<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>')
+math.display = "block"
+math.to_xml
+# => "<math xmlns=\"http://www.w3.org/1998/Math/MathML\" display=\"block\"><mi>x</mi></math>"
+----
+
+== Element reference
+
+=== Element types
+
+*Token elements*: `mi`, `mn`, `mo`, `ms`, `mtext`, `mspace`, `mglyph`
+
+*General layout*: `mrow`, `mfrac`, `msqrt`, `mroot`, `mstyle`, `merror`, `mpadded`, `mphantom`, `mfenced`, `menclose`, `maction`
+
+*Script elements*: `msub`, `msup`, `msubsup`, `munder`, `mover`, `munderover`, `mmultiscripts`, `mprescripts`
+
+*Table elements*: `mtable`, `mtr`, `mtd`
+
+*Row and stack elements*: `mstack`, `msrow`, `mscarries`, `mscarry`, `msline`, `msgroup`, `mlongdiv`
+
+*Semantic elements*: `mfraction`, `semantics`
+
+*v4 only*: `a` (hyperlink)
+
+*Deprecated*: `mlabeledtr`, `none` (classes exist but hidden from CommonAttributes in v4)
+
+=== Token elements (leaf nodes)
+
+Token elements hold text content in the `value` attribute:
+
+[source,ruby]
+----
+Mml::Mi.new(value: "x")
+Mml::Mn.new(value: "42")
+Mml::Mo.new(value: "+")
+Mml::Ms.new(value: "text")
+Mml::Mtext.new(value: "label")
+Mml::Mspace.new(width: "1em")
+Mml::Mglyph.new(alt: "symbol")
+----
+
+=== Container elements
+
+Container elements hold child elements via `#{tag}_value` collection attributes:
+
+[source,ruby]
+----
+Mml::Mrow.new(
+  mi_value: [Mml::Mi.new(value: "x")],
+  mo_value: [Mml::Mo.new(value: "+")],
+  mn_value: [Mml::Mn.new(value: "1")],
+)
+# => <mrow><mi>x</mi><mo>+</mo><mn>1</mn></mrow>
+----
+
+=== Composing expressions
+
+Build an expression tree by nesting elements:
+
+[source,ruby]
+----
+Mml::Math.new(
+  mfrac_value: [
+    Mml::Mfrac.new(
+      mi_value: [Mml::Mi.new(value: "a"), Mml::Mi.new(value: "b")],
+    ),
+  ],
+)
+# => <math><mfrac><mi>a</mi><mi>b</mi></mfrac></math>
+----
+
+=== Tables
+
+[source,ruby]
+----
+Mml::Mtable.new(
+  mtr_value: [
+    Mml::Mtr.new(
+      mtd_value: [
+        Mml::Mtd.new(mi_value: [Mml::Mi.new(value: "a")]),
+        Mml::Mtd.new(mi_value: [Mml::Mi.new(value: "b")]),
+      ],
+    ),
+  ],
+)
+----
+
+=== Hyperlinks (MathML 4 only)
+
+[source,ruby]
+----
+Mml::V4::A.new(
+  href: "https://example.com",
+  hreflang: "en",
+  mi_value: [Mml::V4::Mi.new(value: "click")]
+)
+# => <a href="https://example.com" hreflang="en"><mi>click</mi></a>
+----
+
+== Internal architecture
+
+=== Element class patterns
+
+All element classes inherit from `Lutaml::Model::Serializable`:
+
+* *Leaf elements*: use `map_content to: :value` for text content
+* *Container elements*: use `mixed_content` for child elements
+
+[source,ruby]
+----
+# Leaf — text content
+class Mi < Lutaml::Model::Serializable
+  attribute :value, :string
+  xml do
+    element "mi"
+    map_content to: :value
+  end
+end
+
+# Container — child elements
+class Mrow < Lutaml::Model::Serializable
+  xml do
+    element "mrow"
+    mixed_content
+  end
+end
+----
+
+=== CommonAttributes
+
+Container elements that accept arbitrary MathML children import `CommonAttributes`,
+which defines `#{tag}_value` collection attributes for all supported child elements.
+The list of classes that receive this mixin is in
+`Configuration::COMMON_ATTRIBUTES_CLASSES`.
+
+=== Namespace
+
+All elements use the MathML namespace URI (`http://www.w3.org/1998/Math/MathML`).
+Three input forms are supported:
+
+* Default namespace: `<math xmlns="http://www.w3.org/1998/Math/MathML">`
+* Prefixed: `<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML">`
+* No namespace: namespace is injected before parsing when `namespace_exist: false`
+
+== Configuration
+
+[source,ruby]
+----
+# Switch XML adapter (default: :ox, also supports :nokogiri)
+Mml::Configuration.adapter = :nokogiri
+
+# Register custom model replacements
+Mml::Configuration.custom_models = { Mi => MyCustomMi }
+----
+
+== Development
+
+[source,bash]
+----
+rake                    # Run specs + rubocop
+bundle exec rspec       # Run tests
+bundle exec rubocop     # Lint
+bin/console             # Interactive IRB
+----
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/plurimath/mml.
+
+== Copyright and license
 
-== Copyright and License
+Copyright Ribose Inc.
 
-Copyright (c) 2024 Ribose Inc.
+https://opensource.org/licenses/BSD-2-Clause[BSD-2-Clause License].

data/lib/mml/v3/common_attributes.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mml
+  module V3
+    Mml::V3::Configuration::SUPPORTED_TAGS.each do |tag|
+      autoload(tag.to_s.capitalize.to_sym, "mml/v3/#{tag}.rb")
+    end
+
+    class CommonAttributes < Lutaml::Model::Serializable
+      Mml::V3::Configuration::SUPPORTED_TAGS.each do |tag|
+        attribute :"#{tag}_value", Mml::V3.const_get(tag.to_s.capitalize),
+                  collection: true
+      end
+
+      xml do
+        Mml::V3::Configuration::SUPPORTED_TAGS.each do |tag|
+          map_element tag, to: :"#{tag}_value"
+        end
+      end
+    end
+  end
+end