Moxml: Modern XML processing for Ruby

# In your Gemfile
gem 'moxml'
gem 'nokogiri'  # Or 'oga', 'rexml', 'ox', or 'libxml-ruby'

doc = Moxml.new.create_document

# Add XML declaration
doc.add_child(doc.create_declaration("1.0", "UTF-8"))

# Create root element with namespace
root = doc.create_element('book')
root.add_namespace('dc', 'http://purl.org/dc/elements/1.1/')
doc.add_child(root)

# Add content
title = doc.create_element('dc:title')
title.text = 'XML Processing with Ruby'
root.add_child(title)

# Output formatted XML
puts doc.to_xml(indent: 2)

doc = Moxml::Builder.new(Moxml.new).build do
  declaration version: "1.0", encoding: "UTF-8"

  element 'library', xmlns: 'http://example.org/library' do
    element 'book' do
      element 'title' do
        text 'Ruby Programming'
      end

      element 'author' do
        text 'Jane Smith'
      end

      comment 'Publication details'
      element 'published', year: '2024'

      cdata '<custom>metadata</custom>'
    end
  end
end

doc = Moxml.new.create_document

# Add declaration
doc.add_child(doc.create_declaration("1.0", "UTF-8"))

# Create root with namespace
root = doc.create_element('library')
root.add_namespace(nil, 'http://example.org/library')
root.add_namespace("dc", "http://purl.org/dc/elements/1.1/")
doc.add_child(root)

# Add elements with attributes
book = doc.create_element('book')
book['id'] = 'b1'
book['type'] = 'technical'
root.add_child(book)

# Add mixed content
book.add_child(doc.create_comment('Book details'))
title = doc.create_element('title')
title.text = 'Ruby Programming'
book.add_child(title)

# Old way - verbose and less readable
element = doc.create_element('book')
element.add_namespace("dc", "http://purl.org/dc/elements/1.1/")
element["id"] = "123"
element["type"] = "article"
child = doc.create_element("title")
child.text = "Hello"
element.add_child(child)

# New way - fluent and chainable
element = doc.create_element('book')
  .with_namespace("dc", "http://purl.org/dc/elements/1.1/")
  .set_attributes(id: "123", type: "article")
  .with_child(doc.create_element("title").tap { |t| t.text = "Hello" })

# Creating a document
doc = Moxml.new.create_document
doc = Moxml.new.parse(xml_string)

# Document properties and methods
doc.encoding               # Get document encoding
doc.encoding = "UTF-8"     # Set document encoding
doc.version                # Get XML version
doc.version = "1.1"        # Set XML version
doc.standalone             # Get standalone declaration
doc.standalone = "yes"     # Set standalone declaration

# Document structure
doc.root                  # Get root element
doc.children              # Get all top-level nodes
doc.add_child(node)       # Add a child node
doc.remove_child(node)    # Remove a child node

# Node creation methods
doc.create_element(name)    # Create new element
doc.create_text(content)    # Create text node
doc.create_cdata(content)   # Create CDATA section
doc.create_comment(content) # Create comment
doc.create_processing_instruction(target, content) # Create PI

# Document querying
doc.xpath(expression)      # Find nodes by XPath
doc.at_xpath(expression)   # Find first node by XPath

# Serialization
doc.to_xml(options)        # Convert to XML string

# Convenience methods
doc.add_element(name, attributes = {}, &block) # Create, configure, and add element
doc.find(xpath)                                # Alias for at_xpath
doc.find_all(xpath)                            # Returns array of matching elements

# Element properties
element.name               # Get element name
element.name = "new_name"  # Set element name
element.text              # Get text content
element.text = "content"   # Set text content
element.inner_text        # Get text content for current node only
element.inner_xml         # Get inner XML content
element.inner_xml = xml   # Set inner XML content

# Attributes
element[name]             # Get attribute value
element[name] = value     # Set attribute value
element.attributes        # Get all attributes
element.remove_attribute(name) # Remove attribute

# Namespace handling
element.namespace         # Get element's namespace
element.namespace = ns     # Set element's namespace
element.add_namespace(prefix, uri) # Add new namespace
element.namespaces        # Get all namespace definitions

# Node structure
element.parent            # Get parent node
element.children          # Get child nodes
element.add_child(node)   # Add child node
element.remove_child(node) # Remove child node
element.add_previous_sibling(node) # Add sibling before
element.add_next_sibling(node)    # Add sibling after
element.replace(node)     # Replace with another node
element.remove           # Remove from document

# Node type checking
element.element?         # Returns true
element.text?           # Returns false
element.cdata?          # Returns false
element.comment?        # Returns false
element.processing_instruction? # Returns false

# Node querying
element.xpath(expression)  # Find nodes by XPath
element.at_xpath(expression) # Find first node by XPath

# Convenience methods
element.with_namespace(prefix, uri) # Add namespace and return self
element.set_attributes(hash)        # Set multiple attributes, returns self
element.with_child(node)            # Add child and return self
element.find_element(xpath)         # Alias for at_xpath
element.find_all(xpath)             # Returns array of matching elements

# Creating text nodes
text = doc.create_text("content")

# Text properties
text.content             # Get text content
text.content = "new"     # Set text content

