moxml 0.1.9 → 0.1.11

data/docs/_pages/adapters/ox.adoc

@@ -48,7 +48,37 @@ doc.xpath("//book").find { |book| book["id"] == "123" }
 IMPORTANT: For complete XPath 1.0 specification with zero limitations today, use
 Nokogiri or Oga adapters.
 
+==== Element Ordering in Round-Trip Tests
 
+[IMPORTANT]
+.Round-trip tests for Ox are experimental
+--
+Ox round-trip tests (`nokogiri-ox` CI job) are **experimental** because Ox lacks full XML
+conformance:
+
+* **Namespace support**: Ox does not properly handle namespaced elements in XPath queries
+* **XPath limitations**: Uses `locate()` instead of standard XPath; no attribute value
+  predicates, no logical operators, no position predicates
+* **Element ordering**: Ox produces elements in a different order than Nokogiri/Oga for
+  certain complex fixtures
+
+For production use with complex XML, prefer Nokogiri or Oga adapters.
+--
+
+The Ox adapter produces elements in a different order than other adapters for certain
+fixtures with complex nested structures. In round-trip tests, this causes the
+`elements_with_attributes` array length comparison to fail, even though the semantic
+equivalence check (double round-trip) passes.
+
+Known affected fixtures:
+
+* `niso-jats/element_citation.xml`
+* `niso-jats/pnas_sample.xml`
+* `metanorma/collection1nested.xml`
+
+This is a known limitation tracked in the round-trip test suite via
+`KNOWN_ELEMENT_ORDERING_ISSUES`. The `elements_with_attributes` comparison is
+automatically skipped for these Ox adapter pairs.
 
 See also:
 

data/docs/_pages/adapters/rexml.adoc

@@ -283,7 +283,7 @@ end
 === References
 
 * link:https://github.com/ruby/rexml[REXML on GitHub]
-* link:https://ruby-doc.org/stdlib/libdoc/rexml/rdoc/REXML.html[REXML documentation]
+* link:https://ruby-doc.org/stdlib/libdoc/rexml/rdoc/REXML[REXML documentation]
 
 === See also
 

data/docs/_pages/configuration.adoc

@@ -97,6 +97,49 @@ context.config.default_encoding = 'UTF-16'
 
 **Default:** `"UTF-8"`
 
+==== Namespace URI validation mode
+
+Control how strictly namespace URIs are validated:
+
+[source,ruby]
+----
+# Strict mode (default) — validates namespace URIs against RFC 3986
+context.config.namespace_uri_mode = :strict
+doc = context.parse(xml)  # Raises ValidationError for invalid URIs
+
+# Lenient mode — accepts any string as a namespace URI
+context.config.namespace_uri_mode = :lenient
+doc = context.parse(xml)  # Accepts non-standard namespace URIs
+----
+
+**Default:** `:strict`
+
+**Modes:**
+
+`:strict`:: Validates namespace URIs against the
+https://www.rfc-editor.org/rfc/rfc3986[RFC 3986] URI-reference specification, as
+required by https://www.w3.org/TR/xml-names/[Namespaces in XML]. Invalid URIs
+raise a `Moxml::ValidationError`. This is the recommended mode for
+standards-compliant XML processing.
+
+`:lenient`:: Accepts any string as a namespace URI, only rejecting strings
+containing XML-invalid control characters (`0x00`-`0x08`, `0x0B`, `0x0C`,
+`0x0E`-`0x1F`). Use this mode when processing XML documents that use
+non-standard namespace identifiers such as URNs or other non-URI strings.
+
+**Example:**
+
+[source,ruby]
+----
+# Process documents with non-standard namespace URIs
+context = Moxml.new do |config|
+  config.namespace_uri_mode = :lenient
+end
+
+xml = '<root xmlns:ex="not a valid URI but accepted in lenient mode"/>'
+doc = context.parse(xml)  # Parses successfully
+----
+
 === Context switching
 
 Use different configurations for different tasks:

data/docs/_pages/node-api-reference.adoc

