smacks-apricoteatsgorilla 0.4.1 → 0.4.2

data/README.rdoc

@@ -2,9 +2,9 @@
 
 Apricot eats Gorilla is a SOAP communication helper.
 
-It translates between SOAP response messages (XML) and Ruby Hashes and may
-be used to build a SOAP request envelope. It is based on CobraVsMongoose but
-uses Hpricot instead of REXML and doesn't follow the BadgerFish convention.
+It translates between SOAP messages (XML) and Ruby Hashes while offering some
+helpful methods for working with SOAP webservices. Apricot eats Gorilla was
+initially based on CobraVsMongoose but uses Hpricot instead of REXML.
 
 == Install
 
@@ -18,6 +18,12 @@ uses Hpricot instead of REXML and doesn't follow the BadgerFish convention.
 
 === xml_to_hash(xml, root_node = nil)
 
+Converts a given XML String into a Ruby Hash. Starts parsing at root node by
+default. The optional root_node parameter can be used to specify a custom root
+node to start parsing at using an XPath expression (Hpricot search). The root
+node itself won't be included in the Hash. Converts tag names from CamelCase/
+lowerCamelCase to snake_case and into Symbols by default.
+
   xml = '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
     <soap:Body>
       <ns2:authenticateResponse xmlns:ns2="http://v1_0.ws.example.com/">
@@ -36,13 +42,20 @@ uses Hpricot instead of REXML and doesn't follow the BadgerFish convention.
 
 === hash_to_xml(hash)
 
-  hash = { :apricot => { :eats => "Gorilla" } }
+Converts a given Ruby Hash into an XML String. Converts Hash keys from snake_case
+to lowerCamelCase by default.
+
+  hash = { :apricot => { :eats => { :lots_of => "Gorillas" } } }
 
   ApricotEatsGorilla[hash]
-  # => "<apricot><eats>Gorilla</eats></apricot>"
+  # => "<apricot><eats><lotsOf>Gorillas</lotsOf></eats></apricot>"
 
 === soap_envelope(namespaces = {})
 
+Builds a SOAP request envelope and includes the content from a given block
+into the envelope body. Accepts a Hash (namespace => namespace_uri) of additional
+namespaces to set.
+
   ApricotEatsGorilla.soap_envelope { "<authenticate>me</authenticate>" }
 
   # => '<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
@@ -51,6 +64,34 @@ uses Hpricot instead of REXML and doesn't follow the BadgerFish convention.
   # =>    </env:Body>
   # =>  </env:Envelope>'
 
-== More examples
+== Changing defaults
+
+There are several options for changing the default behavior. Options can be
+set using a setup block or by setting one option at a time.
+
+  ApricotEatsGorilla.setup do |s|
+    s.disable_tag_names_to_lower_camel_case = true
+    s.disable_hash_keys_to_snake_case = true
+    s.disable_hash_keys_to_symbol = true
+  end
+
+=== Disable conversion of tag names to lowerCamelCase
+
+By default XML tags created by hash_to_xml are converted from snake_case to
+lowerCamelCase. Disable by setting disable_tag_names_to_lower_camel_case to true.
+
+  ApricotEatsGorilla.disable_tag_names_to_lower_camel_case = true
+
+=== Disable conversion of Hash keys to snake_case
+
+By default Hash keys created by xml_to_hash are converted from lowerCamelCase/
+CamelCase to snake_case. Disable by setting disable_hash_keys_to_snake_case to true.
+
+  ApricotEatsGorilla.disable_hash_keys_to_snake_case = true
+
+=== Disable conversion of Hash keys to Symbols
+
+By default Hash keys created by xml_to_hash are converted to Symbols.
+Disable by setting disable_hash_keys_to_symbol to true.
 
-Please take a look at the tests for some more examples.
+  ApricotEatsGorilla.disable_hash_keys_to_symbol = true

data/lib/apricoteatsgorilla.rb

@@ -3,48 +3,13 @@ require "hpricot"
 
 # Apricot eats Gorilla is a SOAP communication helper.
 # 
