moxml 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f1290755cf60610b63b7c82a4d043e662627a0c1b7a5692a70e987ddae69fa6
-  data.tar.gz: 05c9430233444a7915cb36789af8ebad99bc34391324c010a8e9c07f1cd36d33
+  metadata.gz: 4b2faed71c75f32fcfe528621b1d3ed01c603b04f81e75d5b45b6c525d9d1836
+  data.tar.gz: 68ead788c2e5098b2f1f88653443fe4d8ff1e76b17dab09c08badb64c7ab70a3
 SHA512:
-  metadata.gz: ca2bf23c9b78a09dc984a974b86eadabddca8e4f90dbcdda263ff2295a61a4a6c1252fdeb5ad7ace732533887abef1d8636f5e1c6556f720485ed61d8e93da32
-  data.tar.gz: 508e707c528f5a729dea7de4a5940a6df8f70a3bd537295ef510a1280be322833b06bdc3b4242f869dae11c7cda09b07b84a9e13ead7f5810fb90f6f565e872c
+  metadata.gz: 8aa59a486d44d101e1c078fc6fde2eea1cad9d4d7690d937dc7faef233a4143206432ffab53da3a2ef01af9245d17f706ddb01bc55b2c3555b358a6a3df10143
+  data.tar.gz: b5256089daef1f94012046bd7ff0fcbff1827c615b46d416231933de3193f3a262063a6ad761a87c629cdfe15fc51644fc1887d43eaeff5f8710bd16a791ea3c

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-24 13:45:20 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: 192
 # 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: 42
 # 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/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

@@ -12,6 +12,12 @@ Task-oriented guides for common XML processing operations with Moxml.
 link:parsing-xml[Parsing XML]::
 Parse XML from strings, files, and IO streams with different adapters.
 
+link:sax-parsing[SAX parsing]::
+Memory-efficient event-driven parsing for large XML files and streaming data.
+
+link:xml-declaration[XML declaration preservation]::
+Understand how Moxml preserves XML declarations for round-trip fidelity and standards compliance.
+
 link:creating-documents[Creating documents]::
 Build XML documents from scratch using the builder pattern or direct
 manipulation.

data/docs/_guides/modifying-xml.adoc

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

data/docs/_guides/parsing-xml.adoc

@@ -1,6 +1,5 @@
 ---
 title: Parsing XML
-parent: Overview
 nav_order: 2
 ---
 

data/docs/_guides/xml-declaration.adoc

