woahdae-consumer 0.8.1

data/examples/shipping/ups_rate_response.xml

@@ -0,0 +1,340 @@
+<?xml version="1.0"?>
+<RatingServiceSelectionResponse>
+  <Response>
+    <TransactionReference>
+      <CustomerContext>RatingandService</CustomerContext>
+      <XpciVersion>1.0001</XpciVersion>
+    </TransactionReference>
+    <ResponseStatusCode>1</ResponseStatusCode>
+    <ResponseStatusDescription>Success</ResponseStatusDescription>
+  </Response>
+  <RatedShipment>
+    <Service>
+      <Code>03</Code>
+    </Service>
+    <RatedShipmentWarning>Yourinvoicemayvaryfromthedisplayedreferencerates</RatedShipmentWarning>
+    <BillingWeight>
+      <UnitOfMeasurement>
+        <Code>LBS</Code>
+      </UnitOfMeasurement>
+      <Weight>5.0</Weight>
+    </BillingWeight>
+    <TransportationCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>5.03</MonetaryValue>
+    </TransportationCharges>
+    <ServiceOptionsCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>0.00</MonetaryValue>
+    </ServiceOptionsCharges>
+    <TotalCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>5.03</MonetaryValue>
+    </TotalCharges>
+    <GuaranteedDaysToDelivery/>
+    <ScheduledDeliveryTime/>
+    <RatedPackage>
+      <TransportationCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>5.03</MonetaryValue>
+      </TransportationCharges>
+      <ServiceOptionsCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>0.00</MonetaryValue>
+      </ServiceOptionsCharges>
+      <TotalCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>5.03</MonetaryValue>
+      </TotalCharges>
+      <Weight>5.0</Weight>
+      <BillingWeight>
+        <UnitOfMeasurement>
+          <Code>LBS</Code>
+        </UnitOfMeasurement>
+        <Weight>5.0</Weight>
+      </BillingWeight>
+    </RatedPackage>
+  </RatedShipment>
+  <RatedShipment>
+    <Service>
+      <Code>12</Code>
+    </Service>
+    <RatedShipmentWarning>Yourinvoicemayvaryfromthedisplayedreferencerates</RatedShipmentWarning>
+    <BillingWeight>
+      <UnitOfMeasurement>
+        <Code>LBS</Code>
+      </UnitOfMeasurement>
+      <Weight>5.0</Weight>
+    </BillingWeight>
+    <TransportationCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>9.12</MonetaryValue>
+    </TransportationCharges>
+    <ServiceOptionsCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>0.00</MonetaryValue>
+    </ServiceOptionsCharges>
+    <TotalCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>9.12</MonetaryValue>
+    </TotalCharges>
+    <GuaranteedDaysToDelivery>3</GuaranteedDaysToDelivery>
+    <ScheduledDeliveryTime/>
+    <RatedPackage>
+      <TransportationCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>9.12</MonetaryValue>
+      </TransportationCharges>
+      <ServiceOptionsCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>0.00</MonetaryValue>
+      </ServiceOptionsCharges>
+      <TotalCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>9.12</MonetaryValue>
+      </TotalCharges>
+      <Weight>5.0</Weight>
+      <BillingWeight>
+        <UnitOfMeasurement>
+          <Code>LBS</Code>
+        </UnitOfMeasurement>
+        <Weight>5.0</Weight>
+      </BillingWeight>
+    </RatedPackage>
+  </RatedShipment>
+  <RatedShipment>
+    <Service>
+      <Code>59</Code>
+    </Service>
+    <RatedShipmentWarning>Yourinvoicemayvaryfromthedisplayedreferencerates</RatedShipmentWarning>
+    <BillingWeight>
+      <UnitOfMeasurement>
+        <Code>LBS</Code>
+      </UnitOfMeasurement>
+      <Weight>5.0</Weight>
+    </BillingWeight>
+    <TransportationCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>14.91</MonetaryValue>
+    </TransportationCharges>
+    <ServiceOptionsCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>0.00</MonetaryValue>
+    </ServiceOptionsCharges>
+    <TotalCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>14.91</MonetaryValue>
+    </TotalCharges>
+    <GuaranteedDaysToDelivery>2</GuaranteedDaysToDelivery>
+    <ScheduledDeliveryTime>10:30A.M.</ScheduledDeliveryTime>
+    <RatedPackage>
+      <TransportationCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>14.91</MonetaryValue>
+      </TransportationCharges>
+      <ServiceOptionsCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>0.00</MonetaryValue>
+      </ServiceOptionsCharges>
+      <TotalCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>14.91</MonetaryValue>
+      </TotalCharges>
+      <Weight>5.0</Weight>
+      <BillingWeight>
+        <UnitOfMeasurement>
+          <Code>LBS</Code>
+        </UnitOfMeasurement>
+        <Weight>5.0</Weight>
+      </BillingWeight>
+    </RatedPackage>
+  </RatedShipment>
+  <RatedShipment>
+    <Service>
+      <Code>02</Code>
+    </Service>
+    <RatedShipmentWarning>Yourinvoicemayvaryfromthedisplayedreferencerates</RatedShipmentWarning>
+    <BillingWeight>
+      <UnitOfMeasurement>
+        <Code>LBS</Code>
+      </UnitOfMeasurement>
+      <Weight>5.0</Weight>
+    </BillingWeight>
+    <TransportationCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>12.79</MonetaryValue>
+    </TransportationCharges>
+    <ServiceOptionsCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>0.00</MonetaryValue>
+    </ServiceOptionsCharges>
+    <TotalCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>12.79</MonetaryValue>
+    </TotalCharges>
+    <GuaranteedDaysToDelivery>2</GuaranteedDaysToDelivery>
+    <ScheduledDeliveryTime/>
+    <RatedPackage>
+      <TransportationCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>12.79</MonetaryValue>
+      </TransportationCharges>
+      <ServiceOptionsCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>0.00</MonetaryValue>
+      </ServiceOptionsCharges>
+      <TotalCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>12.79</MonetaryValue>
+      </TotalCharges>
+      <Weight>5.0</Weight>
+      <BillingWeight>
+        <UnitOfMeasurement>
+          <Code>LBS</Code>
+        </UnitOfMeasurement>
+        <Weight>5.0</Weight>
+      </BillingWeight>
+    </RatedPackage>
+  </RatedShipment>
+  <RatedShipment>
+    <Service>
+      <Code>13</Code>
+    </Service>
+    <RatedShipmentWarning>Yourinvoicemayvaryfromthedisplayedreferencerates</RatedShipmentWarning>
+    <BillingWeight>
+      <UnitOfMeasurement>
+        <Code>LBS</Code>
+      </UnitOfMeasurement>
+      <Weight>5.0</Weight>
+    </BillingWeight>
+    <TransportationCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>23.71</MonetaryValue>
+    </TransportationCharges>
+    <ServiceOptionsCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>0.00</MonetaryValue>
+    </ServiceOptionsCharges>
+    <TotalCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>23.71</MonetaryValue>
+    </TotalCharges>
+    <GuaranteedDaysToDelivery>1</GuaranteedDaysToDelivery>
+    <ScheduledDeliveryTime>3:00P.M.</ScheduledDeliveryTime>
+    <RatedPackage>
+      <TransportationCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>23.71</MonetaryValue>
+      </TransportationCharges>
+      <ServiceOptionsCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>0.00</MonetaryValue>
+      </ServiceOptionsCharges>
+      <TotalCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>23.71</MonetaryValue>
+      </TotalCharges>
+      <Weight>5.0</Weight>
+      <BillingWeight>
+        <UnitOfMeasurement>
+          <Code>LBS</Code>
+        </UnitOfMeasurement>
+        <Weight>5.0</Weight>
+      </BillingWeight>
+    </RatedPackage>
+  </RatedShipment>
+  <RatedShipment>
+    <Service>
+      <Code>14</Code>
+    </Service>
+    <RatedShipmentWarning>Yourinvoicemayvaryfromthedisplayedreferencerates</RatedShipmentWarning>
+    <BillingWeight>
+      <UnitOfMeasurement>
+        <Code>LBS</Code>
+      </UnitOfMeasurement>
+      <Weight>5.0</Weight>
+    </BillingWeight>
+    <TransportationCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>64.25</MonetaryValue>
+    </TransportationCharges>
+    <ServiceOptionsCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>0.00</MonetaryValue>
+    </ServiceOptionsCharges>
+    <TotalCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>64.25</MonetaryValue>
+    </TotalCharges>
+    <GuaranteedDaysToDelivery>1</GuaranteedDaysToDelivery>
+    <ScheduledDeliveryTime>8:00A.M.</ScheduledDeliveryTime>
+    <RatedPackage>
+      <TransportationCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>64.25</MonetaryValue>
+      </TransportationCharges>
+      <ServiceOptionsCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>0.00</MonetaryValue>
+      </ServiceOptionsCharges>
+      <TotalCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>64.25</MonetaryValue>
+      </TotalCharges>
+      <Weight>5.0</Weight>
+      <BillingWeight>
+        <UnitOfMeasurement>
+          <Code>LBS</Code>
+        </UnitOfMeasurement>
+        <Weight>5.0</Weight>
+      </BillingWeight>
+    </RatedPackage>
+  </RatedShipment>
+  <RatedShipment>
+    <Service>
+      <Code>01</Code>
+    </Service>
+    <RatedShipmentWarning>Yourinvoicemayvaryfromthedisplayedreferencerates</RatedShipmentWarning>
+    <BillingWeight>
+      <UnitOfMeasurement>
+        <Code>LBS</Code>
+      </UnitOfMeasurement>
+      <Weight>5.0</Weight>
+    </BillingWeight>
+    <TransportationCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>27.63</MonetaryValue>
+    </TransportationCharges>
+    <ServiceOptionsCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>0.00</MonetaryValue>
+    </ServiceOptionsCharges>
+    <TotalCharges>
+      <CurrencyCode>USD</CurrencyCode>
+      <MonetaryValue>27.63</MonetaryValue>
+    </TotalCharges>
+    <GuaranteedDaysToDelivery>1</GuaranteedDaysToDelivery>
+    <ScheduledDeliveryTime>10:30A.M.</ScheduledDeliveryTime>
+    <RatedPackage>
+      <TransportationCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>27.63</MonetaryValue>
+      </TransportationCharges>
+      <ServiceOptionsCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>0.00</MonetaryValue>
+      </ServiceOptionsCharges>
+      <TotalCharges>
+        <CurrencyCode>USD</CurrencyCode>
+        <MonetaryValue>27.63</MonetaryValue>
+      </TotalCharges>
+      <Weight>5.0</Weight>
+      <BillingWeight>
+        <UnitOfMeasurement>
+          <Code>LBS</Code>
+        </UnitOfMeasurement>
+        <Weight>5.0</Weight>
+      </BillingWeight>
+    </RatedPackage>
+  </RatedShipment>
+</RatingServiceSelectionResponse>

