Ox Ruby XML Parser and Object Marshaller

The Ox::HasAttrs module provides an 'easy' API for interacting with XML attributes. Objects including this module treat attributes as a Hash where keys can be either String or Symbol.

Key capabilities include:

• Direct Access: Use [] to retrieve values by name.
• Dynamic Access: Use method_missing to access attributes as if they were method calls (e.g., node.id).
• Bulk Access: Use attributes to get all attributes as a Hash.
• Modification: Use []= to set or add attributes.

Note: When setting attributes via []=, the value is automatically converted to a String.

# Assuming an object 'node' includes Ox::HasAttrs

# 1. Accessing attributes
val = node[:id]          # Using Symbol
val = node['id']        # Using String
val = node.id          # Using method-style access

# 2. Setting attributes
node[:class] = 'container'
node['type'] = 'header'

# 3. Getting all attributes
all_attrs = node.attributes # Returns a Hash

For simple, regularly formatted XML, you can navigate the document tree by calling methods named after the element or attribute names directly on the Ox::Element object.

• Elements: Access child elements by their name. If multiple elements with the same name exist, you can specify an index using parentheses, e.g., element.Name(1).
• Attributes: Access attribute values by calling the attribute name as a method.
• Text: Use the .text method to retrieve the first String node within an element's children.

Note: This API raises a NoMethodError if the requested name is not found.

doc = Ox.parse(%{
<?xml?>
<People>
  <Person age="58">
    <given>Peter</given>
    <surname>Ohler</surname>
  </Person>
  <Person>
    <given>Makie</given>
    <surname>Ohler</surname>
  </Person>
</People>
})

# Accessing elements and attributes via method calls
doc.People.Person.given.text  # => "Peter"
doc.People.Person(1).given.text # => "Makie"
doc.People.Person.age          # => "58"

Ox provides a SAX (Simple API for XML) parser for event-based XML parsing, which is ideal for processing very large files or IO streams without loading the entire document into memory.

To use it, you must create a subclass of Ox::Sax and implement the specific callback methods you wish to trigger. These methods must be public in your subclass; if they remain private, the parser will not call them.

Argument Types:

• name arguments are passed as Symbol.
• str arguments are passed as String.
• value arguments are passed as Ox::Sax::Value objects.

Callback Overlap Rules:

• If you define or make value(value) public, the text(str) method will be ignored for that element.
• Similarly, if you define or make attr_value(name, value) public, the attr(name, str) method will be ignored.
• The attrs_done() callback is invoked once all attributes for an element have been read.

require 'ox'

class MySax < ::Ox::Sax
  def initialize
    @element_names = []
  end

  def start_element(name)
    @element_names << name
  end
end

any = MySax.new()
File.open('any.xml', 'r') do |f|
  Ox.sax_parse(any, f)
end

Ox provides a way to build XML documents programmatically using Ox::Document, Ox::Element, and Ox::Instruct. You can append elements to each other and add special nodes like Ox::CData, Ox::Comment, or Ox::Raw (for direct injection).

require 'ox'

doc = Ox::Document.new

instruct = Ox::Instruct.new(:xml)
instruct[:version] = '1.0'
instruct[:encoding] = 'UTF-8'
instruct[:standalone] = 'yes'
doc << instruct

top = Ox::Element.new('top')
top[:name] = 'sample'
doc << top

mid = Ox::Element.new('middle')
mid[:name] = 'second'
top << mid

bot = Ox::Element.new('bottom')
bot[:name] = 'third'
bot << 'text at bottom'
mid << bot

other_elements = Ox::Element.new('otherElements')
other_elements << Ox::CData.new('<sender>John Smith</sender>')
other_elements << Ox::Comment.new("Director's commentary")
# other_elements << Ox::DocType.new('content')
other_elements << Ox::Raw.new('<warning>Be carefull with this! Direct inject into XML!</warning>')
top << other_elements

xml = Ox.dump(doc)