moxml 0.1.9 → 0.1.11

data/docs/ENTITY_SUPPORT_FOR_LUTAML_MODEL.md

@@ -0,0 +1,102 @@
+# Entity Support for lutaml-model Team
+
+## Overview
+
+Moxml now supports entity restoration during parsing. This feature ensures that XML entities (like `&`, `<`, `>`, `"`, `'`) are preserved as `EntityReference` nodes rather than being resolved to their character values during parsing.
+
+## Key Concept: Entity Restoration
+
+By default, XML parsers resolve entities during parsing:
+- Input: `<root>foo&amp;bar</root>`
+- Default behavior: Text node contains `foo&bar` (resolved `&`)
+- With entity restoration: Text node contains `foo` + EntityReference `&amp;` + Text node `bar`
+
+## Enabling Entity Restoration
+
+### Option 1: Per-Context Configuration
+
+```ruby
+context = Moxml.new(:nokogiri, restore_entities: true)
+doc = context.parse('<root>foo&amp;bar</root>')
+# doc.to_xml will preserve &amp; as EntityReference
+```
+
+### Option 2: Global Configuration
+
+```ruby
+Moxml.configure do |config|
+  config.restore_entities = true
+end
+```
+
+## Preloading Entity Sets
+
+You can preload standard entity sets (HTML5, MathML, ISO) for faster entity resolution:
+
+```ruby
+context = Moxml.new(:nokogiri,
+  restore_entities: true,
+  preload_entity_sets: [:html5, :mathml]
+)
+```
+
+## W3C XML Core WG Compliance
+
+Per W3C XML Core WG guidance:
+- Standard XML entities (`amp`, `lt`, `gt`, `quot`, `apos`) are implicitly declared per XML spec
+- The `EntityRegistry` class tracks all known entities and their Unicode codepoints
+- Entity names are preserved through round-trip serialization
+
+## What lutaml-model Needs to Know
+
+### 1. Document Structure with Entities
+
+When entity restoration is enabled, documents containing entities will have mixed node types:
+
+```
+Document
+└── Element: root
+    ├── Text: "foo"
+    ├── EntityReference: "amp"  # Represents &
+    └── Text: "bar"
+```
+
+### 2. Serialization
+
+`doc.to_xml` will serialize EntityReference nodes as proper XML entity syntax:
+- `EntityReference("amp")` → `&amp;`
+- `EntityReference("lt")` → `&lt;`
+- etc.
+
+### 3. XPath Queries
+
+EntityReference nodes participate in XPath queries like any other node. You can query for them specifically if needed.
+
+### 4. Configuration Inheritance
+
+When using `Moxml::Context`, the entity restoration setting is preserved through document operations. However, when creating new contexts, you need to set the option explicitly.
+
+## Example Usage in lutaml-model
+
+```ruby
+# Parse XML with entities preserved
+context = Moxml.new(:nokogiri, restore_entities: true)
+doc = context.parse(your_xml_string)
+
+# Serialize back - entities are preserved
+output = doc.to_xml
+```
+
+## Testing Considerations
+
+When writing tests for models that handle XML with entities:
+1. Enable `restore_entities: true` in your test context
+2. Verify that EntityReference nodes are created for entities in text
+3. Test round-trip: parse → serialize → parse should preserve entities
+
+## Files of Interest
+
+- `lib/moxml/entity_registry.rb` - Entity definitions and lookup
+- `lib/moxml/config.rb` - Configuration options
+- `lib/moxml/document_builder.rb` - Entity restoration logic
+- `lib/moxml/entity_reference.rb` - EntityReference node class

data/docs/_guides/index.adoc

@@ -10,23 +10,25 @@ Task-oriented guides for common XML processing operations with Moxml.
 === Document operations
 
 link:parsing-xml[Parsing XML]::
-Parse XML from strings, files, and IO streams with different adapters.
+Parse XML from strings, files, and IO streams
 