@@ -1,9 +1,81 @@
 ---
-title: Node API reference
-nav_order: 5
+title: Node API Reference
+:toc:
+:toclevels: 3
 ---
 
-== Node API reference
+== Node API Reference
+
+This reference documents the API of all node types in Moxml. For a guide on API consistency and safe coding patterns, see the link:../guides/node-api-consistency[Node API Consistency Guide].
+
+== Node Identity: The #identifier Method
+
+All node types in Moxml support the `#identifier` method, which returns the primary identifier for a node:
+
+[cols="1,2,1"]
+|===
+| Node Type | #identifier Returns | Example
+
+| Element
+| The tag name
+| `"book"`, `"title"`
+
+| Attribute
+| The attribute name
+| `"id"`, `"class"`
+
+| ProcessingInstruction
+| The PI target
+| `"xml-stylesheet"`
+
+| Text, Comment, Cdata
+| `nil` (no identifier)
+| `nil`
+
+| EntityReference
+| The entity name
+| `"nbsp"`, `"copy"`
+
+| Declaration
+| `nil` (no identifier)
+| `nil`
+
+| Document
+| `nil` (no identifier)
+| `nil`
+|===
+
+**Example usage:**
+
+[source,ruby]
+----
+element = doc.at_xpath("//book")
+puts element.identifier  # => "book"
+
+attr = element.attribute("id")
+puts attr.identifier     # => "id"
+
+pi = doc.children.find { |n| n.processing_instruction? }
+puts pi.identifier       # => "xml-stylesheet"
+
+text = element.children.find { |n| n.text? }
+puts text.identifier     # => nil
+----
+
+**Safe iteration over mixed nodes:**
+
+[source,ruby]
+----
+doc.root.children.each do |node|
+  if id = node.identifier
+    puts "#{node.class.name.split('::').last}: #{id}"
+  else
+    puts "#{node.class.name.split('::').last}: (no identifier)"
+  end
+end
+----
+
+== Common Node Methods
 
 == XML objects and their methods
 
@@ -47,3 +119,56 @@ See also:
 
 * link:../guides/working-with-documents[Working with documents guide]
 * link:../guides/advanced-features[Advanced features guide]
+=== Doctype nodes
+
+Doctype nodes represent DOCTYPE declarations in XML documents.
+
+[source,ruby]
+----
+doctype = doc.create_doctype("html", "-//W3C//DTD HTML 4.01//EN",
+                              "http://www.w3.org/TR/html4/strict.dtd")
+doctype.name         # => "html"
+doctype.external_id  # => "-//W3C//DTD HTML 4.01//EN"
+doctype.system_id    # => "http://www.w3.org/TR/html4/strict.dtd"
+doctype.identifier   # => "html"
+----
+
+*Available methods:*
+
+* `name` - Returns the DOCTYPE name (root element name)
+* `external_id` - Returns the PUBLIC identifier (or nil)
+* `system_id` - Returns the SYSTEM identifier (DTD URI, or nil)
+* `identifier` - Returns the primary identifier (same as `name`)
+
+All Doctype accessor methods are fully implemented across all 6 adapters.
+
+=== EntityReference nodes
+
+EntityReference nodes represent XML entity references like ` `, `©`, or custom entities declared in the DOCTYPE.
+
+[source,ruby]
+----
+# Create programmatically
+ref = doc.create_entity_reference('nbsp')
+element.add_child(ref)
+
+# Or via builder
+doc = Moxml::Builder.new(Moxml.new).build do
+  element 'text' do
+    entity_reference 'ndash'
+  end
+end
+----
+
+*Available methods:*
+
+* `name` - Returns the entity name (e.g., `"nbsp"`, `"copy"`)
+* `identifier` - Returns the primary identifier (same as `name`)
+* `text` - Returns empty string (`""`) since entity has no text content
+* `content` - Returns empty string (entity content is in the name)
+* `to_xml` - Returns the entity syntax (e.g., `" "`)
+
+*Adapter notes:*
+
+* *Nokogiri*: Preserves custom declared entities as `EntityReference` nodes
+* *Ox, Oga*: These adapters resolve entities during parsing and do not expose entity reference nodes. Use Nokogiri or LibXML for entity preservation.