data/lib/consumer/helper.rb

@@ -0,0 +1,111 @@
+module Consumer::Helper
+  # if you pass in a newline-less glob of xml it'll return an indented copy
+  # for improved readability.
+  def self.tidy(xml)
+    xml = xml.clone # avoid modifying @response_xml due to pass by reference
+    
+    # remove all formatting to start from a common base
+    xml.gsub!(/\>[\t\n\r ]*\</, "><")
+    # replace empty tag pairs with <tag/>
+    xml.gsub!(/\<(\w*?)\>\<\/\1\>/, "<\\1/>")
+    # add in newlines after >, and sometimse before <
+    xml.gsub!(/\>\</,">\n<")
+    
+    declaration = /\<\?xml/
+    start_tag   = /\<[^\/]+?\>[\n\t\r ]+/
+    end_tag     = /^[\t ]*\<\//
+    
+    ## add appropriate spacing before each newline.
+    tab = 0
+    siblings = false
+    first_tag = true
+    return xml.collect do |line|
+      next line if line =~ declaration
+      
+      # calculate the indentation.
+      # In general we want to add spacing if it's a start tag or leaf node, and
+      # remove spacing if it's an end tag. The only times we don't want to add
+      # spacing is if it's the very first node or the previous node was a sibling
+      # instead of a parent.
+      if line =~ end_tag
+        tab -= 1
+      else
+        tab += 1 unless first_tag || siblings
+      end
+
+      # if the line is a start tag, the next lines will no longer be siblings
+      siblings = line =~ start_tag ? false : true
+      first_tag = false
+      
+      # return line with appropriate amount of preceding spaces #
+      line = "  " * (tab > 0 ? tab : 0) + line
+    end.join << "\n"
+  end
+  
+  # returns a copy of the xml without empty nodes. Also removes internal 
+  # (non-leaf) nodes that only contain empty leaves. Nodes containing only
+  # whitespace characters (space, newline, tab, and return) are considered empty.
+  def self.compact_xml(xml)
+    old_xml = xml
+    loop do
+      new_xml = old_xml.gsub(/\<(\w*?)\>[ \t\r\n]*\<\/\1\>\n?/, "")
+      if old_xml == new_xml # nothing was changed
+        return new_xml
+      else # something changed, so we'll go through it again
+        old_xml = new_xml
+      end
+    end
+  end
+
+  # returns a hash of defaults if +self.yaml_defaults+ is defined and the file
+  # defined there exists, empty hash otherwise.
+  # 
+  # Also takes a namespace, i.e. a sub-hash, and when given a namespace it also
+  # enables a global namespace called 'all'. Thus if you had the yaml:
+  # 
+  # <pre>
+  # all:
+  #   my_name: Buster
+  # greetings:
+  #   hello: world
+  # other:
+  #   irrelevant: data
+  # </pre>
+  # 
+  # a namespace of 'greetings' would return the hash:
+  # 
+  # <code>
+  # {"my_name" => "Buster", "hello" => "world"}
+  # </code>
+  # 
+  # You don't have to use the global namespace, but if you do, it will be included
+  # everywhere.
+  def self.hash_from_yaml(base_path, file, namespace = nil)
+    begin
+      hash = (base_path && file) ? YAML.load(File.read(File.join(base_path, file))) : {}
+    rescue => e
+      raise ArgumentError, "YAML load error: #{e.message}"
+    end
+    
+    return {} if !hash
+    
+    if namespace
+      global = hash["all"] || {}
+      namespaced_hash = hash[namespace] || {}
+      hash = global.merge(namespaced_hash)
+    end
+    
+    return hash
+  end
+  
+  def self.http_from_url(url)
+    uri = URI.parse url
+    http = Net::HTTP.new uri.host, uri.port
+    if uri.port == 443
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+    end
+    return http, uri
+  end
+  
+end

