heycarsten-postalcoder 0.1.3

data/README.rdoc

@@ -0,0 +1,7 @@
+= PostalCoder
+
+Instead of letting postal codes turn me into a postal coder, I made this gem!
+
+== Copyright
+
+Copyright (C) 2009 Carsten Nielsen. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,58 @@
+require 'rubygems'
+require 'rake'
+
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |g|
+    g.name = 'postalcoder'
+    g.summary = 'A library for geocoding postal codes via the Google Maps ' \
+      'Geocoding API with a persisted cache through Tokyo Tyrant'
+    g.email = 'heycarsten@gmail.com'
+    g.homepage = 'http://github.com/heycarsten/postalcoder'
+    g.authors = ['Carsten Nielsen']
+  end
+rescue LoadError
+  puts 'Jeweler not available. Install it with: sudo gem install ' \
+    'technicalpickles-jeweler -s http://gems.github.com'
+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 :default => :test
+
+# require 'rake/rdoctask'
+# Rake::RDocTask.new do |rdoc|
+#   if File.exist?('VERSION.yml')
+#     config = YAML.load(File.read('VERSION.yml'))
+#     version = [config[:major], config[:minor], config[:patch]].join('.')
+#   else
+#     version = ''
+#   end
+#   rdoc.rdoc_dir = 'rdoc'
+#   rdoc.title = "PostalCoder #{version}"
+#   rdoc.rdoc_files.include('README*')
+#   rdoc.rdoc_files.include('lib/**/*.rb')
+# end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 1
+:patch: 3
+:major: 0

data/lib/postalcoder/config.rb

@@ -0,0 +1,25 @@
+module PostalCoder
+  module Config
+
+    # If :tt_port is 0 then :tt_host should point to a Unix socket.
+    @default_settings = {
+      :gmaps_api_key => nil,
+      :gmaps_api_timeout => 2,
+      :tt_host => nil,
+      :tt_port => 0,
+      :accepted_formats => [:ca_postal_code, :us_zip_code] }
+
+    def self.merge(overrides)
+      @default_settings.merge(overrides)
+    end
+
+    def self.update(hsh)
+      @default_settings.update(hsh)
+    end
+
+    def self.[](key)
+      @default_settings[key]
+    end
+
+  end
+end

data/lib/postalcoder/formats.rb

@@ -0,0 +1,120 @@
+module PostalCoder
+  module Formats
+
+    SYMBOLS_TO_NAMES_MAP = {
+      :ca_postal_code => 'CAPostalCode',
+      :us_zip_code => 'USZipCode' }
+
+    def self.symbol_to_class(symbol)
+      unless symbol.is_a?(Symbol)
+        raise ArgumentError, "expected Symbol, not: #{symbol.class}"
+      end
+      class_name = SYMBOLS_TO_NAMES_MAP.fetch(symbol) do |sym|
+        raise Errors::UnknownFormatSymbolError, 'The format symbol ' \
+        "#{sym.inspect} is not one of the reconized symbols, which are: " \
+        "#{SYMBOLS_TO_NAMES_MAP.keys.inspect}"
+      end
+      eval class_name
+    end
+
+    def self.symbols_to_classes(symbols)
+      unless symbols.is_a?(Array)
+        raise ArgumentError, "symbols must be Array, not: #{symbols.class}"
+      end
+      if symbols.empty?
+        raise ArgumentError, 'symbols must contain format symbols, it is empty.'
+      end
+      symbols.map { |f| symbol_to_class(f) }
+    end
+
+    def self.instantiate(postal_code, format_symbol = nil)
+      unless postal_code.is_a?(String)
+        raise Errors::MalformedPostalCodeError, 'postal_code must be a ' \
+        "String, not: #{postal_code.class}"
+      end
+      if format_symbol
+        symbol_to_class(format_symbol).new(postal_code)
+      else
+        auto_instantiate(postal_code)
+      end
+    end
+
+    def self.auto_instantiate(postal_code, accepted_formats = Config[:accepted_formats])
+      results = symbols_to_classes(accepted_formats).map do |format|
+        begin
+          format.new(postal_code)
+        rescue Errors::MalformedPostalCodeError
+          nil
+        end
+      end.compact
+      return results[0] if results.any?
+      raise Errors::MalformedPostalCodeError, "The postal code: #{postal_code}" \
+      ' did not properly map to any of the accepted formats.'
+    end
+
+
+    class AbstractFormat
+
+      attr_reader :value
+
+      def initialize(raw_value)
+        unless raw_value.is_a?(String)
+          raise ArgumentError, "value must be String, not: #{raw_value.class}"
+        end
+        @value = cleanup(raw_value)
+        validate_form!
+      end
+
+      def to_s
+        value
+      end
+
+      def cleanup(raw_value)
+        raw_value.upcase.gsub(/\s|\-/, '')
+      end
+
+      def has_valid_form?
+        raise NotImplementedError, "#{self.class}#has_valid_form? must be " \
+        'implemented.'
+      end
+
+      protected
+
+      def validate_form!
+        return true if has_valid_form?
+        raise Errors::MalformedPostalCodeError, "#{@value.inspect} is not a " \
+        "properly formed #{self.class}"
+      end
+
+    end
+
+
+    class CAPostalCode < AbstractFormat
+
+      def has_valid_form?
+        value =~ /\A([A-Z][0-9]){3}\Z/
+      end
+
+    end
+
+
+    class USZipCode < AbstractFormat
+
+      def to_s
+        case value.length
+        when 5
+          value
+        when 9
+          "#{value[0,5]}-#{value[5,4]}"
+        end
+      end
+
+      def has_valid_form?
+        value =~ /\A([0-9]{5}|[0-9]{9})\Z/
+      end
+
+    end
+
+
+  end
+end

