mml 2.0.3 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4534e22a8c030145f41918044bbfb90390f9dc769cb6cc6c00494bfd308f959
-  data.tar.gz: 935e60485c754b7c5cc9d0a3a7e7a07e4674ba584f5f439de2d77f2428b0a406
+  metadata.gz: 0edf00bb97f74177c28a416132046bd265a61a8720de3a0a9d1b9515721170db
+  data.tar.gz: 9b11f8ecc3869145617584f9afb422ae3ced36db62994f89750483f039e1bb99
 SHA512:
-  metadata.gz: e535b06933158eed3b043dc21464c2b2f1d199a7b3f8d563bf4065173e28219dd76dbd5c8d874f5e7f6617d5ffa13140befe1c4d92c5bbe79b8603c16245d5bb
-  data.tar.gz: d45a10ba72fe8c6830cfc4d7e481837e8035807a22f7f4e16f7c117e99d967fd014bea1b5d0eb778fca11daa1754ba7443891729a89d74b7e6f1db09125a1c0d
+  metadata.gz: ce86364277e4aae63f893d64ccbabb3752beb2acb11f634caaab20fb01b2768902180eab714dbcb69ab91fcc183778004dcbbf50fb3da4f976071effc687d293
+  data.tar.gz: b3ae2643d010604f0a293fbf35ca7d5ad776055a67b9c90293e4fd7a97a7b8ae70735526c5cd3bf2c96cd2528f3d27048069a481590d6119f7fed7a2d9a365da

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,81 +1,35 @@
 # 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-26 05:47:46 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
-# 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'
+    - 'spec/mml_spec.rb'
 
-# Offense count: 8
+# Offense count: 5
 # 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'
+    - 'spec/mml_spec.rb'
+    - 'spec/spec_helper.rb'
 
-# Offense count: 7
+# Offense count: 1
 # 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'
 
 # Offense count: 1
 # Configuration parameters: Prefixes, AllowedPatterns.
@@ -84,32 +38,15 @@ RSpec/ContextWording:
   Exclude:
     - '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/PendingWithoutReason:
   Exclude:
     - 'spec/mml_spec.rb'
 
-# Offense count: 2
+# Offense count: 1
 # 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:
   Exclude:
     - 'spec/mml_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,318 @@
-= Plurimath MathML library
+= Mml: MathML parser and builder
+
+:toc:
+:toclevels: 2
 
 == Purpose
 
