moxml 0.1.7 → 0.1.9

data/docs/_pages/adapters/oga.adoc

@@ -0,0 +1,291 @@
+---
+title: Oga
+parent: Adapters
+nav_order: 3
+---
+
+== Oga adapter
+
+=== Purpose
+
+The Oga adapter provides pure Ruby XML processing with full XPath 1.0
+support, making it ideal for environments where C extensions are not allowed
+or desired.
+
+=== Overview
+
+link:https://github.com/yorickpeterse/oga[Oga] is a pure Ruby XML parser that
+requires no C extensions. It's perfect for JRuby, TruffleRuby, Opal, or any
+environment where native extensions are problematic.
+
+=== Installation
+
+Add to your Gemfile:
+
+[source,ruby]
+----
+gem 'moxml'
+gem 'oga'
+----
+
+Install:
+
+[source,shell]
+----
+bundle install
+----
+
+=== Configuration
+
+[source,ruby]
+----
+# Explicit selection
+context = Moxml.new
+context.config.adapter = :oga
+
+# Global default
+Moxml::Config.default_adapter = :oga
+----
+
+=== Features
+
+==== Full XPath 1.0 support
+
+Pure Ruby implementation of XPath 1.0:
+
+[source,ruby]
+----
+doc = Moxml.new.parse(xml)
+
+# All XPath features work
+books = doc.xpath('//book[@price < 30]')
+count = doc.xpath('count(//book)')
+titles = doc.xpath('//book[position() < 3]/title')
+
+# Namespace-aware queries
+doc.xpath('//ns:element', 'ns' => 'http://example.org')
+
+# Functions and predicates
+doc.xpath('//book[contains(title, "Ruby")]')
+----
+
+==== Complete namespace support
+
+Full namespace handling in pure Ruby:
+
+[source,ruby]
+----
+# Create namespaced elements
+element.add_namespace('dc', 'http://purl.org/dc/elements/1.1/')
+
+# Query with namespaces
+results = doc.xpath('//dc:creator',
+  'dc' => 'http://purl.org/dc/elements/1.1/')
+----
+
+==== All node types supported
+
+Complete support for all XML node types:
+
+* Elements with attributes
+* Text nodes
+* CDATA sections
+* Comments
+* Processing instructions
+* DOCTYPE declarations
+* XML declarations
+
+==== Pure Ruby benefits
+
+* No C extension compilation required
+* Works on JRuby and TruffleRuby
+* Compatible with Opal for browser environments
+* Easier debugging and introspection
+* No platform-specific build issues
+
+=== Limitations
+
+Minor limitations compared to native implementations:
+
+* Slower parsing than C-based libraries
+* Higher memory usage than Ox
+* Some advanced XPath 1.0 functions may have edge case differences
+
+NOTE: Oga's pure Ruby implementation makes it slower than C-based libraries,
+but it provides excellent functionality and is faster than REXML.
+
+=== Performance characteristics
+
+Based on benchmarks:
+
+[cols="2,2,3"]
+|===
+| Operation | Performance | Notes
+
+| Parse medium XML
+| ~30-50 ips
+| Pure Ruby parsing
+
+| Serialize medium XML
+| ~2,000+ ips
+| Efficient serialization
+
+| XPath queries
+| ~20,000+ ips
+| Pure Ruby XPath engine
+
+| Memory usage
+| Medium
+| More than C libraries, less than REXML
+|===
+
+=== Best use cases
+
+**Choose Oga when:**
+
+* Pure Ruby environment is required (JRuby, TruffleRuby)
+* C extensions cannot be compiled or used
+* Browser deployment via Opal is needed
+* Full XPath 1.0 support is required without C dependencies
+* Easier debugging of XML processing is desired
+
+**Avoid Oga when:**
+
+* Maximum parsing performance is critical (use link:ox[Ox] or
+link:nokogiri[Nokogiri])
+* Memory usage must be minimized (use link:ox[Ox])
+* Standard library only is required (use link:rexml[REXML])
+
+=== Example usage
+
+==== Basic document processing
+
+[source,ruby]
+----
+require 'moxml'
+
+# Configure Oga adapter
+context = Moxml.new
+context.config.adapter = :oga
+
+xml = <<~XML
+  <library>
+    <book id="1">
+      <title>Ruby Programming</title>
+      <price>29.99</price>
+    </book>
+  </library>
+XML
+
+doc = context.parse(xml)
+
+# Query with XPath
+book = doc.at_xpath('//book[@id="1"]')
+puts book.at_xpath('.//title').text  # => "Ruby Programming"
+
+# Modify
+book.at_xpath('.//price').text = '24.99'
+
+# Serialize
+puts doc.to_xml(indent: 2)
+----
+
+==== XPath queries
+
+[source,ruby]
+----
+# Complex XPath expressions work
+cheap_books = doc.xpath('//book[price < 25]')
+fiction = doc.xpath('//book[@category="fiction"]')
+last_book = doc.at_xpath('//book[last()]')
+
+# Functions
+book_count = doc.xpath('count(//book)')
+has_isbn = doc.xpath('//book[string-length(@isbn) = 13]')
+----
+
+==== Namespace handling
+
+[source,ruby]
+----
+xml = <<~XML
+  <library xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <book>
+      <dc:title>Programming</dc:title>
+      <dc:creator>Smith</dc:creator>
+    </book>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Query with namespaces
+ns = { 'dc' => 'http://purl.org/dc/elements/1.1/' }
+titles = doc.xpath('//dc:title', ns)
+
+puts titles.first.text  # => "Programming"
+----
+
+=== JRuby and TruffleRuby support
+
+Oga is particularly valuable for alternative Ruby implementations:
+
+[source,ruby]
+----
+# Works identically on JRuby
+# jruby -S gem install moxml oga
+# jruby script.rb
+
+# Works on TruffleRuby
+# Same code, no modifications needed
+
+require 'moxml'
+context = Moxml.new
+context.config.adapter = :oga
+
+# Full functionality on all Ruby implementations
+doc = context.parse(xml)
+results = doc.xpath('//book[@id="1"]')
+----
+
+=== Comparison with other pure Ruby options
+
+[cols="2,2,2"]
+|===
+| Aspect | Oga | REXML
+
+| XPath support
+| Full XPath 1.0
+| Limited
+
+| Performance
+| Fast for pure Ruby
+| Medium
+
+| Memory usage
+| Medium
+| Medium
+
+| Namespace XPath
+| Full support
+| Not supported
+
+| Standard library
+| No (external gem)
+| Yes (built-in)
+
+| Maintenance
+| Active
+| Active
+|===
+
+=== References
+
+* link:https://github.com/yorickpeterse/oga[Oga on GitHub]
+* link:https://github.com/yorickpeterse/oga/tree/master/doc[Oga documentation]
+
+=== See also
+
+* link:../compatibility[Compatibility matrix] - Feature comparison
+* link:rexml[REXML adapter] - Alternative pure Ruby option
+* link:../../guides/adapter-switching[Adapter switching guide]