data/lib/postalcoder/geocoding_api.rb

@@ -0,0 +1,121 @@
+module PostalCoder
+  module GeocodingAPI
+
+    BASE_URI = 'http://maps.google.com/maps/geo'
+    BASE_PARAMS = {
+      :q => nil,
+      :output => 'json',
+      :oe => 'utf8',
+      :sensor => 'false',
+      :key => nil }
+
+
+    class Query
+
+      attr_reader :query
+
+      def self.get(query, options = {})
+        new(query, options).to_hash
+      end
+
+      def initialize(query, options = {})
+        unless query.is_a?(String)
+          raise ArgumentError, "query must be a String, not: #{query.class}"
+        end
+        @config = Config.merge(options)
+        @query = query
+        validate_state!
+      end
+
+      def to_hash
+        return tidy_response if @response
+        parse_json_response(http_get)
+      end
+
+      def params
+        BASE_PARAMS.merge(:key => @config[:gmaps_api_key], :q => query)
+      end
+
+      def to_params
+        # No need to escape the keys and values because (so far) they do not
+        # contain escapable characters. -- CKN
+        params.inject([]) { |a, (k, v)| a << "#{k}=#{v}" }.join('&')
+      end
+
+      def uri
+        [BASE_URI, '?', to_params].join
+      end
+
+      protected
+
+      def placemark
+        @response['Placemark'][0]
+      end
+
+      def latlon_box
+        placemark['ExtendedData']['LatLonBox']
+      end
+
+      def country
+        placemark['AddressDetails']['Country']
+      end
+
+      def tidy_response
+        { :accuracy => placemark['AddressDetails']['Accuracy'],
+          :country => {
+            :name => country['CountryName'],
+            :code => country['CountryNameCode'],
+            :administrative_area => country['AdministrativeArea']['AdministrativeAreaName']
+          },
+          :point => {
+            :latitude => placemark['Point']['coordinates'][0],
+            :longitude => placemark['Point']['coordinates'][1]
+          },
+          :box => {
+            :north => latlon_box['north'],
+            :south => latlon_box['south'],
+            :east => latlon_box['east'],
+            :west => latlon_box['west']
+        } }
+      end
+
+      def http_get
+        return @json_response if @json_response
+        Timeout.timeout(@config[:gmaps_api_timeout]) do
+          @json_response = open(uri).read
+        end
+      rescue Timeout::TimeoutError
+        raise Errors::QueryTimeoutError, 'The query timed out at ' \
+        "#{@config[:timeout]} second(s)"
+      end
+
+      def parse_json_response(json_response)
+        @response = JSON.parse(json_response)
+        case @response['Status']['code']
+        when 200
+          tidy_response
+        when 400
+          raise Errors::APIMalformedRequestError, 'The GMaps Geo API has ' \
+          'indicated that the request is not formed correctly: ' \
+          "(#{query.inspect})"
+        when 602
+          raise Errors::APIGeocodingError, 'The GMaps Geo API has indicated ' \
+          "that it is not able to geocode the request: (#{query.inspect})"
+        end
+      end
+
+      def validate_state!
+        if '' == query.strip.to_s
+          raise Errors::BlankQueryError, 'You must specifiy a query to resolve.'
+        end
+        unless @config[:gmaps_api_key]
+          raise Errors::NoAPIKeyError, 'You must provide a Google Maps API ' \
+          'key in your configuration. Go to http://code.google.com/apis/maps/' \
+          'signup.html to get one.'
+        end
+      end
+
+    end
+
+  end
+end

