moxml 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f1290755cf60610b63b7c82a4d043e662627a0c1b7a5692a70e987ddae69fa6
-  data.tar.gz: 05c9430233444a7915cb36789af8ebad99bc34391324c010a8e9c07f1cd36d33
+  metadata.gz: 07caeff68b2413d8ccaab1e827b151c4b98381f76b0f1feb63cec118be54ae05
+  data.tar.gz: 76e3eb23022b6d49e5c265467966d29d6ad12617f2a00af3b34680b32f96b8ac
 SHA512:
-  metadata.gz: ca2bf23c9b78a09dc984a974b86eadabddca8e4f90dbcdda263ff2295a61a4a6c1252fdeb5ad7ace732533887abef1d8636f5e1c6556f720485ed61d8e93da32
-  data.tar.gz: 508e707c528f5a729dea7de4a5940a6df8f70a3bd537295ef510a1280be322833b06bdc3b4242f869dae11c7cda09b07b84a9e13ead7f5810fb90f6f565e872c
+  metadata.gz: e0a41270e30bca0664d5e4bf32019d82a262cbfe6c2d001879d8e6259bf06e80a24df2372698ecd651835e88b27be2b7f2552b0d26aaf40aa514de7a870bf5e8
+  data.tar.gz: 7ade8a4b671b3eb3fe06d2b909783f61bd5172d1645e3c1e9c6344d3e3fb01b5b1c32b8da09b39fedc2b73d04e52edb19956bf00240fbb145798f4be9c598058

data/.rubocop_todo.yml

@@ -1,23 +1,24 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-11-24 02:45:12 UTC using RuboCop version 1.80.0.
+# on 2025-11-26 03:06:16 UTC using RuboCop version 1.80.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 179
+# Offense count: 203
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 6
+# Offense count: 7
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
 Lint/ConstantDefinitionInBlock:
   Exclude:
+    - 'spec/moxml/declaration_preservation_spec.rb'
     - 'spec/moxml/sax_spec.rb'
 
 # Offense count: 6
@@ -59,7 +60,7 @@ Lint/NoReturnInBeginEndBlocks:
   Exclude:
     - 'examples/api_client/api_client.rb'
 
-# Offense count: 86
+# Offense count: 93
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -75,12 +76,12 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 57
+# Offense count: 63
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 157
+# Offense count: 164
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 110
@@ -90,23 +91,10 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 7
 
-# Offense count: 36
+# Offense count: 43
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
-  Exclude:
-    - 'benchmarks/generate_report.rb'
-    - 'examples/web_scraper/web_scraper.rb'
-    - 'lib/moxml/adapter/customized_oga/xml_generator.rb'
-    - 'lib/moxml/adapter/customized_rexml/formatter.rb'
-    - 'lib/moxml/adapter/libxml.rb'
-    - 'lib/moxml/adapter/ox.rb'
-    - 'lib/moxml/adapter/rexml.rb'
-    - 'lib/moxml/document.rb'
-    - 'lib/moxml/xpath/compiler.rb'
-    - 'lib/moxml/xpath/conversion.rb'
-    - 'lib/moxml/xpath/lexer.rb'
-    - 'lib/moxml/xpath/parser.rb'
-    - 'lib/moxml/xpath/ruby/generator.rb'
+  Enabled: false
 
 # Offense count: 15
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
@@ -130,14 +118,7 @@ Naming/PredicateMethod:
   Exclude:
     - 'lib/moxml/xpath/ruby/node.rb'
 
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: OnlySumOrWithInitialValue.
-Performance/Sum:
-  Exclude:
-    - 'lib/moxml/xpath/compiler.rb'
-
-# Offense count: 42
+# Offense count: 46
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
@@ -145,11 +126,12 @@ RSpec/ContextWording:
     - 'spec/integration/headed_ox_integration_spec.rb'
     - 'spec/moxml/adapter/headed_ox_spec.rb'
     - 'spec/moxml/adapter/shared_examples/adapter_contract.rb'
