moxml 0.1.6 → 0.1.8

data/docs/_tutorials/xpath-queries.adoc

@@ -0,0 +1,359 @@
+---
+title: XPath queries
+parent: Overview
+nav_order: 3
+---
+
+== XPath queries
+
+=== Purpose
+
+Master XPath querying in Moxml to efficiently find and select XML nodes using
+path expressions, predicates, and functions.
+
+=== Prerequisites
+
+* Basic understanding of XPath syntax
+* Moxml installed with an adapter
+* Familiarity with link:basic-usage[basic Moxml usage]
+
+=== Step 1: Basic path expressions
+
+Start with simple path selection:
+
+[source,ruby]
+----
+require 'moxml'
+
+xml = <<~XML
+  <library>
+    <section name="programming">
+      <book id="1">Ruby Basics</book>
+      <book id="2">Advanced Ruby</book>
+    </section>
+    <section name="fiction">
+      <book id="3">Ruby Story</book>
+    </section>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Absolute path - from root
+sections = doc.xpath('/library/section')
+puts sections.length  # => 2
+
+# Descendant-or-self - any depth
+all_books = doc.xpath('//book')
+puts all_books.length  # => 3
+
+# Relative path - from current node
+section = sections.first
+books = section.xpath('.//book')
+puts books.length  # => 2
+
+# Parent path
+book = all_books.first
+parent = book.xpath('..').first
+puts parent.name  # => "section"
+----
+
+=== Step 2: Attribute predicates
+
+Filter elements by attributes:
+
+[source,ruby]
+----
+# Elements with specific attribute
+books_with_id = doc.xpath('//book[@id]')
+puts books_with_id.length  # => 3 (all have id)
+
+# Elements with attribute value
+book1 = doc.at_xpath('//book[@id="1"]')
+puts book1.text  # => "Ruby Basics"
+
+# Multiple attribute conditions
+sections = doc.xpath('//section[@name="programming"]')
+puts sections.first['name']  # => "programming"
+----
+
+=== Step 3: Position predicates
+
+Select by position:
+
+[source,ruby]
+----
+# First book
+first = doc.at_xpath('//book[1]')
+puts first.text  # => "Ruby Basics"
+
+# Last book
+last = doc.at_xpath('//book[last()]')
+puts last.text  # => "Ruby Story"
+
+# First two books
+first_two = doc.xpath('//book[position() <= 2]')
+puts first_two.length  # => 2
+
+# Every second book
+even_books = doc.xpath('//book[position() mod 2 = 0]')
+----
+
+=== Step 4: Text predicates
+
+Filter by text content:
+
+[source,ruby]
+----
+xml = <<~XML
+  <library>
+    <book><title>Ruby Programming</title></book>
+    <book><title>Python Programming</title></book>
+    <book><title>Advanced Ruby</title></book>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Exact text match
+ruby_book = doc.at_xpath('//title[text()="Ruby Programming"]')
+puts ruby_book.text  # => "Ruby Programming"
+
+# Contains text
+ruby_books = doc.xpath('//title[contains(text(), "Ruby")]')
+puts ruby_books.length  # => 2
+
+# Starts with
+programming = doc.xpath('//title[starts-with(text(), "Ruby")]')
+----
+
+=== Step 5: Logical operators
+
+Combine conditions:
+
+[source,ruby]
+----
+xml = <<~XML
+  <library>
+    <book id="1" category="programming" price="29.99">
+      <title>Ruby Basics</title>
+    </book>
+    <book id="2" category="fiction" price="19.99">
+      <title>Ruby Story</title>
+    </book>
+    <book id="3" category="programming" price="39.99">
+      <title>Advanced Ruby</title>
+    </book>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# AND condition
+cheap_programming = doc.xpath('//book[@category="programming" and @price < 35]')
+puts cheap_programming.length  # => 1
+
+# OR condition
+fiction_or_cheap = doc.xpath('//book[@category="fiction" or @price < 25]')
+puts fiction_or_cheap.length  # => 2
+
+# Complex conditions
+results = doc.xpath('//book[(@category="programming" and @price < 40) or @id="2"]')
+puts results.length  # => 2
+----
+
+=== Step 6: XPath functions
+
+Use built-in XPath functions:
+
+[source,ruby]
+----
+# Count function
+book_count = doc.xpath('count(//book)')
+puts book_count  # => 3
+
+# String functions
+titles = doc.xpath('//title[string-length(text()) > 10]')
+
+# Concat function
+full_title = doc.xpath('concat(//book[1]/title, " - Edition 2")')
+
+# Position functions
+middle_books = doc.xpath('//book[position() > 1 and position() < last()]')
+----
+
+=== Step 7: Namespace-aware queries
+
+Query XML with namespaces:
+
+[source,ruby]
+----
+xml = <<~XML
+  <library xmlns="http://example.org/library"
+           xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <book>
+      <dc:title>Ruby Programming</dc:title>
+      <dc:creator>Jane Smith</dc:creator>
+    </book>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Define namespace mappings
+namespaces = {
+  'lib' => 'http://example.org/library',
+  'dc' => 'http://purl.org/dc/elements/1.1/'
+}
+
+# Query with namespace prefixes
+books = doc.xpath('//lib:book', namespaces)
+titles = doc.xpath('//dc:title', namespaces)
+creators = doc.xpath('//dc:creator', namespaces)
+
+puts titles.first.text  # => "Ruby Programming"
+puts creators.first.text  # => "Jane Smith"
+
+# Complex namespace queries
+all_dc_elements = doc.xpath('//dc:*', namespaces)
+puts all_dc_elements.length  # => 2 (title + creator)
+----
+
+=== Step 8: Axes and advanced selection
+
+Use XPath axes for complex traversal:
+
+[source,ruby]
+----
+xml = <<~XML
+  <book>
+    <chapter id="1">Introduction</chapter>
+    <chapter id="2">Basics</chapter>
+    <chapter id="3">Advanced</chapter>
+  </book>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Following sibling
+chapter1 = doc.at_xpath('//chapter[@id="1"]')
+next_chapters = chapter1.xpath('following-sibling::chapter')
+puts next_chapters.length  # => 2
+
+# Preceding sibling
+chapter3 = doc.at_xpath('//chapter[@id="3"]')
+prev_chapters = chapter3.xpath('preceding-sibling::chapter')
+puts prev_chapters.length  # => 2
+
+# Ancestor
+chapter = doc.at_xpath('//chapter[@id="2"]')
+book = chapter.xpath('ancestor::book').first
+puts book.name  # => "book"
+
+# Descendant
+all_text = doc.root.xpath('descendant::text()')
+----
+
+=== Adapter-specific considerations
+
+==== Nokogiri, LibXML, Oga
+
+Full XPath 1.0 support - all examples above work perfectly.
+
+==== REXML
+
+Limited support - namespace queries don't work:
+
+[source,ruby]
+----
+# Works
+doc.xpath('//book')
+doc.xpath('//book[@id="1"]')
+
+# Does NOT work
+doc.xpath('//ns:book', namespaces)  # ❌
+
+# Workaround
+books = doc.xpath('//book')
+books.select { |b| b.namespace == 'http://example.org' }
+----
+
+==== Ox
+
+Basic paths only - use Ruby for complex filtering:
+
+[source,ruby]
+----
+# Works
+all_books = doc.xpath('//book')
+
+# Does NOT work - use Ruby instead
+# doc.xpath('//book[@id="1"]')  # ❌
+
+# Workaround
+books = doc.xpath('//book')
+book1 = books.find { |b| b['id'] == '1' }
+----
+
+=== Best practices
+
+. **Use specific paths** when possible for better performance
+. **Cache XPath results** if querying multiple times
+. **Choose the right adapter** for your XPath needs
+. **Test namespace queries** with your chosen adapter
+. **Use relative paths** (`.//`) when querying from elements
+
+=== Common patterns
+
+==== Extract structured data
+
+[source,ruby]
+----
+products = doc.xpath('//product').map do |product|
+  {
+    id: product['id'],
+    name: product.at_xpath('.//name').text,
+    price: product.at_xpath('.//price').text.to_f,
+    stock: product.at_xpath('.//stock').text.to_i
+  }
+end
+----
+
+==== Conditional processing
+
+[source,ruby]
+----
+# Find and process matching elements
+expensive_books = doc.xpath('//book[price > 30]')
+expensive_books.each do |book|
+  # Apply discount
+  price = book.at_xpath('.//price')
+  current = price.text.to_f
+  price.text = (current * 0.9).to_s
+end
+----
+
+==== Validation
+
+[source,ruby]
+----
+# Check required elements exist
+required = ['title', 'author', 'isbn']
+missing = required.reject { |elem| doc.at_xpath("//#{elem}") }
+
+if missing.any?
+  raise "Missing elements: #{missing.join(', ')}"
+end
+----
+
+=== Next steps
+
+* link:namespace-handling[Namespace handling] - Master XML namespaces
+* link:working-with-elements[Working with elements] - Element manipulation
+* link:../guides/xpath-queries[XPath queries guide] - Advanced patterns
+
+=== See also
+
+* link:../pages/adapters/[Adapters] - XPath capabilities per adapter
+* link:../references/xpath-api[XPath API reference]
+* link:../pages/compatibility[Compatibility matrix] - XPath support comparison

data/docs/index.adoc

@@ -0,0 +1,122 @@
+---
+title: Home
+nav_order: 1
+---
+:page-layout: home
+
+== Moxml: Modern XML processing for Ruby
+
+image:https://github.com/lutaml/moxml/workflows/rake/badge.svg["Build Status", link="https://github.com/lutaml/moxml/actions?workflow=rake"]
+image:https://img.shields.io/gem/v/moxml.svg["Gem Version", link="https://rubygems.org/gems/moxml"]
+
+Moxml provides a unified, modern XML processing interface for Ruby
+applications. It offers a consistent API that abstracts away the underlying
+XML implementation details while maintaining high performance through
+efficient node mapping and native XPath querying.
+
+== Key features
+
+* **Unified interface** - Consistent API across different XML libraries
+* **Multiple adapters** - Support for Nokogiri, LibXML, Oga, REXML, Ox, and HeadedOx
+* **Full XPath support** - Native XPath querying with namespace handling
+* **SAX parsing** - Memory-efficient event-driven XML processing
+* **Ruby-idiomatic** - Natural, expressive API for XML manipulation
+* **High performance** - Efficient node mapping and adapter optimization
+* **Thread-safe** - Safe for concurrent operations
+* **Complete node support** - Handle all XML node types
+
+== Quick example
+
+[source,ruby]
+----
+require 'moxml'
+
+# Parse XML
+doc = Moxml.new.parse('<library><book id="1">Ruby</book></library>')
+
+# Query with XPath
+books = doc.xpath('//book[@id="1"]')
+puts books.first.text  # => "Ruby"
+
+# Modify content
+books.first.text = 'Advanced Ruby'
+books.first['edition'] = '2nd'
+
+# Output formatted XML
+puts doc.to_xml(indent: 2)
+----
+
+== Getting started
+
+Choose your path:
+
+[.grid]
+--
+link:pages/installation[**Installation**]::
+Install Moxml and choose an XML adapter
+
+link:tutorials/[**Tutorials**]::
+Step-by-step guides to learn Moxml
+
+link:guides/[**Guides**]::
+Task-oriented documentation for common operations
+
+link:pages/adapters/[**Adapters**]::
+Learn about supported XML libraries
+--
+
+== Supported adapters
+
+[cols="2,3,1"]
+|===
+| Adapter | Best for | Performance
+
+| link:pages/adapters/nokogiri[Nokogiri]
+| Industry standard, wide compatibility
+| Fast
+
+| link:pages/adapters/libxml[LibXML]
+| Alternative to Nokogiri, full features
+| Very Fast
+
+| link:pages/adapters/oga[Oga]
+| Pure Ruby, no C extensions
+| Fast
+
+| link:pages/adapters/rexml[REXML]
+| Standard library, maximum portability
+| Medium
+
+| link:pages/adapters/ox[Ox]
+| Maximum speed, simple documents
+| Very Fast
+
+| link:pages/adapters/headed-ox[HeadedOx]
+| Fast parsing + comprehensive XPath 1.0 (99.20% pass rate)
+| Very Fast
+|===
+
+== Why Moxml?
+
+**Consistent API**:: Write once, run with any XML library. Switch adapters
+without changing your code.
+
+**Full XPath support**:: Powerful querying with namespace awareness across all
+adapters.
+
+**Modern design**:: Clean, Ruby-idiomatic interface that feels natural to use.
+
+**Production ready**:: Comprehensive error handling, thread safety, and
+performance optimization.
+
+== Community
+
+* link:https://github.com/lutaml/moxml[GitHub repository]
+* link:https://github.com/lutaml/moxml/issues[Issue tracker]
+* link:https://rubygems.org/gems/moxml[RubyGems page]
+
+== License
+
+Moxml is released under the Ribose 3-Clause BSD License.
+
+Copyright (c) 2025 Ribose Inc.

data/examples/README.md

@@ -0,0 +1,124 @@
+# Moxml Real-World Examples
+
+This directory contains practical, runnable examples demonstrating moxml usage in common real-world scenarios.
+
+## Overview
+
+Each example demonstrates different aspects of moxml's capabilities:
+
+- **RSS Parser**: Parse RSS/Atom feeds with XPath queries and namespace handling
+- **Web Scraper**: Extract data from HTML/XML using DOM navigation
+- **API Client**: Build and parse XML API requests/responses
+
+## Requirements
+
+All examples require moxml and at least one XML adapter:
+
+```bash
+gem install moxml nokogiri
+```
+
+## Running the Examples
+
+Each example is self-contained and can be run directly:
+
+```bash
+# RSS Parser Example
+ruby examples/rss_parser/rss_parser.rb
+
+# Web Scraper Example
+ruby examples/web_scraper/web_scraper.rb
+
+# API Client Example
+ruby examples/api_client/api_client.rb
+```
+
+## Example Details
+
+### RSS Parser (`rss_parser/`)
+
+Demonstrates:
+- Parsing RSS/Atom feed XML
+- XPath queries for data extraction
+- Namespace handling
+- Element traversal
+- Attribute access
+
+**Files:**
+- `rss_parser.rb` - Main parser implementation
+- `example_feed.xml` - Sample RSS feed
+- `README.md` - Detailed documentation
+
+### Web Scraper (`web_scraper/`)
+
+Demonstrates:
+- HTML/XML document parsing
+- Table data extraction
+- DOM structure navigation
+- Attribute and text content access
+- Error handling
+
+**Files:**
+- `web_scraper.rb` - Main scraper implementation
+- `example_page.html` - Sample HTML page
+- `README.md` - Detailed documentation
+
+### API Client (`api_client/`)
+
+Demonstrates:
+- Building XML API requests
+- Parsing XML API responses
+- SOAP message handling
+- Authentication elements
+- Error response processing
+
+**Files:**
+- `api_client.rb` - Main client implementation
+- `example_response.xml` - Sample API response
+- `README.md` - Detailed documentation
+
+## Key Concepts
+
+### Using require_relative
+
+All examples use `require_relative` to load moxml from the local source:
+
+```ruby
+require_relative '../../lib/moxml'
+```
+
+This allows running the examples directly from the repository without installing the gem.
+
+### Error Handling
+
+Each example includes comprehensive error handling:
+
+```ruby
+begin
+  doc = Moxml.new.parse(xml)
+rescue Moxml::ParseError => e
+  puts "Parse error: #{e.message}"
+  exit 1
+end
+```
+
+### Best Practices
+
+The examples demonstrate moxml best practices:
+- Proper namespace handling
+- Efficient XPath queries
+- Clean resource management
+- Comprehensive error handling
+- Clear, commented code
+
+## Learning Path
+
+1. **Start with RSS Parser** - Learn basic parsing and XPath
+2. **Move to Web Scraper** - Understand DOM navigation
+3. **Finish with API Client** - Master XML generation and complex structures
+
+## Additional Resources
+
+- [Main README](../README.adoc) - Complete moxml documentation
+- [API Reference](../docs/) - Detailed API documentation
+- [Guides](../docs/_guides/) - Step-by-step tutorials