-# It translates between SOAP response messages (XML) and Ruby Hashes and may
-# be used to build a SOAP request envelope. It is based on CobraVsMongoose but
-# uses Hpricot instead of REXML and doesn't follow the BadgerFish convention.
-#
-# === xml_to_hash(xml, root_node = nil)
-#
-#   xml = '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
-#     <soap:Body>
-#       <ns2:authenticateResponse xmlns:ns2="http://v1_0.ws.example.com/">
-#         <return>
-#           <authValue>
-#             <token>secret</token>
-#             <client>example</client>
-#           </authValue>
-#         </return>
-#       </ns2:authenticateResponse>
-#     </soap:Body>
-#   </soap:Envelope>'
-#
-#   ApricotEatsGorilla[xml, "//return"]
-#   # => { :auth_value => { :token => "secret", :client => "example" } }
-#
-# === hash_to_xml(hash)
-#
-#   hash = { :apricot => { :eats => "Gorilla" } }
-#
-#   ApricotEatsGorilla[hash]
-#   # => "<apricot><eats>Gorilla</eats></apricot>"
-#
-# === soap_envelope(namespaces = {})
-#
-#   ApricotEatsGorilla.soap_envelope { "<authenticate>me</authenticate>" }
-#
-#   # => '<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
-#   # =>    <env:Body>
-#   # =>      <authenticate>me</authenticate>
-#   # =>    </env:Body>
-#   # =>  </env:Envelope>'
+# It translates between SOAP messages (XML) and Ruby Hashes while offering some
+# helpful methods for working with SOAP webservices. Apricot eats Gorilla was
+# initially based on CobraVsMongoose but uses Hpricot instead of REXML.
 class ApricotEatsGorilla
   class << self # Class methods
 
-    # Flag to enable optional sorting of Hash keys.
+    # Flag to enable sorting of Hash keys.
     attr_accessor :sort_keys
 
     # Flag to disable conversion of tag names to lowerCamelCase.
@@ -59,7 +24,7 @@ class ApricotEatsGorilla
     # Array of XML nodes to add a namespace to.
     attr_accessor :nodes_to_namespace
 
-    # The namespace for nodes in :nodes_to_namespace.
+    # The namespace for nodes set by nodes_to_namespace.
     attr_accessor :node_namespace
 
     # Shortcut method for translating between XML Strings and Ruby Hashes.
@@ -86,15 +51,16 @@ class ApricotEatsGorilla
     def setup
       yield self if block_given?
     end
-    
+
     # Converts a given +xml+ String into a Ruby Hash. Starts parsing at root
     # node by default. The optional +root_node+ parameter can be used to specify
-    # a custom root node to start parsing at via XPath (Hpricot search).
-    # The root node itself won't be included in the Hash.
+    # a custom root node to start parsing at using an XPath (Hpricot search).
+    # The root node itself won't be included in the Hash. Converts tag names
+    # from CamelCase/lowerCamelCase to snake_case and into Symbols by default.
     #
     # ==== Parameters
     #
-    # * +xml+ - The XML String to translate into a Ruby Hash.
+    # * +xml+ - The XML String to translate.
     # * +root_node+ - Optional. Custom root node to start parsing the given XML.
     #
     # ==== Examples
@@ -107,19 +73,29 @@ class ApricotEatsGorilla
     #   ApricotEatsGorilla[xml, "//eats"]
     #   # => { :lots_of => "Gorillas" }
     def xml_to_hash(xml, root_node = nil)
-      xml = clean_xml(xml)
-      doc = Hpricot.XML(xml)
-      root = root_node ? doc.at(root_node) : doc.root
+      doc = Hpricot.XML clean_xml(xml)
+      root = root_node ? doc.search(root_node) : doc.root
 
       return nil if root.nil?
+      # root is an Hpricot::Elements object
+      if root.respond_to?(:count)
+        # root is an Hpricot::Elements object with only one element
+        return root.entries.map { |e| xml_node_to_hash(e) } if root.count > 1
+        root = root.entries.first
+        if root.children.size == 1 && root.children.first.text?
+          # root contains text only
+          return root.children.first.to_s
+        end
+      end
       xml_node_to_hash(root)
     end
 
-    # Converts a given +hash+ into an XML String.
+    # Converts a given Ruby Hash into an XML String. Converts Hash keys from
+    # snake_case to lowerCamelCase by default.
     #
     # ==== Parameters
     #