data/lib/postalcoder/persistence.rb

@@ -0,0 +1,62 @@
+module PostalCoder
+  module Persistence
+
+
+    class DataStore
+
+      def initialize(options = {})
+        @config = Config.merge(options)
+        unless @config[:tt_host]
+          raise ArgumentError, ':tt_host must be specified when it is not ' \
+          'present in the global configuration.'
+        end
+        @tyrant = Rufus::Tokyo::Tyrant.new(@config[:tt_host], @config[:tt_port])
+      rescue RuntimeError => boom
+        if boom.message.include?('couldn\'t connect to tyrant')
+          raise Errors::TTUnableToConnectError, 'Unable to connect to the ' \
+          "Tokyo Tyrant server at #{@config[:tt_host]} [#{@config[:tt_port]}]"
+        else
+          raise boom
+        end
+      end
+
+      def fetch(key, &block)
+        unless block_given?
+          raise ArgumentError, 'no block was given but one was expected'
+        end
+        value = storage_get(key)
+        return value if value
+        storage_put(key, block.call(key.to_s))
+      end
+
+      def [](key)
+        storage_get(key)
+      end
+
+      def []=(key, value)
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise ArgumentError, "key must be String or Symbol, not: #{key.class}"
+        end
+        storage_put(key, value)
+      end
+
+      protected
+
+      def storage_get(key)
+        value = tyrant[key.to_s]
+        value ? YAML.load(value) : nil
+      end
+
+      def storage_put(key, value)
+        tyrant[key.to_s] = YAML.dump(value)
+        value # <- We don't want to return YAML in this case.
+      end
+
+      def tyrant
+        @tyrant
+      end
+
+    end
+
+  end
+end

data/lib/postalcoder/resolver.rb

@@ -0,0 +1,16 @@
+module PostalCoder
+  class Resolver < Persistence::DataStore
+
+    def resolve(postal_code_value, format_symbol = nil)
+      postal_code = Formats.instantiate(postal_code_value, format_symbol)
+      fetch(postal_code.to_s) do |code|
+        GeocodingAPI::Query.get(code, @config)
+      end
+    end
+
+    def [](postal_code)
+      resolve(postal_code)
+    end
+
+  end
+end

data/lib/postalcoder.rb

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'rufus/tokyo/tyrant'
+require 'json'
+require 'yaml'
+require 'open-uri'
+require 'timeout'
+
+$:.unshift(File.dirname(__FILE__))
+
+require 'postalcoder/config'
+require 'postalcoder/formats'
+require 'postalcoder/geocoding_api'
+require 'postalcoder/persistence'
+require 'postalcoder/resolver'
+
+
+module PostalCoder
+
+  module Errors
+    class Error < StandardError; end
+    class MalformedPostalCodeError < Error; end
+    class BlankQueryError < Error; end
+    class QueryTimeoutError < Error; end
+    class NoAPIKeyError < Error; end
+    class APIMalformedRequestError < Error; end
+    class APIGeocodingError < Error; end
+    class TTUnableToConnectError < Error; end
+    class InvalidStorageValueError < Error; end
+    class UnknownFormatSymbolError < Error; end
+  end
+
+
+  module ProxyMethods
+    def PostalCoder.config=(hsh)
+      Config.update(hsh)
+    end
+
+    def PostalCoder.connect(options = {})
+      Resolver.new(options)
+    end
+  end
+
+end

data/test/config_test.rb

