ansi_codes 0.0.1

data/data/state.txt

@@ -0,0 +1,58 @@
+STATE|STUSAB|STATE_NAME|STATENS
+01|AL|Alabama|01779775
+02|AK|Alaska|01785533
+04|AZ|Arizona|01779777
+05|AR|Arkansas|00068085
+06|CA|California|01779778
+08|CO|Colorado|01779779
+09|CT|Connecticut|01779780
+10|DE|Delaware|01779781
+11|DC|District of Columbia|01702382
+12|FL|Florida|00294478
+13|GA|Georgia|01705317
+15|HI|Hawaii|01779782
+16|ID|Idaho|01779783
+17|IL|Illinois|01779784
+18|IN|Indiana|00448508
+19|IA|Iowa|01779785
+20|KS|Kansas|00481813
+21|KY|Kentucky|01779786
+22|LA|Louisiana|01629543
+23|ME|Maine|01779787
+24|MD|Maryland|01714934
+25|MA|Massachusetts|00606926
+26|MI|Michigan|01779789
+27|MN|Minnesota|00662849
+28|MS|Mississippi|01779790
+29|MO|Missouri|01779791
+30|MT|Montana|00767982
+31|NE|Nebraska|01779792
+32|NV|Nevada|01779793
+33|NH|New Hampshire|01779794
+34|NJ|New Jersey|01779795
+35|NM|New Mexico|00897535
+36|NY|New York|01779796
+37|NC|North Carolina|01027616
+38|ND|North Dakota|01779797
+39|OH|Ohio|01085497
+40|OK|Oklahoma|01102857
+41|OR|Oregon|01155107
+42|PA|Pennsylvania|01779798
+44|RI|Rhode Island|01219835
+45|SC|South Carolina|01779799
+46|SD|South Dakota|01785534
+47|TN|Tennessee|01325873
+48|TX|Texas|01779801
+49|UT|Utah|01455989
+50|VT|Vermont|01779802
+51|VA|Virginia|01779803
+53|WA|Washington|01779804
+54|WV|West Virginia|01779805
+55|WI|Wisconsin|01779806
+56|WY|Wyoming|01779807
+60|AS|American Samoa|01802701
+66|GU|Guam|01802705
+69|MP|Northern Mariana Islands|01779809
+72|PR|Puerto Rico|01779808
+74|UM|U.S. Minor Outlying Islands|01878752
+78|VI|U.S. Virgin Islands|01802710

data/lib/ansi_codes.rb

@@ -0,0 +1,5 @@
+require 'ansi_codes/version'
+require 'ansi_codes/state'
+require 'ansi_codes/county'
+
+module AnsiCodes; end

data/lib/ansi_codes/county.rb

@@ -0,0 +1,86 @@
+module AnsiCodes
+  # A representation of US counties and equivalent census areas.
+  # County instances are created at class load time and are immutable.
+  class County
+    # @return [State] the {State} that this county belongs to
+    attr_reader :state
+    # @return [String] the three digit ANSI code for this county
+    attr_reader :ansi_code
+    # @return [String] the county's full name in title case
+    attr_reader :name
+    # @return [String] the county name, minus the designation
+    # @note some cities have no designation, so this attribute will be the same as {#name}
+    attr_reader :short_name
+    # @return [String] the census designation (County, Parish, Municipio, etc.)
+    # @note some cities have no designation, in which case this will return the empty string
+    attr_reader :designation
+
+    private
+
+    # Suffixes for counties (parishes, etc.) to help split names into their parts.
+    Designations = /(.*) (city|Borough|County|City and Borough|Census Area|Municipality|Parish|Islands?|District|Municipio)$/
+
+    # Create a new County instance.
+    # @note This is only meant to be called internally during class loading.
+    #       You cannot call #new directly.
+    # @param state_ansi [String] the two-digit state ANSI code
+    # @param county_ansi [String] the three-digit county ANSI code
+    # @param name [String] the county name
+    def initialize(state_ansi, county_ansi, name)
+      @state = State.find(state_ansi)
+      @ansi_code = county_ansi
+      @name = name
+      match = name.match(Designations)
+      @short_name = match && match[1] || name
+      @designation = match && match[2] || ''
+      freeze
+      self.class.instance_variable_get(:@counties)[@state].tap do |counties|
+        counties[:ansi_code][@ansi_code.downcase] =
+          counties[:name][@name.downcase] = self
+      end
+    end
+
+    public
+
+    # @param [State] state an optional {State} object to narrow the results
+    # @return [Array<County>] all counties or all of a {State}'s counties if one is provided
+    def self.all(state = nil)
+      state ? @counties[state][:ansi_code].values :
+        @counties.values.flat_map {|values| values[:ansi_code]}.flat_map(&:values)
+    end
+
+    # Look up a county by state and county ANSI code or name
+    # @param [State, Fixnum, String] state the state portion of the query.
+    #   This method will accept a {State} object or anything that {State.find} will accept.
+    # @param [Fixnum, String] county the county ANSI code or name to look up
+    # @return [County] the {County} associated with the query parameters
+    # @raise [ArgumentError] if the county parameter is not a Fixnum or String,
+    #   or if the state parameter is not a {State}, Fixnum, or String.
+    # @raise [RuntimeError] if no associated {State} or {County} is found
+    def self.find(state, county)
+      state = state.is_a?(State) ? state : State.find(state)
+      case county
+      when Fixnum
+        county, selector = '%03d' % county, :ansi_code
+      when String
+        selector = county =~ /^[0-9]{3}$/ ? :ansi_code : :name
+      else raise(ArgumentError, 'Argument must be an integer or a string.')
+      end
+      @counties[state][selector][county.downcase].tap do |result|
+        raise(RuntimeError, "No county found for lookup '#{county}' in state #{state.name}") unless result
+        yield result if block_given?
+      end
+    end
+
+    @counties = Hash[State.all.map {|state| [state, { ansi_code: {}, name: {} }] }]
+    data_file = File.expand_path('../../../data/national_county.txt', __FILE__)
+    options = { headers: true, header_converters: :symbol }
+    CSV.foreach(data_file, options) do |row|
+      new row[:state_ansi], row[:county_ansi], row[:county_name]
+    end
+    @counties.values.flat_map(&:values).map(&:freeze)
+    @counties.values.map &:freeze
+    @counties.freeze
+    freeze
+  end
+end

