Skip to content
a little xml-to-object-to-xml library
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
benchmarks
lib
profiling
spec
.gitignore
LICENSE
README
Rakefile

README

= 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

- Author:: Clint Hill clint.hill@h3osoftware.com
- Home Page:: http://h3osoftware.com/acdc
- GitHub:: git://github.com/clinth3o/acdc.git

== Special Thanks

I want to thank John Nunemaker for his HappyMapper gem. I stole quite a bit
of code from that gem.
* http://railstips.org/2008/11/17/happymapper-making-xml-fun-again
* http://github.com/jnunemaker/happymapper/

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.
You can’t perform that action at this time.