moxml 0.1.7 → 0.1.9

data/docs/_guides/modifying-xml.adoc

@@ -0,0 +1,292 @@
+---
+title: Modifying XML
+nav_order: 3
+---
+
+== Modifying XML
+
+=== Purpose
+
+Learn how to modify existing XML documents by adding, updating, and removing
+elements, attributes, and content.
+
+=== Modifying element content
+
+Update text content of elements:
+
+[source,ruby]
+----
+xml = '<library><book><title>Old Title</title></book></library>'
+doc = Moxml.new.parse(xml)
+
+# Find and update
+title = doc.at_xpath('//title')
+title.text = 'New Title'
+
+puts doc.to_xml
+# => <library><book><title>New Title</title></book></library>
+----
+
+=== Adding elements
+
+Add new elements to existing documents:
+
+[source,ruby]
+----
+xml = '<library><book id="1"><title>Ruby Basics</title></book></library>'
+doc = Moxml.new.parse(xml)
+
+book = doc.at_xpath('//book[@id="1"]')
+
+# Add author element
+author = doc.create_element('author')
+author.text = 'Jane Smith'
+book.add_child(author)
+
+# Add price element
+price = doc.create_element('price')
+price.text = '29.99'
+price['currency'] = 'USD'
+book.add_child(price)
+
+# Add ISBN element
+isbn = doc.create_element('isbn')
+isbn.text = '978-0-123456-78-9'
+book.add_child(isbn)
+
+puts doc.to_xml(indent: 2)
+----
+
+=== Removing elements
+
+Remove elements from documents:
+
+[source,ruby]
+----
+xml = <<~XML
+  <library>
+    <book id="1">
+      <title>Ruby Basics</title>
+      <author>Jane Smith</author>
+      <draft>true</draft>
+    </book>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Find and remove element
+draft = doc.at_xpath('//draft')
+draft.remove
+
+# Remove by parent
+book = doc.at_xpath('//book')
+author = book.at_xpath('.//author')
+book.remove_child(author)
+
+puts doc.to_xml
+----
+
+=== Modifying attributes
+
+Update, add, and remove attributes:
+
+[source,ruby]
+----
+xml = '<book id="1" status="draft">Ruby Basics</book>'
+doc = Moxml.new.parse(xml)
+
+book = doc.root
+
+# Update existing attribute
+book['id'] = '100'
+
+# Add new attribute
+book['edition'] = '2nd'
+book['category'] = 'programming'
+
+# Remove attribute
+book.remove_attribute('status')
+
+# Get all attributes
+book.attributes.each do |attr|
+  puts "#{attr.name}=#{attr.value}"
+end
+# => id=100
+# => edition=2nd
+# => category=programming
+----
+
+=== Replacing nodes
+
+Replace elements with new content:
+
+[source,ruby]
+----
+xml = '<book><title>Old Title</title><author>Old Author</author></book>'
+doc = Moxml.new.parse(xml)
+
+# Replace title element
+old_title = doc.at_xpath('//title')
+new_title = doc.create_element('title')
+new_title.text = 'New Title'
+new_title['lang'] = 'en'
+
+old_title.replace(new_title)
+
+# Replace text node
+author = doc.at_xpath('//author')
+author.children.first.replace(doc.create_text('New Author'))
+
+puts doc.to_xml
+----
+
+=== Adding siblings
+
+Insert elements relative to existing nodes:
+
+[source,ruby]
+----
+xml = <<~XML
+  <book>
+    <title>Ruby Programming</title>
+    <price>29.99</price>
+  </book>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Add before price
+price = doc.at_xpath('//price')
+author = doc.create_element('author')
+author.text = 'Jane Smith'
+price.add_previous_sibling(author)
+
+# Add after title
+title = doc.at_xpath('//title')
+subtitle = doc.create_element('subtitle')
+subtitle.text = 'A Comprehensive Guide'
+title.add_next_sibling(subtitle)
+
+puts doc.to_xml(indent: 2)
+----
+
+Output:
+
+[source,xml]
+----
+<book>
+  <title>Ruby Programming</title>
+  <subtitle>A Comprehensive Guide</subtitle>
+  <author>Jane Smith</author>
+  <price>29.99</price>
+</book>
+----
+
+=== Batch modifications
+
+Update multiple elements at once:
+
+[source,ruby]
+----
+xml = <<~XML
+  <library>
+    <book><price currency="USD">29.99</price></book>
+    <book><price currency="USD">39.99</price></book>
+    <book><price currency="USD">19.99</price></book>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Apply 10% discount to all books
+doc.xpath('//price').each do |price|
+  current = price.text.to_f
+  discounted = (current * 0.9).round(2)
+  price.text = discounted.to_s
+  price['original'] = current.to_s
+end
+
+puts doc.to_xml(indent: 2)
+----
+
+=== Preserving structure
+
+Maintain document structure during modifications:
+
+[source,ruby]
+----
+xml = <<~XML
+  <?xml version="1.0" encoding="UTF-8"?>
+  <library>
+    <book id="1">Ruby Basics</book>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Modifications preserve declaration
+book = doc.at_xpath('//book')
+book['edition'] = '2nd'
+
+# Original structure maintained
+puts doc.to_xml(indent: 2)
+# => Still has <?xml ... ?> declaration
+----
+
+=== Common modification patterns
+
+==== Update or create pattern
+
+[source,ruby]
+----
+def ensure_element(parent, name, text)
+  elem = parent.at_xpath(".//#{name}")
+
+  if elem
+    # Update existing
+    elem.text = text
+  else
+    # Create new
+    elem = parent.document.create_element(name)
+    elem.text = text
+    parent.add_child(elem)
+  end
+
+  elem
+end
+
+book = doc.at_xpath('//book')
+ensure_element(book, 'author', 'Jane Smith')
+ensure_element(book, 'price', '29.99')
+----
+
+==== Conditional modification
+
+[source,ruby]
+----
+doc.xpath('//book').each do |book|
+  price = book.at_xpath('.//price')
+  next unless price
+
+  # Add discount for expensive books
+  if price.text.to_f > 30
+    book['discount'] = '10%'
+    price.text = (price.text.to_f * 0.9).to_s
+  end
+end
+----
+
+=== Best practices
+
+. **Find before modifying** - always locate elements first
+. **Check element exists** before calling methods on it
+. **Use transactions** for complex modifications if needed
+. **Validate structure** after major changes
+. **Preserve document metadata** (declarations, encoding)
+
+=== See also
+
+* link:creating-documents[Creating documents] - Build from scratch
+* link:../tutorials/basic-usage[Basic usage] - Fundamentals
+* link:../references/element-api[Element API] - Complete method reference

