mml 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4edc2cd98bf5ea40cd990bc2f7de88334fda8964d0d50b5c7a3347624276dca6
-  data.tar.gz: aaec60ab3f027aa98e7f1bc8690551714414f463802cd981c6f724da8c4c8e9a
+  metadata.gz: 0edf00bb97f74177c28a416132046bd265a61a8720de3a0a9d1b9515721170db
+  data.tar.gz: 9b11f8ecc3869145617584f9afb422ae3ced36db62994f89750483f039e1bb99
 SHA512:
-  metadata.gz: d6db4bcf4ae1dd66116a5e6e5a90915f2e03ccf205840752fcf682f693e0078a46a38a89f5fa7178101d2fa0400c4638d3afda8561ecc6cdd7ec04f75b5b7b6f
-  data.tar.gz: 412834bc7a1872505e480d35c01a58c35cde48eeac5525239d6da2d0622e67597a2735ada95baf0f9fa77c4155c330e8597b98b960282e364d3399a8f5de37d3
+  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

@@ -1,11 +1,14 @@
-AllCops:
-  TargetRubyVersion: 3.0
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+  - .rubocop_todo.yml
 
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
+plugins:
+- rubocop-performance
+- rubocop-rake
+- rubocop-rspec
 
-Documentation:
-  Enabled: false
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'

data/.rubocop_todo.yml

@@ -0,0 +1,52 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# 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: 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
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Exclude:
+    - 'mml.gemspec'
+    - 'spec/mml_spec.rb'
+    - 'spec/spec_helper.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'spec/mml_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: Prefixes, AllowedPatterns.
+# Prefixes: when, with, without
+RSpec/ContextWording:
+  Exclude:
+    - 'spec/mml_spec.rb'
+
+# Offense count: 1
+RSpec/PendingWithoutReason:
+  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:
+  Exclude:
+    - 'spec/mml_spec.rb'

data/Gemfile

@@ -5,11 +5,13 @@ 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"
 gem "rspec", "~> 3.0"
 gem "rubocop"
 gem "rubocop-performance"
-gem "rubocop-rails"
+gem "rubocop-rake"
+gem "rubocop-rspec"

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

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

data/lib/mml/configuration.rb

@@ -2,7 +2,7 @@
 
 module Mml
   module Configuration
-    SUPPORTED_TAGS = %w[
+    SUPPORTED_TAGS = %i[
       mmultiscripts
       maligngroup
       malignmark
@@ -42,6 +42,37 @@ module Mml
       ms
     ].freeze
 
+    COMMON_ATTRIBUTES_CLASSES = %w[
+      Math
+      Mmultiscripts
+      Munderover
+      Semantics
+      Mscarries
+      Mfraction
+      Mlongdiv
+      Mphantom
+      Menclose
+      Mfenced
+      Mpadded
+      Msubsup
+      Msgroup
+      Mscarry
+      Munder
+      Mstyle
+      Mstack
+      Merror
+      Mover
+      Mfrac
+      Msrow
+      Mroot
+      Msqrt
+      Mrow
+      Msub
+      Msup
+      Mtd
+      Ms
+    ].freeze
+
     module_function
 
     def config
@@ -62,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

@@ -5,19 +5,15 @@ module Mml
     attribute :mathcolor, :string
     attribute :mathbackground, :string
     attribute :notation, :string
-    Mml::Configuration::SUPPORTED_TAGS.each do |tag|
-      attribute :"#{tag}_value", Mml.const_get(tag.capitalize), collection: true
-    end
 
     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
-      Mml::Configuration::SUPPORTED_TAGS.each do |tag|
-        map_element tag.to_sym, to: :"#{tag}_value"
-      end
+      map_attribute "mathcolor", to: :mathcolor
+      map_attribute "mathbackground", to: :mathbackground
+      map_attribute "notation", to: :notation
     end
   end
 end

data/lib/mml/merror.rb

@@ -4,18 +4,14 @@ module Mml
   class Merror < Lutaml::Model::Serializable
     attribute :mathbackground, :string
     attribute :mathcolor, :string
-    Mml::Configuration::SUPPORTED_TAGS.each do |tag|
-      attribute :"#{tag}_value", Mml.const_get(tag.capitalize), collection: true
-    end
 
     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
-      Mml::Configuration::SUPPORTED_TAGS.each do |tag|
-        map_element tag.to_sym, to: :"#{tag}_value"
-      end
+      map_attribute "mathcolor", to: :mathcolor
+      map_attribute "mathbackground", to: :mathbackground
     end
   end
 end