data/lib/consumer/mapping.rb

@@ -0,0 +1,184 @@
+module Consumer::Mapping
+  def self.included(base)
+    base.extend ClassMethods
+  end
+  
+  ### our lone instance method ###
+  
+  ##
+  # Same as doing:
+  # 
+  # <code>self.association(s) = Association.from_xml(xml)</code>
+  # === Behaviors
+  # * sets the association to a call to Klass.from_xml
+  # === Parameters
+  # [+xml+]         String of xml
+  # [+association+] The association name (i.e. self.something)
+  # [+klass+]       The association class (i.e. Something.from_xml). 
+  #                 Defaults to singular, capitalized +association+.
+  # === Returns
+  # Nothing in particular
+  def association_from_xml(xml, association, klass = nil)
+    klass ||= association.to_s.capitalize.singularize.constantize 
+
+    association_instance = klass.from_xml(xml)
+    return if association_instance.nil?
+    
+    self.send(association.to_s + "=", association_instance)
+  end
+  
+  module ClassMethods
+    # Creates a new mapping hash in self.maps
+    # === Parameters
+    # The parameters here are used to add a new mapping hash to self.maps, which
+    # in turn is used by from_xml_via_map to instantiate new objects
+    # [+first_or_all+] If +:all+, from_xml_via_map will return an array instead
+    #                  of a single instance (i.e. sets map[:all] to true)
+    # [+base_path+]    A fully qualified xpath, such as //SomethingResponse/bah.
+    #                  Also, uniquely identifies the map for a particular xml
+    #                  response in the case of multiple maps.
+    # [+registry+]     A hash of :attribute => 'xpath' pairs. Xpaths are
+    #                  relative to +base_path+, but fully qualified xpaths are
+    #                  also valid.
+    #                  
+    #                  For example, if the base path was //Response/Bah and the
+    #                  registry was {:foo => "FooElm"}, then from_xml_via_map
+    #                  will set instance.foo to the value at
+    #                  //Response/Bah/FooElm in the xml. However, if you set
+    #                  {:foo => "//Response/Woot/Ack"}, then it will pull the
+    #                  value from //Response/Woot/Ack (not
+    #                  //Response/Bah/Response/Woot/Ack).
+    # [+options+]      Valid options are:
+    #                  * +:include+ - sets map[:associations], which is an
+    #                    array of parameters to association_from_xml
+    # [+block+]        In from_xml_via_map this gets called with the new 
+    #                  instance as the last step of instantiation.
+    # === Returns
+    # The newly created map
+    # === Raises
+    # * RuntimeError if the base path is already defined in another mapping
+    #   in the class
+    def map(first_or_all, base_path, registry, options = {}, &block)
+      if self.maps.find {|m| m[:base_path] == base_path}
+        raise "Base path exists: #{base_path}" 
+      end
+      
+      map = {
+        :all => first_or_all == :all ? true : false,
+        :base_path => base_path,
+        :registry => registry,
+        :associations => [*options[:include]].compact,
+        :block => block
+      }
+      self.maps << map
+      
+      return map
+    end
+    
+    # Returns @maps or []
+    def maps
+      @maps ||= []
+    end
+    
+    # Pulls attributes from the xml using xpaths defined in the mapping whose
+    # base path matches the xml, and instantiates a new object with those attrs.
+    # === Behaviors
+    # * If multiple elements match the base path and map[:all] is true, it will
+    #   return an array of objects.
+    # * Calls from_xml on elements in map[:associations] (see
+    #   association_from_xml)
+    # * Calls map[:block] with the new instance (and optionally the libxml node)
+    #   just before adding it to the return array for custom post-processing
+    # === Returns
+    # * An array of instances or a new instance depending on whether map[:all]
+    #   is true or false, respectively
+    def from_xml_via_map(xml)
+      nodes, map = find_nodes_and_map(xml)
+      return nil if map.nil?
+      instances = []
+
+      nodes.each do |node|
+        attrs = attrs_from_node_and_registry(node, map[:registry])
+        instance = self.from_hash(attrs)
+        
+        map[:associations].each do |association|
+          # TODO: spec
+          instance.association_from_xml(xml, association)
+        end
+        
+        b = map[:block]
+        if b
+          case b.arity # number of parameters
+          when 1
+            b.call(instance)
+          when 2
+            b.call(instance, node)
+          end
+        end
+        
+        return instance unless map[:all]
+        instances << instance
+      end
+      
+      return instances
+    end
+    
+    # you can override this to what you want. Defaults to
+    # an alias for from_xml_via_map.
+    def from_xml(xml)
+      @xml = xml
+      self.before_from_xml if defined?(before_from_xml)
+      from_xml_via_map(@xml)
+    end
+    
+    # initializes a new instance of self and uses the attribute setters to 
+    # populate attributes from the hash. Objects inheriting from ActiveRecord
+    # do this automatically in initialize, but the world doesn't (always) revolve
+    # around AR
+    def from_hash(attrs)
+      object = self.new
+    
+      attrs.each do |attribute, value|
+        object.send("#{attribute}=", value)
+      end
+    
+      object
+    end
+  
+  private
+  
+    # find the first map whose base path matches the xml,
+    # and return the nodes found at that base path along with the map
+    # === Parameters
+    # [+xml+] - String of xml
+    # === Returns
+    # two-member array of the form [[LibXML::XML::XPath::Object], Consumer::Mapping::Map]
+    # === Raises
+    # nothing
+    def find_nodes_and_map(xml)
+      self.maps.each do |map|
+        doc = LibXML::XML::Parser.string(xml).parse
+        nodes = doc.find(map[:base_path])
+        return nodes, map if !nodes.empty?
+      end
+      return [], nil
+      puts "No map found in #{self.class} for xml #{xml[0..100]}..." if $DEBUG
+    end
+    
+    # returns a hash of attribute => value pairs given an xpath node and a
+    # map registry
+    # (LibXML::XML::XPath::Object and Consumer::Mapping::Map#registry, respectively)
+    def attrs_from_node_and_registry(node, registry)
+      attrs = {}
+      
+      registry.each do |attribute, path|
+        leaf = node.find(path).first
+        attrs[attribute] = leaf.content if leaf.respond_to?(:content)
+        attrs[attribute] = leaf.value if leaf.respond_to?(:value)
+      end
+
+      attrs
+    end
+    
+  end
+end