-Mml is the MathML library used by Plurimath.
+Mml provides MathML 3 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
+* **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 install directly:
+
+[source,bash]
+----
+$ gem install mml
+----
+
+== Quick start
+
+=== Parse with a namespace (compliant)
+
+`Mml.parse` expects a namespace by default (`namespace_exist: true`). It accepts
+both default and prefixed forms:
+
+[source,ruby]
+----
+require "mml"
+
+# Default namespace
+math = Mml.parse('<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>')
+
+# Prefixed namespace
+math = Mml.parse('<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"><mml:mi>x</mml:mi></mml:math>')
+----
+
+=== Parse without namespace (non-compliant)
+
+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:
+
+[source,ruby]
+----
+math = Mml.parse("<math><mi>x</mi></math>", namespace_exist: false)
+----
+
+=== Serialize to XML
+
+[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)
+----
+
+== Building MathML with the API
+
+=== Leaf elements
+
+Leaf elements (`Mi`, `Mn`, `Mo`, `Ms`, `Mtext`) 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")
+----
+
+=== 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.
+
+[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")],
+)
+----
+
+=== Composing complex expressions
+
+Build an expression tree by nesting elements, then wrap in `Mml::Math`:
+
+[source,ruby]
+----
+# <math xmlns="http://www.w3.org/1998/Math/MathML">
+#   <mfrac><mi>a</mi><mi>b</mi></mfrac>
+# </math>
+math = 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")],
+)
+----
+
+=== 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(
+      mtd_value: [
+        Mml::Mtd.new(mi_value: [Mml::Mi.new(value: "a")]),
+        Mml::Mtd.new(mi_value: [Mml::Mi.new(value: "b")]),
+      ],
+    ),
+  ],
+)
+----
+
+=== Parsing, modifying, and re-serializing
+
+The object graph is fully mutable — parse, modify attributes or children, then
+serialize back:
+
+[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>"
+----
+
+== Architecture
+
+Mml follows a data mapper pattern where each MathML element is a Ruby class
+under the `Mml::` namespace, inheriting from `Lutaml::Model::Serializable`.
+
+=== Element classes
+
+Two element patterns:
+
+* *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`
+
+[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
+  end
+end
+
+# Container element — child elements
+module Mml
+  class Mrow < Lutaml::Model::Serializable
+    xml do
+      namespace Namespace
+      element "mrow"
+      mixed_content
+    end
+  end
+end
+----
+
+=== CommonAttributes
+
+Container elements that can hold arbitrary MathML children use a shared
+`CommonAttributes` model.
+
+The classes that receive it are listed 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:
+
+* 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
+
+=== Configuration
+
+[source,ruby]
+----
+# Switch XML adapter
+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
+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/common_attributes.rb

@@ -13,8 +13,6 @@ module Mml
     end
 
     xml do
-      no_root
-
       Mml::Configuration::SUPPORTED_TAGS.each do |tag|
         map_element tag, to: :"#{tag}_value"
       end

data/lib/mml/configuration.rb

@@ -43,8 +43,7 @@ module Mml
     ].freeze
 
     COMMON_ATTRIBUTES_CLASSES = %w[
-      MathWithNilNamespace
-      MathWithNamespace
+      Math
       Mmultiscripts
       Munderover
       Semantics
@@ -94,7 +93,7 @@ module Mml
     end
 
     def adapter=(adapter)
-      Lutaml::Model::Config.xml_adapter_type = adapter.downcase
+      Lutaml::Model::Config.xml_adapter_type = adapter
     end
 
     def class_for(class_name)

data/lib/mml/maction.rb

@@ -8,12 +8,13 @@ module Mml
     attribute :selection, :string
 
     xml do
-      root "maction"
+      namespace Namespace
+      element "maction"
 
-      map_attribute "mathcolor", to: :mathcolor, namespace: nil
-      map_attribute "mathbackground", to: :mathbackground, namespace: nil
-      map_attribute "actiontype", to: :actiontype, namespace: nil
-      map_attribute "selection", to: :selection, namespace: nil
+      map_attribute "mathcolor", to: :mathcolor
+      map_attribute "mathbackground", to: :mathbackground
+      map_attribute "actiontype", to: :actiontype
+      map_attribute "selection", to: :selection
     end
   end
 end

data/lib/mml/maligngroup.rb

@@ -7,11 +7,12 @@ module Mml
     attribute :groupalign, :string
 
     xml do
-      root "maligngroup"
+      namespace Namespace
+      element "maligngroup"
 
-      map_attribute "mathcolor", to: :mathcolor, namespace: nil
-      map_attribute "mathbackground", to: :mathbackground, namespace: nil
-      map_attribute "groupalign", to: :groupalign, namespace: nil
+      map_attribute "mathcolor", to: :mathcolor
+      map_attribute "mathbackground", to: :mathbackground
+      map_attribute "groupalign", to: :groupalign
     end
   end
 end

data/lib/mml/malignmark.rb

@@ -7,11 +7,12 @@ module Mml
     attribute :edge, :string
 
     xml do
-      root "malignmark"
+      namespace Namespace
+      element "malignmark"
 
-      map_attribute "mathcolor", to: :mathcolor, namespace: nil
-      map_attribute "mathbackground", to: :mathbackground, namespace: nil
-      map_attribute "edge", to: :edge, namespace: nil
+      map_attribute "mathcolor", to: :mathcolor
+      map_attribute "mathbackground", to: :mathbackground
+      map_attribute "edge", to: :edge
     end
   end
 end

data/lib/mml/math.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mml
+  class Math < Lutaml::Model::Serializable
+    attribute :display, :string
+
+    xml do
+      namespace Namespace
+      element "math"
+      mixed_content
+
+      map_attribute :display, to: :display
+    end
+  end
+
+  # For backward compatibility, we keep MathWithNamespace as an alias to Math.
+  MathWithNamespace = Math
+end

data/lib/mml/menclose.rb

@@ -7,11 +7,13 @@ module Mml
     attribute :notation, :string
 
     xml do
-      root "menclose", mixed: true
+      namespace Namespace
+      element "menclose"
+      mixed_content
 
-      map_attribute "mathcolor", to: :mathcolor, namespace: nil
-      map_attribute "mathbackground", to: :mathbackground, namespace: nil
-      map_attribute "notation", to: :notation, namespace: nil
+      map_attribute "mathcolor", to: :mathcolor
+      map_attribute "mathbackground", to: :mathbackground
+      map_attribute "notation", to: :notation
     end
   end
 end

data/lib/mml/merror.rb

@@ -6,10 +6,12 @@ module Mml
     attribute :mathcolor, :string
 
     xml do
-      root "merror", mixed: true
+      namespace Namespace
+      element "merror"
+      mixed_content
 
-      map_attribute "mathcolor", to: :mathcolor, namespace: nil
-      map_attribute "mathbackground", to: :mathbackground, namespace: nil
+      map_attribute "mathcolor", to: :mathcolor
+      map_attribute "mathbackground", to: :mathbackground
     end
   end
 end

data/lib/mml/mfenced.rb

@@ -10,15 +10,17 @@ module Mml
     attribute :open, :string
 
     xml do
-      root "mfenced", mixed: true
+      namespace Namespace
+      element "mfenced"
+      mixed_content
 
       map_content to: :content
 
-      map_attribute "mathbackground", to: :mathbackground, namespace: nil
-      map_attribute "separators", to: :separators, namespace: nil
-      map_attribute "mathcolor", to: :mathcolor, namespace: nil
-      map_attribute "close", to: :close, namespace: nil
-      map_attribute "open", to: :open, namespace: nil
+      map_attribute "mathbackground", to: :mathbackground
+      map_attribute "separators", to: :separators
+      map_attribute "mathcolor", to: :mathcolor
+      map_attribute "close", to: :close
+      map_attribute "open", to: :open
     end
   end
 end