woahdae-consumer 0.8.1

data/lib/consumer/request.rb

@@ -0,0 +1,280 @@
+require 'net/http'
+require 'net/https'
+require 'yaml'
+
+##
+# === Class Attrubutes
+# [+required+]       Defines attributes that must be present in any instance
+#                    before calling +do+. Anything defined here but not set in
+#                    the instance will raise a RequiredFieldError on calling +do+
+#
+#                    Defaluts to []
+# [+response_class+] String for setting the class the request will use to parse
+#                    the response.
+#
+#                    Defaults to [Something]Request, ex. for a
+#                    RateRequest, this would default to "Rate".
+#
+#                    Note that the instance method with the same name returns a
+#                    constant rather than the string set here.
+# [+yaml_defaults+]  Consists of two parameters. In order:
+#                    * The location (as a string) for a yaml file containing
+#                      attribute defaults.
+#                    * A namespace to grab the defaults out of.
+#
+#                      If your yaml looked like this:
+#
+#                      <pre>
+#                      ups:
+#                        user_id: Woody
+#                      usps:
+#                        user_id: John
+#                      </pre>
+#
+#                      UPSRequest would want to use "ups" as the namespace value,
+#                      where USPSRequest would want to use "usps"
+#
+#                      This is optional and has no default
+# [+error_paths+]    If you define this in your subclasses to return a hash for
+#                    error options (see "Options" below) they will raise
+#                    informative RequestError errors with xml error info in the
+#                    message.
+#
+#                    If this is left undefined and the remote server returns
+#                    error xml rather than what you were expecting, you'll get
+#                    generic xml parsing errors instead of something informative.
+#
+#                    Note: currently only handles one error.
+#
+#                    === Options
+#
+#                    All options are xpaths. All options except +:root+ are relative
+#                    to the root (unless prefixed with "//")
+#                    * +:root+    - Root element of the error(s)
+#                    * +:code+    - Remote API's error code for this error
+#                    * +:message+ - Informative part of the error
+#
+#                    === Example
+#
+#                    <pre>
+#                    {
+#                      :root => "//Error",
+#                      :code => "ErrorCode",
+#                      :message => "LongDescription"
+#                    }
+#                    </pre>
+#
+#                    Anything passed in to initialize will override these, though.
+class Consumer::Request
+  include Consumer
+ 
+  class << self
+    def url(url = nil)
+      @url = url if url
+      @url
+    end
+ 
+    def required(*args)
+      @required = args if !args.empty?
+      @required || []
+    end
+ 
+    def response_class(klass = nil)
+      @response_class = klass if klass
+      self.to_s =~ /(.+?)Request/
+      @response_class || $1
+    end
+ 
+    def yaml_defaults(*args)
+      @yaml_defaults = args if !args.empty?
+      @yaml_defaults
+    end
+ 
+    def defaults(defaults = nil)
+      @defaults = defaults if defaults
+      @defaults || {}
+    end
+ 
+    def error_paths(options = nil)
+      @error_paths = options if options
+      @error_paths
+    end
+  end
+ 
+  class RequestError < StandardError;end
+  class RequiredFieldError < StandardError;end
+ 
+  attr_reader :response_xml, :request_xml
+ 
+  # First gets defaults from self.defaults, merges them with defaults from
+  # +yaml_defaults+, merges all that with passed in attrs, and initializes all
+  # those into instance variables for use in to_xml.
+  def initialize(attrs = {})
+    # it's really handy to have all the other attrs init'd when we call
+    # self.defaults 'cuz we can use them to help define conditional defaults.
+    root = self.config_root
+    yaml = Helper.hash_from_yaml(root, *yaml_defaults)
+    yaml, attrs = symbolize_keys(yaml, attrs)
+
+    initialize_attrs(yaml.merge(attrs)) # load yaml, but attrs will overwrite dups
+
+    # now self.defaults has access to above stuff
+    class_defaults = self.defaults
+    class_defaults = symbolize_keys(class_defaults).first
+
+    # but we wanted defaults loaded first.
+    all_defaults = class_defaults.merge(yaml)
+    final_attrs = all_defaults.merge(attrs)
+    initialize_attrs(final_attrs)
+  end
+ 
+  # Sends self.to_xml to self.url and returns new object(s) created via
+  # [response_class].from_xml
+  # === Prerequisites
+  # * All attributes in self.required must exist; raises RequiredFieldError
+  #   otherwise
+  # * self.to_xml must be defined; RuntimeError otherwise
+  # * self.url must be set; RuntimeError otherwise
+  # * response_class.from_xml must be defined; RuntimeError otherwise
+  # === Returns
+  # Whatever response_class.from_xml(@response_xml) returns, which should be
+  # an object or array of objects (an array of objects if response_class is
+  # using Consumer::Mapping)
+  def do
+    return if defined?(self.abort?) && self.abort?
+    raise "to_xml not defined for #{self.class}" if not defined?(self.to_xml)
+    raise "url not defined for #{self.class}" if not self.url
+    raise "from_xml not defined for #{response_class}" if not defined?(response_class.from_xml)
+ 
+    @request_xml = self.to_xml_etc
+    
+    http, uri = Helper.http_from_url(self.url)
+    head = defined?(self.headers) ? self.headers : {}
+    
+    puts "\n##### Request to #{url}:\n\n#{@request_xml}\n" if $DEBUG
+    debugger if $POST_DEBUGGER
+    resp = http.post(uri.request_uri, @request_xml, head)
+    
+    if resp.response.code == "302" # moved
+      puts "\n##### Redirected to #{resp['Location']}\n" if $DEBUG
+      http, uri = Helper.http_from_url(resp['Location'])
+      resp = http.post(uri.request_uri, @request_xml, head)
+    end
+    
+    @response_xml = resp.body
+    puts "\n##### Response:\n\n#{Helper.tidy(@response_xml)}\n" if $DEBUG
+ 
+    check_request_error(@response_xml)
+ 
+    return response_class.from_xml(@response_xml)
+  end
+  
+  def self.do(args = {})
+    self.new(args).do
+  end
+  
+  # Gets called during do instead of just to_xml, and does a bit more than
+  # just return xml.
+  # 
+  # First, it calls before_to_xml if it has been defined.
+  # Then it calls check_required, then returns the results of to_xml sans
+  # empty nodes (see Helper.compact_xml).
+  # 
+  # You can set a COMPACT_XML constant to false to avoid the latter behavior,
+  # but most APIs complain when you send them empty nodes (even if the nodes
+  # were optional to begin with).
+  def to_xml_etc
+    self.before_to_xml if defined?(before_to_xml)
+    self.check_required
+    xml = self.to_xml
+    return (defined?(COMPACT_XML) && !COMPACT_XML) ? xml : Helper.compact_xml(xml)
+  end
+ 
+  # returns self.class.response_class as a constant (not a string)
+  #
+  # Raises a runtime error if self.class.response_class is nil
+  def response_class
+    ret = self.class.response_class
+    raise "Invalid response_class; see docs for naming conventions etc" if !ret
+    return Object.const_get(ret)
+  end
+ 
+  def error_paths
+    self.class.error_paths
+  end
+ 
+  def required
+    self.class.required
+  end
+ 
+  def yaml_defaults
+    self.class.yaml_defaults
+  end
+ 
+  def url
+    self.class.url
+  end
+ 
+  def defaults
+    self.class.defaults
+  end
+  
+  def config_root
+    if defined?(RAILS_ROOT)
+      RAILS_ROOT + "/config"
+    else
+      "config"
+    end
+  end
+
+protected
+
+  # Will raise a RequiredFieldError if an attribute in self.required is nil
+  def check_required
+    return if self.required.nil?
+ 
+    self.required.each do |attribute|
+      if eval("@#{attribute}").nil?
+        raise RequiredFieldError, "#{attribute} needs to be set"
+      end
+    end
+  end
+
+private
+
+  # If the xml contains an error notification, this'll raise a
+  # RequestError with the xml error code and message as defined in
+  # the options in error_paths. Returns nil otherwise.
+  def check_request_error(xml)
+    return if !error_paths
+    return if !xml || !xml.include?('<?xml')
+ 
+    response_doc = LibXML::XML::Parser.string(xml).parse
+    error = response_doc.find_first(error_paths[:root])
+    return if error.nil? || error.empty?
+ 
+    code = error.find_first(error_paths[:code]).first.content
+    message = error.find_first(error_paths[:message]).first.content
+ 
+    raise RequestError, "Code #{code}: #{message}"
+  end
+  
+  def builder # :nodoc:
+    @builder ||= Builder::XmlMarkup.new(:target => @xml, :indent => 2)
+  end
+  alias :b :builder
+ 
+ 
+  # set instance variables based on a hash, i.e. @key = value
+  def initialize_attrs(attrs)
+    attrs.each do |attr, value|
+      self.instance_variable_set("@#{attr}", value)
+    end
+  end
+  
+  def symbolize_keys(*hashes)
+    hashes.each do |hash|
+      hash.each {|k,v| hash[k.to_sym] = v;hash.delete(k.to_s)}
+    end
+  end
+end

