AC/DC - h3o(software)

For Those About To Rock

This is a little XML-to-object-to-XML library that gets Dirty Deeds Done Dirt Cheap.

Features

  • Take XML string objects and convert them to real Ruby objects from your library

  • Take real Ruby objects and convert them to XML strings

  • Declare XML elements/attributes easily and with type enforcement

Usage

It’s A Long Way To The Top, If You Want To Rock n Roll

AcDc::Body assists you with declaring XML objects with ease. And #acdc makes marshaling those objects from XML a breeze.

Simple Data Model

This example will go over a simple Address data model and all of the ways you could use it.

require 'rubygems'
require 'acdc'

class Address < AcDc::Body
  attribute :type, String, :tag => "Type"
end

puts Address.new.acdc
#=> <?xml version="1.0" encoding="UTF-8"?><address Type=""></address>

First thing to point out is the #attribute class method that allows you to specify the name of the method (:type) the type of the data (String) and the XML tag (“Type”).

You can also do this with #element. 

class Address < AcDc::Body
  attribute :type, String, :tag => "Type"
  element :street, String, :tag => "Street"
end

puts Address.new.acdc
#=> <?xml version="1.0" encoding="UTF-8"?><address Type=""><Street/></address>

The :tag parameter is optional. The reason it’s demonstrated here is simply to capitalize the attribute/element tag. You could :tag any element/attribute with another name for rendering. By default AcDc will output XML in lowercase. 

class Address < AcDc::Body
  attribute :type, String
  element :street, String
end

puts Address.new.acdc
#=> <?xml version="1.0" encoding="UTF-8"?><address type=""><street/></address>

You could also specify a custom type for the second parameter. In the following example the Street element will be created as a custom type.

class Street < AcDc::Body
  element :line_1, String
end

class Address < AcDc::Body
  attribute :type, String
  element :street, Street
end

add = Address.new
add.street = Street.new
add.street.line_1 = "1234 Somewhere"

puts add.acdc
#=> <?xml version="1.0" encoding="UTF-8"?><address type=""><street><line_1>1234 Somewhere</line_1></street></address>

AcDc will also recognize collections of elements. You can do this with the :single parameter. Here is an example:

class Street < AcDc::Body
   element :line_1, String
end

class Address < AcDc::Body
  attribute :type, String
  element :streets, Street, :single => false
end

add = Address.new
street1 = Street.new
street2 = Street.new
street1.line_1 = "1234 Somewhere"
street2.line_1 = "5678 Somwhere Else"
add.streets = [street1,street2]
puts add.acdc
#=> <?xml version="1.0" encoding="UTF-8"?><address type=""><street><line_1>1234 Somewhere</line_1></street><street><line_1>5678 Somwhere Else</line_1></street></address>

The final example is the Dc part - Xml to Object. The following example uses the Street and Address classes above and the #acdc method to derive the objects from the XML string.

addy = acdc <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<address type="">
<street><line_1>1234 Somewhere</line_1></street>
<street><line_1>5678 Somwhere Else</line_1></street>
</address>
EOF

puts addy.inspect
#<Address:0x3342f8 @type="", @streets=[#<Street:0x32abb8 @line_1="1234 Somewhere">, #<Street:0x329290 @line_1="5678 Somwhere Else">]>

Contact

Special Thanks

I want to thank John Nunemaker for his HappyMapper gem. I stole quite a bit of code from that gem.

And if you might ask why not just use his library? Well - that’s the acdc part of this story. He had the AC - I added the DC.