omml 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 396fdf98892abceb0356b66ddc126cd1bf17dd09b56d20d6e300acb70581bbb7
-  data.tar.gz: 375640f63f5c1fc558e63d8124a38f450a7ff899e433c2f5ad629e70594d96b0
+  metadata.gz: 601a769419b5024287dbaf137b26684b871295bd560e9a8e48c46c11293893aa
+  data.tar.gz: 004b46f3db7b23ecf117d67a8d8dadf20aede7a7ca3fc17477dec6027127cec5
 SHA512:
-  metadata.gz: 429a2e4d69e94fbd3af19e5675cac37596400749953653523bfcf82971a05811519745f3c2691aadb3b5d941bf88eed2309c3402d894a0c0f255b519b7b05d5c
-  data.tar.gz: 4fac51cee7307f401d99a49f2a198b58d1a7792d0ff2835c7a3b2eaa597b1fa1ed149654c25a48b5137fc35fc6c7ba97e2d3941f4cc97fabdc387e25615b8943
+  metadata.gz: c290b2273ca8bfc569fae9a7bb42a8b00cd58ca94638308a275f1adef89e44462493101e26ab5f5b8dfcc68ab601311851413e9a253ae60187aca13d7655ebda
+  data.tar.gz: aacf63d8d5c2b9ff51fba1f2f6da289ac435899c3c8ba6e9ff03430bb61a0347888cd8367693ab717bcf268aaa8a17a89acb47fe5b2161c40e3e93a645f40184

data/.github/workflows/rake.yml

@@ -0,0 +1,22 @@
+name: rake
+
+on:
+  push:
+    branches: [ main ]
+    tags: [ v* ]
+  pull_request:
+
+jobs:
+  rake:
+    uses: metanorma/ci/.github/workflows/generic-rake.yml@main
+    with:
+      # This is to fix Ruby 3.4 on Windows, as per lutaml/lutaml-model#447
+      before-setup-ruby: |
+        mkdir -p .bundle
+        touch .bundle/config
+        cat .bundle/config
+        echo "---" >> .bundle/config
+        echo 'BUNDLE_BUILD__RUBY___LL: "--with-cflags=-std=gnu17"' >> .bundle/config
+        cat .bundle/config
+    secrets:
+      pat_token: ${{ secrets.PLURIMATH_CI_PAT_TOKEN }}

data/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+name: release
+
+on:
+  workflow_dispatch:
+    inputs:
+      next_version:
+        description: |
+          Next release version. Possible values: x.y.z, major, minor, patch or pre|rc|etc
+        required: true
+        default: 'skip'
+  push:
+    tags: [ v* ]
+
+jobs:
+  release:
+    permissions:
+      contents: write
+      id-token: write
+    uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
+    with:
+      next_version: ${{ github.event.inputs.next_version }}
+    secrets:
+      rubygems-api-key: ${{ secrets.PLURIMATH_CI_RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1 @@
+.rspec_status

data/.rubocop.yml

@@ -0,0 +1,25 @@
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+  - .rubocop_todo.yml
+
+plugins:
+- rubocop-performance
+- rubocop-rake
+- rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+
+Metrics/BlockLength:
+  AllowedMethods:
+    - choice
+    - xml
+
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleExpectations:
+  Max: 10

data/.rubocop_todo.yml

@@ -0,0 +1,19 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2026-05-01 11:14:00 UTC using RuboCop version 1.86.1.
+# 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
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
+Metrics/AbcSize:
+  Exclude:
+    - 'spec/omml_fixture_round_trip_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: .
+# SupportedStyles: have_received, receive
+RSpec/MessageSpies:
+  EnforcedStyle: receive

data/CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`omml` is a Ruby gem that parses and serializes OMML (Office Math Markup Language), the XML format used by Microsoft Word for mathematical equations. It is part of the [Plurimath](https://github.com/plurimath) ecosystem. Models are defined using `lutaml-model` (declarative XML serialization) with `ox` as the XML backend.
+
+## Commands
+
+```bash
+bundle install          # Install dependencies
+bundle exec rake        # Run specs + rubocop (default task)
+bundle exec rspec       # Run all specs
+bundle exec rspec spec/omml_spec.rb              # Run a single spec file
+bundle exec rspec spec/omml_spec.rb:77           # Run a single test by line number
+bundle exec rubocop     # Lint
+```
+
+## Architecture
+
+### Entry point and parsing flow
+
+`Omml.parse(xml_string)` → `Parser.parse` → parses XML via the adapter → resolves the root class (`OMath` or `OMathPara` based on root element name) → calls `.of_xml` to deserialize into a Lutaml model tree.
+
+The top-level API is in `lib/omml.rb`. `Parser` in `lib/omml/parser.rb` handles the parsing pipeline.
+
+### Type context system (`Omml::Configuration`)
+
+`Configuration` manages a Lutaml `GlobalContext` (context ID `:omml`) that holds a registry of all model classes. Models are registered via `Omml::Configuration.register_model(Class)` at load time, and the context is populated lazily on first parse. Custom contexts can be created for downstream libraries (e.g., Plurimath) that fall back to the OMML context.
+
+Model IDs are derived from class names: prefix `CT`/`EG`/`ST` is stripped and snake-cased with the prefix (e.g., `CTOMath` → `:ct_o_math`).
+
+### Model layer (`lib/omml/models/`)
+
+Three categories of models, all extending `Lutaml::Model::Serializable`:
+
+- **Complex types** (`ct_*.rb`) — represent OMML schema complex types. Each defines attributes and XML element mappings, and self-registers via `Omml::Configuration.register_model`.
+- **Simple types** (`simple_types/*.rb`) — enum/value types like `STJc`, `STOnOff`. These wrap string values with validation.
+- **Group models** (`groups/*.rb`) — shared compositional groups (e.g., `EGOMathElements`). These use `import_model_attributes` / `import_model_mappings` to compose attributes from other groups, implementing the OMML schema's choice/sequence patterns.
+
+Root element wrappers (`o_math.rb`, `o_math_para.rb`) extend `CommonCode::RootModel` and use `omml_root_element` to declare themselves as XML root elements with the OMML namespace.
+
+### Namespaces
+
+- `Omml::Namespace` — the OMML namespace (`http://schemas.openxmlformats.org/officeDocument/2006/math`, prefix `m`)
+- `Omml::WordprocessingNamespace` — the Word ML namespace (prefix `w`), used for elements like `w:rPr` that appear inside OMML
+
+### Type substitutions (`TypeSubstitutions`)
+
+Many OMML simple types are aliases for built-in Lutaml types (e.g., `STString` → `Lutaml::Model::Type::String`). These are registered as aliases in the context rather than as separate model classes.
+
+## Testing
+
+- `spec/omml_spec.rb` — unit tests for parsing, context management, and error handling
+- `spec/fixture_round_trip_spec.rb` — parses 279 OMML fixture files from `spec/fixtures/omml/`, round-trips them through parse → serialize, and compares the XML trees structurally (not string-equality). This is the primary correctness check.
+- The round-trip spec expects exact XML structural fidelity: same elements, attributes, namespaces, text content, and child ordering.
+
+## Key conventions
+
+- All models are in the `Omml::Models` module namespace
+- The XML adapter defaults to `:ox` (MRI) or `:oga` (Opal)
+- Models use `ordered` and `sequence` blocks for XML mapping to preserve element order
+- `render_empty: true` is used on elements that must be emitted even when empty

data/Gemfile

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 gemspec
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-gem 'pry'
-gem 'rake', '~> 12.0'
-gem 'rspec', '~> 3.0'
-gem 'rubocop'
-gem 'rubocop-performance'
-gem 'rubocop-rails'
+# TODO: remove this override once lutaml-model 0.8.0 is released.
+gem "lutaml-model", github: "lutaml/lutaml-model", branch: "main"
+
+gem "pry"
+gem "rake", "~> 12.0"
+gem "rspec", "~> 3.0"
+gem "rubocop"
+gem "rubocop-performance"
+gem "rubocop-rake"
+gem "rubocop-rspec"

data/README.adoc

@@ -1,9 +1,227 @@
-= Plurimath OMML library
+= Omml: OMML parser and builder for Ruby
+
+:toc:
+:toclevels: 2
 
 == Purpose
 
-`omml` is the OMML (Office Math Markup Language) library used by Plurimath.
+Omml provides OMML (Office Math Markup Language) XML parsing and serialization
+for Ruby. It maps the full OMML 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:
+
+* **Round-trip fidelity**: Parse XML to an object graph, modify, and serialize back
+* **Full schema coverage**: 172 complex types, 53 simple types, and 17 group models
+  generated from the OOXML Shared Math schema (`shared-math.xsd`)
+* **Namespace handling**: OMML namespace with `m:` prefix, plus Word ML namespace
+  for embedded `w:rPr` run properties
+* **Opal support**: Runs in the browser via Ruby-to-JavaScript compilation
+
+== Installation
+
+[source,ruby]
+----
+gem 'omml'
+----
+
+[source,bash]
+----
+$ bundle install
+# or
+$ gem install omml
+----
+
+== Quick start
+
+[source,ruby]
+----
+require "omml"
+
+# Parse OMML XML
+math = Omml.parse('<m:oMath xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math"><m:r><m:t>x</m:t></m:r></m:oMath>')
+# => #<Omml::Models::OMath:...>
+
+# Serialize back to XML
+math.to_xml(prefix: 'm')
+# => "<m:oMath xmlns:m=\"...\">...</m:oMath>"
+----
+
+== Parsing and serialization
+
+=== Parsing
+
+`Omml.parse` accepts an XML string and returns a model tree. The root element
+determines the wrapper class:
+
+* `<m:oMath>` → `Omml::Models::OMath`
+* `<m:oMathPara>` → `Omml::Models::OMathPara`
+
+[source,ruby]
+----
+# oMath root
+math = Omml.parse('<m:oMath xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math"><m:r><m:t>x</m:t></m:r></m:oMath>')
+math.class # => Omml::Models::OMath
+
+# oMathPara root
+para = Omml.parse('<m:oMathPara xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math"><m:oMath><m:r><m:t>y</m:t></m:r></m:oMath></m:oMathPara>')
+para.class # => Omml::Models::OMathPara
+----
+
+=== Serialization
+
+[source,ruby]
+----
+math.to_xml              # Default serialization
+math.to_xml(prefix: 'm') # With m: prefix on all elements
+----
+
+=== Round-trip (parse, modify, serialize)
+
+[source,ruby]
+----
+math = Omml.parse(xml_string)
+# Access and modify the model tree
+math.r.first.t.content = "new value"
+math.to_xml(prefix: 'm')
+----
+
+== Internal architecture
+
+=== Parsing flow
+
+`Omml.parse(xml_string)` delegates to `Parser.parse`, which:
+
+1. Configures the XML adapter (`:ox` on MRI, `:oga` on Opal)
+2. Parses the XML string into a document
+3. Resolves the root class from the root element name (`OMath` or `OMathPara`)
+4. Calls `.of_xml` to deserialize into a Lutaml model tree
+
+=== Type context system
+
+`Omml::Configuration` manages a `Lutaml::Model::GlobalContext` (context ID `:omml`)
+that holds a registry of all model classes. Models register themselves at load
+time via `Omml::Configuration.register_model`. The context is populated lazily on
+first parse.
+
+Custom contexts can be created for downstream libraries (e.g., Plurimath) that
+fall back to the OMML context:
+
+[source,ruby]
+----
+# Create a custom context with OMML fallback
+Omml::Configuration.create_context(id: :custom_omml)
+
+# Parse using the custom context
+Omml.parse(xml, context: :custom_omml)
+----
+
+Model IDs are derived from class names by stripping the `CT`/`EG`/`ST` prefix
+and snake-casing with the prefix (e.g., `CTOMath` → `:ct_o_math`,
+`EGOMathElements` → `:eg_o_math_elements`).
+
+=== Model layer (`lib/omml/models/`)
+
+Three categories of models, all extending `Lutaml::Model::Serializable`:
+
+*Complex types* (`ct_*.rb`): Represent OMML schema complex types. Each defines
+attributes and XML element mappings, and self-registers via
+`Omml::Configuration.register_model`.
+
+*Simple types* (`simple_types/st_*.rb`): Enum/value types like `STJc`, `STOnOff`.
+These wrap string values with validation.
+
+*Group models* (`groups/eg_*.rb`): Shared compositional groups (e.g.,
+`EGOMathElements`). These use `import_model_attributes` /
+`import_model_mappings` to compose attributes from other groups, implementing
+the OMML schema's choice/sequence patterns.
+
+Root element wrappers (`o_math.rb`, `o_math_para.rb`) extend
+`CommonCode::RootModel` and use `omml_root_element` to declare themselves as XML
+root elements with the OMML namespace.
+
+=== Namespaces
+
+* `Omml::Namespace` — OMML namespace
+  (`http://schemas.openxmlformats.org/officeDocument/2006/math`, prefix `m`)
+* `Omml::WordprocessingNamespace` — Word ML namespace (prefix `w`), used for
+  elements like `w:rPr` that appear inside OMML `ctrlPr` elements
+
+=== Type substitutions
+
+Many OMML simple types are aliases for built-in Lutaml types (e.g., `STString`
+→ `Lutaml::Model::Type::String`). These are registered as aliases in the
+context rather than as separate model classes, via `Omml::TypeSubstitutions`.
+
+== Configuration
+
+[source,ruby]
+----
+# XML adapter (default: :ox, :oga on Opal)
+Omml.configure_adapter!
+Omml::Configuration.adapter = :oga
+
+# Access the built-in context
+Omml::Configuration.context_id # => :omml
+Omml::Configuration.context
+
+# Rebuild after a reset
+Omml::Configuration.populate_context!
+
+# Resolve a model class by its context ID
+Omml::Configuration.resolve_type(:ct_o_math)
+# => Omml::Models::CTOMath
+----
+
+== Test Suite and Fixtures
+
+The gem uses 279 OMML fixture files from `spec/fixtures/omml/` for round-trip
+validation. Each fixture is parsed, serialized, and the output is compared
+structurally against the original.
+
+=== Running Tests
+
+[source,bash]
+----
+bundle exec rake        # Run all specs + rubocop
+bundle exec rspec       # Run all tests
+bundle exec rspec spec/omml_spec.rb              # Run specific test file
+bundle exec rspec spec/omml_spec.rb:77           # Run single test by line
+bundle exec rspec --only-failures                # Re-run failures
+----
+
+=== XSD Validation
+
+The fixture round-trips are validated against the OOXML `shared-math.xsd`
+schema. Some fixtures contain Word-specific deviations from the strict XSD:
+
+* Element ordering differences (Word may output children in a different order
+  than the schema sequence)
+* Numeric `val` values (`1`/`0`) on `CT_OnOff` elements where the XSD specifies
+  `on`/`off` enumeration
+* `r` elements directly under `oMathPara` (Word output, not in the XSD sequence)
+
+These are well-known Word compatibilities and do not represent parser bugs.
+
+== Development
+
+[source,bash]
+----
+bundle install          # Install dependencies
+bundle exec rake        # Run specs + rubocop
+bundle exec rspec       # Run tests
+bundle exec rubocop     # Lint
+----
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/plurimath/omml.
+
+== 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/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-require 'rubocop/rake_task'
+require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 

data/bin/console

@@ -1,11 +1,11 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'omml'
+require "bundler/setup"
+require "omml"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
-require 'irb'
+require "irb"
 IRB.start(__FILE__)

data/lib/omml/configuration/adapter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Omml
+  module Configuration
+    # Extended only by Omml::Configuration together with the sibling modules.
+    module Adapter
+      def adapter
+        Lutaml::Model::Config.xml_adapter_type
+      end
+
+      def adapter=(adapter)
+        Lutaml::Model::Config.xml_adapter_type = adapter
+      end
+
+      def xml_adapter
+        self.adapter = Omml.default_adapter unless adapter
+
+        Lutaml::Model::Config.adapter_for(:xml)
+      end
+    end
+  end
+end

data/lib/omml/configuration/context_registry.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Omml
+  module Configuration
+    # Extended only by Omml::Configuration together with the sibling modules.
+    module ContextRegistry
+      def context(id = context_id)
+        Lutaml::Model::GlobalContext.context(id.to_sym)
+      end
+
+      def create_context(id:, registry: nil, fallback_to: [context_id],
+                         substitutions: [])
+        normalized_id = normalize_context_id(id)
+        if default_context_id?(normalized_id)
+          return create_default_context(registry, fallback_to,
+                                        substitutions)
+        end
+
+        create_custom_context(
+          id: normalized_id, registry: registry,
+          fallback_to: fallback_to, substitutions: substitutions
+        )
+      end
+
+      def populate_context!
+        # Trigger the model manifest autoload before replaying registrations.
+        Omml.const_get(:Models)
+        reset_context!
+        register_models_in(populate_base_context)
+      end
+
+      def require_context!(id = context_id)
+        normalized_id = id.to_sym
+        type_context = context(normalized_id)
+        return type_context if type_context
+
+        raise Omml::Errors::MissingContextError, normalized_id
+      end
+
+      def reset_context!(id: context_id)
+        normalized_id = normalize_context_id(id)
+        existing_context = Lutaml::Model::GlobalContext.context(normalized_id)
+        return unless existing_context
+
+        Lutaml::Model::GlobalContext.unregister_context(normalized_id)
+      end
+
+      private
+
+      def default_context_id?(id)
+        id == context_id
+      end
+
+      def create_default_context(registry, fallback_to, substitutions)
+        unless default_context_options?(registry, fallback_to, substitutions)
+          raise ArgumentError,
+                "create_context cannot customize the default " \
+                ":#{context_id} context; use populate_context! to rebuild it."
+        end
+
+        populate_context!
+      end
+
+      def default_context_options?(registry, fallback_to, substitutions)
+        registry.nil? &&
+          normalize_fallbacks(fallback_to) == [context_id] &&
+          Array(substitutions).empty?
+      end
+
+      def create_custom_context(id:, registry:, fallback_to:, substitutions:)
+        reset_context!(id: id)
+        create_type_context(
+          id: id,
+          registry: registry || Lutaml::Model::TypeRegistry.new,
+          fallback_to: prepare_fallback_contexts(fallback_to),
+          substitutions: substitutions,
+        )
+      end
+
+      def populate_base_context
+        base_type_context.tap { bind_namespace!(context_id) }
+      end
+
+      def create_type_context(id:, registry:, fallback_to:, substitutions: [])
+        Lutaml::Model::GlobalContext.create_context(
+          id: id,
+          registry: registry,
+          fallback_to: Array(fallback_to),
+          substitutions: substitutions,
+        ).tap do
+          Lutaml::Model::GlobalContext.clear_caches
+        end
+      end
+
+      def base_type_context
+        create_type_context(
+          id: context_id,
+          registry: Lutaml::Model::TypeRegistry.new,
+          fallback_to: [:default],
+        )
+      end
+
+      def prepare_fallback_contexts(fallback_to)
+        normalize_fallbacks(fallback_to).tap do |fallbacks|
+          populate_context! if populate_fallback_context?(fallbacks)
+        end
+      end
+
+      def populate_fallback_context?(fallbacks)
+        fallbacks.include?(context_id) && !context(context_id)
+      end
+
+      def normalize_fallbacks(fallback_to)
+        Array(fallback_to).map do |fallback|
+          normalize_context_id(fallback)
+        end
+      end
+
+      def normalize_context_id(id)
+        id.to_sym
+      end
+
+      def bind_namespace!(id)
+        Lutaml::Model::GlobalContext.bind_register_to_namespace(
+          id,
+          Omml::Namespace.uri,
+        )
+      end
+    end
+  end
+end

data/lib/omml/configuration/model_registry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Omml
+  module Configuration
+    # Extended only by Omml::Configuration together with the sibling modules.
+    module ModelRegistry
+      def register_model(klass, id: nil)
+        model_id = (id || model_id_for(klass)).to_sym
+        registered_models[model_id] = klass
+
+        if (type_context = context(context_id))
+          type_context.registry.register(model_id, klass)
+          clear_cache(klass, type_context.id)
+        end
+
+        klass
+      end
+
+      def model_id_for(klass)
+        class_name = klass.name.split("::").last
+        prefix = SCHEMA_MODEL_PREFIXES.find do |candidate|
+          class_name.start_with?(candidate) && class_name != candidate
+        end
+
+        if prefix
+          model_name = class_name.delete_prefix(prefix)
+          return :"#{prefix.downcase}_#{Lutaml::Model::Utils.snake_case(model_name)}"
+        end
+
+        Lutaml::Model::Utils.snake_case(class_name).to_sym
+      end
+
+      def registered_models
+        @registered_models ||= {}
+      end
+
+      private
+
+      def register_models_in(type_context)
+        register_id = type_context.id
+        registered_models.each do |model_id, klass|
+          type_context.registry.register(model_id, klass)
+          clear_cache(klass, register_id)
+        end
+
+        Omml::TypeSubstitutions.each_alias do |type_name, klass|
+          type_context.registry.register(type_name, klass)
+        end
+
+        Lutaml::Model::GlobalContext.clear_caches
+        type_context
+      end
+
+      def clear_cache(klass, register_id)
+        klass.instance_variable_set(:@register, register_id)
+        klass.clear_cache(register_id) if klass.respond_to?(:clear_cache)
+      end
+    end
+  end
+end