lib/apricoteatsgorilla/apricoteatsgorilla.rb in smacks-apricoteatsgorilla-0.5.1 vs lib/apricoteatsgorilla/apricoteatsgorilla.rb in smacks-apricoteatsgorilla-0.5.2

@@ -20,11 +20,12 @@
     attr_accessor :disable_hash_keys_to_snake_case
 
     # Flag to disable conversion of Hash keys to Symbols.
     attr_accessor :disable_hash_keys_to_symbols
 
-    # Hash of namespaces and XML nodes to apply these namespaces to.
+    # Hash of namespaces (keys) and XML nodes (values) to apply these
+    # namespaces to.
     attr_accessor :nodes_to_namespace
 
     # Shortcut method for translating between XML Strings and Ruby Hashes.
     # Delegates to +xml_to_hash+ in case +source+ is a String or delegates
     # to +hash_to_xml+ in case +source+ is a Hash. Returns nil otherwise.
@@ -37,24 +38,26 @@
         else
           nil
       end
     end
 
-    # Yields this class in case a +block+ was given.
+    # Yields this class to a given +block+ for wrapping the setup of multiple
+    # flags at once.
     def setup
       yield self if block_given?
     end
 
     # Translates a given +xml+ String into a Ruby Hash.
     #
     # Starts parsing at the XML root node by default. Accepts an optional
     # +root_node+ parameter for defining a custom root node to start parsing
     # at using an XPath-Expression (Hpricot search).
     #
-    # Notice that the root node itself won't be included in the Hash.
+    # Notice that both namespaces and attributes get removed and the root node
+    # itself won't be included in the Hash.
     #
-    # ==== Example
+    # ==== Examples
     #
     #   xml = '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
     #       <soap:Body>
     #         <ns2:authenticateResponse xmlns:ns2="http://v1_0.ws.example.com/">
     #           <return>
@@ -64,17 +67,20 @@
     #           </return>
     #         </ns2:authenticateResponse>
     #       </soap:Body>
     #     </soap:Envelope>'
     #
+    #   ApricotEatsGorilla.xml_to_hash(xml)
+    #   # => { :body => { :authenticate_response => { :return => { :apricot => { :eats => "Gorilla" } } } } }
+    #
     #   ApricotEatsGorilla.xml_to_hash(xml, "//return")
     #   # => { :apricot => { :eats => "Gorilla" } }
     def xml_to_hash(xml, root_node = nil)
       doc = Hpricot.XML remove_whitespace(xml)
       root = root_node ? doc.search(root_node) : doc.root
 
-      return nil if root.nil?
+      return nil if root.nil? || (root.respond_to?(:size) && root.size == 0)
       if !root.respond_to? :each
         xml_node_to_hash(root)
       elsif root.size == 1
         single_xml_root_node_to_hash(root)
       else
@@ -82,31 +88,45 @@
       end
     end
 
     # Translates a given Ruby +hash+ into an XML String.
     #
-    # ==== Example
+    # ==== Examples
     #
     #   hash = { :apricot => { :eats => "Gorilla" } }
-    #
     #   ApricotEatsGorilla.hash_to_xml(hash)
+    #
     #   # => "<apricot><eats>Gorilla</eats></apricot>"
+    #
+    #   hash = { :apricot => { :eats => ["Gorillas", "Snakes"] } }
+    #   ApricotEatsGorilla.hash_to_xml(hash)
+    #
+    #   # => "<apricot><eats>Gorillas</eats><eats>Snakes</eats></apricot>"
     def hash_to_xml(hash)
       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+ to set.
+    # Builds a SOAP request envelope and includes the content of a given
+    # +block+ into the envelope body. Accepts a Hash of additional +namespaces+
+    # to set.
     #
-    # ==== Example
+    # ==== Examples
     #
     #   ApricotEatsGorilla.soap_envelope do
     #     "<apricot><eats>Gorilla</eats></apricot>"
     #   end
     #
     #   # => '<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
     #   # =>    <env:Body>
     #   # =>      <apricot><eats>Gorilla</eats></apricot>
+    #   # =>    </env:Body>
+    #   # =>  </env:Envelope>'
+    #
+    #   ApricotEatsGorilla.soap_envelope(:wsdl => "http://example.com") { "pureText" }
+    #
+    #   # => '<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://example.com">
+    #   # =>    <env:Body>
+    #   # =>      pureText
     #   # =>    </env:Body>
     #   # =>  </env:Envelope>'
     def soap_envelope(namespaces = {})
       namespaces[:env] = "http://schemas.xmlsoap.org/soap/envelope/"