@@ -0,0 +1,37 @@
+require 'test_helper'
+
+class ConfigTest < Test::Unit::TestCase
+
+  context 'Config#merge' do
+    setup do
+      @config = PostalCoder::Config.merge(:gmaps_api_timeout => 3)
+    end
+
+    should 'return a hash of updated config settings' do
+      assert_instance_of Hash, @config
+      assert_equal 5, @config.size
+      assert_equal 3, @config[:gmaps_api_timeout]
+    end
+
+    should 'not change default configuration' do
+      assert_equal 2, PostalCoder::Config[:gmaps_api_timeout]
+    end
+  end
+
+  context 'Config#update' do
+    setup do
+      @config = PostalCoder::Config.update(:gmaps_api_timeout => 1)
+    end
+
+    should 'return a hash of updated config settings' do
+      assert_instance_of Hash, @config
+      assert_equal 5, @config.size
+      assert_equal 1, @config[:gmaps_api_timeout]
+    end
+    
+    should 'change default configuration' do
+      assert_equal 1, PostalCoder::Config[:gmaps_api_timeout]
+    end
+  end
+
+end

data/test/formats_test.rb

@@ -0,0 +1,163 @@
+require 'test_helper'
+
+class FormatsTest < Test::Unit::TestCase
+
+  context 'Formats.symbol_to_class' do
+    should 'throw an argument error unless given a symbol' do
+      assert_raise ArgumentError do
+        PostalCoder::Formats.symbol_to_class('boom!')
+      end
+    end
+
+    should 'throw an error when passed an unknown format symbol' do
+      assert_raise PostalCoder::Errors::UnknownFormatSymbolError do
+        PostalCoder::Formats.symbol_to_class(:uberfail)
+      end
+    end
+
+    should 'return the appropriate class when passed the proper symbol' do
+      assert_equal PostalCoder::Formats::CAPostalCode,
+        PostalCoder::Formats.symbol_to_class(:ca_postal_code)
+    end
+  end
+
+  context 'Formats.symbols_to_classes' do
+    should 'throw an argument error unless passed an array' do
+      assert_raise ArgumentError do
+        PostalCoder::Formats.symbols_to_classes(nil)
+      end
+    end
+
+    should 'throw an argument error if passed an empty array' do
+      assert_raise ArgumentError do
+        PostalCoder::Formats.symbols_to_classes([])
+      end
+    end
+
+    should 'return the appropriate classes when passed proper symbols' do
+      assert_equal [PostalCoder::Formats::CAPostalCode],
+        PostalCoder::Formats.symbols_to_classes([:ca_postal_code])
+    end
+  end
+
+  context 'Formats.auto_instantiate' do
+    should 'raise a malformed postal code error if no accepted formats match the input' do
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        PostalCoder::Formats.auto_instantiate('failtron')
+      end
+    end
+
+    should 'return the first matching instance' do
+      assert_instance_of PostalCoder::Formats::USZipCode,
+        PostalCoder::Formats.auto_instantiate('20037')
+    end
+  end
+
+  context 'Formats.instantiate' do
+    should 'raise an error if passed nil as a postal code' do
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        PostalCoder::Formats.instantiate(nil)
+      end
+    end
+
+    should 'auto instantiate to the first matching accepted format if no format is specified' do
+      assert_instance_of PostalCoder::Formats::CAPostalCode,
+        PostalCoder::Formats.instantiate('m6r2g5')
+    end
+
+    should 'return true if passed a postal code that matches at least one of the accepted formats' do
+      assert_instance_of PostalCoder::Formats::CAPostalCode,
+        PostalCoder::Formats.instantiate('m6r2g5', :ca_postal_code)
+    end
+  end
+
+  context 'Creating an instance of AbstractFormat' do
+    should 'throw a not implemented error' do
+      assert_raise NotImplementedError do
+        PostalCoder::Formats::AbstractFormat.new('test')
+      end
+    end
+  end
+
+  context 'Creating an instance of USZipCode' do
+    should 'fail with the wrong type' do
+      assert_raise ArgumentError do
+        PostalCoder::Formats::USZipCode.new(nil)
+      end
+      assert_raise ArgumentError do
+        PostalCoder::Formats::USZipCode.new(20037)
+      end
+    end
+
+    should 'fail with a string of the wrong format' do
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        PostalCoder::Formats::USZipCode.new('2003')
+      end
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        PostalCoder::Formats::USZipCode.new('20037-8')
+      end
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        PostalCoder::Formats::USZipCode.new('')
+      end
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        PostalCoder::Formats::USZipCode.new('BOOM7-8001')
+      end
+    end
+
+    should 'work with whitespace present' do
+      assert PostalCoder::Formats::USZipCode.new(' 200 37   ')
+    end
+
+    should 'allow ZIP+4 with or without a dash' do
+      assert PostalCoder::Formats::USZipCode.new('20037-8001')
+      assert PostalCoder::Formats::USZipCode.new('20037 8001')
+      assert PostalCoder::Formats::USZipCode.new('200378001')
+    end
+  end
+
+  context 'An instance of USZipCode for ZIP+4 address' do
+    setup do
+      @zip = PostalCoder::Formats::USZipCode.new(' 20037 8001 ')
+    end
+
+    should 'reformat the value to include a dash' do
+      assert_equal '20037-8001', @zip.to_s
+    end
+  end
+
+  context 'Creating an instance of CAPostalCode' do
+    should 'fail with the wrong type' do
+      assert_raise ArgumentError do
+        PostalCoder::Formats::CAPostalCode.new(123456)
+      end
+      assert_raise ArgumentError do
+        PostalCoder::Formats::CAPostalCode.new(nil)
+      end
+    end
+
+    should 'fail with a string of the wrong format' do
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        PostalCoder::Formats::CAPostalCode.new('M6R')
+      end
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        PostalCoder::Formats::CAPostalCode.new('')
+      end
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        PostalCoder::Formats::CAPostalCode.new('M6R2G5A1')
+      end
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        PostalCoder::Formats::CAPostalCode.new('M6R205')
+      end
+    end
+
+    should 'work with whitespace present' do
+      assert PostalCoder::Formats::CAPostalCode.new('   M6R2G5 ')
+      assert PostalCoder::Formats::CAPostalCode.new('   M6R 2G5 ')
+    end
+
+    should 'upcase any lowercase characters' do
+      assert_equal 'M6R2G5', PostalCoder::Formats::CAPostalCode.new('m6r2g5').to_s
+    end
+  end
+
+end