data/docs/_guides/parsing-xml.adoc

@@ -0,0 +1,230 @@
+---
+title: Parsing XML
+nav_order: 2
+---
+
+== Parsing XML
+
+=== Purpose
+
+Learn how to parse XML from various sources including strings, files, and IO
+streams using different Moxml adapters.
+
+=== Basic string parsing
+
+Parse XML from a string:
+
+[source,ruby]
+----
+require 'moxml'
+
+xml_string = '<root><child>content</child></root>'
+
+# Parse with default adapter
+doc = Moxml.new.parse(xml_string)
+
+# Access parsed content
+puts doc.root.name  # => "root"
+puts doc.root.children.first.text  # => "content"
+----
+
+=== Parsing from files
+
+Read and parse XML files:
+
+[source,ruby]
+----
+# Read file first, then parse
+xml_content = File.read('document.xml')
+doc = Moxml.new.parse(xml_content)
+
+# Or use File.open with read
+File.open('document.xml') do |file|
+  doc = Moxml.new.parse(file.read)
+  # Process document
+end
+----
+
+=== Parsing with options
+
+Control parsing behavior:
+
+[source,ruby]
+----
+# Strict parsing (raises errors on malformed XML)
+doc = Moxml.new.parse(xml, strict: true)
+
+# With specific encoding
+doc = Moxml.new.parse(xml, encoding: 'ISO-8859-1')
+
+# Relaxed parsing (attempts to handle malformed XML)
+doc = Moxml.new.parse(possibly_invalid_xml, strict: false)
+----
+
+=== Handling parse errors
+
+Catch and handle parsing errors:
+
+[source,ruby]
+----
+xml = '<root><unclosed>'
+
+begin
+  doc = Moxml.new.parse(xml, strict: true)
+rescue Moxml::ParseError => e
+  puts "Parse failed at line #{e.line}, column #{e.column}"
+  puts "Error: #{e.message}"
+  puts e.to_s  # Includes helpful hints
+end
+----
+
+=== Parsing large documents
+
+Handle large XML files efficiently:
+
+[source,ruby]
+----
+# For large files, consider memory usage
+large_xml = File.read('large_document.xml')
+
+context = Moxml.new
+# Choose appropriate adapter for size
+context.config.adapter = :ox  # Fast for large files
+
+doc = context.parse(large_xml)
+
+# Process in chunks if possible
+doc.xpath('//record').each_slice(1000) do |records|
+  process_batch(records)
+end
+----
+
+=== Parsing with different adapters
+
+Each adapter may handle edge cases differently:
+
+[source,ruby]
+----
+xml_with_namespaces = <<~XML
+  <library xmlns="http://example.org">
+    <book>Title</book>
+  </library>
+XML
+
+# Parse with Nokogiri (full namespace support)
+context_nokogiri = Moxml.new
+context_nokogiri.config.adapter = :nokogiri
+doc = context_nokogiri.parse(xml_with_namespaces)
+
+# Parse with REXML (limited namespace XPath)
+context_rexml = Moxml.new
+context_rexml.config.adapter = :rexml
+doc = context_rexml.parse(xml_with_namespaces)
+# Namespace preserved but XPath queries limited
+----
+
+=== Common parse patterns
+
+==== Parse and extract data
+
+[source,ruby]
+----
+xml = <<~XML
+  <products>
+    <product id="1">
+      <name>Widget A</name>
+      <price>9.99</price>
+    </product>
+    <product id="2">
+      <name>Widget B</name>
+      <price>14.99</price>
+    </product>
+  </products>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Extract data into Ruby structures
+products = doc.xpath('//product').map do |prod|
+  {
+    id: prod['id'],
+    name: prod.at_xpath('.//name').text,
+    price: prod.at_xpath('.//price').text.to_f
+  }
+end
+
+products.each { |p| puts "#{p[:name]}: $#{p[:price]}" }
+----
+
+==== Parse and validate
+
+[source,ruby]
+----
+doc = Moxml.new.parse(xml)
+
+# Validate required elements exist
+required_elements = ['title', 'author', 'price']
+
+required_elements.each do |elem|
+  unless doc.at_xpath("//#{elem}")
+    raise "Missing required element: #{elem}"
+  end
+end
+----
+
+=== Troubleshooting
+
+**Encoding issues:**
+
+[source,ruby]
+----
+# Specify encoding explicitly
+doc = Moxml.new.parse(xml, encoding: 'UTF-8')
+
+# Or let adapter auto-detect
+doc = Moxml.new.parse(xml)  # Usually works
+----
+
+**Malformed XML:**
+
+[source,ruby]
+----
+# Use relaxed parsing
+doc = Moxml.new.parse(possibly_broken_xml, strict: false)
+
+# Check what was parsed
+puts doc.root.name
+puts doc.to_xml  # See what was actually parsed
+----
+
+**Empty or whitespace:**
+
+[source,ruby]
+----
+xml = "  \n  <root/>  \n  "
+
+# Whitespace is handled automatically
+doc = Moxml.new.parse(xml)
+puts doc.root.name  # => "root"
+----
+
+=== Best practices
+
+. **Always use strict mode in production** for data integrity
+. **Specify encoding** when working with non-UTF-8 documents
+. **Handle parse errors** gracefully with appropriate error messages
+. **Choose the right adapter** based on document size and complexity
+. **Validate critical elements** after parsing
+
+=== Next steps
+
+* link:xpath-queries[XPath queries tutorial] - Learn advanced querying
+* link:working-with-elements[Working with elements] - Element manipulation
+* link:../guides/error-handling[Error handling guide] - Comprehensive error
+management
+
+=== See also
+
+* link:../pages/adapters/[Adapters] - Choose the right adapter for parsing
+* link:../references/document-api[Document API] - Complete parsing reference
+* link:../pages/compatibility[Compatibility] - Adapter differences