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.
- checksums.yaml +4 -4
- data/.gitattributes +12 -0
- data/.github/workflows/corpus.yml +106 -0
- data/.github/workflows/portable-models.yml +32 -0
- data/.github/workflows/release.yml +10 -10
- data/.rubocop.yml +5 -0
- data/README.adoc +14 -0
- data/lib/mml/opal.rb +1 -0
- data/lib/mml/portable.rb +53 -0
- data/lib/mml/version.rb +1 -1
- data/lib/mml.rb +1 -0
- data/mml.gemspec +2 -1
- data/model/portable/manifest.json +31 -0
- data/model/portable/mathml-v3.bundle.json +1 -0
- data/model/portable/mathml-v4.bundle.json +1 -0
- data/scripts/export_portable_models.rb +66 -0
- data/scripts/replay_corpus.rb +457 -0
- data/scripts/verify_portable_models.rb +38 -0
- metadata +12 -3
- data/CLAUDE.md +0 -145
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.
|