data/test/geocoding_api_test.rb

@@ -0,0 +1,73 @@
+require 'test_helper'
+
+
+class GeocodingAPITest < Test::Unit::TestCase
+
+  context 'initialize with incorrect arguments' do
+    should 'fail with no arguments' do
+      assert_raise ArgumentError do
+        PostalCoder::GeocodingAPI::Query.new
+      end
+    end
+
+    should 'fail with any argument other than a string' do
+      assert_raise ArgumentError do
+        PostalCoder::GeocodingAPI::Query.new(nil)
+      end
+      assert_raise ArgumentError do
+        PostalCoder::GeocodingAPI::Query.new(0)
+      end
+    end
+
+    should 'fail when passed a blank string as an argument' do
+      assert_raise PostalCoder::Errors::BlankQueryError do
+        PostalCoder::GeocodingAPI::Query.new('         ')
+      end
+    end
+  end
+
+  context 'initialize with no API key present' do
+    should 'fall down, go boom' do
+      assert_raise PostalCoder::Errors::NoAPIKeyError do
+        PostalCoder::GeocodingAPI::Query.new('M6R2G5')
+      end
+    end
+  end
+
+  context 'query with correct arguments' do
+    setup do
+      @zip = PostalCoder::GeocodingAPI::Query.new('M6R2G5',
+        :gmaps_api_key => 'apikey')
+    end
+
+    should 'return parsed and tidied JSON' do
+      @zip.expects(:http_get).returns(PAYLOADS[:json_m6r2g5])
+      assert_equal 5, @zip.to_hash[:accuracy]
+      assert_equal 'Canada', @zip.to_hash[:country][:name]
+      assert_equal 'CA', @zip.to_hash[:country][:code]
+      assert_equal 'ON', @zip.to_hash[:country][:administrative_area]
+      assert_equal -79.4449720, @zip.to_hash[:point][:latitude]
+      assert_equal 43.6504650, @zip.to_hash[:point][:longitude]
+      assert_equal 43.6536126, @zip.to_hash[:box][:north]
+      assert_equal 43.6473174, @zip.to_hash[:box][:south]
+      assert_equal -79.4418244, @zip.to_hash[:box][:east]
+      assert_equal -79.4481196, @zip.to_hash[:box][:west]
+    end
+
+    should 'raise an error when API returns malformed request' do
+      @zip.expects(:http_get).returns(PAYLOADS[:json_400])
+      assert_raise PostalCoder::Errors::APIMalformedRequestError do
+        @zip.to_hash
+      end
+    end
+
+    should 'have an appropriate URI' do
+      assert_match /output=json/, @zip.uri
+      assert_match /q=M6R2G5/, @zip.uri
+      assert_match /oe=u/, @zip.uri
+      assert_match /sensor=false/, @zip.uri
+      assert_match /key=apikey/, @zip.uri
+    end
+  end
+
+end