-link:sax-parsing[SAX parsing]::
-Memory-efficient event-driven parsing for large XML files and streaming data.
+link:working-with-documents[Working with Documents]::
+Create and manipulate XML documents
 
-link:xml-declaration[XML declaration preservation]::
-Understand how Moxml preserves XML declarations for round-trip fidelity and standards compliance.
+link:modifying-xml[Modifying XML]::
+Edit elements, attributes, and content
 
-link:creating-documents[Creating documents]::
-Build XML documents from scratch using the builder pattern or direct
-manipulation.
+link:sax-parsing[SAX Parsing]::
+Memory-efficient event-driven parsing
 
-link:modifying-xml[Modifying XML]::
-Add, remove, and modify elements, attributes, and content in XML documents.
+link:advanced-features[Advanced Features]::
+Namespaces, XPath, and more
+
+link:node-api-consistency[Node API Consistency]::
+Understanding node types and their APIs
 
-link:serializing-xml[Serializing XML]::
-Convert XML documents to strings with formatting and encoding options.
+link:development-testing[Development & Testing]::
+Contributing to Moxml
 
 === Querying and traversal
 

data/docs/_guides/node-api-consistency.adoc

@@ -0,0 +1,572 @@
+= Node API consistency guide
+:toc:
+:toclevels: 3
+
+== Overview
+
+This guide documents the API surface of all node types in Moxml, providing clear
+expectations for developers about which methods are available on which node
+types.
+
+== Node Type Hierarchy
+
+[source]
+----
+Node (abstract base)
+├── Document
+├── Element
+├── Attribute
+├── Text
+├── Cdata
+├── Comment
+├── ProcessingInstruction
+├── Declaration
+└── Doctype
+----
+
+== Common Node Methods
+
+All node types inherit these methods from `Moxml::Node`:
+
+=== Document Navigation
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#document`
+| Returns the containing document
+| ✅ Yes
+
+| `#parent`
+| Returns the parent node
+| ✅ Yes
+
+| `#children`
+| Returns a NodeSet of child nodes
+| ✅ Yes (may be empty)
+
+| `#next_sibling`
+| Returns the next sibling node
+| ✅ Yes (may be nil)
+
+| `#previous_sibling`
+| Returns the previous sibling node
+| ✅ Yes (may be nil)
+|===
+
+=== Tree Manipulation
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#add_child(node)`
+| Adds a child node
+| ✅ Yes
+
+| `#add_previous_sibling(node)`
+| Adds a sibling before this node
+| ✅ Yes
+
+| `#add_next_sibling(node)`
+| Adds a sibling after this node
+| ✅ Yes
+
+| `#remove`
+| Removes this node from the tree
+| ✅ Yes
+
+| `#replace(node)`
+| Replaces this node with another
+| ✅ Yes
+|===
+
+=== Serialization
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#to_xml(options = {})`
+| Serializes node to XML string
+| ✅ Yes
+
+| `#clone` / `#dup`
+| Creates a deep copy of the node
+| ✅ Yes
+|===
+
+=== XPath Queries
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#xpath(expression, ns = {})`
+| Returns NodeSet matching XPath
+| ✅ Yes (adapter-dependent)
+
+| `#at_xpath(expression, ns = {})`
+| Returns first node matching XPath
+| ✅ Yes (adapter-dependent)
+|===
+
+=== Type Checking
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#element?`
+| Returns true if node is an Element
+| ✅ Yes
+
+| `#text?`
+| Returns true if node is a Text node
+| ✅ Yes
+
+| `#cdata?`
+| Returns true if node is a CDATA section
+| ✅ Yes
+
+| `#comment?`
+| Returns true if node is a Comment
+| ✅ Yes
+
+| `#processing_instruction?`
+| Returns true if node is a PI
+| ✅ Yes
+
+| `#document?`
+| Returns true if node is a Document
+| ✅ Yes
+
+| `#declaration?`
+| Returns true if node is a Declaration
+| ✅ Yes
+
+| `#doctype?`
+| Returns true if node is a Doctype
+| ✅ Yes
+
+| `#attribute?`
+| Returns true if node is an Attribute
+| ✅ Yes
+|===
+
+== Node Type-Specific APIs
+
+=== Document
+
+The root document node.
+
+==== Additional Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#root`
+| Returns the root element
+| ✅ Yes
+
+| `#root=(element)`
+| Sets the root element
+| ✅ Yes
+
+| `#encoding`
+| Returns document encoding
+| ✅ Yes
+
+| `#create_element(name, content = nil)`
+| Creates a new element
+| ✅ Yes
+
+| `#create_text(content)`
+| Creates a new text node
+| ✅ Yes
+
+| `#create_comment(content)`
+| Creates a new comment
+| ✅ Yes
+
+| `#create_cdata(content)`
+| Creates a new CDATA section
+| ✅ Yes
+
+| `#create_processing_instruction(target, content)`
+| Creates a new processing instruction
+| ✅ Yes
+
+| `#create_declaration(version, encoding, standalone)`
+| Creates a new XML declaration
+| ✅ Yes (adapter-dependent)
+|===
+
+=== Element
+
+Elements are the primary structural nodes with tag names, attributes, and children.
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#name`
+| Returns the element tag name
+| ✅ Yes
+
+| `#name=(value)`
+| Sets the element tag name
+| ✅ Yes
+
+| `#identifier`
+| Returns the primary identifier (same as #name)
+| ✅ Yes
+|===
+
+==== Namespace Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#namespace`
+| Returns the element's namespace
+| ✅ Yes (may be nil)
+
+| `#namespace=(ns_or_hash)`
+| Sets the element's namespace
+| ✅ Yes
+
+| `#namespace_prefix`
+| Returns the namespace prefix
+| ✅ Yes (may be nil)
+
+| `#namespace_uri`
+| Returns the namespace URI
+| ✅ Yes (may be nil)
+
+| `#namespaces`
+| Returns all namespace definitions
+| ✅ Yes
+
+| `#add_namespace(prefix, uri)`
+| Adds a namespace definition
+| ✅ Yes
+|===
+
+==== Attribute Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#[](name)`
+| Gets attribute value
+| ✅ Yes
+
+| `#[]=(name, value)`
+| Sets attribute value
+| ✅ Yes
+
+| `#attribute(name)`
+| Returns Attribute object
+| ✅ Yes (may be nil)
+
+| `#attributes`
+| Returns array of all attributes
+| ✅ Yes
+
+| `#remove_attribute(name)`
+| Removes an attribute
+| ✅ Yes
+|===
+
+==== Content Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#text`
+| Returns text content
+| ✅ Yes
+
+| `#text=(content)`
+| Sets text content
+| ✅ Yes
+
+| `#inner_text`
+| Returns inner text (concatenated)
+| ✅ Yes
+
+| `#inner_xml`
+| Returns inner XML as string
+| ✅ Yes
+
+| `#inner_xml=(xml)`
+| Sets inner XML from string
+| ✅ Yes
+|===
+
+=== Attribute
+
+Attributes are name-value pairs attached to elements.
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#name`
+| Returns the attribute name
+| ✅ Yes
+
+| `#name=(new_name)`
+| Sets the attribute name
+| ✅ Yes
+
+| `#identifier`
+| Returns the primary identifier (same as #name)
+| ✅ Yes
+|===
+
+==== Value Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#value`
+| Returns the attribute value
+| ✅ Yes
+
+| `#value=(new_value)`
+| Sets the attribute value
+| ✅ Yes
+
+| `#text`
+| Alias for #value (XPath compatibility)
+| ✅ Yes
+|===
+
+==== Relationship Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#element`
+| Returns the owning element
+| ✅ Yes
+
+| `#namespace`
+| Returns the attribute's namespace
+| ✅ Yes (may be nil)
+|===
+
+=== Text
+
+Text nodes contain character data.
+
+==== Content Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#content`
+| Returns the text content
+| ✅ Yes
+
+| `#content=(text)`
+| Sets the text content
+| ✅ Yes
+
+| `#text`
+| Alias for #content
+| ✅ Yes
+|===
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#identifier`
+| Returns nil (content nodes have no identifier)
+| ✅ Yes
+|===
+
+=== Cdata
+
+CDATA sections contain character data that should not be parsed.
+
+==== Content Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#content`
+| Returns the CDATA content
+| ✅ Yes
+
+| `#content=(text)`
+| Sets the CDATA content
+| ✅ Yes
+
+| `#text`
+| Alias for #content
+| ✅ Yes
+|===
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#identifier`
+| Returns nil (content nodes have no identifier)
+| ✅ Yes
+|===
+
+=== Comment
+
+Comment nodes contain XML comments.
+
+==== Content Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#content`
+| Returns the comment text
+| ✅ Yes
+
+| `#content=(text)`
+| Sets the comment text
+| ✅ Yes
+
+| `#text`
+| Alias for #content
+| ✅ Yes
+|===
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#identifier`
+| Returns nil (content nodes have no identifier)
+| ✅ Yes
+|===
+
+=== ProcessingInstruction
+
+Processing instructions provide directives to applications.
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#target`
+| Returns the PI target
+| ✅ Yes
+
+| `#target=(new_target)`
+| Sets the PI target
+| ✅ Yes
+
+| `#identifier`
+| Returns the primary identifier (same as #target)
+| ✅ Yes
+|===
+
+==== Content Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#content`
+| Returns the PI content
+| ✅ Yes
+
+| `#content=(new_content)`
+| Sets the PI content
+| ✅ Yes
+|===
+
+=== Declaration
+
+XML declarations specify document metadata.
+
+==== Property Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#version`
+| Returns XML version (e.g., "1.0")
+| ✅ Yes
+
+| `#version=(new_version)`
+| Sets XML version
+| ✅ Yes
+
+| `#encoding`
+| Returns character encoding
+| ✅ Yes (may be nil)
+
+| `#encoding=(new_encoding)`
+| Sets character encoding
+| ✅ Yes
+
+| `#standalone`
+| Returns standalone status
+| ✅ Yes (may be nil)
+
+| `#standalone=(new_standalone)`
+| Sets standalone status
+| ✅ Yes
+|===
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#identifier`
+| Returns nil (declarations have no identifier)
+| ✅ Yes
+|===
+
+=== Doctype
+
+Document type declarations specify DTD information.
+
+WARNING: Doctype accessor methods are **not fully implemented** across all adapters. The availability of these methods depends on the specific adapter being used.
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+|Doctype |`#name` |✅ Yes |Returns DOCTYPE name (root element)
+|Doctype |`#external_id` |✅ Yes |Returns PUBLIC identifier
+|Doctype |`#system_id` |✅ Yes |Returns SYSTEM identifier (DTD URI)
+|Doctype |`#identifier` |✅ Yes |Returns DOCTYPE name (same as `#name`)
+|===

data/docs/_guides/xml-declaration.adoc

@@ -439,12 +439,12 @@ doc.to_xml                       # Use automatic preservation
 Controls whether XML declaration is included in serialized output:
 
 * `true`: Always include declaration
-* `false`: Never include declaration  
+* `false`: Never include declaration
 * Not specified: Use `has_xml_declaration` value (automatic preservation)
 
 == See Also
 
-* link:parsing-xml.html[Parsing XML] - How to parse XML documents
-* link:modifying-xml.html[Modifying XML] - Working with parsed documents
-* link:../adapters/index.html[Adapters] - Adapter-specific behavior
-* link:../best-practices.html[Best Practices] - General XML processing guidelines
+* link:parsing-xml[Parsing XML] - How to parse XML documents
+* link:modifying-xml[Modifying XML] - Working with parsed documents
+* link:../adapters/index[Adapters] - Adapter-specific behavior
+* link:../best-practices[Best Practices] - General XML processing guidelines