moxml 0.1.7 → 0.1.8

data/docs/_pages/compatibility.adoc

@@ -0,0 +1,468 @@
+---
+title: Compatibility
+parent: Overview
+nav_order: 6
+---
+
+== Compatibility
+
+=== Purpose
+
+This page provides a comprehensive comparison of features, performance, and
+capabilities across all supported XML adapters.
+
+=== Feature compatibility matrix
+
+[cols="3,1,1,1,1,1", options="header"]
+|===
+| Feature/Operation | Nokogiri | Oga | REXML | LibXML | Ox
+
+| **Core operations**
+|
+|
+|
+|
+|
+
+| Parse XML string
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Parse XML file/IO
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Serialize to XML
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| **Element operations**
+|
+|
+|
+|
+|
+
+| Create elements
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Get/set attributes
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Add/remove children
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Replace nodes
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ⚠️ Limited^1^
+
+| **Namespace operations**
+|
+|
+|
+|
+|
+
+| Add namespaces
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Default namespaces
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ⚠️ Basic
+
+| Namespace inheritance
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+
+| Namespaced attributes
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ⚠️ Limited
+
+| **XPath queries**
+|
+|
+|
+|
+|
+
+| Basic paths (`//element`)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Attribute predicates (`[@id]`)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ⚠️ Name only^2^
+
+| Attribute values (`[@id='123']`)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None^3^
+
+| Logical operators
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+
+| Position predicates
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+
+| Text predicates
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+
+| Namespace XPath
+| ✅ Full
+| ✅ Full
+| ❌ None
+| ✅ Full
+| ❌ None
+
+| Parent axis (`..`)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+
+| Sibling axes
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+
+| XPath functions
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+
+| **Special content**
+|
+|
+|
+|
+|
+
+| CDATA sections
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Comments
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Processing instructions
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| DOCTYPE declarations
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ⚠️ Limited^4^
+| ✅ Full
+
+| **Performance**
+|
+|
+|
+|
+|
+
+| Parse speed
+| Fast
+| Fast
+| Medium
+| Very Fast
+| Very Fast
+
+| Serialize speed
+| Fast
+| Fast
+| Medium
+| Very Fast
+| Fastest
+
+| Memory usage
+| Good
+| Medium
+| Medium
+| Excellent
+| Best
+
+| Thread safety
+| ✅ Yes
+| ✅ Yes
+| ✅ Yes
+| ✅ Yes
+| ✅ Yes
+|===
+
+=== Legend
+
+✅ Full:: Complete support with no limitations
+⚠️ Limited:: Partial support with workarounds available
+❌ None:: Not supported
+
+=== Footnotes
+
+^1^ Ox: Text node replacement may fail in some cases due to internal node
+structure
+
+^2^ Ox: `//book[@id]` returns all book elements (doesn't filter by attribute
+existence)
+
+^3^ Ox: Use `.find { |el| el["id"] == "123" }` instead of XPath attribute
+value predicates
+
+^4^ LibXML: DOCTYPE parsing works, serialization is limited (no perfect
+round-trip)
+
+=== Performance comparison
+
+==== Parsing performance (medium 10KB XML)
+
+[source]
+----
+Ox         ████████████████████████████████████████████████ 289 ips
+LibXML     ███████████████████████████████████ 120 ips
+Nokogiri   █████████████████ 76 ips
+Oga        ███████████ 50 ips
+REXML      ████ 15 ips
+----
+
+==== Serialization performance
+
+[source]
+----
+Ox         ████████████████████████████████████████████████ 39,203 ips
+Nokogiri   █████████████████ 13,900 ips
+LibXML     ███████ 5,600 ips
+Oga        ████ 3,200 ips
+REXML      ██ 1,500 ips
+----
+
+==== XPath performance (simple queries)
+
+[source]
+----
+Nokogiri   ████████████████████████████████████████████████ 64,958 ips
+LibXML     ███████████████████████████████████████████████ 62,000 ips
+Oga        ███████████████████████ 28,000 ips
+REXML      ███████ 8,500 ips
+Ox         ███████ 9,640 ips
+----
+
+NOTE: Performance numbers are approximate and vary by system and document
+complexity.
+
+=== Memory usage comparison
+
+[cols="2,2,3"]
+|===
+| Adapter | Memory delta | Description
+
+| Ox
+| 0.0 MB
+| Best - minimal allocation
+
+| Nokogiri
+| -0.1 MB
+| Excellent efficiency
+
+| LibXML
+| +0.1 MB
+| Very good
+
+| Oga
+| +0.3 MB
+| Good for pure Ruby
+
+| REXML
+| +0.5 MB
+| Medium overhead
+|===
+
+=== XPath capability summary
+
+[cols="2,4"]
+|===
+| Capability level | Adapters
+
+| Full XPath 1.0
+| Nokogiri, LibXML, Oga
+
+| Basic XPath
+| REXML (no namespaces), Ox (no predicates)
+
+| Ruby workarounds needed
+| Ox, REXML (for complex queries)
+|===
+
+=== Adapter selection decision tree
+
+[source]
+----
+Need pure Ruby?
+├─ Yes
+│  ├─ Need full XPath? → Oga
+│  ├─ No external gems? → REXML
+│  └─ Basic XPath OK? → REXML
+└─ No (C extensions OK)
+   ├─ Need maximum speed? → Ox
+   ├─ Simple documents? → Ox
+   ├─ Complex XPath? → Nokogiri or LibXML
+   ├─ Industry standard? → Nokogiri
+   └─ Alternative to Nokogiri? → LibXML
+----
+
+=== Recommendations by use case
+
+[cols="2,2,3"]
+|===
+| Use case | Primary choice | Alternative
+
+| General XML processing
+| Nokogiri
+| LibXML
+
+| Maximum performance
+| Ox
+| LibXML
+
+| Pure Ruby requirement
+| Oga
+| REXML
+
+| No external dependencies
+| REXML
+| N/A
+
+| Complex XPath queries
+| Nokogiri
+| LibXML, Oga
+
+| High-throughput simple docs
+| Ox
+| LibXML
+
+| Namespace-heavy documents
+| Nokogiri
+| LibXML, Oga
+
+| Memory-constrained
+| Ox
+| Nokogiri
+|===
+
+=== Testing across adapters
+
+To ensure your code works across adapters:
+
+[source,ruby]
+----
+# Test with multiple adapters
+[:nokogiri, :libxml, :oga, :rexml, :ox].each do |adapter_name|
+  next unless adapter_available?(adapter_name)
+
+  context = Moxml.new
+  context.config.adapter = adapter_name
+
+  doc = context.parse(xml)
+
+  # Test your operations
+  results = doc.xpath('//book')
+  # Add assertions
+end
+----
+
+=== Migration guide
+
+**From Nokogiri to Ox:**
+
+* Replace complex XPath with Ruby filtering
+* Test namespace operations carefully
+* Verify text node replacements work
+
+**From REXML to Nokogiri/LibXML:**
+
+* No code changes needed
+* XPath queries will work better automatically
+* Performance will improve significantly
+
+**From Ox to Nokogiri:**
+
+* Complex XPath will work automatically
+* No workarounds needed
+* Performance may decrease for parsing
+
+=== See also
+
+* link:adapters/[Individual adapter documentation]
+* link:../guides/adapter-switching[Adapter switching guide]
+* link:../guides/performance-optimization[Performance optimization]

