mml 2.4.7 → 2.4.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/CLAUDE.md DELETED
@@ -1,145 +0,0 @@
1
- # CLAUDE.md
2
-
3
- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
-
5
- ## Project Overview
6
-
7
- `mml` is a Ruby gem that provides MathML 2, MathML 3, and MathML 4 XML parsing and serialization. It maps MathML elements into Ruby model classes using the `lutaml-model` framework. Part of the [Plurimath](https://github.com/plurimath/mml) ecosystem.
8
-
9
- ## Commands
10
-
11
- ```bash
12
- rake # Run specs + rubocop (default task)
13
- bundle exec rspec # Run all tests
14
- bundle exec rspec spec/mml/v3/msub_spec.rb:14 # Run single test by line
15
- bundle exec rspec --only-failures # Previously failing tests only
16
- bundle exec rubocop # Lint
17
- bundle exec rubocop -a # Auto-fix lint issues
18
- bin/console # IRB with gem loaded
19
- ```
20
-
21
- ## Versioned Architecture
22
-
23
- The gem maintains **three** separate class hierarchies: `Mml::V2::` (MathML 2), `Mml::V3::` (MathML 3), and `Mml::V4::` (MathML 4). Users must reference the versioned namespace explicitly — no backward-compat aliases.
24
-
25
- ```ruby
26
- Mml.parse(input) # Default: MathML 3
27
- Mml.parse(input, version: 2) # MathML 2
28
- Mml.parse(input, version: 3) # Explicit MathML 3
29
- Mml.parse(input, version: 4) # MathML 4 with intent/arg attributes
30
- ```
31
-
32
- **Directory structure:**
33
- - `lib/mml/base/` — version-agnostic element modules, mixed into each version's class via `include Base::XYZ`. The single source of truth for the XML mapping DSL.
34
- - `lib/mml/v2/`, `lib/mml/v3/`, `lib/mml/v4/` — per-version class declarations (each ~3 lines: declare class, mix in base module, register).
35
-
36
- **Key difference (V3 → V4):** MathML 4 adds `intent`, `arg`, `displaystyle`, and `scriptlevel` as universal presentation attributes for accessibility markup; removes some deprecated attributes.
37
-
38
- **No hidden delegation:** The `Mml` module does not alias or delegate constants. Use `Mml::V3::Math`, `Mml::V4::Mi`, etc. directly.
39
-
40
- ## Entry Points
41
-
42
- - `Mml.parse(input, version: N)` — parse XML, returns `Mml::V{2,3,4}::Math` object graph
43
- - `Mml::V3.parse(input)` / `Mml::V4.parse(input)` — version-specific parsing
44
- - `Mml::V4::Math.from_xml(input)` — directly parse with v4 classes
45
- - Call `to_xml` on any element to serialize back
46
-
47
- ## Element Mapping Pattern
48
-
49
- Each MathML element is a `Lutaml::Model::Serializable` subclass with an `xml do...end` DSL block. The XML mapping lives in `lib/mml/base/<tag>.rb` as a module included into each version's class (e.g., `Mml::V3::Msub` includes `Mml::Base::Msub`).
50
-
51
- ### Content model — `mixed_content` vs `ordered` vs `map_content`
52
-
53
- This is the most important decision when adding or editing an element. Pick based on the **schema** (see `schemas/mathml3/`, `schemas/mathml4/`, `reference-docs/mathml-source/`):
54
-
55
- | Schema content model | Use | Examples |
56
- |---------------------------------------------------|--------------------------------------|--------------------------------|
57
- | True mixed `(#PCDATA \| mglyph \| malignmark)*` | `mixed_content` + `map_content` | `Mi`, `Mn`, `Mo`, `Ms`, `Mtext`|
58
- | Element-only (`ImpliedMrow`, `<xs:sequence>`, etc.) | `ordered` | `Msub`, `Mfrac`, `Mrow`, `Math`, `Munder`, `Mfenced`, `Msgroup`, … |
59
-
60
- **Why this matters:** lutaml-model's `each_mixed_content` iteration exposes all children to consumers (Plurimath's translator does positional indexing like `children[0]`, `children[1]` for `msub`/`mfrac`/etc.).
61
- - Under `mixed_content`, whitespace between elements is yielded as a String child, shifting positional indices.
62
- - Under `ordered`, whitespace-only text nodes are skipped — only elements and non-whitespace text are yielded.
63
-
64
- If you mistakenly use `mixed_content` on an element-only schema element, downstream consumers see phantom whitespace children and silently misinterpret the tree (e.g., render `<msub><mi>t</mi><mn>90</mn></msub>` with whitespace between children as base=whitespace, sub=`<mi>t</mi>`, dropping `<mn>90</mn>`).
65
-
66
- **Verification workflow for any element edit:**
67
- ```bash
68
- grep -A15 'name="<tag>"' schemas/mathml3/mathml3-presentation.xsd schemas/mathml3/mathml3-common.xsd
69
- grep -A3 '<tag>\s*=\s*element' schemas/mathml4/mathml4-core.rnc schemas/mathml4/mathml4-presentation.rnc
70
- ```
71
-
72
- If the schema says `ImpliedMrow`, `MathExpression, MathExpression`, `MstackExpression*`, `TableRowExpression*`, etc. (any element-only sequence), use `ordered`. If it says `(#PCDATA | mglyph | malignmark)*`, use `mixed_content` + `map_content` + `map_element` for the inline children.
73
-
74
- ### Token elements are the only true mixed content
75
-
76
- Per MathML schema, token elements (`mi`, `mn`, `mo`, `ms`, `mtext`) accept `(#PCDATA | mglyph | malignmark)*` — text interleaved with inline elements. They use:
77
-
78
- ```ruby
79
- attribute :value, :string, collection: true # collection required for mixed_content
80
- attribute :mglyph_value, :mglyph, collection: true
81
- attribute :malignmark_value, :malignmark, collection: true
82
-
83
- xml do
84
- element "<tag>"
85
- mixed_content
86
- map_content to: :value
87
- map_element "mglyph", to: :mglyph_value
88
- map_element "malignmark", to: :malignmark_value
89
- end
90
- ```
91
-
92
- `value` is a `String` **collection** (Array) because text can be split by intervening inline elements (e.g., `<mi>x<malignmark/>y</mi>` → `["x", "y"]`).
93
-
94
- ### CommonAttributes
95
-
96
- A `no_root` Lutaml model imported into container elements via `import_model`. It dynamically creates `#{tag}_value` attributes for each tag in `Configuration::SUPPORTED_TAGS`. Classes that receive it are listed in `Configuration::COMMON_ATTRIBUTES_CLASSES`.
97
-
98
- ### Version module body registration
99
-
100
- Each `lib/mml/v{2,3,4}.rb` declares `autoload :Klass, "mml/v{2,3,4}/klass"` for every element class, then calls `Configuration.register_model(Klass, id: :tag)` in the module body. The register_model call triggers autoload on first reference, preserving eager-registration semantics while using Ruby autoload (no `require_relative` for internal code).
101
-
102
- Per-element files (e.g. `lib/mml/v3/math.rb`) define only the class — they no longer call `register_model` themselves. The version module is the single source of truth for registration.
103
-
104
- For grouped files (e.g. `lib/mml/v3/arith.rb` defines 22 classes), each class has its own `autoload` entry pointing at the shared file.
105
-
106
- `spec/mml/code_quality_spec.rb` enforces the lint rules and verifies every expected element ID is registered in its version's context.
107
-
108
- **Namespace:** All versions use the same URI (`http://www.w3.org/1998/Math/MathML`) — MathML 4 chose backward compatibility over a new namespace.
109
-
110
- ## Adapter
111
-
112
- `Mml.default_adapter` returns `:oga` under Opal, otherwise delegates to `Lutaml::Model::Config.xml_adapter_type` (defaults to `:nokogiri`). Specs pin `:nokogiri` in `spec_helper.rb`. Users can override globally via `Lutaml::Model::Config`.
113
-
114
- ## Spec Structure
115
-
116
- - `spec/mml/v2/`, `spec/mml/v3/`, `spec/mml/v4/` — per-version element specs (round-trip + attribute preservation)
117
- - `spec/mml/v3_spec.rb`, `spec/mml/v4_spec.rb` — whole-testsuite round-trip tests against `spec/fixtures/mml3-testsuite/` and `spec/fixtures/mmlcore-testsuite/`
118
- - `spec/mml/ordered_content_spec.rb` — regression specs locking in the mixed_content vs ordered distinction (whitespace handling + token element inline children)
119
- - `spec/mml/adapter_configuration_spec.rb` — adapter delegation
120
- - `spec/context_support_spec.rb`, `spec/lutaml_default_register_spec.rb` — registry/context behavior
121
- - `spec/fixtures/mml2-testsuite/`, `mml3-testsuite/`, `mmlcore-testsuite/` — W3C test suites (submodules)
122
- - `spec/fixtures/v2/`, `v4/` — version-specific fixtures
123
-
124
- Specs use `canon`'s `be_xml_equivalent_to` matcher with the `:spec_friendly` profile (whitespace-tolerant). When adding a regression spec for an ordering bug, **explicitly test the inter-element-whitespace scenario** — the suite's whitespace tolerance masks positional bugs.
125
-
126
- ## Key Dependencies
127
-
128
- - `lutaml-model` (~> 0.8.0) — data mapper framework; all element classes inherit from `Lutaml::Model::Serializable`
129
- - `moxml` — XML parsing backbone (adapter selected via `Lutaml::Model::Config`)
130
- - `canon` — XML comparison for specs
131
-
132
- ## Conventions
133
-
134
- - `frozen_string_literal: true` in all files
135
- - RuboCop targets Ruby 3.0; inherits from Ribose OSS guides
136
- - CI workflows are auto-generated by Cimas — do not edit manually
137
- - `Gemfile.lock` is gitignored; dependencies come from the gemspec
138
- - Type signatures exist in `sig/mml.rbs`
139
-
140
- ## Reference Materials
141
-
142
- - `schemas/mathml2/`, `schemas/mathml3/`, `schemas/mathml4/` — official W3C schemas (XSD for 2/3, RelaxNG for 4). **Authoritative** source for content models and attribute lists.
143
- - `reference-docs/mathml-source/` — W3C spec source XML (presentation-markup.xml, validation-grammar.xml, etc.)
144
-
145
- When deciding whether an element should have `mixed_content`, `ordered`, or `map_content`, **always** verify against the schema first.