+    - 'spec/moxml/declaration_preservation_spec.rb'
     - 'spec/moxml/xpath/lexer_spec.rb'
     - 'spec/moxml/xpath/parser_spec.rb'
     - 'spec/performance/benchmark_spec.rb'
 
-# Offense count: 14
+# Offense count: 15
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Exclude:
@@ -161,6 +143,7 @@ RSpec/DescribeClass:
     - 'spec/consistency/adapter_parity_spec.rb'
     - 'spec/integration/all_adapters_spec.rb'
     - 'spec/integration/headed_ox_integration_spec.rb'
+    - 'spec/moxml/declaration_preservation_spec.rb'
     - 'spec/moxml/error_spec.rb'
     - 'spec/moxml/xpath/axes_spec.rb'
     - 'spec/moxml/xpath/functions/boolean_functions_spec.rb'
@@ -173,7 +156,7 @@ RSpec/DescribeClass:
     - 'spec/moxml/xpath_capabilities_spec.rb'
     - 'spec/performance/xpath_benchmark_spec.rb'
 
-# Offense count: 215
+# Offense count: 217
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 85
@@ -197,9 +180,10 @@ RSpec/InstanceVariable:
   Exclude:
     - 'spec/moxml/sax_spec.rb'
 
-# Offense count: 6
+# Offense count: 7
 RSpec/LeakyConstantDeclaration:
   Exclude:
+    - 'spec/moxml/declaration_preservation_spec.rb'
     - 'spec/moxml/sax_spec.rb'
 
 # Offense count: 2
@@ -208,7 +192,7 @@ RSpec/LeakyConstantDeclaration:
 RSpec/MessageSpies:
   EnforcedStyle: receive
 
-# Offense count: 308
+# Offense count: 317
 RSpec/MultipleExpectations:
   Max: 10
 
@@ -217,6 +201,11 @@ RSpec/MultipleExpectations:
 RSpec/MultipleMemoizedHelpers:
   Max: 7
 
+# Offense count: 10
+# Configuration parameters: AllowedGroups.
+RSpec/NestedGroups:
+  Max: 4
+
 # Offense count: 3
 # Configuration parameters: AllowedPatterns.
 # AllowedPatterns: ^expect_, ^assert_
@@ -262,12 +251,6 @@ Security/Eval:
   Exclude:
     - 'spec/moxml/xpath/ruby/generator_spec.rb'
 
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-Style/CombinableLoops:
-  Exclude:
-    - 'lib/moxml/adapter/customized_rexml/formatter.rb'
-
 # Offense count: 1
 Style/DocumentDynamicEvalDefinition:
   Exclude:

data/README.adoc

@@ -26,6 +26,8 @@ Key features:
 
 == Supported XML libraries
 
+=== General
+
 Moxml supports the following XML libraries:
 
 REXML:: https://github.com/ruby/rexml[REXML], a pure Ruby XML parser
@@ -110,7 +112,9 @@ section.
 NOTE: HeadedOx provides full XPath 1.0 support via a pure Ruby XPath engine
 layered on top of Ox's C parser. See HeadedOx documentation for details.
 
-NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element, characters, errors). No separate CDATA, comment, or processing instruction events.
+NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element,
+characters, errors). No separate CDATA, comment, or processing instruction
+events.
 
 == Adapter comparison
 
@@ -356,7 +360,7 @@ NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element, c
 | ✅ Full
 | ✅ Full
 | ✅ Full
-| ⚠️ Limited^4^
+| ✅ Full
 | ✅ Full
 | ✅ Full
 
@@ -400,13 +404,12 @@ NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element, c
 | ✅ Yes
 | ✅ Yes
 |===
-
++
 ^1^ Ox/HeadedOx: Text node replacement may fail in some cases due to internal node structure +
 ^2^ Ox: `//book[@id]` works (returns all book elements), but doesn't filter by attribute existence +
 ^3^ HeadedOx: Full XPath 1.0 with all 27 functions and 6 axes. Pure Ruby XPath engine on Ox's C parser. 99.20% pass rate. See link:docs/headed-ox.adoc[] +
 ^4^ Ox: Use `.find { |el| el["id"] == "123" }` instead of XPath attribute value predicates +
