omml 0.2.11 → 0.2.12

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,74 +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
- `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.
8
-
9
- ## Commands
10
-
11
- ```bash
12
- bundle install # Install dependencies
13
- bundle exec rake # Run specs + rubocop (default task)
14
- bundle exec rspec # Run all specs
15
- bundle exec rspec spec/omml_spec.rb # Run a single spec file
16
- bundle exec rspec spec/omml_spec.rb:77 # Run a single test by line number
17
- bundle exec rubocop # Lint
18
- ```
19
-
20
- ## Architecture
21
-
22
- ### Entry point and parsing flow
23
-
24
- `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.
25
-
26
- The top-level API is in `lib/omml.rb`. `Parser` in `lib/omml/parser.rb` handles the parsing pipeline.
27
-
28
- ### Type context system (`Omml::Configuration`)
29
-
30
- `Configuration` manages a Lutaml `GlobalContext` (context ID `:omml`) that holds a registry of all model classes. The context is populated lazily on first parse via `populate_context!`, which eager-loads every model so its `inherited` hook fires and registers it.
31
-
32
- 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`).
33
-
34
- Consumers (e.g. Uniword) register their own context via `Omml::Configuration.register_in(:consumer_id)`. This populates the consumer's type registry directly with all Omml types so OMML subtrees embedded in foreign-context models resolve without falling back through `:omml`. See `spec/omml/cross_context_spec.rb` for the contract.
35
-
36
- ### Model layer (`lib/omml/models/`)
37
-
38
- All model loading is `autoload`-based. `lib/omml/models.rb` declares every class as an `autoload` on the `Omml::Models` module, plus an `eager_load!` helper that `populate_context!` invokes to trigger class definition (and thus registration).
39
-
40
- Three categories of models:
41
-
42
- - **Complex types** (`ct_*.rb`) and root element wrappers (`o_math.rb`, `o_math_para.rb`) — extend `Omml::Models::Base`, which provides:
43
- - `lutaml_default_register` returning `Omml::Configuration.context_id` (single source of truth), so consumers referencing Omml classes route serialization and parsing back to `:omml`.
44
- - An `inherited` hook that auto-registers each subclass with `Omml::Configuration`. No per-file `register_model` call is needed.
45
- - **Simple types** (`simple_types/*.rb`) — enum/value types like `STJc`, `STOnOff`. Most extend `EnumString` or `Token`, both of which carry an `inherited` hook for auto-registration. A handful extend Lutaml types directly (`Lutaml::Model::Type::Integer`, `::Decimal`, `::Value`) and are registered explicitly. Three classes (`STAdjCoordinate`, `STHexColor`, `STLang`) include `Omml::Models::Registerable` because they resolve dependent types via a class-level register accessor.
46
- - **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. Like complex types, they extend `Base`.
47
-
48
- ### Namespaces
49
-
50
- - `Omml::Namespace` — the OMML namespace (`http://schemas.openxmlformats.org/officeDocument/2006/math`, prefix `m`). This is the canonical OMML namespace class; downstream consumers (Uniword, Plurimath) should reference it directly rather than redefine their own.
51
- - `Omml::WordprocessingNamespace` — the Word ML namespace (prefix `w`), used for elements like `w:rPr` that appear inside OMML.
52
-
53
- ### Type substitutions (`TypeSubstitutions`)
54
-
55
- 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.
56
-
57
- ## Testing
58
-
59
- - `spec/omml_spec.rb` — unit tests for parsing, context management, and error handling
60
- - `spec/omml_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.
61
- - The round-trip spec expects exact XML structural fidelity: same elements, attributes, namespaces, text content, and child ordering.
62
- - `spec/omml/lutaml_default_register_spec.rb` — asserts every `Serializable` subclass under `Omml::Models` carries `:omml` as its default register (mirrors the Mml gem's coverage spec).
63
- - `spec/omml/cross_context_spec.rb` — proves embedded OMML parses correctly when a foreign-context parent references Omml types (the Uniword scenario).
64
- - `spec/omml/opal_boot_spec.rb` — verifies the Opal boot file stays in sync with autoload declarations.
65
-
66
- ## Key conventions
67
-
68
- - All models are in the `Omml::Models` module namespace
69
- - New complex types or groups inherit `Omml::Models::Base`; new enum-like simple types inherit `EnumString` or `Token`. No `register_model` call is needed — `inherited` handles it.
70
- - All internal library loading uses Ruby `autoload`, never `require_relative`
71
- - No `instance_variable_set` / `instance_variable_get` / `send(:private_method)` / `respond_to?` — use public APIs and structural type checks (`is_a?`, `<`, `include?`)
72
- - The XML adapter is resolved by lutaml-model's AdapterResolver (lazy auto-detection)
73
- - Models use `ordered` and `sequence` blocks for XML mapping to preserve element order
74
- - `render_empty: true` is used on elements that must be emitted even when empty