data/lib/ansi_codes/state.rb

@@ -0,0 +1,87 @@
+require 'csv'
+
+module AnsiCodes
+  # A representation of US states and equivalent census areas.
+  # State instances are created at class load time and are immutable.
+  class State
+    # @return [String] the two-digit ANSI code string
+    # @api public
+    attr_reader :ansi_code
+    # @return [String] the state name in title case
+    # @api public
+    attr_reader :name
+    # @return [String] the two-letter state abbreviation in caps
+    # @api public
+    attr_reader :abbreviation
+
+    private
+
+    # Create a new State instance.
+    # @note This is only meant to be called internally during class loading.
+    #       You cannot call #new directly.
+    # @param ansi_code [String] the two-digit state ANSI code
+    # @param name [String] the state name
+    # @param abbreviation [String] the two-letter state abbreviation
+    def initialize(ansi_code, name, abbreviation)
+      @ansi_code = ansi_code
+      @name = name
+      @abbreviation = abbreviation
+      freeze
+      self.class.instance_variable_get(:@states).tap do |states|
+        states[:ansi_code][@ansi_code.downcase] =
+          states[:name][@name.downcase] =
+          states[:abbreviation][@abbreviation.downcase] = self
+      end
+    end
+
+    public
+
+
+    # @return [Array<County>] all of this state's counties
+    # @api public
+    # @!attribute [r] counties
+    def counties
+      County.all(self)
+    end
+
+    # Look up a state by ANSI code, abbreviation, or name
+    # @param [Fixnum, String] value the lookup query
+    # @return [State] the {State} associated with the query parameter
+    # @raise [ArgumentError] if the argument is not a Fixnum or String
+    # @raise [RuntimeError] if no associated {State} is found
+    def self.find(value)
+      case value
+      when Fixnum
+        value = '%02d' % value
+        selector = :ansi_code
+      when String
+        begin
+          Integer(value, 10)
+          selector = :ansi_code
+        rescue ArgumentError
+          selector = value.size == 2 ? :abbreviation : :name
+        end
+      else raise(ArgumentError, 'Argument must be an integer or a string.')
+      end
+      @states[selector][value.downcase].tap do |result|
+        raise(RuntimeError, "No state found for lookup '#{value}'") unless result
+        yield result if block_given?
+      end
+    end
+
+    # @return [Array<State>] an array of all states
+    def self.all
+      @states[:ansi_code].values
+    end
+
+    @states = { ansi_code: {}, name: {}, abbreviation: {} }
+    data_file = File.expand_path('../../../data/state.txt', __FILE__)
+    options = { col_sep: '|', headers: true, header_converters: :symbol }
+    CSV.foreach(data_file, options) do |row|
+      new row[:state], row[:state_name], row[:stusab]
+    end
+    @states.values.map &:freeze
+    @states.freeze
+    freeze
+  end
+end

data/lib/ansi_codes/version.rb

@@ -0,0 +1,3 @@
+module AnsiCodes
+  VERSION = "0.0.1"
+end

data/spec/county_spec.rb

