mml 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0edf00bb97f74177c28a416132046bd265a61a8720de3a0a9d1b9515721170db
-  data.tar.gz: 9b11f8ecc3869145617584f9afb422ae3ced36db62994f89750483f039e1bb99
+  metadata.gz: efbc2e4b8156916d34e524d2f7b6456168f8ef4a0c0c2ade8fbfb2b02bdc2efb
+  data.tar.gz: 8f826d13adfc7f0b556aa5ab6f32f8e8390bf06002a76570845605af7282058a
 SHA512:
-  metadata.gz: ce86364277e4aae63f893d64ccbabb3752beb2acb11f634caaab20fb01b2768902180eab714dbcb69ab91fcc183778004dcbbf50fb3da4f976071effc687d293
-  data.tar.gz: b3ae2643d010604f0a293fbf35ca7d5ad776055a67b9c90293e4fd7a97a7b8ae70735526c5cd3bf2c96cd2528f3d27048069a481590d6119f7fed7a2d9a365da
+  metadata.gz: 694df3fcc6b3611d6bac5b5c380b420b91823e697b219ba93a5d9ec22c70d910f8ecef6fef6c419b1acf80660d726259056717380faf8e77d235879b056e3c85
+  data.tar.gz: 72b8f2d1960adec6a3777e43c792cf3d1d3aa4658be47e5bdbf9f7e5cd428ac1dbd3990d7c1685ae4f6ed1a90566b80932046c15424bf4b6a94efa4e39360a29

data/.rubocop_todo.yml

@@ -1,20 +1,12 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-03-26 05:47:46 UTC using RuboCop version 1.86.0.
+# 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: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'spec/mml_spec.rb'
-
-# Offense count: 5
+# Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -25,28 +17,28 @@ Layout/LineLength:
     - 'spec/spec_helper.rb'
 
 # Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'spec/mml_spec.rb'
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 27
 
-# Offense count: 1
+# Offense count: 3
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
   Exclude:
+    - 'spec/mml4_spec.rb'
     - 'spec/mml_spec.rb'
 
 # Offense count: 1
-RSpec/PendingWithoutReason:
+RSpec/MultipleDescribes:
   Exclude:
     - 'spec/mml_spec.rb'
 
 # Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
-# SupportedStyles: single_quotes, double_quotes
-Style/StringLiterals:
+# 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/README.adoc

@@ -5,181 +5,269 @@
 
 == Purpose
 
-Mml provides MathML 3 XML parsing and serialization for Ruby. It maps the full
-MathML element set into Ruby model classes using the
+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:
 
-* **MathML 3 element support**: 43 elements including presentation markup,
-  tables, scripts, fractions, and more
-* **Namespace handling**: Default `xmlns`, prefixed `mml:`, and namespace-less
-  input
-* **Round-trip fidelity**: Parse XML to an object graph, modify, and serialize
-  back
+* **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
 
-Add to your application's Gemfile:
-
 [source,ruby]
 ----
 gem 'mml'
 ----
 
-Then execute:
-
 [source,bash]
 ----
 $ bundle install
+# or
+$ gem install mml
 ----
 
-Or install directly:
+== Quick start
 
-[source,bash]
+[source,ruby]
 ----
-$ gem install mml
+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)
 ----
 
-== Quick start
+== 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.
 
-=== Parse with a namespace (compliant)
+[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)         │
+                        └─────────────────────────────────────────┘
+----
 
-`Mml.parse` expects a namespace by default (`namespace_exist: true`). It accepts
-both default and prefixed forms:
+=== Version selection
 
 [source,ruby]
 ----
-require "mml"
+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)
+----
 
-# Default namespace
-math = Mml.parse('<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>')
+=== Key differences between MathML 3 and MathML 4
 