data/docs/_pages/configuration.adoc

@@ -0,0 +1,251 @@
+---
+title: Configuration
+parent: Overview
+nav_order: 7
+---
+
+== Configuration
+
+=== Purpose
+
+Learn how to configure Moxml for your application's requirements including
+adapter selection, parsing options, and encoding settings.
+
+=== Global configuration
+
+Configure Moxml globally for your application:
+
+[source,ruby]
+----
+# Set default adapter
+Moxml::Config.default_adapter = :nokogiri
+
+# Access global config
+config = Moxml::Config.new
+config.adapter = :libxml
+config.strict_parsing = true
+config.default_encoding = 'UTF-8'
+----
+
+=== Instance configuration
+
+Configure per Moxml instance:
+
+[source,ruby]
+----
+# During initialization
+context = Moxml.new do |config|
+  config.adapter = :oga
+  config.strict_parsing = false
+  config.default_encoding = 'ISO-8859-1'
+end
+
+# After creation
+context = Moxml.new
+context.config.adapter = :libxml
+context.config.strict_parsing = true
+----
+
+=== Configuration options
+
+==== Adapter selection
+
+Choose the XML processing library:
+
+[source,ruby]
+----
+context = Moxml.new
+context.config.adapter = :nokogiri  # or :libxml, :oga, :rexml, :ox
+----
+
+**Available adapters:**
+
+* `:nokogiri` - Default, full features
+* `:libxml` - Native performance
+* `:oga` - Pure Ruby
+* `:rexml` - Standard library
+* `:ox` - Maximum speed
+
+See link:adapters/[Adapters documentation] for details.
+
+==== Strict parsing
+
+Control error handling for malformed XML:
+
+[source,ruby]
+----
+# Strict mode (recommended for production)
+context.config.strict_parsing = true
+doc = context.parse(xml)  # Raises ParseError on malformed XML
+
+# Relaxed mode (attempt to parse malformed XML)
+context.config.strict_parsing = false
+doc = context.parse(xml)  # Attempts to recover from errors
+----
+
+**Default:** `true`
+
+==== Default encoding
+
+Set default character encoding:
+
+[source,ruby]
+----
+context.config.default_encoding = 'UTF-8'    # Default
+context.config.default_encoding = 'ISO-8859-1'
+context.config.default_encoding = 'UTF-16'
+----
+
+**Default:** `"UTF-8"`
+
+=== Context switching
+
+Use different configurations for different tasks:
+
+[source,ruby]
+----
+# High-performance context for simple docs
+fast_context = Moxml.new
+fast_context.config.adapter = :ox
+
+# Feature-rich context for complex docs
+full_context = Moxml.new
+full_context.config.adapter = :nokogiri
+
+# Process based on requirements
+if simple_document?(xml)
+  doc = fast_context.parse(xml)
+else
+  doc = full_context.parse(xml)
+end
+----
+
+=== Serialization options
+
+Control XML output format:
+
+[source,ruby]
+----
+xml = doc.to_xml(
+  indent: 2,                    # Indentation spaces
+  encoding: 'UTF-8',            # Output encoding
+  no_declaration: false,         # Include <?xml ...?>
+  expand_empty: false            # Expand empty tags <tag></tag>
+)
+----
+
+=== Adapter-specific configuration
+
+Some adapters support additional options:
+
+==== Nokogiri
+
+[source,ruby]
+----
+# Nokogiri parse options
+doc = context.parse(xml,
+  strict: true,
+  encoding: 'UTF-8',
+  recover: false  # Don't recover from errors
+)
+----
+
+==== LibXML
+
+[source,ruby]
+----
+# LibXML parse options
+doc = context.parse(xml,
+  strict: true,
+  encoding: 'UTF-8'
+)
+----
+
+==== Ox
+
+[source,ruby]
+----
+# Ox typically uses fewer options
+doc = context.parse(xml)
+----
+
+=== Configuration best practices
+
+. **Set adapter explicitly** in production for consistency
+. **Use strict parsing** to catch XML errors early
+. **Specify encoding** when working with non-UTF-8 documents
+. **Document configuration** in your application setup
+. **Test with target adapter** during development
+
+=== Environment-based configuration
+
+Configure based on environment:
+
+[source,ruby]
+----
+# config/initializers/moxml.rb
+case Rails.env
+when 'production'
+  Moxml::Config.default_adapter = :nokogiri
+  Moxml.new.config.strict_parsing = true
+when 'development'
+  Moxml::Config.default_adapter = :nokogiri
+  Moxml.new.config.strict_parsing = false
+when 'test'
+  Moxml::Config.default_adapter = :rexml  # No C extensions needed
+end
+----
+
+=== Runtime adapter switching
+
+Change adapters dynamically:
+
+[source,ruby]
+----
+def process_with_best_adapter(xml)
+  # Try fast adapter first
+  context = Moxml.new
+  context.config.adapter = :ox
+
+  doc = context.parse(xml)
+
+  # Check if complex operations needed
+  if needs_complex_xpath?(doc)
+    # Switch to full-featured adapter
+    context.config.adapter = :nokogiri
+    doc = context.parse(xml)
+  end
+
+  doc
+end
+----
+
+=== Configuration validation
+
+Verify configuration is correct:
+
+[source,ruby]
+----
+context = Moxml.new
+
+# Check adapter loaded
+puts context.config.adapter.name
+# => "Moxml::Adapter::Nokogiri"
+
+# Verify adapter available
+begin
+  context.config.adapter = :missing_adapter
+rescue Moxml::AdapterError => e
+  puts "Adapter not available: #{e.message}"
+end
+
+# Test parsing works
+test_doc = context.parse('<root/>')
+puts "Configuration valid" if test_doc.root
+----
+
+=== See also
+
+* link:adapters/[Adapters] - Adapter-specific documentation
+* link:installation[Installation] - Setting up adapters
+* link:../guides/adapter-switching[Adapter switching guide]