Quick Start Guide

This is a short usage example. See ROXML::ClassMethods::Declarations and
packaged test cases for more information.

Basic Mapping

Consider an XML document representing a Library containing a number of
Books. You can map this structure to Ruby classes that provide addition
useful behavior. With ROXML, you can annotate the Ruby classes as follows:

classBookincludeROXMLxml_accessor:isbn,:from=>"@ISBN"# attribute with name 'ISBN'
xml_accessor:titlexml_accessor:description,:cdata=>true# text node with cdata protection
xml_accessor:authorendclassLibraryincludeROXMLxml_accessor:name,:from=>"NAME",:cdata=>truexml_accessor:books,:as=>[Book]# by default roxml searches for books for in <book> child nodes, then, if none are present, in ./books/book children
end

To create a library and put a number of books in it we could run the
following code:

Note: In the above example, xml_name annotation tells ROXML to set
the element name to “book” for mapping to XML. The default is XML element
name is the class name in lowercase; “bookwithpublisher” in this case.

Namespace Support

Namespaced nodes are supported via the xml_namespace and xml_namespaces
declarations and the :from and :namespace attr options. See
spec/xml/namespace_spec.rb for usage.

Note that ROXML does not currently support outputting namespaced nodes.
This is planned for a future version.

Manipulation

Extending the above examples, say you want to parse a book's page count
and have it available as an Integer. In such a case, you can extend any
object with a block to manipulate it's value at parse time. For
example:

The result of the block above is stored, rather than the actual value
parsed from the document.

Construction

Object life-cycle is as follows: .from_xml is called with a first argument
representing the xml in file, string, or path form, and with optional
initialization_args following.

Firt .new and thus #initialize, is called with those same
initialization_args, or no args if none are present. Then the object is
populated with the attribute values from xml. Then the #after_parse
callback is called, with no arguments.

In #after_parse you can ensure that your object initialization is complete,
including initialization which requires more than one variable in concert.