= Apricot eats Gorilla

Apricot eats Gorilla translates between XML documents and Hashes.
It's based on CobraVsMongoose but uses Hpricot instead of REXML to parse
XML and it also doesn't follow the BadgerFish convention.

Its initial purpose was to convert SOAP response messages to Hashes,
but it quickly evolved into a more general translation tool.

== Install

  $ sudo gem install smacks-apricoteatsgorilla --source http://gems.github.com

== Dependencies

  Hpricot 0.6.164 (also available for JRuby)

== An example

Let's assume you receive the following SOAP response:

xml = '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
      <ns2:findCustomerByIdResponse xmlns:ns2="http://v1_0.ws.example.com/">
        <return>
          <empty>false</empty>
          <customer>
            <id>449810</id>
            <title xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
            <name>Jungle Julia</name>
            <email>jj@example.com</email>
            <address />
          </customer>
        </return>
      </ns2:findCustomerByIdResponse>
    </soap:Body>
  </soap:Envelope>'

Just pass in the raw XML string:

  require "rubygems"
  require "apricoteatsgorilla
  hash = ApricotEatsGorilla.xml_to_hash(xml, "//return")

Or use the shortcut:

  hash = ApricotEatsGorilla(xml, "//return")

And it gets converted into a nice little Hash:

  "empty" => false,
  "customer" => {
    "address" => nil,
    "name" => "Jungle Julia",
    "title" => nil,
    "id" => "449810",
    "email" => "jj@example.com"
  }

== Conclusions

* The xml_to_hash method starts parsing the XML at the root node by default.
  By calling the method with an XPath expression as second parameter, we're
  able to define a custom root node.
* Node attributes are ignored and won't be included in the hash.
* The value of empty element nodes will be nil.
* Node values of "true" or "false" will be converted to boolean objects.

== More information

Take a look at the tests for some more examples.