-^5^ LibXML: DOCTYPE parsing works, serialization is limited (no round-trip preservation) +
-^6^ HeadedOx limitations: Namespace introspection and 7 axes not implemented. See link:docs/HEADED_OX_LIMITATIONS.md[]
+^5^ HeadedOx limitations: Namespace introspection and 7 axes not implemented. See link:docs/HEADED_OX_LIMITATIONS.md[]
 
 === Adapter selection guide
 
@@ -453,10 +456,13 @@ NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element, c
 * Need more XPath capabilities than standard Ox provides
 * Memory efficiency is important but XPath features are required
 
-CAUTION: Ox's custom XPath engine supports common patterns but may not handle
+CAUTION: Ox's custom XPath engine supports common patterns but cannot handle
 complex XPath expressions. Test thoroughly if your use case requires advanced
 XPath.
 
+TODO: We should throw errors when unsupported XPath features are used with Ox
+or HeadedOx to prevent silent failures.
+
 
 == Getting started
 
@@ -643,6 +649,23 @@ For complete SAX documentation including all handler types, event methods, adapt
 
 For complete node API reference including traversal methods, manipulation, queries, type checking, and node information, see link:docs/_pages/node-api-reference.adoc[Node API Reference].
 
+=== Node identity
+
+Moxml provides a consistent `#identifier` method across all node types to safely identify nodes:
+
+[source,ruby]
+----
+element = doc.at_xpath("//book")
+puts element.identifier  # => "book"
+
+attr = element.attribute("id")
+puts attr.identifier     # => "id"
+----
+
+The `#identifier` method returns the primary identifier for each node type (tag name for elements, attribute name for attributes, target for processing instructions, or `nil` for content nodes).
+
+IMPORTANT: Always use type-safe patterns when working with mixed node types. See the link:docs/_guides/node-api-consistency.adoc[Node API Consistency Guide] for complete documentation on safe coding patterns, API surface by node type, and migration guidelines.
+
 
 == Advanced features
 
@@ -694,7 +717,8 @@ rescue Moxml::Error => e
 end
 ----
 
-For complete error class hierarchy, error types, best practices, and debugging techniques, see link:docs/_pages/error-handling.adoc[Error Handling Guide].
+For complete error class hierarchy, error types, best practices, and debugging
+techniques, see link:docs/_pages/error-handling.adoc[Error Handling Guide].
 
 
 == Configuration
@@ -717,22 +741,31 @@ context = Moxml.new do |config|
 end
 ----
 
-For all configuration options, adapter selection, serialization options, and environment-based configuration, see link:docs/_pages/configuration.adoc[Configuration Guide].
+For all configuration options, adapter selection, serialization options, and
+environment-based configuration, see
+link:docs/_pages/configuration.adoc[Configuration Guide].
 
 
 
 == Thread safety
 
-For complete information on thread-safe patterns, context management, and concurrent processing, see the link:docs/_pages/thread-safety.adoc[Thread Safety Guide].
+For complete information on thread-safe patterns, context management, and
+concurrent processing, see the link:docs/_pages/thread-safety.adoc[Thread Safety
+Guide].
 
 
 == Performance considerations
 
-For detailed performance optimization strategies, memory management best practices, and efficient querying patterns, see the link:docs/_pages/performance.adoc[Performance Considerations Guide].
+For detailed performance optimization strategies, memory management best
+practices, and efficient querying patterns, see the
+link:docs/_pages/performance.adoc[Performance Considerations Guide].
 
 == Best practices
 
-For comprehensive best practices covering XPath queries, adapter selection, error handling, namespace handling, memory management, thread safety, performance optimization, and testing strategies, see link:docs/_pages/best-practices.adoc[Best Practices Guide].
+For comprehensive best practices covering XPath queries, adapter selection,
+error handling, namespace handling, memory management, thread safety,
+performance optimization, and testing strategies, see
+link:docs/_pages/best-practices.adoc[Best Practices Guide].
 
 
 == Specific adapter limitations