data/docs/_tutorials/namespace-handling.adoc

@@ -276,6 +276,27 @@ puts all_children.length  # => 2
 * link:../pages/adapters/rexml[REXML] - ⚠️ No namespace XPath
 * link:../pages/adapters/ox[Ox] - ⚠️ Basic only, no XPath
 
+=== Namespace URI validation
+
+By default, Moxml validates namespace URIs against
+https://www.rfc-editor.org/rfc/rfc3986[RFC 3986] (strict mode). To accept
+non-standard namespace identifiers, use lenient mode:
+
+[source,ruby]
+----
+# Strict mode (default) — validates URIs per RFC 3986
+context = Moxml.new do |config|
+  config.namespace_uri_mode = :strict
+end
+
+# Lenient mode — accepts any string as namespace URI
+context = Moxml.new do |config|
+  config.namespace_uri_mode = :lenient
+end
+----
+
+See link:../pages/configuration[Configuration] for details.
+
 === Troubleshooting
 
 **Namespace XPath not working:**

data/examples/rss_parser/rss_parser.rb

@@ -179,9 +179,7 @@ if __FILE__ == $0
 
   # Count categories
   all_categories = articles.flat_map(&:categories)
-  category_counts = all_categories.each_with_object(Hash.new(0)) do |cat, counts|
-    counts[cat] += 1
-  end
+  category_counts = all_categories.tally
   puts "Categories: #{category_counts.map do |cat, count|
     "#{cat} (#{count})"
   end.join(', ')}"

data/lib/moxml/adapter/base.rb

@@ -98,12 +98,24 @@ module Moxml
           create_native_declaration(version, encoding, standalone)
         end
 
-        def create_namespace(element, prefix, uri)
+        def create_namespace(element, prefix, uri, namespace_uri_mode: :strict)
+          if prefix && uri.to_s.empty?
+            raise NamespaceError.new(
+              "Prefixed namespace declaration cannot have an empty URI",
+              prefix: prefix,
+              uri: uri,
+            )
+          end
           validate_prefix(prefix) if prefix
-          validate_uri(uri)
+          validate_uri(uri, mode: namespace_uri_mode)
           create_native_namespace(element, prefix, uri)
         end
 
+        def create_entity_reference(name)
+          validate_entity_reference_name(name)
+          create_native_entity_reference(name)
+        end
+
         def set_attribute_name(attribute, name)
           attribute.name = name
         end
@@ -112,6 +124,10 @@ module Moxml
           attribute.value = value
         end
 
+        def entity_reference_name(node)
+          node.name
+        end
+
         def duplicate_node(node)
           node.dup
         end
@@ -193,6 +209,14 @@ module Moxml
             adapter: name,
           )
         end
+
+        def create_native_entity_reference(_name)
+          raise Moxml::NotImplementedError.new(
+            "create_native_entity_reference not implemented",
+            feature: "create_native_entity_reference",
+            adapter: name,
+          )
+        end
       end
     end
   end

data/lib/moxml/adapter/headed_ox.rb

@@ -26,7 +26,7 @@ module Moxml
     class HeadedOx < Ox
       class << self
         # Override parse to use HeadedOx context instead of Ox context
-        def parse(xml, _options = {})
+        def parse(xml, _options = {}, _context = nil)
           native_doc = begin
             result = ::Ox.parse(xml)
 
@@ -45,8 +45,9 @@ module Moxml
             )
           end
 
-          # Use :headed_ox context instead of :ox
-          DocumentBuilder.new(Context.new(:headed_ox)).build(native_doc)
+          # Use provided context if available, otherwise create new one
+          ctx = _context || Context.new(:headed_ox)
+          DocumentBuilder.new(ctx).build(native_doc)
         end
 
         # Execute XPath query using Moxml's XPath engine