data/docs/_pages/adapters/ox.adoc

@@ -0,0 +1,56 @@
+---
+title: Ox
+parent: Adapters
+nav_order: 5
+---
+
+== Ox adapter
+
+=== Overview
+
+Ox is the fastest XML parser available for Ruby, providing excellent performance for simple to moderately complex XML documents.
+
+**Best for:**
+
+* Maximum parsing speed
+* Simple document structures
+* Memory-constrained environments
+* When XPath usage is minimal
+
+== Specific adapter limitations
+
+=== Ox adapter
+
+==== XPath limitations
+
+The Ox adapter uses a custom "XPath-to-locate" translation engine.
+
+The following XPath features are NOT supported:
+
+* Attribute value predicates: `//book[@id='123']` ❌
+* Logical operators: `//book[@id and @title]` ❌
+* Position predicates: `//book[1]`, `//book[last()]` ❌
+* Text predicates: `//book[text()='Title']` ❌
+* Namespace queries: `//ns:element` ❌
+* Parent axis: `//child/..` ❌
+* Sibling axes: `following-sibling::*` ❌
+* XPath functions: `count()`, `concat()`, etc. ❌
+
+*Workaround:* Use Ruby enumerable methods after basic queries:
+
+[source,ruby]
+----
+# Instead of: doc.xpath("//book[@id='123']")
+# Use:
+doc.xpath("//book").find { |book| book["id"] == "123" }
+----
+
+IMPORTANT: For complete XPath 1.0 specification with zero limitations today, use
+Nokogiri or Oga adapters.
+
+
+
+See also:
+
+* link:headed-ox[HeadedOx adapter] - Ox with full XPath support
+* link:../compatibility[Adapter compatibility matrix]