-    # * +hash+ - The Ruby Hash to translate into an XML String.
+    # * +hash+ - The Ruby Hash to translate.
     #
     # ==== Examples
     #
@@ -134,13 +110,13 @@ class ApricotEatsGorilla
       nested_data_to_xml(hash.keys.first, hash.values.first)
     end
 
-    # Builds a SOAP request envelope and includes the content from a given
-    # +block+ into the envelope body. Accepts a Hash of +namespaces+ and their
-    # corresponding URI for specifying custom namespaces.
+    # Builds a SOAP request envelope and includes the content from a given +block+
+    # into the envelope body. Accepts a Hash (namespace => namespace_uri) of
+    # additional +namespaces+ to set.
     #
     # ==== Parameters
     #
-    # * +namespaces+ - A Hash of namespaces and their corresponding URI.
+    # * +namespaces+ - A Hash of namespaces and their URI.
     #
     # ==== Examples
     #
@@ -191,7 +167,7 @@ class ApricotEatsGorilla
     #
     # ==== Parameters
     #
-    # * +element+ - The Hpricot element to translate into a Ruby Hash.
+    # * +element+ - The Hpricot element to translate.
     def xml_node_to_hash(element)
       this_node = {}
       element.each_child do |child|
@@ -199,7 +175,7 @@ class ApricotEatsGorilla
         if child.children.nil? || child.children.empty?
           key, value = child.name, nil
         elsif child.children.size == 1 && child.children.first.text?
-          key, value = child.name, booleanize(child.children.first.to_html)
+          key, value = child.name, to_boolean(child.children.first.to_html)
         else
           key, value = child.name, xml_node_to_hash(child)
         end
@@ -225,8 +201,8 @@ class ApricotEatsGorilla
     #
     # ==== Parameters
     #
-    # * +name+ - A Hash key to translate into an XML String.
-    # * +item+ - A Hash value to translate into an XML String.
+    # * +name+ - Root key from Hash to translate.
+    # * +item+ - Root value from Hash to translate.
     def nested_data_to_xml(name, item)
       case item
       when Array
@@ -282,15 +258,15 @@ class ApricotEatsGorilla
     end
 
     # Checks to see if a given +string+ matches "true" or "false" and converts
-    # these values to actual Boolean objects. Returns the original string in
+    # these values to actual Boolean objects. Returns the original String in
     # case it does not match "true" or "false".
-    def booleanize(string)
+    def to_boolean(string)
       return true if string == "true"
       return false if string == "false"
       string
     end
 
-    # Returns a sorted version of a given +hash+ if :sort_keys was enabled.
+    # Returns a sorted version of a given +hash+ if sort_keys is enabled.
     def opt_order(hash)
       return hash unless sort_keys
       hash.keys.sort_by { |s| s.to_s }.map { |key| [key, hash[key]] }

data/test/apricoteatsgorilla/xml_to_hash_test.rb

@@ -63,6 +63,27 @@ class XmlToHashTest < Test::Unit::TestCase
       end
     end
 
+    context "with XML containing no subnodes at custom root node" do
+      should "return the plain content of the custom root node" do
+        xml = '<root><return>123</return></root>'
+        expected = "123"
+
+        result = ApricotEatsGorilla.xml_to_hash(xml, "//return")
+        assert_equal expected, result
+      end
+    end
+
+    context "with XML containing multiple custom root nodes" do
+      should "return an Array containing the multiple root nodes" do
+        xml = '<root><return><id>3</id><name>Julia</name></return>' <<
+          '<return><id>5</id><name>Gorilla</name></return></root>'
+        expected = [{ :id => "3", :name => "Julia"}, { :id => "5", :name => "Gorilla"}]
+
+        result = ApricotEatsGorilla.xml_to_hash(xml, "//return")
+        assert_equal expected, result
+      end
+    end
+
     context "with XML containing lowerCamelCase nodes" do
       should "convert lowerCamelCase nodes to snake_case" do
         xml = "<contact><firstName>Jungle</firstName><lastName>Julia</lastName></contact>"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: smacks-apricoteatsgorilla
 version: !ruby/object:Gem::Version 
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors: 
 - Daniel Harrington