mysmallidea-address_standardization 0.4.1

data/.gitignore

@@ -0,0 +1,3 @@
+.svn
+.DS_Store
+*.gem

data/README.md

@@ -0,0 +1,95 @@
+# address_standardization
+
+## Summary
+
+A tiny Ruby library to quickly standardize a postal address, either through MelissaData or Google Maps.
+
+## Installation
+
+If you are using Rails, put this in your environment.rb:
+
+    config.gem 'address_standardization'
+
+Then run `rake gems:install` to install the gem.
+
+Otherwise, just run
+
+    gem install address_standardization
+
+## Usage
+
+Right now this library supports two services: MelissaData and Google Maps.
+
+MelissaData provides two services itself: [US address lookup](http://www.melissadata.com/lookups/AddressVerify.asp) and [Canadian address lookup](http://www.melissadata.com/lookups/CanadianAddressVerify.asp). They both work the same way, however. First, here's how to standardize a US address:
+
+    addr = AddressStandardization::MelissaData.standardize_address(
+      :street => "1 Infinite Loop",
+      :city => "Cupertino",
+      :state => "CA"
+    )
+  
+This submits the address to MelissaData. If the address can't be found, you'll get back `nil`. But if the address can be found (as in this case), you'll get an instance of `AddressStandardization::Address`. If you store the instance, you can refer to the individual fields like so:
+
+    addr.street  #=> "1 INFINITE LOOP"
+    addr.city    #=> "CUPERTINO"
+    addr.state   #=> "CA"
+    addr.zip     #=> "95014-2083"
+    addr.country #=> "USA"
+
+And standardizing a Canadian address:
+
+    addr = AddressStandardization::MelissaData.standardize_address(
+      :street => "103 Metig St",
+      :city => "Sault Ste Marie",
+      :province => "ON",
+      :country => "Canada"
+    )
+    addr.street      #=> "103 METIG ST RR 4"
+    addr.city        #=> "SAULT STE MARIE"
+    addr.province    #=> "ON"
+    addr.postalcode  #=> "P6A 5K9"
+    addr.country     #=> "CANADA"
+
+Note that when standardizing a Canadian address, the `:country` must be "Canada" (or "CANADA", or anything like that). Otherwise it will be treated as a US address.
+
+Also note that I'm referring to the address's province as `province`, but you can also use `state` if you like. Same goes for the postal code -- you can also refer to it as `zip`.
+
+Using Google Maps to validate an address is just as easy:
+
+    addr = AddressStandardization::GoogleMaps.standardize_address(
+      :street => "1600 Amphitheatre Parkway",
+      :city => "Mountain View",
+      :state => "CA"
+    )
+    addr.street     #=> "1600 AMPHITHEATRE PKWY"
+    addr.city       #=> "MOUNTAIN VIEW"
+    addr.state      #=> "CA"
+    addr.zip        #=> "94043"
+    addr.country    #=> "USA"
+  
+And, again, a Canadian address:
+
+    addr = AddressStandardization::GoogleMaps.standardize_address(
+      :street => "1770 Stenson Blvd.",
+      :city => "Peterborough",
+      :province => "ON"
+    )
+    addr.street      #=> "1770 STENSON BLVD"
+    addr.city        #=> "PETERBOROUGH"
+    addr.province    #=> "ON"
+    addr.postalcode  #=> "K9K"
+    addr.country     #=> "CANADA"
+
+Sharp eyes will notice that the Google Maps API doesn't return the full postal code for Canadian addresses. If you know why this is please let me know (my email address is below).
+
+## Support
+
+If you find any bugs with this plugin, feel free to:
+
+* file a bug report in the [Issues area on Github](http://github.com/mcmire/address_standardization/issues)
+* fork the [project on Github](http://github.com/mcmire/address_standardization) and send me a pull request
+* email me (*firstname* dot *lastname* at gmail dot com)
+
+## Author/License
+
+(c) 2008-2010 Elliot Winkler. Released under the MIT license.

data/Rakefile

@@ -0,0 +1,58 @@
+require 'rubygems'
+require 'rake'
+
+require File.dirname(__FILE__) + "/lib/address_standardization/version.rb"
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.version = AddressStandardization::VERSION
+    gem.name = "address_standardization"
+    gem.summary = %Q{A tiny Ruby library to quickly standardize a postal address}
+    gem.description = %Q{A tiny Ruby library to quickly standardize a postal address}
+    gem.authors = ["Elliot Winkler"]
+    gem.email = "elliot.winkler@gmail.com"
+    gem.homepage = "http://github.com/mcmire/address_standardization"
+    gem.add_dependency "mechanize"
+    gem.add_development_dependency "mcmire-context"
+    gem.add_development_dependency "mcmire-matchy"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => [:"check_dependencies:development", :check_dependencies]
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "address_standardization #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO

@@ -0,0 +1 @@
+* MelissaData will let us know if there are other residents in the building that the address points to and thus whether to supply the suite number -- tap into this

data/address_standardization.gemspec

@@ -0,0 +1,67 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{mysmallidea-address_standardization}
+  s.version = "0.4.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Elliot Winkler"]
+  s.date = %q{2010-02-01}
+  s.description = %q{A tiny Ruby library to quickly standardize a postal address}
+  s.email = %q{elliot.winkler@gmail.com}
+  s.extra_rdoc_files = [
+    "README.md",
+     "TODO"
+  ]
+  s.files = [
+    ".gitignore",
+     "README.md",
+     "Rakefile",
+     "TODO",
+     "address_standardization.gemspec",
+     "lib/address_standardization.rb",
+     "lib/address_standardization/abstract_service.rb",
+     "lib/address_standardization/address.rb",
+     "lib/address_standardization/class_level_inheritable_attributes.rb",
+     "lib/address_standardization/google_maps.rb",
+     "lib/address_standardization/melissa_data.rb",
+     "lib/address_standardization/ruby_ext.rb",
+     "lib/address_standardization/version.rb",
+     "test/google_maps_test.rb",
+     "test/melissa_data_test.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/mcmire/address_standardization}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{A tiny Ruby library to quickly standardize a postal address}
+  s.test_files = [
+    "test/google_maps_test.rb",
+     "test/melissa_data_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<mechanize>, [">= 0"])
+      s.add_development_dependency(%q<mcmire-context>, [">= 0"])
+      s.add_development_dependency(%q<mcmire-matchy>, [">= 0"])
+    else
+      s.add_dependency(%q<mechanize>, [">= 0"])
+      s.add_dependency(%q<mcmire-context>, [">= 0"])
+      s.add_dependency(%q<mcmire-matchy>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<mechanize>, [">= 0"])
+    s.add_dependency(%q<mcmire-context>, [">= 0"])
+    s.add_dependency(%q<mcmire-matchy>, [">= 0"])
+  end
+end
+

data/lib/address_standardization.rb

@@ -0,0 +1,28 @@
+# address_standardization: A tiny Ruby library to quickly standardize a postal address.
+# Copyright (C) 2008-2010 Elliot Winkler. Released under the MIT license.
+
+require 'mechanize'
+
+require 'address_standardization/ruby_ext'
+require 'address_standardization/class_level_inheritable_attributes'
+        
+require 'address_standardization/address'
+require 'address_standardization/abstract_service'
+require 'address_standardization/melissa_data'
+require 'address_standardization/google_maps'
+
+module AddressStandardization
+  class << self
+    attr_accessor :test_mode
+    alias_method :test_mode?, :test_mode
+    
+    attr_accessor :debug_mode
+    alias_method :debug_mode?, :debug_mode
+    
+    def debug(*args)
+      puts(*args) if debug_mode?
+    end
+  end
+  self.test_mode = false
+  self.debug_mode = $DEBUG || ENV["DEBUG"] || false
+end

data/lib/address_standardization/abstract_service.rb

@@ -0,0 +1,31 @@
+module AddressStandardization
+  class AbstractService
+    extend ClassLevelInheritableAttributes
+    cattr_inheritable :canned_response
+    self.canned_response = :success
+    
+    class << self
+      def standardize_address(address_info)
+        if AddressStandardization.test_mode?
+          get_canned_response(address_info)
+        else
+          get_live_response(address_info)
+        end
+      end
+      
+      def with_canned_response(response, &block)
+        old_response = self.canned_response
+        self.canned_response = response
+        ret = yield
+        self.canned_response = old_response
+        ret
+      end
+      
+    protected
+      def get_canned_response(address_info)
+        response = (self.canned_response ||= :success)
+        response == :success ? Address.new(address_info) : nil
+      end
+    end
+  end
+end

data/lib/address_standardization/address.rb

@@ -0,0 +1,57 @@
+# TODO: Rename to address.rb
+
+module AddressStandardization
+  class StandardizationError < StandardError; end
+  
+  class Address
+    class << self
+      attr_accessor :valid_keys
+    end
+    self.valid_keys = %w(street city state province zip postalcode country)
+    
+    attr_reader :address_info
+  
+    def initialize(address_info)
+      raise NotImplementedError, "You must define valid_keys" unless self.class.valid_keys
+      raise ArgumentError, "No address given!" if address_info.empty?
+      address_info = address_info.stringify_keys
+      validate_keys(address_info)
+      standardize_values!(address_info)
+      @address_info = address_info
+    end
+  
+    def validate_keys(hash)
+      # assume keys are already stringified
+      invalid_keys = hash.keys - self.class.valid_keys
+      unless invalid_keys.empty?
+        raise ArgumentError, "Invalid keys: #{invalid_keys.join(', ')}. Valid keys are: #{self.class.valid_keys.join(', ')}"
+      end
+    end
+  
+    def method_missing(name, *args)
+      name = name.to_s
+      if self.class.valid_keys.include?(name)
+        if args.empty?
+          @address_info[name]
+        else
+          @address_info[name] = standardize_value(args.first)
+        end
+      else
+        super(name.to_sym, *args)
+      end
+    end
+    
+    def ==(other)
+      other.kind_of?(self.class) && @address_info == other.address_info
+    end
+    
+  private
+    def standardize_values!(hash)
+      hash.each {|k,v| hash[k] = standardize_value(v) }
+    end
+    
+    def standardize_value(value)
+      value ? value.strip_whitespace : ""
+    end
+  end
+end

data/lib/address_standardization/class_level_inheritable_attributes.rb

@@ -0,0 +1,20 @@
+# from <http://railstips.org/2008/6/13/a-class-instance-variable-update>
+module ClassLevelInheritableAttributes
+  def cattr_inheritable(*args)
+    @cattr_inheritable_attrs ||= [:cattr_inheritable_attrs]
+    @cattr_inheritable_attrs += args
+    args.each do |arg|
+      class_eval %(
+        class << self; attr_accessor :#{arg} end
+      )
+    end
+    @cattr_inheritable_attrs
+  end
+
+  def inherited(subclass)
+    @cattr_inheritable_attrs.each do |inheritable_attribute|
+      instance_var = "@#{inheritable_attribute}" 
+      subclass.instance_variable_set(instance_var, instance_variable_get(instance_var))
+    end
+  end
+end

data/lib/address_standardization/google_maps.rb

@@ -0,0 +1,54 @@
+module AddressStandardization
+  # See <http://code.google.com/apis/maps/documentation/geocoding/>
+  class GoogleMaps < AbstractService
+    class << self
+      attr_accessor :api_key
+    
+    protected
+      # much of this code was borrowed from GeoKit, thanks...
+      def get_live_response(address_info)
+        raise "API key not specified.\nCall AddressStandardization::GoogleMaps.api_key = '...' before you call .standardize()." unless GoogleMaps.api_key
+        
+        address_info = address_info.stringify_keys
+        
+        address_str = [
+          address_info["street"],
+          address_info["city"],
+          (address_info["state"] || address_info["province"]),
+          address_info["zip"]
+        ].join(" ")
+        url = "http://maps.google.com/maps/geo?q=#{address_str.url_escape}&output=xml&key=#{GoogleMaps.api_key}&oe=utf-8"
+        AddressStandardization.debug "[GoogleMaps] Hitting URL: #{url}"
+        uri = URI.parse(url)
+        res = Net::HTTP.get_response(uri)
+        return unless res.is_a?(Net::HTTPSuccess)
+        
+        content = res.body
+        AddressStandardization.debug "[GoogleMaps] Response body:"
+        AddressStandardization.debug "--------------------------------------------------"
+        AddressStandardization.debug content
+        AddressStandardization.debug "--------------------------------------------------"
+        xml = Nokogiri::XML(content)
+        xml.remove_namespaces! # good or bad? I say good.
+        return unless xml.at("/kml/Response/Status/code").inner_text == "200"
+        
+        addr = {}
+        
+        addr[:street]   = get_inner_text(xml, '//ThoroughfareName').to_s
+        addr[:city]     = get_inner_text(xml, '//LocalityName').to_s
+        addr[:province] = addr[:state] = get_inner_text(xml, '//AdministrativeAreaName').to_s
+        addr[:zip]      = addr[:postalcode] = get_inner_text(xml, '//PostalCodeNumber').to_s
+        addr[:country]  = get_inner_text(xml, '//CountryName').to_s
+        
+        return if addr[:street] =~ /^\s*$/ or addr[:city]  =~ /^\s*$/
+        
+        Address.new(addr)
+      end
+      
+    private
+      def get_inner_text(xml, xpath)
+        lambda {|x| x && x.inner_text.upcase }.call(xml.at(xpath))
+      end
+    end
+  end
+end

data/lib/address_standardization/melissa_data.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8
+
+module AddressStandardization
+  class MelissaData < AbstractService
+    class << self
+    protected
+      def get_live_response(address_info)
+        address_info = address_info.stringify_keys
+        
+        is_canada = (address_info["country"].to_s.upcase == "CANADA")
+        addr = Address.new(address_info)
+        
+        url = "http://www.melissadata.com/lookups/#{action(is_canada)}"
+        params = []
+        attrs_to_fields(is_canada).each do |attr, field|
+          key, val = field, address_info[attr]
+          params << "#{key}=#{val.url_escape}" if val
+        end
+        url << "?" + params.join("&")
+        url << "&FindAddress=Submit"
+        
+        #puts "URL: <#{url}>"
+        
+        attrs = {:country => (is_canada ? "CANADA" : "USA")}
+        Mechanize.new do |ua|
+          AddressStandardization.debug "[MelissaData] Hitting URL: #{url}"
+          results_page = ua.get(url)
+          AddressStandardization.debug "[MelissaData] Response body:"
+          AddressStandardization.debug "--------------------------------------------------"
+          AddressStandardization.debug results_page.body
+          AddressStandardization.debug "--------------------------------------------------"
+
+          table = results_page.search("table.Tableresultborder")[1]
+          return unless table
+          status_row = table.at("span.Titresultableok")
+          return unless status_row && status_row.inner_text =~ /Address Verified/
+          main_td = table.search("tr:eq(#{is_canada ? 2 : 3})/td:eq(2)")
+          main_td_s = main_td.inner_html
+          main_td_s.encode!("utf-8") if main_td_s.respond_to?(:encode!)
+          street_part, city_state_zip_part = main_td_s.split("<br>")[0..1]
+          street = street_part.strip_html.strip_whitespace
+          if main_td_s.respond_to?(:encode!)
+            # ruby 1.9
+            separator = city_state_zip_part.include?("&#160;&#160;") ? "&#160;&#160;" : "  "
+          else
+            # ruby 1.8
+            separator = "\240\240"
+          end
+          city, state, zip = city_state_zip_part.strip_html.split(separator)
+          attrs[:street] = street.upcase
+          attrs[:city] = city.upcase
+          attrs[:province] = attrs[:state] = state.upcase
+          attrs[:postalcode] = attrs[:zip] = zip.upcase
+        end
+        Address.new(attrs)
+      end
+      
+      def action(is_canada)
+        is_canada ? "CanadianAddressVerify.asp" : "AddressVerify.asp"
+      end
+      
+      def attrs_to_fields(is_canada)
+        if is_canada
+          {"street" => 'Street', "city" => 'city', "province" => 'Province', "postalcode" => 'Postcode'}
+        else
+          {"street" => 'Address', "city" => 'city', "state" => 'state', "zip" => 'zip'}
+        end
+      end
+    end
+  end
+end

data/lib/address_standardization/ruby_ext.rb

@@ -0,0 +1,23 @@
+class String
+  def strip_html
+    gsub(/<\/?([^>]+)>/, '')
+  end
+  def strip_newlines
+    gsub(/[\r\n]+/, '')
+  end
+  def strip_whitespace
+    strip_newlines.squeeze(" ").strip
+  end
+  
+  def url_escape
+    gsub(/([^ a-zA-Z0-9_.-]+)/n) do
+      '%' + $1.unpack('H2' * $1.size).join('%').upcase
+    end.tr(' ', '+')
+  end
+end
+
+class Hash
+  def stringify_keys
+    self.inject({}) {|h,(k,v)| h[k.to_s] = v; h }
+  end
+end

data/lib/address_standardization/version.rb

@@ -0,0 +1,3 @@
+module AddressStandardization
+  VERSION = "0.4.1"
+end

data/test/google_maps_test.rb

@@ -0,0 +1,122 @@
+require 'test_helper'
+
+AddressStandardization::GoogleMaps.api_key = "ABQIAAAALHg3jKnK9wN9K3_ArJA6TxSTZ2OgdK08l2h0_gdsozNQ-6zpaxQvIY84J7Mh1fAHQrYGI4W27qKZaw"
+
+class GoogleMapsTest < Test::Unit::TestCase
+  shared "production mode tests" do
+    test "A valid US address" do
+      addr = AddressStandardization::GoogleMaps.standardize_address(
+        "street" => "1600 Amphitheatre Parkway",
+        :city => "Mountain View",
+        :state => "CA"
+      )
+      addr.should == AddressStandardization::Address.new(
+        "street" => "1600 AMPHITHEATRE PKWY",
+        "city" => "MOUNTAIN VIEW",
+        "state" => "CA",
+        "province" => "CA",
+        "postalcode" => "94043",
+        "zip" => "94043",
+        "country" => "USA"
+      )
+    end
+  
+    test "A valid Canadian address" do
+      addr = AddressStandardization::GoogleMaps.standardize_address(
+        :street => "1770 Stenson Boulevard",
+        :city => "Peterborough",
+        "province" => "ON"
+      )
+      addr.should == AddressStandardization::Address.new(
+        "street" => "1770 STENSON BLVD",
+        "city" => "PETERBOROUGH",
+        "state" => "ON",
+        "province" => "ON",
+        "postalcode" => "K9K",
+        "zip" => "K9K",
+        "country" => "CANADA"
+      )
+    end
+  
+    test "An invalid address" do    
+      addr = AddressStandardization::GoogleMaps.standardize_address(
+        :street => "123 Imaginary Lane",
+        :city => "Some Town",
+        :state => "AK"
+      )
+      addr.should == nil
+    end
+  end
+  
+  context "With test mode explicitly false" do
+    setup do
+      AddressStandardization.test_mode = false
+    end
+    uses "production mode tests"
+  end
+  
+  context "With test mode implicitly false" do
+    setup do
+      AddressStandardization.test_mode = nil
+    end
+    uses "production mode tests"
+  end
+  
+  context "With test mode true" do
+    setup do
+      AddressStandardization.test_mode = true
+    end
+    
+    test "Valid address (before and after)" do
+      AddressStandardization::GoogleMaps.canned_response = :success
+      addr = AddressStandardization::GoogleMaps.standardize_address(
+        :street => "123 Imaginary Lane",
+        :city => "Some Town",
+        :state => "AK"
+      )
+      addr.should == AddressStandardization::Address.new(
+        :street => "123 Imaginary Lane",
+        :city => "Some Town",
+        :state => "AK"
+      )
+      AddressStandardization::GoogleMaps.canned_response = nil
+    end
+    
+    test "Valid address (block)" do
+      AddressStandardization::GoogleMaps.with_canned_response(:success) do
+        addr = AddressStandardization::GoogleMaps.standardize_address(
+          :street => "123 Imaginary Lane",
+          :city => "Some Town",
+          :state => "AK"
+        )
+        addr.should == AddressStandardization::Address.new(
+          :street => "123 Imaginary Lane",
+          :city => "Some Town",
+          :state => "AK"
+        )
+      end
+    end
+    
+    test "Invalid address (before and after)" do
+      AddressStandardization::GoogleMaps.canned_response = :failure
+      addr = AddressStandardization::GoogleMaps.standardize_address(
+        :street => "123 Imaginary Lane",
+        :city => "Some Town",
+        :state => "AK"
+      )
+      addr.should == nil
+      AddressStandardization::GoogleMaps.canned_response = nil
+    end
+    
+    test "Invalid address (block)" do
+      AddressStandardization::GoogleMaps.with_canned_response(:failure) do
+        addr = AddressStandardization::GoogleMaps.standardize_address(
+          :street => "123 Imaginary Lane",
+          :city => "Some Town",
+          :state => "AK"
+        )
+        addr.should == nil
+      end
+    end
+  end
+end

data/test/melissa_data_test.rb

@@ -0,0 +1,148 @@
+require 'test_helper'
+
+class MelissaDataTest < Test::Unit::TestCase
+  shared "production mode tests" do
+    test "Valid US address (implicit country)" do
+      addr = AddressStandardization::MelissaData.standardize_address(
+        :street => "1 Infinite Loop",
+        "city" => "Cupertino",
+        :state => "CA"
+      )
+      addr.should == AddressStandardization::Address.new(
+        "street" => "1 INFINITE LOOP",
+        "city" => "CUPERTINO",
+        "state" => "CA",
+        "province" => "CA",
+        "zip" => "95014-2083",
+        "postalcode" => "95014-2083",
+        "country" => "USA"
+      )
+    end
+  
+    test "Valid US address (explicit country)" do
+      addr = AddressStandardization::MelissaData.standardize_address(
+        :street => "1 Infinite Loop",
+        :city => "Cupertino",
+        "state" => "CA",
+        "country" => "USA"
+      )
+      addr.should == AddressStandardization::Address.new(
+        "street" => "1 INFINITE LOOP",
+        "city" => "CUPERTINO",
+        "state" => "CA",
+        "province" => "CA",
+        "zip" => "95014-2083",
+        "postalcode" => "95014-2083",
+        "country" => "USA"
+      )
+    end
+  
+    test "Invalid US address" do
+      addr = AddressStandardization::MelissaData.standardize_address(
+        :street => "123 Imaginary Lane",
+        :city => "Some Town",
+        :state => "AK"
+      )
+      addr.should == nil
+    end
+  
+    test "Valid Canadian address" do
+      addr = AddressStandardization::MelissaData.standardize_address(
+        "street" => "3025 Clayhill Rd",
+        :city => "Mississauga",
+        "province" => "ON",
+        :country => "CANADA"
+      )
+      addr.should == AddressStandardization::Address.new(
+        "street" => "3025 CLAYHILL RD",
+        "state" => "ON",
+        "province" => "ON",
+        "city" => "MISSISSAUGA",
+        "zip" => "L5B 4L2",
+        "postalcode" => "L5B 4L2",
+        "country" => "CANADA"
+      )
+    end
+  
+    test "Invalid Canadian address" do
+      addr = AddressStandardization::MelissaData.standardize_address(
+        :street => "123 Imaginary Lane",
+        :city => "Some Town",
+        :province => "BC"
+      )
+      addr.should == nil
+    end
+  end
+  
+  context "With test mode explicitly false" do
+    setup do
+      AddressStandardization.test_mode = false
+    end
+    uses "production mode tests"
+  end
+  
+  context "With test mode implicitly false" do
+    setup do
+      AddressStandardization.test_mode = nil
+    end
+    uses "production mode tests"
+  end
+  
+  context "With test mode true" do
+    setup do
+      AddressStandardization.test_mode = true
+    end
+    
+    test "Valid address (before and after)" do
+      AddressStandardization::MelissaData.canned_response = :success
+      addr = AddressStandardization::MelissaData.standardize_address(
+        :street => "123 Imaginary Lane",
+        :city => "Some Town",
+        :province => "BC"
+      )
+      addr.should == AddressStandardization::Address.new(
+        :street => "123 Imaginary Lane",
+        :city => "Some Town",
+        :province => "BC"
+      )
+      AddressStandardization::MelissaData.canned_response = nil
+    end
+    
+    test "Valid address (block)" do
+      AddressStandardization::MelissaData.with_canned_response(:success) do
+        addr = AddressStandardization::MelissaData.standardize_address(
+          :street => "123 Imaginary Lane",
+          :city => "Some Town",
+          :province => "BC"
+        )
+        addr.should == AddressStandardization::Address.new(
+          :street => "123 Imaginary Lane",
+          :city => "Some Town",
+          :province => "BC"
+        )
+      end
+    end
+    
+    test "Invalid address (before and after)" do
+      AddressStandardization::MelissaData.canned_response = :failure
+      addr = AddressStandardization::MelissaData.standardize_address(
+        :street => "123 Imaginary Lane",
+        :city => "Some Town",
+        :province => "BC"
+      )
+      addr.should == nil
+      AddressStandardization::MelissaData.canned_response = nil
+    end
+    
+    test "Invalid address (block)" do
+      AddressStandardization::MelissaData.with_canned_response(:failure) do
+        addr = AddressStandardization::MelissaData.standardize_address(
+          :street => "123 Imaginary Lane",
+          :city => "Some Town",
+          :province => "BC"
+        )
+        addr.should == nil
+      end
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,48 @@
+require 'rubygems'
+gem 'mcmire-context'
+require 'context'
+gem 'mcmire-matchy'
+require 'matchy'
+
+require 'address_standardization'
+
+module Context
+  class SharedBehavior < Module
+    # Fix this so that sharing a module twice within two sub-contexts
+    # doesn't fail with something like "'test: blah blah' is already defined"
+    def included(arg) # :nodoc:
+      arg.instance_eval(&@_behavior)
+    end
+  end
+end
+
+class << Test::Unit::TestCase
+  # Modify this so that the constant is set within the current context (and sub-contexts)
+  def shared(name, &block)
+    case name.class.name
+    when "String"
+      name = name.to_module_name
+    when "Symbol"
+      name = name.to_s.to_module_name
+    else
+      raise ArgumentError, "Provide a String or Symbol as the name of the shared behavior group"
+    end
+    const_set(name, Context::SharedBehavior.create_from_behavior(block))
+  end
+  %w(shared_behavior share_as share_behavior_as shared_examples_for).each {|m| alias_method m, :shared}
+  
+  # Modify this so that we look in the current context (and any super-contexts) for the module
+  def use(shared_name)
+    case shared_name.class.name
+    when "Context::SharedBehavior", "Module"
+      include shared_name
+    when "String"
+      include const_get(shared_name.to_module_name)
+    when "Symbol"
+      include const_get(shared_name.to_s.to_module_name)
+    else
+      raise ArgumentError, "Provide a String or Symbol as the name of the shared behavior group or the module name"
+    end
+  end
+  %w(uses it_should_behave_like behaves_like uses_examples_from).each {|m| alias_method m, :use}
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification 
+name: mysmallidea-address_standardization
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 4
+  - 1
+  version: 0.4.1
+platform: ruby
+authors: 
+- Elliot Winkler
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-01 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mechanize
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: mcmire-context
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: mcmire-matchy
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: A tiny Ruby library to quickly standardize a postal address
+email: elliot.winkler@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+- TODO
+files: 
+- .gitignore
+- README.md
+- Rakefile
+- TODO
+- address_standardization.gemspec
+- lib/address_standardization.rb
+- lib/address_standardization/abstract_service.rb
+- lib/address_standardization/address.rb
+- lib/address_standardization/class_level_inheritable_attributes.rb
+- lib/address_standardization/google_maps.rb
+- lib/address_standardization/melissa_data.rb
+- lib/address_standardization/ruby_ext.rb
+- lib/address_standardization/version.rb
+- test/google_maps_test.rb
+- test/melissa_data_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/mcmire/address_standardization
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A tiny Ruby library to quickly standardize a postal address
+test_files: 
+- test/google_maps_test.rb
+- test/melissa_data_test.rb
+- test/test_helper.rb