@@ -0,0 +1,450 @@
+= XML Declaration Preservation
+:toc:
+:toclevels: 3
+
+== Overview
+
+Moxml automatically preserves the presence or absence of XML declarations (`<?xml version="1.0"?>`) when parsing and serializing documents. This ensures round-trip fidelity and compliance with standards that require specific declaration handling.
+
+=== Why This Matters
+
+Some XML use cases require specific declaration handling:
+
+* **SVG Files**: Often have no XML declaration
+* **XML Fragments**: Should not have declarations
+* **Standards Compliance**: Some specs prohibit declarations in certain contexts
+* **Round-Trip Fidelity**: Parse → Modify → Serialize should preserve format
+
+=== Key Features
+
+* **Automatic Detection**: Moxml detects whether input had a declaration
+* **Automatic Preservation**: Output matches input format by default
+* **Explicit Override**: Force add or remove declarations when needed
+* **All Adapters**: Works across all 6 XML adapters
+
+== Basic Usage
+
+=== Automatic Preservation
+
+Moxml automatically preserves whether input had an XML declaration:
+
+[source,ruby]
+----
+require 'moxml'
+
+# Document without declaration
+svg = '<svg xmlns="http://www.w3.org/2000/svg"><rect/></svg>'
+doc = Moxml.new.parse(svg)
+doc.to_xml
+# => "<svg xmlns=\"http://www.w3.org/2000/svg\"><rect/></svg>"
+# ✓ No <?xml...?> added
+
+# Document with declaration
+xml = '<?xml version="1.0" encoding="UTF-8"?><root><child/></root>'
+doc = Moxml.new.parse(xml)
+doc.to_xml
+# => "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root><child/></root>"
+# ✓ Declaration preserved
+----
+
+=== Checking Declaration Presence
+
+Use the `has_xml_declaration` attribute to check if a document has a declaration:
+
+[source,ruby]
+----
+# Document without declaration
+doc = Moxml.new.parse('<root/>')
+doc.has_xml_declaration  # => false
+
+# Document with declaration
+doc = Moxml.new.parse('<?xml version="1.0"?><root/>')
+doc.has_xml_declaration  # => true
+----
+
+== Explicit Control
+
+=== Forcing Declaration Addition
+
+Add a declaration to documents that don't have one:
+
+[source,ruby]
+----
+svg = '<svg><rect/></svg>'
+doc = Moxml.new.parse(svg)
+
+# Force add declaration
+output = doc.to_xml(declaration: true)
+# => "<?xml version=\"1.0\" encoding=\"UTF-8\"?><svg><rect/></svg>"
+----
+
+=== Removing Declarations
+
+Remove declaration from documents that have one:
+
+[source,ruby]
+----
+xml = '<?xml version="1.0"?><root><item/></root>'
+doc = Moxml.new.parse(xml)
+
+# Force remove declaration
+output = doc.to_xml(declaration: false)
+# => "<root><item/></root>"
+----
+
+== Use Cases
+
+=== SVG File Processing
+
+SVG files often don't have XML declarations. Moxml preserves this:
+
+[source,ruby]
+----
+# Original SVG without declaration
+svg_content = File.read('image.svg')
+doc = Moxml.new.parse(svg_content)
+
+# Modify SVG (add viewBox)
+doc.root['viewBox'] = '0 0 100 100'
+
+# Save - no declaration added
+File.write('image.svg', doc.to_xml)
+----
+
+=== XML Fragment Generation
+
+Create XML fragments without declarations:
+
+[source,ruby]
+----
+context = Moxml.new
+doc = context.create_document
+
+# Build fragment
+root = doc.create_element('fragment')
+root << doc.create_element('item')
+doc.root = root
+
+# Serialize without declaration (default for built documents)
+doc.to_xml  # => "<fragment><item/></fragment>"
+----
+
+=== Standards-Compliant XML
+
+Some XML standards require or prohibit declarations:
+
+[source,ruby]
+----
+# Standard prohibits declarations
+doc = Moxml.new.parse(compliant_xml_without_decl)
+output = doc.to_xml  # Declaration correctly absent
+
+# Standard requires declarations
+doc = Moxml.new.parse(standard_xml_with_decl)
+output = doc.to_xml  # Declaration correctly present
+----
+
+=== Round-Trip Processing
+
+Preserve original format through multiple parse/serialize cycles:
+
+[source,ruby]
+----
+original = '<data><item id="1"/></data>'
+
+# First round-trip
+doc1 = Moxml.new.parse(original)
+intermediate = doc1.to_xml
+
+# Second round-trip
+doc2 = Moxml.new.parse(intermediate)
+final = doc2.to_xml
+
+# All three are identical
+original == intermediate && intermediate == final  # => true
+----
+
+== Adapter Behavior
+
+All 6 adapters support declaration preservation:
+
+[cols="1,3"]
+|===
+|Adapter |Implementation
+
+|Nokogiri
+|Uses `SaveOptions::NO_DECLARATION` flag
+
+|Oga
+|Custom serialization logic
+
+|REXML
+|Conditional declaration output
+
+|Ox
+|Declaration control in serialize
+
+|LibXML
+|Custom serializer respects flag
+
+|HeadedOx
+|Inherits Ox implementation
+|===
+
+== Advanced Usage
+
+=== Programmatically Built Documents
+
+Documents built from scratch default to no declaration:
+
+[source,ruby]
+----
+doc = Moxml.new.create_document
+root = doc.create_element('config')
+doc.root = root
+
+doc.has_xml_declaration  # => false
+doc.to_xml  # => "<config/>"
+
+# Explicitly add declaration if needed
+doc.to_xml(declaration: true)
+# => "<?xml version=\"1.0\" encoding=\"UTF-8\"?><config/>"
+----
+
+=== Element Serialization
+
+Only document nodes can have declarations. Element serialization never includes declarations:
+
+[source,ruby]
+----
+doc = Moxml.new.parse('<?xml version="1.0"?><root><child/></root>')
+element = doc.root
+
+# Element serialization - no declaration
+element.to_xml  # => "<root><child/></root>"
+
+# Even with explicit request (ignored for elements)
+element.to_xml(declaration: true)  # => "<root><child/></root>"
+----
+
+=== Custom Declaration Attributes
+
+When forcing declaration addition, use standard attributes:
+
+[source,ruby]
+----
+doc = Moxml.new.parse('<root/>')
+
+# Default declaration
+doc.to_xml(declaration: true)
+# => "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root/>"
+
+# Custom encoding via adapter
+doc.to_xml(declaration: true, encoding: "ISO-8859-1")
+# => "<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?><root/>"
+----
+
+== Best Practices
+
+=== Let Moxml Handle It
+
+In most cases, rely on automatic preservation:
+
+[source,ruby]
+----
+# Good - automatic preservation
+doc = Moxml.new.parse(xml_content)
+modified = process_document(doc)
+output = doc.to_xml  # Declaration preserved automatically
+
+# Only use explicit control when required by specific needs
+output = doc.to_xml(declaration: false)  # Explicit requirement
+----
+
+=== Check Declaration Before Processing
+
+Know what you're working with:
+
+[source,ruby]
+----
+doc = Moxml.new.parse(xml_source)
+
+if doc.has_xml_declaration
+  # Handle documents with declarations
+  process_with_declaration(doc)
+else
+  # Handle fragments without declarations
+  process_fragment(doc)
+end
+----
+
+=== Document Your Requirements
+
+Make declaration requirements explicit in code:
+
+[source,ruby]
+----
+def save_svg(doc)
+  # SVG files should not have XML declarations
+  raise "SVG has declaration" if doc.has_xml_declaration
+  File.write('output.svg', doc.to_xml)
+end
+
+def save_xml_config(doc)
+  # Config files require declarations
+  File.write('config.xml', doc.to_xml(declaration: true))
+end
+----
+
+== Migration from Previous Versions
+
+=== Behavior Change
+
+In Moxml versions before 0.2.1, serialization *always* added an XML declaration. Starting with 0.2.1, behavior changed to preserve input format:
+
+[cols="1,2,2"]
+|===
+|Scenario |Before v0.2.1 |v0.2.1+
+
+|Parse without declaration
+|Added declaration ❌
+|No declaration ✓
+
+|Parse with declaration
+|Preserved declaration ✓
+|Preserved declaration ✓
+
+|Built document
+|Added declaration
+|No declaration (can override)
+|===
+
+=== Update Your Code
+
+If you relied on automatic declaration addition:
+
+[source,ruby]
+----
+# Before (relied on automatic declaration)
+doc = Moxml.new.parse('<root/>')
+output = doc.to_xml  # Had declaration
+
+# After (explicitly request if needed)
+doc = Moxml.new.parse('<root/>')
+output = doc.to_xml(declaration: true)  # Force add
+----
+
+=== Minimal Impact
+
+Most code will see **no change** because:
+
+* Documents with declarations still preserve them
+* Only fragments without declarations behave differently
+* New behavior is arguably more correct
+
+== Troubleshooting
+
+=== Declaration Not Preserved
+
+If declaration isn't being preserved, check:
+
+1. **Input Format**: Verify input actually has `<?xml...?>`
++
+[source,ruby]
+----
+xml_content = File.read('file.xml')
+puts "Has declaration: #{xml_content.strip.start_with?('<?xml')}"
+----
+
+2. **Explicit Override**: Check if code explicitly removes it
++
+[source,ruby]
+----
+# This will remove declaration regardless of input
+doc.to_xml(declaration: false)
+----
+
+3. **Element vs Document**: Only documents can have declarations
++
+[source,ruby]
+----
+element = doc.root
+element.to_xml  # Never has declaration (correct)
+----
+
+=== Unwanted Declaration
+
+If declaration is added when you don't want it:
+
+[source,ruby]
+----
+# Solution 1: Parse input without declaration
+svg = '<svg><rect/></svg>'  # No <?xml...?>
+doc = Moxml.new.parse(svg)
+doc.to_xml  # No declaration
+
+# Solution 2: Explicitly remove
+doc.to_xml(declaration: false)
+
+# Solution 3: Check and fix source
+if doc.has_xml_declaration
+  # Input has declaration - remove from source or override
+  output = doc.to_xml(declaration: false)
+end
+----
+
+=== Whitespace Before Declaration
+
+XML declarations must be at the document start. Whitespace before the declaration makes it invalid:
+
+[source,ruby]
+----
+# Invalid - whitespace before declaration
+invalid = '  <?xml version="1.0"?><root/>'
+doc = Moxml.new.parse(invalid)  # May raise error depending on adapter
+
+# Valid - declaration at start
+valid = '<?xml version="1.0"?><root/>'
+doc = Moxml.new.parse(valid)  # Works correctly
+----
+
+== API Reference
+
+=== Document Attributes
+
+==== has_xml_declaration
+
+[source,ruby]
+----
+doc.has_xml_declaration  # => Boolean
+----
+
+Returns `true` if the document was parsed from XML that contained an XML declaration, `false` otherwise.
+
+* Read/write attribute (can be manually set)
+* Defaults to `false` for programmatically built documents
+* Automatically set during parsing
+
+=== Serialization Options
+
+==== declaration
+
+[source,ruby]
+----
+doc.to_xml(declaration: true)   # Force include declaration
+doc.to_xml(declaration: false)  # Force exclude declaration
+doc.to_xml                       # Use automatic preservation
+----
+
+Controls whether XML declaration is included in serialized output:
+
+* `true`: Always 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

data/docs/_pages/adapter-compatibility.adoc

@@ -1,4 +1,4 @@
-= Moxml adapter compatibility matrix
+= Adapter compatibility matrix
 :toc:
 :toc-placement!: