moxml 0.1.6 → 0.1.8

data/docs/_pages/index.adoc

@@ -0,0 +1,35 @@
+---
+title: Overview
+nav_order: 1
+---
+
+== Core topics
+
+This section covers the fundamental concepts and essential information for
+working with Moxml.
+
+=== Topics covered
+
+link:installation[Installation]::
+How to install Moxml and select an XML adapter for your needs.
+
+link:quick-start[Quick start]::
+Get up and running with Moxml in minutes with practical examples.
+
+link:architecture[Architecture]::
+Understand how Moxml's unified interface and adapter system works.
+
+link:adapters/[Adapters]::
+Learn about the supported XML libraries and how to choose the right one.
+
+link:compatibility[Compatibility]::
+Compare features, performance, and compatibility across adapters.
+
+link:configuration[Configuration]::
+Configure Moxml for your application's requirements.
+
+link:error-handling[Error handling]::
+Comprehensive guide to Moxml's error classes and debugging.
+
+link:best-practices[Best practices]::
+Recommended patterns and practices for using Moxml effectively.

data/docs/_pages/installation.adoc

@@ -0,0 +1,141 @@
+---
+title: Installation
+parent: Overview
+nav_order: 2
+---
+
+== Installation
+
+=== Purpose
+
+This guide covers how to install Moxml and set up your chosen XML adapter for
+Ruby applications.
+
+=== Requirements
+
+* Ruby >= 3.0.0
+* At least one supported XML library (Nokogiri, LibXML, Oga, REXML, or Ox)
+
+=== Basic installation
+
+Add Moxml and your chosen XML adapter to your Gemfile:
+
+[source,ruby]
+----
+# Gemfile
+gem 'moxml'
+
+# Choose one or more XML adapters:
+gem 'nokogiri'      # Recommended: Fast, widely used
+gem 'libxml-ruby'   # Alternative: Native performance
+gem 'oga'           # Pure Ruby: No C extensions
+gem 'ox'            # Fastest: Best for simple documents
+# REXML is included in Ruby standard library
+----
+
+Then install:
+
+[source,shell]
+----
+bundle install
+----
+
+=== Installing without Bundler
+
+Install directly using gem:
+
+[source,shell]
+----
+gem install moxml
+gem install nokogiri  # Or your preferred adapter
+----
+
+=== Adapter selection
+
+Moxml automatically detects and uses available XML libraries. The default
+adapter priority order is:
+
+. Nokogiri (if available)
+. LibXML (if available)
+. Oga (if available)
+. REXML (always available)
+. Ox (if available)
+
+You can override the default adapter in your application:
+
+[source,ruby]
+----
+# Set default adapter globally
+Moxml::Config.default_adapter = :libxml
+
+# Or configure per instance
+moxml = Moxml.new
+moxml.config.adapter = :oga
+----
+
+=== Verifying installation
+
+Test your installation:
+
+[source,ruby]
+----
+require 'moxml'
+
+# Check version
+puts Moxml::VERSION
+
+# Verify adapter loaded
+context = Moxml.new
+puts context.config.adapter.name
+# => "Moxml::Adapter::Nokogiri" (or your adapter)
+
+# Parse simple XML
+doc = context.parse('<root><child>test</child></root>')
+puts doc.root.name
+# => "root"
+----
+
+=== Troubleshooting
+
+**Gem not found:**
+
+Ensure bundler is using the correct gem source:
+
+[source,ruby]
+----
+# Add to top of Gemfile
+source 'https://rubygems.org'
+----
+
+**Adapter not loading:**
+
+If your chosen adapter isn't loading:
+
+. Verify the adapter gem is installed: `bundle list | grep nokogiri`
+. Check for version conflicts: `bundle update moxml`
+. Try explicitly requiring: `require 'nokogiri'` before `require 'moxml'`
+
+**C extension compilation errors:**
+
+If Nokogiri or LibXML fail to install on your system, consider using pure
+Ruby adapters:
+
+[source,ruby]
+----
+gem 'moxml'
+gem 'oga'  # Pure Ruby alternative
+----
+
+Or use REXML which requires no additional gems:
+
+[source,ruby]
+----
+gem 'moxml'
+# REXML is included in Ruby standard library
+----
+
+=== Next steps
+
+* link:../quick-start[Quick start guide] - Get started with basic usage
+* link:adapters/[Learn about adapters] - Understand adapter differences
+* link:../tutorials/[Tutorials] - Step-by-step learning paths

