Configuration

Purpose

Learn how to configure Moxml for your application’s requirements including adapter selection, parsing options, and encoding settings.

Global configuration

Configure Moxml globally for your application:

# Set default adapter
Moxml::Config.default_adapter = :nokogiri

# Access global config
config = Moxml::Config.new
config.adapter = :libxml
config.strict_parsing = true
config.default_encoding = 'UTF-8'

Instance configuration

Configure per Moxml instance:

# During initialization
context = Moxml.new do |config|
  config.adapter = :oga
  config.strict_parsing = false
  config.default_encoding = 'ISO-8859-1'
end

# After creation
context = Moxml.new
context.config.adapter = :libxml
context.config.strict_parsing = true

Configuration options

Adapter selection

Choose the XML processing library:

context = Moxml.new
context.config.adapter = :nokogiri  # or :libxml, :oga, :rexml, :ox

Available adapters:

  • :nokogiri - Default, full features

  • :libxml - Native performance

  • :oga - Pure Ruby

  • :rexml - Standard library

  • :ox - Maximum speed

See Adapters documentation for details.

Strict parsing

Control error handling for malformed XML:

# Strict mode (recommended for production)
context.config.strict_parsing = true
doc = context.parse(xml)  # Raises ParseError on malformed XML

# Relaxed mode (attempt to parse malformed XML)
context.config.strict_parsing = false
doc = context.parse(xml)  # Attempts to recover from errors

Default: true

Default encoding

Set default character encoding:

context.config.default_encoding = 'UTF-8'    # Default
context.config.default_encoding = 'ISO-8859-1'
context.config.default_encoding = 'UTF-16'

Default: "UTF-8"

Namespace validation mode

Control how strictly namespace URIs and prefixes are validated:

# Strict mode (default) — validates namespace URIs against RFC 3986 and
# prefixes against NCName rules
context.config.namespace_validation_mode = :strict
doc = context.parse(xml)  # Raises ValidationError for invalid URIs/prefixes

# Lenient mode — accepts any URI string and defers prefix validation to the
# underlying XML parser
context.config.namespace_validation_mode = :lenient
doc = context.parse(xml)  # Accepts non-standard namespace URIs/prefixes

Default: :strict

Modes:

:strict

Validates namespace URIs against the RFC 3986 URI-reference specification and namespace prefixes against NCName rules, as required by Namespaces in XML. Invalid values raise a Moxml::ValidationError. This is the recommended mode for standards-compliant XML processing.

:lenient

Accepts any string as a namespace URI (only rejecting control characters) and defers prefix validation to the underlying XML parser. Use this mode when processing XML documents that use non-standard namespace identifiers or prefixes (e.g., xmlns_1.0).

Example:

# Process documents with non-standard namespace URIs and prefixes
context = Moxml.new do |config|
  config.namespace_validation_mode = :lenient
end

xml = '<root xmlns:ex="not a valid URI but accepted in lenient mode"/>'
doc = context.parse(xml)  # Parses successfully

Context switching

Use different configurations for different tasks:

# High-performance context for simple docs
fast_context = Moxml.new
fast_context.config.adapter = :ox

# Feature-rich context for complex docs
full_context = Moxml.new
full_context.config.adapter = :nokogiri

# Process based on requirements
if simple_document?(xml)
  doc = fast_context.parse(xml)
else
  doc = full_context.parse(xml)
end

Serialization options

Control XML output format:

xml = doc.to_xml(
  indent: 2,                    # Indentation spaces
  encoding: 'UTF-8',            # Output encoding
  no_declaration: false,         # Include <?xml ...?>
  expand_empty: false            # Expand empty tags <tag></tag>
)

Adapter-specific configuration

Some adapters support additional options:

Nokogiri 

# Nokogiri parse options
doc = context.parse(xml,
  strict: true,
  encoding: 'UTF-8',
  recover: false  # Don't recover from errors
)

LibXML 

# LibXML parse options
doc = context.parse(xml,
  strict: true,
  encoding: 'UTF-8'
)

Ox 

# Ox typically uses fewer options
doc = context.parse(xml)

Configuration best practices

  1. Set adapter explicitly in production for consistency

  2. Use strict parsing to catch XML errors early

  3. Specify encoding when working with non-UTF-8 documents

  4. Document configuration in your application setup

  5. Test with target adapter during development

Environment-based configuration

Configure based on environment:

# config/initializers/moxml.rb
case Rails.env
when 'production'
  Moxml::Config.default_adapter = :nokogiri
  Moxml.new.config.strict_parsing = true
when 'development'
  Moxml::Config.default_adapter = :nokogiri
  Moxml.new.config.strict_parsing = false
when 'test'
  Moxml::Config.default_adapter = :rexml  # No C extensions needed
end

Runtime adapter switching

Change adapters dynamically:

def process_with_best_adapter(xml)
  # Try fast adapter first
  context = Moxml.new
  context.config.adapter = :ox

  doc = context.parse(xml)

  # Check if complex operations needed
  if needs_complex_xpath?(doc)
    # Switch to full-featured adapter
    context.config.adapter = :nokogiri
    doc = context.parse(xml)
  end

  doc
end

Configuration validation

Verify configuration is correct:

context = Moxml.new

# Check adapter loaded
puts context.config.adapter.name
# => "Moxml::Adapter::Nokogiri"

# Verify adapter available
begin
  context.config.adapter = :missing_adapter
rescue Moxml::AdapterError => e
  puts "Adapter not available: #{e.message}"
end

# Test parsing works
test_doc = context.parse('<root/>')
puts "Configuration valid" if test_doc.root

See also