@@ -66,7 +67,7 @@ module Moxml
             ctx = Context.new(:headed_ox)
 
             # Wrap the native node - don't rebuild the whole document
-            node = Node.wrap(node, ctx)
+            node = Moxml::Node.wrap(node, ctx)
           end
 
           # Parse XPath expression to AST

data/lib/moxml/adapter/libxml.rb

@@ -48,7 +48,7 @@ module Moxml
           doc.root = element
         end
 
-        def parse(xml, options = {})
+        def parse(xml, options = {}, _context = nil)
           # LibXML doesn't preserve DOCTYPE during parsing, so we need to extract it manually
           xml_string = if xml.is_a?(String)
                          xml
@@ -94,7 +94,8 @@ module Moxml
             native_doc.instance_variable_set(:@moxml_doctype, doctype_wrapper)
           end
 
-          DocumentBuilder.new(Context.new(:libxml)).build(native_doc)
+          ctx = _context || Context.new(:libxml)
+          DocumentBuilder.new(ctx).build(native_doc)
         end
 
         # SAX parsing implementation for LibXML
@@ -788,6 +789,20 @@ module Moxml
           end
         end
 
+        # Doctype accessor methods
+        def doctype_name(native)
+          # LibXML uses DoctypeWrapper which stores the values
+          native.name
+        end
+
+        def doctype_external_id(native)
+          native.external_id
+        end
+
+        def doctype_system_id(native)
+          native.system_id
+        end
+
         def xpath(node, expression, namespaces = nil)
           native_node = unpatch_node(node)
           return [] unless native_node
@@ -1149,7 +1164,7 @@ module Moxml
           # Add namespace definitions (only on this element, not ancestors)
           if elem.respond_to?(:namespaces)
             seen_ns = {}
-            elem.namespaces.definitions.each do |ns|
+            elem.namespaces.each do |ns|
               prefix = ns.prefix
               uri = ns.href
               next if seen_ns.key?(prefix)

data/lib/moxml/adapter/nokogiri.rb

@@ -11,7 +11,7 @@ module Moxml
           doc.root = element
         end
 
-        def parse(xml, options = {})
+        def parse(xml, options = {}, _context = nil)
           native_doc = begin
             if options[:fragment]
               ::Nokogiri::XML::DocumentFragment.parse(xml) do |config|
@@ -29,7 +29,9 @@ module Moxml
                                                    column: e.column)
           end
 
-          DocumentBuilder.new(Context.new(:nokogiri)).build(native_doc)
+          # Use provided context if available, otherwise create new one
+          ctx = _context || Context.new(:nokogiri)
+          DocumentBuilder.new(ctx).build(native_doc)
         end
 
         # SAX parsing implementation for Nokogiri
@@ -104,6 +106,14 @@ module Moxml
           )
         end
 
+        def create_native_entity_reference(name)
+          ::Nokogiri::XML::EntityReference.new(create_document, name)
+        end
+
+        def entity_reference_name(node)
+          node.name
+        end
+
         def declaration_attribute(declaration, attr_name)
           return nil unless declaration.content
 
@@ -150,6 +160,7 @@ module Moxml
           when ::Nokogiri::XML::ProcessingInstruction then :processing_instruction
           when ::Nokogiri::XML::Document, ::Nokogiri::XML::DocumentFragment then :document
           when ::Nokogiri::XML::DTD then :doctype
+          when ::Nokogiri::XML::EntityReference then :entity_reference
           else :unknown
           end
         end
@@ -321,6 +332,19 @@ module Moxml
           node.namespace_definitions
         end
 
+        # Doctype accessor methods
+        def doctype_name(native)
+          native.name
+        end
+
+        def doctype_external_id(native)
+          native.external_id
+        end
+
+        def doctype_system_id(native)
+          native.system_id
+        end
+
         def xpath(node, expression, namespaces = nil)
           node.xpath(expression, namespaces).to_a
         rescue ::Nokogiri::XML::XPath::SyntaxError => e