-# Prefixed namespace
-math = Mml.parse('<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"><mml:mi>x</mml:mi></mml:math>')
+[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://...")])
 ----
 
-=== Parse without namespace (non-compliant)
+== Parsing and serialization
 
-Some XML schemas embed MathML without a namespace declaration, which is
-non-compliant but common in practice. Pass `namespace_exist: false` to handle
-this — the namespace is injected internally before parsing:
+=== Parsing
 
 [source,ruby]
 ----
-math = Mml.parse("<math><mi>x</mi></math>", namespace_exist: false)
+# 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)
 ----
 
-=== Serialize to XML
+=== Serialization
 
 [source,ruby]
 ----
-# Default namespace (default)
 math.to_xml
 # => "<math xmlns=\"http://www.w3.org/1998/Math/MathML\"><mi>x</mi></math>"
 
-# Prefixed namespace
 math.to_xml(prefix: true)
 # => "<mml:math xmlns:mml=\"http://www.w3.org/1998/Math/MathML\"><mml:mi>x</mml:mi></mml:math>"
 
-# Omit XML declaration
 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
 
-== Building MathML with the API
+*Token elements*: `mi`, `mn`, `mo`, `ms`, `mtext`, `mspace`, `mglyph`
 
-=== Leaf elements
+*General layout*: `mrow`, `mfrac`, `msqrt`, `mroot`, `mstyle`, `merror`, `mpadded`, `mphantom`, `mfenced`, `menclose`, `maction`
 
-Leaf elements (`Mi`, `Mn`, `Mo`, `Ms`, `Mtext`) hold text content in the `value`
-attribute:
+*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]
 ----
-# An identifier: <mi>x</mi>
 Mml::Mi.new(value: "x")
-
-# A number: <mn>42</mn>
 Mml::Mn.new(value: "42")
-
-# An operator: <mo>+</mo>
 Mml::Mo.new(value: "+")
-
-# With attributes: <mi mathvariant="bold">x</mi>
-Mml::Mi.new(value: "x", mathvariant: "bold")
+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 collection attributes named
-`#{tag}_value`. The supported child types come from the `CommonAttributes` model
-mixed into container classes.
+Container elements hold child elements via `#{tag}_value` collection attributes:
 
 [source,ruby]
 ----
-# <mrow><mi>x</mi><mo>+</mo><mn>1</mn></mrow>
 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 complex expressions
+=== Composing expressions
 
-Build an expression tree by nesting elements, then wrap in `Mml::Math`:
+Build an expression tree by nesting elements:
 
 [source,ruby]
 ----