data/docs/_pages/node-api-reference.adoc

@@ -0,0 +1,50 @@
+---
+title: Node API reference
+parent: Overview
+nav_order: 5
+---
+
+== Node API reference
+
+== XML objects and their methods
+
+Each node type provides methods for traversing the document structure:
+
+[source,ruby]
+----
+node.parent              # Get parent node
+node.children            # Get child nodes
+node.next_sibling        # Get next sibling
+node.previous_sibling    # Get previous sibling
+
+# Convenience accessors
+node.first_child         # Get first child
+node.last_child          # Get last child
+node.has_children?       # Check if node has children
+
+# Node manipulation
+node.clone              # Deep copy of node
+node.dup                # Alias for clone
+
+# Query methods
+node.find(xpath)        # Alias for at_xpath
+node.find_all(xpath)    # Returns array of matching elements
+
+# Type checking
+node.element?          # Is it an element?
+node.text?             # Is it a text node?
+node.cdata?            # Is it a CDATA section?
+node.comment?          # Is it a comment?
+node.processing_instruction? # Is it a PI?
+node.attribute?        # Is it an attribute?
+node.namespace?        # Is it a namespace?
+
+# Node information
+node.document          # Get owning document
+----
+
+
+See also:
+
+* link:../guides/working-with-documents[Working with documents guide]
+* link:../guides/advanced-features[Advanced features guide]

data/docs/_pages/performance.adoc

@@ -0,0 +1,36 @@
+---
+title: Performance considerations
+parent: Overview
+nav_order: 11
+---
+
+== Performance considerations
+
+=== Memory management
+
+Moxml maintains a node registry to ensure consistent object mapping:
+
+[source,ruby]
+----
+doc = context.parse(large_xml)
+# Process document
+doc = nil  # Allow garbage collection of document and registry
+GC.start   # Force garbage collection if needed
+----
+
+=== Efficient querying
+
+Use specific XPath expressions for better performance:
+
+[source,ruby]
+----
+# More efficient - specific path
+doc.xpath('//book/title')
+
+# Less efficient - requires full document scan
+doc.xpath('//title')
+
+# Most efficient - direct child access
+root.xpath('./*/title')
+----
+

data/docs/_pages/quick-start.adoc