# Node type checking
text.text?              # Returns true

# Structure
text.parent             # Get parent node
text.remove             # Remove from document
text.replace(node)      # Replace with another node

# Creating CDATA sections
cdata = doc.create_cdata("<raw>content</raw>")

# CDATA properties
cdata.content           # Get CDATA content
cdata.content = "new"   # Set CDATA content

# Node type checking
cdata.cdata?           # Returns true

# Structure
cdata.parent           # Get parent node
cdata.remove           # Remove from document
cdata.replace(node)    # Replace with another node

# Creating comments
comment = doc.create_comment("Note")

# Comment properties
comment.content         # Get comment content
comment.content = "new" # Set comment content

# Node type checking
comment.comment?        # Returns true

# Structure
comment.parent          # Get parent node
comment.remove          # Remove from document
comment.replace(node)   # Replace with another node

# Creating processing instructions
pi = doc.create_processing_instruction("xml-stylesheet",
  'type="text/xsl" href="style.xsl"')

# PI properties
pi.target              # Get PI target
pi.target = "new"      # Set PI target
pi.content             # Get PI content
pi.content = "new"     # Set PI content

# Node type checking
pi.processing_instruction? # Returns true

# Structure
pi.parent             # Get parent node
pi.remove             # Remove from document
pi.replace(node)      # Replace with another node

# Attribute properties
attr.name              # Get attribute name
attr.name = "new"      # Set attribute name
attr.value            # Get attribute value
attr.value = "new"     # Set attribute value

# Namespace handling
attr.namespace         # Get attribute's namespace
attr.namespace = ns    # Set attribute's namespace

# Node type checking
attr.attribute?        # Returns true

# Namespace properties
ns.prefix             # Get namespace prefix
ns.uri               # Get namespace URI

# Formatting
ns.to_s              # Format as xmlns declaration

# Node type checking
ns.namespace?        # Returns true

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

# Add namespace to element
element.add_namespace('dc', 'http://purl.org/dc/elements/1.1/')

# Create element in namespace
title = doc.create_element('dc:title')
title.text = 'Document Title'

# Query with namespaces
doc.xpath('//dc:title',
  'dc' => 'http://purl.org/dc/elements/1.1/')

# Get native node
native_node = element.native

# Get adapter being used
adapter = element.context.config.adapter

# Create from native node
element = Moxml::Element.new(native_node, context)

Moxml::Error (< StandardError)
├── ParseError           # XML parsing failures
├── XPathError          # XPath expression errors
├── ValidationError     # XML validation failures
├── NamespaceError      # Namespace-related errors
├── AdapterError        # Adapter loading/operation errors
├── SerializationError  # XML serialization failures
├── DocumentStructureError # Invalid document structure
├── AttributeError      # Attribute operation errors
└── NotImplementedError # Unimplemented adapter features

begin
  doc = context.parse(invalid_xml, strict: true)
rescue Moxml::ParseError => e
  # Enhanced parse errors include:
  puts e.line      # Line number where error occurred
  puts e.column    # Column number where error occurred
  puts e.source    # Excerpt of problematic XML
  puts e.to_s      # Full message with hints
  # Output includes helpful hint:
  # "Hint: Check XML syntax and ensure all tags are properly closed"
end

# Catch specific errors for targeted handling
begin
  doc = Moxml.new.parse(xml_string, strict: true)
  results = doc.xpath("//book[@id='123']")
rescue Moxml::ParseError => e
  # Handle parsing errors
  logger.error("XML parsing failed: #{e.to_s}")
  # e.to_s includes hints for fixing the issue
rescue Moxml::XPathError => e
  # Handle XPath errors
  logger.error("XPath query failed: #{e.expression}")
rescue Moxml::NamespaceError => e
  # Handle namespace errors
  logger.error("Namespace error: #{e.prefix}:#{e.uri}")
rescue Moxml::Error => e
  # Catch-all for other Moxml errors
  logger.error("XML processing error: #{e.message}")
end

# Global configuration
Moxml.configure do |config|
  config.default_adapter = :nokogiri
  config.strict = true
  config.encoding = 'UTF-8'
end

# Instance configuration
moxml = Moxml.new do |config|
  config.adapter = :oga
  config.strict = false
end

Moxml::Config.default_adapter = <adapter-symbol>

doc = context.parse(large_xml)
# Process document
doc = nil  # Allow garbage collection of document and registry
GC.start   # Force garbage collection if needed

# 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')

# Preferred - using builder pattern
doc = Moxml::Builder.new(Moxml.new).build do
  declaration version: "1.0", encoding: "UTF-8"
  element 'root' do
    element 'child' do
      text 'content'
    end
  end
end

# Alternative - direct manipulation
doc = Moxml.new.create_document
doc.add_child(doc.create_declaration("1.0", "UTF-8"))
root = doc.create_element('root')
doc.add_child(root)

# Preferred - chainable operations
element
  .add_namespace('dc', 'http://purl.org/dc/elements/1.1/')
  .add_child(doc.create_text('content'))

# Preferred - clear node type checking
if node.element?
  node.add_namespace('dc', 'http://purl.org/dc/elements/1.1/')
  node.add_child(doc.create_text('content'))
end