@@ -0,0 +1,132 @@
+require 'spec_helper'
+
+describe AnsiCodes::County do
+
+  it 'should not be instantiable' do
+    expect{AnsiCodes::County.new('01', '001', 'Autauga County')}.to raise_error(RuntimeError)
+  end
+
+  it 'should not be modifiable' do
+    expect{AnsiCodes::County.extend Module.new}.to raise_error
+  end
+
+  describe '#ansi_code' do
+    it 'should return a three-digit string' do
+      AnsiCodes::County.all.each do |county|
+        county.ansi_code.should match(/^[0-9]{3}$/)
+      end
+    end
+
+    it 'should return the same county when looked up by result' do
+      AnsiCodes::County.all.each do |county|
+        AnsiCodes::County.find(county.state, county.ansi_code).should be(county)
+      end
+    end
+  end
+
+  describe '#name' do
+    before(:each) { @names = AnsiCodes::County.all.map(&:name) }
+
+    it 'should return a string' do
+      @names.each {|name| name.should be_a(String)}
+    end
+
+    it 'should be at least 4 characters long' do
+      @names.each {|name| name.should have_at_least(4).items}
+    end
+
+    it 'should return the same county when looked up by result' do
+      AnsiCodes::County.all.each do |county|
+        AnsiCodes::County.find(county.state, county.name).should be(county)
+      end
+    end
+  end
+
+  describe '#short_name' do
+    before(:each) { @short_names = AnsiCodes::County.all.map(&:short_name) }
+
+    it 'should return a string' do
+      @short_names.each {|short_name| short_name.should be_a(String)}
+    end
+
+    it 'should be no longer than #name' do
+      AnsiCodes::County.all.each do |county|
+        county.short_name.should have_at_most(county.name.size).characters
+      end
+    end
+  end
+
+  describe '#designation' do
+    before(:each) { @designations = AnsiCodes::County.all.map(&:designation) }
+
+    it 'should return a string' do
+      @designations.each {|designation| designation.should be_a(String)}
+    end
+
+    it 'should be shorter than #name' do
+      AnsiCodes::County.all.each do |county|
+        county.designation.should have_at_most(county.name.size - 1).characters
+      end
+    end
+  end
+
+  describe '#state' do
+    before(:each) { @states = AnsiCodes::County.all.map(&:state) }
+
+    it 'should return an AnsiCodes::State' do
+      @states.each {|state| state.should be_an(AnsiCodes::State)}
+    end
+  end
+
+  describe '.all' do
+    it 'should return 3235 elements' do
+      AnsiCodes::County.all.should have(3235).items
+    end
+
+    it 'should return an array of AnsiCodes::County' do
+      AnsiCodes::County.all.tap do |counties|
+        counties.should be_an(Array)
+        counties.each {|county| county.should be_an_instance_of(AnsiCodes::County)}
+      end
+    end
+  end
+
+  describe '.find' do
+    it 'should accept a string as first param' do
+      expect{AnsiCodes::County.find '01', '001'}.not_to raise_error
+    end
+
+    it 'should accept an integer as first param' do
+      expect{AnsiCodes::County.find 1, '001'}.not_to raise_error
+    end
+
+    it 'should accept an AnsiCodes::State as first param' do
+      expect{AnsiCodes::County.find AnsiCodes::State.all.first, '001'}.not_to raise_error
+    end
+
+    it 'should accept a string as second param' do
+      expect{AnsiCodes::County.find 1, '001'}.not_to raise_error
+    end
+
+    it 'should accept an integer as second param' do
+      expect{AnsiCodes::County.find 1, 1}.not_to raise_error
+    end
+
+    it 'should raise an ArgumentError on any other type as second param' do
+      expect{AnsiCodes::County.find 1, nil}.to raise_error(ArgumentError)
+      expect{AnsiCodes::County.find 1, 1.0}.to raise_error(ArgumentError)
+      expect{AnsiCodes::County.find 1, /really?/}.to raise_error(ArgumentError)
+      expect{AnsiCodes::County.find 1, {}}.to raise_error(ArgumentError)
+      expect{AnsiCodes::County.find 1, []}.to raise_error(ArgumentError)
+    end
+
+    it 'should yield the result if a block is given' do
+      county = AnsiCodes::County.find 'Virginia', 'Norfolk city'
+      expect { |b| AnsiCodes::County.find('Virginia', 'Norfolk city', &b) }.to yield_with_args(county)
+    end
+
+    it 'should raise an exception if no county is found' do
+      expect{AnsiCodes::County.find 45, 1000}.to raise_error
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+begin
+  require 'simplecov'
+  SimpleCov.start do
+    add_filter '/spec/'
+    add_filter {|source| source.lines.count < 10}
+  end
+rescue LoadError
+  STDERR.puts 'SimpleCov not installed.  Not generating coverage report.'
+end
+
+require 'ansi_codes'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+  config.order = 'random'
+end

data/spec/state_spec.rb