data/lib/consumer.rb

@@ -0,0 +1,28 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'libxml'
+require 'builder'
+
+# I just want singularize and constantize from ActiveSupport,
+# but I don't need the rest of AS
+module ActiveSupport
+  module CoreExtensions
+    module String
+      module Inflections
+      end
+    end
+  end
+end
+require 'active_support/core_ext/string/inflections'
+class String
+  include ActiveSupport::CoreExtensions::String::Inflections
+end
+
+module Consumer
+  VERSION = '0.8.1'
+end
+
+require 'consumer/mapping'
+require 'consumer/request'
+require 'consumer/helper'

data/script/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# File: script/console
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+# Perhaps use a console_lib to store any extra methods I may want available in the cosole
+# libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/consumer.rb'}"
+puts "Loading consumer gem"
+exec "#{irb} #{libs} --simple-prompt"

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)

data/script/generate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/generate'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Generate.new.run(ARGV)

data/script/txt2html

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+
+load File.dirname(__FILE__) + "/../Rakefile"
+require 'rubyforge'
+require 'redcloth'
+require 'syntax/convertors/html'
+require 'erb'
+
+download = "http://rubyforge.org/projects/#{$hoe.rubyforge_name}"
+version  = $hoe.version
+
+def rubyforge_project_id
+  RubyForge.new.configure.autoconfig["group_ids"][$hoe.rubyforge_name]
+end
+
+class Fixnum
+  def ordinal
+    # teens
+    return 'th' if (10..19).include?(self % 100)
+    # others
+    case self % 10
+    when 1: return 'st'
+    when 2: return 'nd'
+    when 3: return 'rd'
+    else    return 'th'
+    end
+  end
+end
+
+class Time
+  def pretty
+    return "#{mday}#{mday.ordinal} #{strftime('%B')} #{year}"
+  end
+end
+
+def convert_syntax(syntax, source)
+  return Syntax::Convertors::HTML.for_syntax(syntax).convert(source).gsub(%r!^<pre>|</pre>$!,'')
+end
+
+if ARGV.length >= 1
+  src, template = ARGV
+  template ||= File.join(File.dirname(__FILE__), '/../website/template.html.erb')
+else
+  puts("Usage: #{File.split($0).last} source.txt [template.html.erb] > output.html")
+  exit!
+end
+
+template = ERB.new(File.open(template).read)
+
+title = nil
+body = nil
+File.open(src) do |fsrc|
+  title_text = fsrc.readline
+  body_text_template = fsrc.read
+  body_text = ERB.new(body_text_template).result(binding)
+  syntax_items = []
+  body_text.gsub!(%r!<(pre|code)[^>]*?syntax=['"]([^'"]+)[^>]*>(.*?)</\1>!m){
+    ident = syntax_items.length
+    element, syntax, source = $1, $2, $3
+    syntax_items << "<#{element} class='syntax'>#{convert_syntax(syntax, source)}</#{element}>"
+    "syntax-temp-#{ident}"
+  }
+  title = RedCloth.new(title_text).to_html.gsub(%r!<.*?>!,'').strip
+  body = RedCloth.new(body_text).to_html
+  body.gsub!(%r!(?:<pre><code>)?syntax-temp-(\d+)(?:</code></pre>)?!){ syntax_items[$1.to_i] }
+end
+stat = File.stat(src)
+created = stat.ctime
+modified = stat.mtime
+
+$stdout << template.result(binding)

data/spec/helper_spec.rb

@@ -0,0 +1,136 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe Consumer::Helper do
+  describe "tidy" do
+    it "formats a basic newline-less glob of xml into something pretty" do
+      @dirty = "<hello><woot>hoo yeah nelly</woot></hello>"
+      @clean = <<-EOS
+<hello>
+  <woot>hoo yeah nelly</woot>
+</hello>
+EOS
+    end
+    
+    it "reformats nil nodes into <element/>" do
+      @dirty = "<hello><nil></nil><notnil>text</notnil></hello>"
+      @clean = <<-EOS
+<hello>
+  <nil/>
+  <notnil>text</notnil>
+</hello>
+EOS
+    end
+    
+    it "reformats more complex globs" do
+      @dirty = "<?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></RatedShipment></RatingServiceSelectionResponse>"
+      @clean = <<-EOS
+<?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>
+  </RatedShipment>
+</RatingServiceSelectionResponse>
+EOS
+    end
+    
+    it "reformats xml with newlines" do
+      @dirty = <<-EOS
+<?xml version="1.0"?>
+<Error><Number>-2147219490</Number><Source>Rate_Respond;SOLServerRatesTest.RateV2_Respond</Source><Description>Invalid value for origin ZIP Code.</Description><HelpFile></HelpFile><HelpContext>1000440</HelpContext></Error>
+EOS
+      @clean = <<-EOS
+<?xml version="1.0"?>
+<Error>
+  <Number>-2147219490</Number>
+  <Source>Rate_Respond;SOLServerRatesTest.RateV2_Respond</Source>
+  <Description>Invalid value for origin ZIP Code.</Description>
+  <HelpFile/>
+  <HelpContext>1000440</HelpContext>
+</Error>
+
+EOS
+    end
+    
+    after(:each) do
+      res = Consumer::Helper.tidy(@dirty) 
+      puts res if res != @clean
+      res.should == @clean
+    end
+  end
+  
+  describe "compact_xml" do
+    it "removes empty xml nodes" do
+      @dirty = "<hello><woot></woot><moogle>blah</moogle></hello>"
+      @clean = "<hello><moogle>blah</moogle></hello>"
+    end
+    
+    it "removes nodes with only empty nodes inside" do
+      @dirty = "<hello><woot></woot><moogle><still_empty></still_empty></moogle></hello>"
+      @clean = ""
+    end
+    
+    it "remove empty nodes containing whitespace characters" do
+      @dirty = "<hello>  \r \t\n</hello>"
+      @clean = ""
+    end
+    
+    after(:each) do
+      Consumer::Helper.compact_xml(@dirty).should == @clean
+    end
+  end
+  
+  describe "hash_from_yaml" do
+    it "should load a yaml file and return a hash" do
+      @yaml = <<-EOS
+      hello: world
+      EOS
+      perform
+    end
+    
+    it "should return a subsection of the yaml if given a namespace" do
+      @yaml = <<-EOS
+      greetings:
+        hello: world
+      other:
+        not: relevant
+      EOS
+      @namespace = "greetings"
+      perform
+    end
+    
+    it "should return {} if no hash" do
+      @yaml = ""
+      @namespace = "greetings"
+      perform({})
+    end
+    
+    it "should have 'all' as a global namespace" do
+      @yaml = <<-EOS
+      all:
+        answer: 42
+      greetings:
+        hello: world
+      other:
+        not: relevant
+      EOS
+      @namespace = "greetings"
+      perform({"hello" => "world", "answer" => 42})
+    end
+
+    def perform(result = {"hello" => "world"})
+      File.should_receive(:read).with("config/file.yml").and_return(@yaml)
+      Consumer::Helper.hash_from_yaml("config", "file.yml", @namespace).should == result
+    end
+    
+  end
+end

data/spec/mapping_spec.rb

@@ -0,0 +1,94 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+class MockObject
+  include Consumer::Mapping
+  attr_accessor :price, :integers
+end
+
+describe Consumer::Mapping do
+  before(:each) do
+    # since maps are defined on the class and we want to test variations
+    # on the same map, let's clear it before each spec
+    MockObject.instance_variable_set("@maps", [])
+  end
+  
+  describe "find_nodes_and_map" do
+    it "finds the correct map for the xml" do
+      xml = File.read("spec/xml/rate_response.xml")
+      map = MockObject.map(:first, "//CrazyCarrierRateResponse/ShipService",{})
+      not_the_map = MockObject.map(:first, "//NotTheMapping/ShipService", {})
+      MockObject.send(:find_nodes_and_map, xml)[1].should == map
+    end
+  end
+  
+  it "creates an attribute hash given a node and a map registry" do
+    xml = File.read("spec/xml/rate_response.xml")
+    node = LibXML::XML::Parser.string(xml).parse.find("//ShipService").first
+    registry = {:price => "Cost"}
+    attrs = MockObject.send(:attrs_from_node_and_registry, node, registry)
+    attrs.should == {:price => "5.00"}
+  end
+  
+  it "creates a new instance from an attribute hash" do
+    attrs = {:price => "5.00"}
+    object = MockObject.from_hash(attrs)
+    object.price.should == "5.00"
+  end
+  
+  it "creates instances from xml via the appropriate map" do
+    xml = <<-EOF
+    <CarrierResponse>
+      <ShipService>
+        <Cost>5.00</Cost>
+      </ShipService>
+    </CarrierResponse>
+    EOF
+    MockObject.map(:first, "//CarrierResponse/ShipService",{:price => "Cost"})
+    object = MockObject.from_xml_via_map(xml)
+    object.price.should == "5.00"
+  end
+  
+  it "raises an error if you try to define the same map root twice" do
+    MockObject.map(:first, "//CarrierResponse",{:something => "woot"})
+
+    lambda {
+      MockObject.map(:first, "//CarrierResponse",{:another => "AAA"})
+    }.should raise_error
+  end
+  
+  it "calls map blocks" do
+    MockObject.map(:first, "//empty", {}) {|instance| instance.price = "5"}
+    object = MockObject.from_xml_via_map("<empty></empty>")
+    object.price.should == "5"
+  end
+
+  it "calls map blocks with node also" do
+    MockObject.map(:first, "//empty", {}) {|instance, node| instance.price = node.find_first("//empty").content}
+    object = MockObject.from_xml_via_map("<empty>5</empty>")
+    object.price.should == "5"
+  end
+  
+  describe "association_from_xml" do
+    it "creates an association from xml" do
+      object = MockObject.new
+      Integer.should_receive(:from_xml).with("some xml").and_return([1,2])
+      object.should_receive("integers=").with([1,2])
+      object.association_from_xml("some xml", :integers)
+    end
+  end
+  
+  describe "registry" do
+    it "accepts attributs as values" do
+      xml = <<-EOF
+      <CarrierResponse>
+        <ShipService cost="5.00">
+          Irrelevant value in content
+        </ShipService>
+      </CarrierResponse>
+      EOF
+      MockObject.map(:first, "//CarrierResponse/ShipService",{:price => "attribute::cost"})
+      object = MockObject.from_xml_via_map(xml)
+      object.price.should == "5.00"
+    end
+  end
+end