data/test/persistence_test.rb

@@ -0,0 +1,78 @@
+require 'test_helper'
+
+class PersistenceTest < Test::Unit::TestCase
+
+  context 'DataStore.new' do
+    should 'throw and argument error without :tt_host specified' do
+      assert_raise ArgumentError do
+        PostalCoder::Persistence::DataStore.new
+      end
+    end
+
+    should 'throw a better error if the Tokyo Tyrant connection fails' do
+      assert_raise PostalCoder::Errors::TTUnableToConnectError do
+        PostalCoder::Persistence::DataStore.new(:tt_host => '/tmp/fake')
+      end
+    end
+  end
+
+  context 'DataStore' do
+    setup do
+      Rufus::Tokyo::Tyrant.stubs(:new).returns({})
+      @db = PostalCoder::Persistence::DataStore.new(:tt_host => '/tmp/tttest')
+    end
+
+    context '#fetch' do
+      should 'raise an error without any block specified' do
+        assert_raise ArgumentError do
+          @db.fetch(:stuff)
+        end
+      end
+
+      should 'get a value that exists' do
+        @db[:test_key] = 'test_value'
+        assert_equal 'test_value', @db.fetch(:test_key) { raise 'ultrafail' }
+      end
+
+      should 'set the value to whatever the block yields if value is nil' do
+        @db.fetch(:test_key) { 'block_value' }
+        assert_equal 'block_value', @db[:test_key]
+      end
+    end
+
+    context '#[]=' do
+      should 'now allow numbers or nil as a key' do
+        assert_raise ArgumentError do
+          @db[nil] = 'extreme fail'
+        end
+        assert_raise ArgumentError do
+          @db[23] = 'massive fail'
+        end
+      end
+    end
+
+    context '#[]' do
+      should 'return nil for a key that does not exist' do
+        assert_nil @db['nope']
+        assert_nil @db['']
+        assert_nil @db[0]
+        assert_nil @db[nil]
+      end
+
+      should 'alow retrieval of nil' do
+        @db[:nil_key] = nil
+        assert_nil @db[:nil_key]
+      end
+
+      should 'return parsed JSON for keys that do exist' do
+        @db[:payload_1] = PAYLOADS[:test_string]
+        @db[:payload_2] = PAYLOADS[:test_hash]
+        @db[:payload_3] = PAYLOADS[:test_array]
+        assert_equal PAYLOADS[:test_string], @db[:payload_1]
+        assert_equal PAYLOADS[:test_hash], @db[:payload_2]
+        assert_equal PAYLOADS[:test_array], @db[:payload_3]
+      end
+    end
+  end
+
+end

data/test/postalcoder_test.rb

@@ -0,0 +1,26 @@
+require 'test_helper'
+
+class PostalCoderTest < Test::Unit::TestCase
+
+  context 'ProxyMethods' do
+    should 'be present in PostalCoder module' do
+      assert_respond_to PostalCoder, :config=
+      assert_respond_to PostalCoder, :connect
+    end
+
+    context 'PostalCoder.config=' do
+      should 'proxy to Config.update' do
+        PostalCoder::Config.expects(:update).with({})
+        assert PostalCoder.config = {}
+      end
+    end
+
+    context 'PostalCoder.connect' do
+      should 'proxy to Resolver.new' do
+        PostalCoder::Resolver.expects(:new).with({}).returns(:it_works)
+        assert_equal :it_works, PostalCoder.connect
+      end
+    end
+  end
+
+end