@@ -0,0 +1,142 @@
+require 'spec_helper'
+
+describe AnsiCodes::State do
+  it 'should not be instantiable' do
+    expect{AnsiCodes::State.new('01', 'AL', 'Alabame')}.to raise_error(RuntimeError)
+  end
+
+  it 'should not be modifiable' do
+    expect{AnsiCodes::State.extend Module.new}.to raise_error
+  end
+
+  describe '#ansi_code' do
+    it 'should return a two-digit string' do
+      AnsiCodes::State.all.each do |state|
+        state.ansi_code.should match(/^[0-9]{2}$/)
+      end
+    end
+
+    it 'should return the same state when result is looked up' do
+      AnsiCodes::State.all.each do |state|
+        AnsiCodes::State.find(state.ansi_code).should be(state)
+      end
+    end
+  end
+
+  describe '#name' do
+    it 'should return a string longer than 2 characters' do
+      AnsiCodes::State.all.each do |state|
+        state.name.should have_at_least(3).items
+      end
+    end
+
+    it 'should return a proper name' do
+      AnsiCodes::State.all.each do |state|
+        state.name.should match(/^[A-Z].*[a-z]/)
+      end
+    end
+
+    it 'should return the same state when result is looked up' do
+      AnsiCodes::State.all.each do |state|
+        AnsiCodes::State.find(state.name).should be(state)
+      end
+    end
+  end
+
+  describe '#abbreviation' do
+    it 'should return a two-character uppercase string' do
+      AnsiCodes::State.all.each do |state|
+        state.abbreviation.should match(/^[A-Z]{2}$/)
+      end
+    end
+
+    it 'should return the same state when result is looked up' do
+      AnsiCodes::State.all.each do |state|
+        AnsiCodes::State.find(state.abbreviation).should be(state)
+      end
+    end
+  end
+
+  describe '#counties' do
+    it 'should return an array of AnsiCodes::County' do
+      counties = AnsiCodes::State.all.first.counties
+      counties.should be_an(Array)
+      counties.each do |county|
+        county.should be_a(AnsiCodes::County)
+      end
+    end
+  end
+
+  describe '.all' do
+    it 'should return 57 elements' do
+      AnsiCodes::State.all.should have(57).items
+    end
+
+    it 'should return an array' do
+      AnsiCodes::State.all.should be_an(Array)
+    end
+
+    it 'should contain AnsiCodes::State instances' do
+      AnsiCodes::State.all.each do |state|
+        state.should be_an_instance_of(AnsiCodes::State)
+      end
+    end
+  end
+
+  describe '.find' do
+    it 'should raise ArgumentError with no arguments' do
+      expect{AnsiCodes::State.find}.to raise_error(ArgumentError)
+    end
+
+    it 'should raise ArgumentError with more than one argument' do
+      expect{AnsiCodes::State.find 1, 2}.to raise_error(ArgumentError)
+    end
+
+    it 'should accept an integer argument' do
+      expect{AnsiCodes::State.find 12}.not_to raise_error
+    end
+
+    it 'should accept a string argument' do
+      expect{AnsiCodes::State.find '12'}.not_to raise_error
+    end
+
+    it 'should return Alabama with lookup = 1' do
+      AnsiCodes::State.find(1).name.should == 'Alabama'
+    end
+
+    it 'should return Alabama with lookup = "01"' do
+      AnsiCodes::State.find('01').name.should == 'Alabama'
+    end
+
+    it 'should be case-insensitive' do
+      AnsiCodes::State.find('wi').should == AnsiCodes::State.find('WI')
+      AnsiCodes::State.find('NEW JERSEY').should == AnsiCodes::State.find('nEw JeRsEy')
+    end
+
+    it 'should raise an ArgumentError on any other type as second param' do
+      expect{AnsiCodes::State.find nil}.to raise_error(ArgumentError)
+      expect{AnsiCodes::State.find 1.0}.to raise_error(ArgumentError)
+      expect{AnsiCodes::State.find /really?/}.to raise_error(ArgumentError)
+      expect{AnsiCodes::State.find {}}.to raise_error(ArgumentError)
+      expect{AnsiCodes::State.find []}.to raise_error(ArgumentError)
+    end
+
+    it 'should raise a RuntimeError if no match is found' do
+      expect{AnsiCodes::State.find 'chimichanga'}.to raise_error(RuntimeError)
+    end
+
+    it 'should yield the result if a block is given' do
+      state = AnsiCodes::State.find 'New York'
+      expect { |b| AnsiCodes::State.find('New York', &b) }.to yield_with_args(state)
+    end
+
+    it 'should return identical objects with the same parameters' do
+      AnsiCodes::State.find('01').should eql(AnsiCodes::State.find('01'))
+    end
+
+    it 'should return identical objects when lookup result is same' do
+      AnsiCodes::State.find('AL').should eql(AnsiCodes::State.find('01'))
+    end
+  end
+
+end