@@ -0,0 +1,244 @@
+---
+title: Quick start
+parent: Overview
+nav_order: 3
+---
+
+== Quick start
+
+=== Purpose
+
+Get up and running with Moxml in minutes through practical examples covering
+parsing, creating, querying, and modifying XML documents.
+
+=== Prerequisites
+
+* Moxml installed with at least one adapter
+* Basic familiarity with XML concepts
+* Ruby 3.0 or higher
+
+=== Parse and query XML
+
+The most common operation is parsing existing XML and querying it:
+
+[source,ruby]
+----
+require 'moxml'
+
+xml = <<~XML
+  <library>
+    <book id="1">
+      <title>Ruby Programming</title>
+      <author>Jane Smith</author>
+      <price>29.99</price>
+    </book>
+    <book id="2">
+      <title>Advanced Ruby</title>
+      <author>John Doe</author>
+      <price>39.99</price>
+    </book>
+  </library>
+XML
+
+# Parse the XML
+doc = Moxml.new.parse(xml)
+
+# Query using XPath
+books = doc.xpath('//book')
+puts "Found #{books.length} books"  # => Found 2 books
+
+# Access specific book
+first_book = doc.at_xpath('//book[@id="1"]')
+puts first_book['id']              # => "1"
+puts first_book.at_xpath('.//title').text  # => "Ruby Programming"
+
+# Find all titles
+titles = doc.xpath('//book/title')
+titles.each { |title| puts title.text }
+# => Ruby Programming
+# => Advanced Ruby
+----
+
+=== Create XML documents
+
+Build XML documents from scratch using the builder pattern:
+
+[source,ruby]
+----
+require 'moxml'
+
+doc = Moxml::Builder.build(Moxml.new) do |xml|
+  xml.declaration version: "1.0", encoding: "UTF-8"
+
+  xml.library do
+    xml.book id: "1" do
+      xml.title "Ruby Programming"
+      xml.author "Jane Smith"
+      xml.price "29.99"
+    end
+
+    xml.book id: "2" do
+      xml.title "Advanced Ruby"
+      xml.author "John Doe"
+      xml.price "39.99"
+    end
+  end
+end
+
+puts doc.to_xml(indent: 2)
+----
+
+Output:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<library>
+  <book id="1">
+    <title>Ruby Programming</title>
+    <author>Jane Smith</author>
+    <price>29.99</price>
+  </book>
+  <book id="2">
+    <title>Advanced Ruby</title>
+    <author>John Doe</author>
+    <price>39.99</price>
+  </book>
+</library>
+----
+
+=== Modify existing XML
+
+Add, update, and remove elements and attributes:
+
+[source,ruby]
+----
+require 'moxml'
+
+# Parse existing XML
+xml = '<library><book id="1"><title>Old Title</title></book></library>'
+doc = Moxml.new.parse(xml)
+
+# Find and modify element
+book = doc.at_xpath('//book[@id="1"]')
+
+# Update text content
+book.at_xpath('.//title').text = 'New Title'
+
+# Update attribute
+book['id'] = '100'
+book['edition'] = '2nd'
+
+# Add new child element
+author = doc.create_element('author')
+author.text = 'Jane Smith'
+book.add_child(author)
+
+# Add comment
+book.add_child(doc.create_comment('Updated book'))
+
+# Remove attribute
+book.remove_attribute('edition')
+
+puts doc.to_xml(indent: 2)
+----
+
+=== Work with namespaces
+
+Handle XML namespaces properly:
+
+[source,ruby]
+----
+require 'moxml'
+
+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)
+
+# Query with namespace mapping
+namespaces = {
+  'lib' => 'http://example.org/library',
+  'dc' => 'http://purl.org/dc/elements/1.1/'
+}
+
+books = doc.xpath('//lib:book', namespaces)
+titles = doc.xpath('//dc:title', namespaces)
+
+puts titles.first.text  # => "Ruby Programming"
+
+# Create namespaced elements
+new_book = doc.create_element('book')
+new_book.add_namespace('dc', 'http://purl.org/dc/elements/1.1/')
+
+title = doc.create_element('dc:title')
+title.text = 'Advanced Ruby'
+new_book.add_child(title)
+----
+
+=== Switch adapters
+
+Choose a different XML adapter based on your needs:
+
+[source,ruby]
+----
+require 'moxml'
+
+# Use Nokogiri (default)
+context_nokogiri = Moxml.new
+
+# Use LibXML for native performance
+context_libxml = Moxml.new
+context_libxml.config.adapter = :libxml
+
+# Use Oga for pure Ruby
+context_oga = Moxml.new
+context_oga.config.adapter = :oga
+
+# Use REXML for standard library only
+context_rexml = Moxml.new
+context_rexml.config.adapter = :rexml
+
+# Parse with chosen adapter
+doc = context_libxml.parse(xml)
+----
+
+=== Handle errors
+
+Moxml provides comprehensive error handling:
+
+[source,ruby]
+----
+require 'moxml'
+
+begin
+  # Parse malformed XML
+  doc = Moxml.new.parse('<invalid><unclosed>', strict: true)
+rescue Moxml::ParseError => e
+  puts "Parse error at line #{e.line}: #{e.message}"
+end
+
+begin
+  # Invalid XPath expression
+  doc.xpath('//invalid[[[')
+rescue Moxml::XPathError => e
+  puts "XPath error: #{e.expression}"
+  puts e.to_s  # Includes helpful hints
+end
+----
+
+=== Next steps
+
+Now that you've seen the basics, explore more:
+
+* link:../tutorials/[Tutorials] - Learn Moxml step by step
+* link:adapters/[Adapters] - Choose the right adapter for your needs
+* link:../guides/[Guides] - Task-oriented documentation
+* link:../references/[API Reference] - Complete technical documentation

data/docs/_pages/thread-safety.adoc

@@ -0,0 +1,29 @@
+---
+title: Thread safety
+parent: Overview
+nav_order: 10
+---
+
+== Thread safety
+
+Moxml is thread-safe when used properly. Each instance maintains its own state
+and can be used safely in concurrent operations:
+
+[source,ruby]
+----
+class XmlProcessor
+  def initialize
+    @mutex = Mutex.new
+    @context = Moxml.new
+  end
+
+  def process(xml)
+    @mutex.synchronize do
+      doc = @context.parse(xml)
+      # Modify document
+      doc.to_xml
+    end
+  end
+end
+----
+