data/test/resolver_test.rb

@@ -0,0 +1,42 @@
+require 'test_helper'
+
+class ResolverTest < Test::Unit::TestCase
+
+  context 'Resolver' do
+    setup do
+      Rufus::Tokyo::Tyrant.stubs(:new).returns({})
+      @db = PostalCoder::Resolver.new(:tt_host => '/tmp/tttest', :gmaps_api_key => 'testkey')
+    end
+
+    should 'return a hash of information for a new address' do
+      PostalCoder::GeocodingAPI::Query.any_instance.
+        expects(:http_get).returns(PAYLOADS[:json_m6r2g5])
+      assert_instance_of Hash, @db.resolve('m6r2g5')
+    end
+
+    should 'not call api when a cached postal code is called' do
+      assert_instance_of Hash, @db.resolve('m6r2g5')
+    end
+
+    should 'store the postal code key in the correct format' do
+      assert_instance_of Hash, @db.resolve('M6R2G5')
+    end
+
+    should 'allow [] to resolve with auto-instantiation' do
+      assert_instance_of Hash, @db['M6R2G5']
+    end
+
+    should 'raise malformed postal code error for a malformed postal code' do
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        @db.resolve('m6r212')
+      end
+    end
+
+    should 'raise malformed postal code error for a nil postal code' do
+      assert_raise PostalCoder::Errors::MalformedPostalCodeError do
+        @db.resolve(nil)
+      end
+    end
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,58 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$:.unshift(File.dirname(__FILE__))
+require 'postalcoder'
+
+class Test::Unit::TestCase
+
+  PAYLOADS = {
+    :json_m6r2g5 => %q<
+{
+"name": "M6R2G5",
+"Status": {
+  "code": 200,
+  "request": "geocode"
+},
+"Placemark": [ {
+  "id": "p1",
+  "address": "Ontario M6R 2G5, Canada",
+  "AddressDetails": {"Country": {"CountryNameCode": "CA","CountryName": "Canada","AdministrativeArea": {"AdministrativeAreaName": "ON","PostalCode": {"PostalCodeNumber": "M6R 2G5"}}},"Accuracy": 5},
+  "ExtendedData": {
+    "LatLonBox": {
+      "north": 43.6536126,
+      "south": 43.6473174,
+      "east": -79.4418244,
+      "west": -79.4481196
+    }
+  },
+  "Point": {
+    "coordinates": [ -79.4449720, 43.6504650, 0 ]
+  }
+} ]
+}>,
+    :json_602 => %q<
+{
+  "name": "crashbangboom",
+  "Status": {
+    "code": 602,
+    "request": "geocode"
+  }
+}>,
+    :json_400 => %q<
+{
+  "name": "",
+  "Status": {
+    "code": 400,
+    "request": "geocode"
+  }
+}>,
+    :test_string => "test\nstring",
+    :test_hash => { 'test' => 'value', 100 => 'one hundred' },
+    :test_array => ['test', 1, 3.1415, true, false, nil]
+  }
+
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: heycarsten-postalcoder
+version: !ruby/object:Gem::Version 
+  version: 0.1.3
+platform: ruby
+authors: 
+- Carsten Nielsen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-20 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: heycarsten@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- VERSION.yml
+- lib/postalcoder.rb
+- lib/postalcoder/config.rb
+- lib/postalcoder/formats.rb
+- lib/postalcoder/geocoding_api.rb
+- lib/postalcoder/persistence.rb
+- lib/postalcoder/resolver.rb
+- test/config_test.rb
+- test/formats_test.rb
+- test/geocoding_api_test.rb
+- test/persistence_test.rb
+- test/postalcoder_test.rb
+- test/resolver_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/heycarsten/postalcoder
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A library for geocoding postal codes via the Google Maps Geocoding API with a persisted cache through Tokyo Tyrant
+test_files: 
+- test/config_test.rb
+- test/formats_test.rb
+- test/geocoding_api_test.rb
+- test/persistence_test.rb
+- test/postalcoder_test.rb
+- test/resolver_test.rb
+- test/test_helper.rb