data/docs/_pages/adapters/rexml.adoc

@@ -0,0 +1,292 @@
+---
+title: REXML
+parent: Adapters
+nav_order: 4
+---
+
+== REXML adapter
+
+=== Purpose
+
+The REXML adapter provides XML processing through Ruby's standard library,
+offering maximum portability without requiring any external gems.
+
+=== Overview
+
+link:https://github.com/ruby/rexml[REXML] is Ruby's built-in XML parser,
+distributed as part of the standard library. It requires no external
+dependencies and works on all Ruby installations.
+
+=== Installation
+
+REXML is included with Ruby, so only Moxml needs to be installed:
+
+[source,ruby]
+----
+gem 'moxml'
+# No additional gems needed - REXML is in Ruby stdlib
+----
+
+Install:
+
+[source,shell]
+----
+bundle install
+----
+
+=== Configuration
+
+[source,ruby]
+----
+# Explicit selection
+context = Moxml.new
+context.config.adapter = :rexml
+
+# Global default
+Moxml::Config.default_adapter = :rexml
+----
+
+=== Features
+
+==== Basic XPath support
+
+REXML provides basic XPath querying:
+
+[source,ruby]
+----
+doc = Moxml.new.parse(xml)
+
+# Basic paths work
+books = doc.xpath('//book')
+first_book = doc.xpath('/library/book[1]')
+
+# Attribute predicates work
+has_id = doc.xpath('//book[@id]')
+specific_book = doc.xpath('//book[@id="1"]')
+
+# Position predicates work
+first_three = doc.xpath('//book[position() < 4]')
+----
+
+==== Limited namespace support
+
+REXML can parse and preserve namespaces but cannot use them in XPath queries:
+
+[source,ruby]
+----
+xml = '<library xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:title>Book</dc:title></library>'
+
+doc = Moxml.new.parse(xml)
+
+# Namespace metadata is preserved
+element = doc.root.children.first
+puts element.namespace  # Works - returns namespace URI
+
+# But namespace-aware XPath does NOT work
+doc.xpath('//dc:title', 'dc' => 'http://purl.org/dc/elements/1.1/')
+# => Returns empty, cannot resolve namespace prefix
+
+# Workaround: use element name without namespace
+doc.xpath('//title')  # Works - finds the element
+----
+
+==== All basic node types
+
+Support for standard XML node types:
+
+* Elements with attributes
+* Text nodes
+* CDATA sections
+* Comments
+* Processing instructions
+* DOCTYPE declarations
+* XML declarations
+
+==== Standard library advantage
+
+* Always available - no gem dependencies
+* Maximum portability across Ruby versions
+* Simple deployment - no compilation needed
+* Guaranteed compatibility
+
+=== Limitations
+
+REXML has several limitations compared to other adapters:
+
+**XPath limitations:**
+
+* No namespace-aware XPath queries (see example above)
+* Limited function support
+* Some axes not supported
+* Complex predicates may not work
+
+**Performance:**
+
+* Slower parsing than C-based libraries
+* Medium serialization speed
+* Higher memory usage than Ox
+
+**Namespace XPath workaround:**
+
+[source,ruby]
+----
+# Instead of:
+doc.xpath('//ns:element', 'ns' => 'http://example.org')
+
+# Use element name matching:
+doc.xpath('//element')
+
+# Then filter in Ruby:
+elements.select { |e| e.namespace == 'http://example.org' }
+----
+
+=== Performance characteristics
+
+Based on benchmarks:
+
+[cols="2,2,3"]
+|===
+| Operation | Performance | Notes
+
+| Parse medium XML
+| ~10-20 ips
+| Pure Ruby parsing
+
+| Serialize medium XML
+| ~500-1,000 ips
+| Medium speed
+
+| XPath queries
+| ~5,000-10,000 ips
+| Limited XPath
+
+| Memory usage
+| Medium
+| Pure Ruby overhead
+|===
+
+=== Best use cases
+
+**Choose REXML when:**
+
+* No external gems can be used (standard library only)
+* Maximum portability is required
+* Small to medium documents
+* Deployment simplicity is critical
+* C extensions cannot be compiled
+* Basic XPath without namespaces is sufficient
+
+**Avoid REXML when:**
+
+* Namespace-aware XPath is required (use link:oga[Oga],
+link:nokogiri[Nokogiri], or link:libxml[LibXML])
+* High performance is needed (use link:ox[Ox] or link:nokogiri[Nokogiri])
+* Complex XPath expressions are needed (use link:nokogiri[Nokogiri])
+
+=== Example usage
+
+==== Basic operations
+
+[source,ruby]
+----
+require 'moxml'
+
+# Configure REXML adapter
+context = Moxml.new
+context.config.adapter = :rexml
+
+xml = '<library><book id="1">Ruby Programming</book></library>'
+doc = context.parse(xml)
+
+# Basic XPath works
+book = doc.at_xpath('//book[@id="1"]')
+puts book.text  # => "Ruby Programming"
+
+# Modify
+book.text = 'Advanced Ruby'
+book['edition'] = '2nd'
+
+puts doc.to_xml(indent: 2)
+----
+
+==== XPath queries
+
+[source,ruby]
+----
+# Supported patterns
+books = doc.xpath('//book')
+with_id = doc.xpath('//book[@id]')
+specific = doc.xpath('//book[@id="1"]')
+first_two = doc.xpath('//book[position() <= 2]')
+
+# NOT supported - avoid these
+# doc.xpath('//ns:book', namespaces)  # ❌ No namespace XPath
+# doc.xpath('count(//book)')          # ⚠️ Limited functions
+# doc.xpath('//book[price < 30]')     # ⚠️ May not work
+----
+
+==== Namespace workarounds
+
+[source,ruby]
+----
+xml = <<~XML
+  <library xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:title>Programming</dc:title>
+    <dc:creator>Smith</dc:creator>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Find elements by name (without namespace prefix)
+titles = doc.xpath('//title')
+
+# Check namespace programmatically
+titles.each do |title|
+  if title.namespace == 'http://purl.org/dc/elements/1.1/'
+    puts "DC title: #{title.text}"
+  end
+end
+----
+
+=== Comparison with other pure Ruby option
+
+[cols="2,2,2"]
+|===
+| Aspect | REXML | Oga
+
+| XPath support
+| Limited
+| Full XPath 1.0
+
+| Performance
+| Medium
+| Fast
+
+| Memory usage
+| Medium
+| Medium
+
+| Namespace XPath
+| Not supported
+| Full support
+
+| Standard library
+| Yes
+| No (external gem)
+
+| Dependencies
+| None
+| None (pure Ruby)
+|===
+
+=== References
+
+* link:https://github.com/ruby/rexml[REXML on GitHub]
+* link:https://ruby-doc.org/stdlib/libdoc/rexml/rdoc/REXML.html[REXML documentation]
+
+=== See also
+
+* link:../compatibility[Compatibility matrix] - Feature comparison
+* link:oga[Oga adapter] - Alternative pure Ruby with full XPath
+* link:../../guides/xpath-queries[XPath queries guide]