-# <math xmlns="http://www.w3.org/1998/Math/MathML">
-#   <mfrac><mi>a</mi><mi>b</mi></mfrac>
-# </math>
-math = Mml::Math.new(
+Mml::Math.new(
   mfrac_value: [
     Mml::Mfrac.new(
       mi_value: [Mml::Mi.new(value: "a"), Mml::Mi.new(value: "b")],
     ),
   ],
 )
-
-math.to_xml
-----
-
-=== Fractions, subscripts, and superscripts
-
-[source,ruby]
-----
-# <msup><mi>x</mi><mn>2</mn></msup>  —  x²
-Mml::Msup.new(mi_value: [Mml::Mi.new(value: "x")],
-              mn_value: [Mml::Mn.new(value: "2")])
-
-# <msub><mi>a</mi><mn>1</mn></msup>  —  a₁
-Mml::Msub.new(mi_value: [Mml::Mi.new(value: "a")],
-              mn_value: [Mml::Mn.new(value: "1")])
-
-# <msubsup><mi>b</mi><mn>1</mn><mn>2</mn></msubsup>  —  b₁²
-Mml::Msubsup.new(mi_value: [Mml::Mi.new(value: "b")],
-                 mn_value: [Mml::Mn.new(value: "1"),
-                            Mml::Mn.new(value: "2")])
-
-# <mfrac linethickness="0"><mi>a</mi><mi>b</mi></mfrac>  —  a/b
-Mml::Mfrac.new(
-  linethickness: "0",
-  mi_value: [Mml::Mi.new(value: "a"), Mml::Mi.new(value: "b")],
-)
+# => <math><mfrac><mi>a</mi><mi>b</mi></mfrac></math>
 ----
 
 === Tables
 
-`Mtable` uses typed `mtr_value` and `mlabeledtr_value` attributes for its rows:
-
 [source,ruby]
 ----
-# <mtable>
-#   <mtr><mtd><mi>a</mi></mtd><mtd><mi>b</mi></mtd></mtr>
-# </mtable>
 Mml::Mtable.new(
   mtr_value: [
     Mml::Mtr.new(
@@ -192,112 +280,76 @@ Mml::Mtable.new(
 )
 ----
 
-=== Parsing, modifying, and re-serializing
-
-The object graph is fully mutable — parse, modify attributes or children, then
-serialize back:
+=== Hyperlinks (MathML 4 only)
 
 [source,ruby]
 ----
-math = Mml.parse('<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>')
-
-# Modify the root element's display attribute
-math.display = "block"
-
-# Serialize with the changes
-math.to_xml
-# => "<math xmlns=\"http://www.w3.org/1998/Math/MathML\" display=\"block\">...</math>"
+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>
 ----
 
-== Architecture
-
-Mml follows a data mapper pattern where each MathML element is a Ruby class
-under the `Mml::` namespace, inheriting from `Lutaml::Model::Serializable`.
+== Internal architecture
 
-=== Element classes
+=== Element class patterns
 
-Two element patterns:
+All element classes inherit from `Lutaml::Model::Serializable`:
 
-* *Leaf elements* (`Mi`, `Mn`, `Mo`, `Ms`, `Mtext`, `Mspace`): hold text content
-  via `map_content to: :value`
-* *Container elements* (`Math`, `Mrow`, `Mfrac`, `Mtable`, `Msubsup`): hold
-  child elements via `mixed_content`
+* *Leaf elements*: use `map_content to: :value` for text content
+* *Container elements*: use `mixed_content` for child elements
 
 [source,ruby]
 ----
-# Leaf element — text content
-module Mml
-  class Mi < Lutaml::Model::Serializable
-    attribute :value, :string
-
-    xml do
-      namespace Namespace
-      element "mi"
-      map_content to: :value
-    end
+# Leaf — text content
+class Mi < Lutaml::Model::Serializable
+  attribute :value, :string
+  xml do
+    element "mi"
+    map_content to: :value
   end
 end
 
-# Container element — child elements
-module Mml
-  class Mrow < Lutaml::Model::Serializable
-    xml do
-      namespace Namespace
-      element "mrow"
-      mixed_content
-    end
+# Container — child elements
+class Mrow < Lutaml::Model::Serializable
+  xml do
+    element "mrow"
+    mixed_content
   end
 end
 ----
 
 === CommonAttributes
 
-Container elements that can hold arbitrary MathML children use a shared
-`CommonAttributes` model.
-
-The classes that receive it are listed in
+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 declare `namespace Namespace` using the MathML namespace URI
-(`http://www.w3.org/1998/Math/MathML`) with prefix `mml`. The `Mml.parse`
-method handles three input forms:
+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: handled by injecting the namespace before parsing
+* No namespace: namespace is injected before parsing when `namespace_exist: false`
 
-=== Configuration
+== Configuration
 
 [source,ruby]
 ----
-# Switch XML adapter
+# Switch XML adapter (default: :ox, also supports :nokogiri)
 Mml::Configuration.adapter = :nokogiri
 
 # Register custom model replacements
 Mml::Configuration.custom_models = { Mi => MyCustomMi }
 ----
 
-== Supported elements
-
-Mml supports the following MathML 3 presentation elements:
-
-`math`, `mi`, `mn`, `mo`, `ms`, `mtext`, `mspace`, `mglyph`
-`mrow`, `mfrac`, `msqrt`, `mroot`, `mstyle`, `merror`, `mpadded`,
-`mphantom`, `mfenced`, `menclose`, `maction`
-`msub`, `msup`, `msubsup`, `munder`, `mover`, `munderover`,
-`mmultiscripts`, `mprescripts`
-`mtable`, `mtr`, `mtd`, `mlabeledtr`
-`mstack`, `msrow`, `mscarries`, `mscarry`, `msline`, `msgroup`, `mlongdiv`
-`mfraction`, `semantics`, `none`
-
 == Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then run
-`rake` to run the tests and linter. You can also run `bin/console` for an
-interactive prompt.
-
 [source,bash]
 ----
 rake                    # Run specs + rubocop

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