@@ -756,11 +789,13 @@ The Ox adapter provides maximum parsing speed but has XPath limitations.
 doc.xpath("//book").find { |book| book["id"] == "123" }
 ----
 
-For complete Ox adapter documentation including all limitations and workarounds, see link:docs/_pages/adapters/ox.adoc[Ox Adapter Guide].
+For complete Ox adapter documentation including all limitations and workarounds,
+see link:docs/_pages/adapters/ox.adoc[Ox Adapter Guide].
 
 === HeadedOx adapter
 
-The HeadedOx adapter combines Ox's fast C-based XML parsing with Moxml's comprehensive pure Ruby XPath 1.0 engine.
+The HeadedOx adapter combines Ox's fast C-based XML parsing with Moxml's
+comprehensive pure Ruby XPath 1.0 engine.
 
 **Status:** Production-ready v1.2 (99.20% pass rate, 1,992/2,008 tests)
 
@@ -796,12 +831,6 @@ For complete HeadedOx documentation including architecture, XPath capabilities,
 
 ==== LibXML adapter
 
-*DOCTYPE Limitations:*
-
-* DOCTYPE parsing works
-* DOCTYPE round-trip preservation is limited
-* DOCTYPE cannot be reliably re-serialized after parsing
-
 *Performance:*
 
 * Serialization speed: ~120 ips (slower than target)
@@ -819,7 +848,9 @@ limitations. Use these adapters when you need full XPath and namespace support.
 
 == Development and testing
 
-For complete information on development setup, testing strategies, benchmarking, and coverage reporting, see the link:docs/_guides/development-testing.adoc[Development and Testing Guide].
+For complete information on development setup, testing strategies, benchmarking,
+and coverage reporting, see the
+link:docs/_guides/development-testing.adoc[Development and Testing Guide].
 
 == Contributing
 

data/docs/_config.yml

@@ -1,9 +1,9 @@
 # Site settings
-title: Moxml
+title: "Moxml: Modern XML for Ruby"
 description: >-
   Modern XML processing for Ruby with unified adapter interface
 baseurl: "/moxml"
-url: "https://lutaml.github.io"
+url: "https://www.lutaml.org"
 
 # Theme
 theme: just-the-docs
@@ -43,7 +43,7 @@ back_to_top_text: "Back to top"
 # Footer content
 footer_content: >-
   Copyright © 2025 Ribose. Distributed by a
-  <a href="https://github.com/lutaml/moxml/blob/main/LICENSE.md">BSD-2-Clause license</a>.
+  <a href="https://github.com/lutaml/moxml/blob/main/LICENSE.md">BSD-3-Clause license</a>.
 
 # Footer last edit timestamp
 last_edit_timestamp: true

data/docs/_guides/index.adoc

@@ -10,17 +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:creating-documents[Creating documents]::
-Build XML documents from scratch using the builder pattern or direct
-manipulation.
+link:working-with-documents[Working with Documents]::
+Create and manipulate XML documents
 
 link:modifying-xml[Modifying XML]::
-Add, remove, and modify elements, attributes, and content in XML documents.
+Edit elements, attributes, and content
 
-link:serializing-xml[Serializing XML]::
-Convert XML documents to strings with formatting and encoding options.
+link:sax-parsing[SAX Parsing]::
+Memory-efficient event-driven parsing
+
+link:advanced-features[Advanced Features]::
+Namespaces, XPath, and more
+
+link:node-api-consistency[Node API Consistency]::
+Understanding node types and their APIs
+
+link:development-testing[Development & Testing]::
+Contributing to Moxml
 
 === Querying and traversal
 

data/docs/_guides/modifying-xml.adoc

@@ -1,6 +1,5 @@
 ---
 title: Modifying XML
-parent: Overview
 nav_order: 3
 ---