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.