postal_code 0.0.1

data/lib/postal_code.rb

@@ -0,0 +1,78 @@
+module PostalCode
+
+  VERSION = '0.0.1'
+
+  CityOffset  = 0
+  StateOffset = 1
+  DB = File.join File.dirname(__FILE__), '..', 'db', 'us.csv'
+  FS = "\t"   # field separator
+  RS = "\n"   # record separator
+
+  @cache = {}
+
+  #
+  # Load the entire postal code database into memory.
+  #
+  def self.load_cache
+    open(DB) do |db|
+      db.each_line do |line|
+        pcode, city, state = line.rstrip.split(FS)
+        @cache[pcode] = [city, state]
+      end
+    end
+  end
+
+  #
+  # Clear the in-memory postal code cache.
+  #
+  def self.clear_cache
+    @cache.clear
+  end
+
+  #
+  # Return the city for the given postal code.
+  #
+  def self.city postal_code
+    fetch(postal_code)[CityOffset]
+  end
+
+  #
+  # Return the state (two-letter abbreviation) for the given postal code.
+  #
+  def self.state postal_code
+    fetch(postal_code)[StateOffset]
+  end
+
+  # 
+  # * All postal code parameters must be strings.
+  # * Postal codes are not calculable, therefore should not be numeric.
+  # * A postal code with a leading zero would be an octal. However, *08880* is
+  #   an invalid octal numeric, yet a valid postal code.
+  #
+  def self.valid_format? postal_code
+    postal_code =~ /^\d{5}(-\d{4})?$/
+  end
+
+  #
+  # Fetch postal code record.
+  #
+  def self.fetch postal_code
+    return [nil, nil] unless valid_format? postal_code
+    pcode = postal_code[0..4] # use first 5 characters; ignore ZIP+4 extension
+
+    if @cache.has_key? pcode
+      @cache[pcode]
+    else
+      records = %x[grep "^#{pcode}#{FS}" #{DB}].split(RS)
+
+      if records.empty?
+        [nil, nil]
+      else
+        @cache[pcode] = records.last.split(FS)[1..2]
+      end
+    end
+  end
+
+  private_class_method :fetch, :valid_format?
+
+end

data/lib/postal_code/server.rb

@@ -0,0 +1,56 @@
+#
+# Postal Code resolution service for network clients.
+#
+# Could implement a DRb and TCP/UDP server.
+#
+# Requires in user code would look like this:
+#
+#   require 'postal_code/tcpserver'
+#
+# or
+#
+#   require 'postal_code/drbserver'
+#
+
+__END__
+
+require_relative '../postal_code'
+
+# DRb
+require 'drb'
+
+$SAFE = 1   # disable eval() and friends
+URI = "druby://127.0.0.1:8787"
+
+class PostalCode::DRbServer
+
+  def initialize host, port
+  end
+
+  def postal_code code
+    # could return more than one line
+    #zip, city, state = %x[grep ^#{code} #{DB}].split("\t")
+    #Time.now
+    #"#{zip},#{city},#{state}"
+    code
+  end
+
+end
+
+DRb.start_service(URI, PCode.new)
+DRb.thread.join
+
+
+__END__
+
+# TCP
+require 'socket'
+
+server = TCPServer.new('127.0.0.1', 5100)
+loop do
+  client = server.accept
+  client.gets
+  client.puts 'Hello!'
+  client.puts "Time is #{Time.now}"
+  client.close
+end

data/postal_code.gemspec

@@ -0,0 +1,12 @@
+Gem::Specification.new('postal_code') do |s|
+  s.version     = File.read('lib/postal_code.rb')[/VERSION = '(.*)'/, 1]
+  s.author      = 'Clint Pachl'
+  s.email       = 'pachl@ecentryx.com'
+  s.homepage    = 'http://ecentryx.com/gems/postal_code'
+  s.license     = 'ISC'
+  s.summary     = 'Postal Code Resolver'
+  s.description = 'Resolves a postal code to a corresponding city or state.'
+  s.files       = Dir['README.rdoc', 'Rakefile', 'postal_code.gemspec',
+                      'lib/**/*.rb', 'test/**/*', 'db/*.csv']
+  s.test_files  = Dir['test/*.rb']
+end

data/test/data/us.csv

@@ -0,0 +1,4 @@
+00001	City1	AA
+10000	City2	BA
+20000	City3	CA
+20000	City4	CA

data/test/test_postal_code.rb

@@ -0,0 +1,87 @@
+gem 'minitest'  # minitest in 1.9 stdlib is crufty
+require 'minitest/autorun'
+require 'postal_code'
+
+class PostalCodeTest < Minitest::Test
+
+  ProductionDB = PostalCode::DB.dup
+  TestDB = File.dirname(__FILE__) + '/data/us.csv'
+  PostalCode::DB.replace(TestDB)
+
+  def test_database_format
+    [ProductionDB, TestDB].each do |db|
+      [ %x[head -n1 #{db}],
+        %x[tail -n1 #{db}]
+      ].each do |tuple|
+        assert_match(/^\d{5}\t.+\t[A-Z]{2}$/, tuple)
+      end
+    end
+  end
+
+  def test_postal_code_with_leading_zeros
+    pcode = '00001'
+    assert_equal 'City1', PostalCode.city(pcode)
+    assert_equal 'AA',    PostalCode.state(pcode)
+  end
+
+  def test_postal_code_with_plus_4_extension
+    pcode = '00001-1234'
+    assert_equal 'City1', PostalCode.city(pcode)
+    assert_equal 'AA',    PostalCode.state(pcode)
+  end
+
+  def test_postal_code_found_in_single_city
+    pcode = '10000'
+    assert_equal 'City2', PostalCode.city(pcode)
+    assert_equal 'BA',    PostalCode.state(pcode)
+  end
+
+  def test_postal_code_found_in_multiple_cities
+    pcode = '20000'
+    assert_equal 'City4', PostalCode.city(pcode)
+    assert_equal 'CA',    PostalCode.state(pcode)
+  end
+
+  def test_postal_code_not_found_in_any_city
+    pcode = '99999'
+    assert_equal nil,     PostalCode.city(pcode)
+    assert_equal nil,     PostalCode.state(pcode)
+  end
+
+  def test_reactive_cache
+    PostalCode.clear_cache
+    assert_equal 0, PostalCode.instance_variable_get(:@cache).size
+    PostalCode.city('00001') # hit
+    assert_equal 1, PostalCode.instance_variable_get(:@cache).size
+
+    PostalCode.clear_cache
+    assert_equal 0, PostalCode.instance_variable_get(:@cache).size
+    PostalCode.city('99999') # miss
+    assert_equal 0, PostalCode.instance_variable_get(:@cache).size
+  end
+
+  def test_proactive_cache
+    tuple_cnt      = open(PostalCode::DB) {|db| db.readlines.size}
+    duplicate_cnt  = 1
+    uniq_tuple_cnt = tuple_cnt - duplicate_cnt
+
+    assert_equal 4, tuple_cnt
+    PostalCode.clear_cache
+    assert_equal 0, PostalCode.instance_variable_get(:@cache).size
+    PostalCode.load_cache
+    assert_equal uniq_tuple_cnt, PostalCode.instance_variable_get(:@cache).size
+  end
+
+  def test_postal_code_validations
+    refute PostalCode.send(:valid_format?, '99999').nil?
+    refute PostalCode.send(:valid_format?, '00001').nil?
+    refute PostalCode.send(:valid_format?, '00001-1234').nil?
+    assert PostalCode.send(:valid_format?, '00001-123').nil?
+    assert PostalCode.send(:valid_format?, '00001-').nil?
+    assert PostalCode.send(:valid_format?, 99999).nil?
+    assert PostalCode.send(:valid_format?, 00001).nil?
+    assert PostalCode.send(:valid_format?, '1').nil?
+    assert PostalCode.send(:valid_format?, 1).nil?
+  end
+
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: postal_code
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Clint Pachl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-02 00:00:00.000000000 Z
+dependencies: []
+description: Resolves a postal code to a corresponding city or state.
+email: pachl@ecentryx.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.rdoc
+- Rakefile
+- postal_code.gemspec
+- lib/postal_code/server.rb
+- lib/postal_code.rb
+- test/test_postal_code.rb
+- test/data/us.csv
+- db/us.csv
+homepage: http://ecentryx.com/gems/postal_code
+licenses:
+- ISC
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Postal Code Resolver
+test_files:
+- test/test_postal_code.rb