Peachy

Peachy dynamically slurps XML from an underlying XML DOM, creating Ruby methods on the fly to match the elements and attributes of the XML.

Source available at github.com/njpearman/Peachy

Install

The Peachy gem is available as you would expect. Run:

gem install peachy

then

require 'peachy'

in irb / your codebase to get going.

Usage

The Peachy::Proxy is the key class in Peachy. Create a new instance of a Peachy::Proxy by passing in a raw XML string

proxy = Peachy::Proxy.new('<xml><node>Peachy</node></xml>')

Once you have a Proxy, it’s straightforward to drill down through the XML by node name:

puts 'Contents: ' + proxy.xml.node.value
=> Contents: Peachy

Call #value on a childless node to get the contents of the node, such as the example above.

Peachy expects method names to be called in the Ruby convention of lowercase with underscores. It will do its best to match method names to elements and attributes following different conventions (currently, this is camelCaseNames, PascalCaseNames or hyphen-separated-names)

More detailed usage examples can be found in the .rb files in the /test directory.

Getting the underlying XML

It’s possible to call #to_s on any node in the tree to get the underlying XML at that point in the tree, such as:

puts 'XML: ' + proxy.xml.node.to_s
=> XML: <node>Peachy</node>

The exact representation of the XML will depend on the underlying XML parser that is being used, but the XML will be valid and correct.

XML parsing

Peachy tries to determine which XML parser to load when it is first used. Nokogiri is currently the first choice, defaulting to REXML if Nokogiri is not available. Peachy requires the appropriate XML parser gem at runtime and, as such, I haven’t included Nokogiri as a dependency in the gemspec. It will use Nokogiri when it’s available; otherwise REXML will be loaded and used at runtime.

It is possible to extend out the parser support, for example Hpricot or LibXML, so let me know if there are any other XML parsers that you’d like Peachy to support.

Elements and Attributes

Currently, elements and attributes are accessed in almost exactly the same way; call a method on your current node matching the attribute or element name that is required next. Elements need to have #value called on them to get the contents of the element, however.

E.g.

proxy = Peachy::Proxy.new('<peachy version="1.0.0"><node>Peachy is here.</node></peachy>')
puts "Element contents: " + proxy.peachy.node.value
=> Element contents: Peachy is here
puts "Element attribute: " + proxy.peachy.version
=> Element attribute: 1.0.0

Peachy is just for slurping XML, so this convention should make it easy to know how to access the property that you’re after, be they elements or attributes.

No method name match

By default, Peachy will raise a NoMatchingXmlPart error if a method call does not match a child node of the current location. It’s possible to globally switch of this behaviour and return nil when no child node is found. This might be desirable if you cannot be certain of the XML that you are trying to interpret until runtime.