namxam-carmen 0.1.2

data/data/states/ua.yml

@@ -0,0 +1,51 @@
+---
+- - Autonomous Republic of Crimea
+  - CR
+- - Cherkashchyna
+  - CK
+- - Chernihivshchyna
+  - CN
+- - Chernivechchyna
+  - CV
+- - Dnipropetrovshchyna
+  - DP
+- - Donechchyna
+  - DN
+- - Ivano-Frankivshchyna
+  - IF
+- - Kharkivshchyna
+  - KH
+- - Khersonshchyna
+  - KS
+- - Khmel'nychchyna
+  - KM
+- - Kyivshchyna
+  - KV
+- - Kirovohradshchyna
+  - KR
+- - Luhanshchyna
+  - LG
+- - L'vivshchyna
+  - LV
+- - Mykolaivshchyna
+  - MK
+- - Odeshchyna
+  - OD
+- - Poltavshchyna
+  - PL
+- - Rivnenshchyna
+  - RV
+- - Sumshchyna
+  - SM
+- - Ternopil'shchyna
+  - TAS
+- - Vinnychchyna
+  - VN
+- - Volyn'
+  - VOLYN
+- - Zakarpattia
+  - ZK
+- - Zaporizhzhia
+  - ZP
+- - Zhytomyrshchyna
+  - ZT

data/data/states/us.yml

@@ -0,0 +1,124 @@
+# from http://www.usps.com/ncsc/lookups/usps_abbreviations.html
+---
+- - Alabama
+  - AL
+- - Alaska
+  - AK
+- - Arizona
+  - AZ
+- - Arkansas
+  - AR
+- - California
+  - CA
+- - Colorado
+  - CO
+- - Connecticut
+  - CT
+- - Delaware
+  - DE
+- - District Of Columbia
+  - DC
+- - Florida
+  - FL
+- - Georgia
+  - GA
+- - Hawaii
+  - HI
+- - Idaho
+  - ID
+- - Illinois
+  - IL
+- - Indiana
+  - IN
+- - Iowa
+  - IA
+- - Kansas
+  - KS
+- - Kentucky
+  - KY
+- - Louisiana
+  - LA
+- - Maine
+  - ME
+- - Maryland
+  - MD
+- - Massachusetts
+  - MA
+- - Michigan
+  - MI
+- - Minnesota
+  - MN
+- - Mississippi
+  - MS
+- - Missouri
+  - MO
+- - Montana
+  - MT
+- - Nebraska
+  - NE
+- - Nevada
+  - NV
+- - New Hampshire
+  - NH
+- - New Jersey
+  - NJ
+- - New Mexico
+  - NM
+- - New York
+  - NY
+- - North Carolina
+  - NC
+- - North Dakota
+  - ND
+- - Ohio
+  - OH
+- - Oklahoma
+  - OK
+- - Oregon
+  - OR
+- - Pennsylvania
+  - PA
+- - Rhode Island
+  - RI
+- - South Carolina
+  - SC
+- - South Dakota
+  - SD
+- - Tennessee
+  - TN
+- - Texas
+  - TX
+- - Utah
+  - UT
+- - Vermont
+  - VT
+- - Virginia
+  - VA
+- - Washington
+  - WA
+- - West Virginia
+  - WV
+- - Wisconsin
+  - WI
+- - Wyoming
+  - WY
+- - Federated States of Micronesia
+  - FM
+- - Guam
+  - GU
+- - Marshall Islands
+  - MH
+- - Northern Mariana Islands
+  - MP
+- - Palau
+  - PW
+- - Puerto Rico
+  - PR
+- - Virgin Islands
+  - VI
+- - Armed Forces Americas (except Canada)
+  - AA
+- - Armed Forces Europe, Armed Forces Canada, Armed Forces Africa, or Armed Forces Middle East
+  - AE
+- - Armed Forces Pacific
+  - AP

data/lib/carmen.rb

@@ -0,0 +1,132 @@
+require 'yaml'
+begin
+  require 'ftools'
+rescue LoadError
+  require 'fileutils' # ftools is now fileutils in Ruby 1.9
+end
+
+module Carmen
+
+  class << self
+    attr_accessor :default_country, :locale
+  end
+  
+  self.default_country = 'US'
+  self.locale = :en
+  
+  @data_path = File.join(File.dirname(__FILE__), '../data')
+  
+  DEFAULT_COUNTRIES = @countries = YAML.load_file(File.join(@data_path, 'countries.yml'))
+  
+  STATES = Dir[@data_path + '/states/*.yml'].map do |file_name|
+    [File::basename(file_name, '.yml').upcase, YAML.load_file(file_name)]
+  end
+
+  # Raised when attempting to retrieve states for an unsupported country
+  class StatesNotSupported < RuntimeError; end
+
+  # Raised when attempting to work with a country not in the data set
+  class NonexistentCountry < RuntimeError; end
+  
+  # Raised when attemting to switch to a locale which does not exist
+  class UnavailableLocale < RuntimeError; end
+
+  # Loads a localized version of the country list
+  def self.locale=(input)
+    localization = File.join(@data_path, "countries.#{input}.yml")
+    
+    raise UnavailableLocale unless File.exists?(localization)
+    
+    # Load localization
+    localized_countries = YAML.load_file(localization)
+    
+    # Merge the defaults with the localized versions
+    @countries = DEFAULT_COUNTRIES # Reset countries to default list
+    positions = country_codes # for speed optimization
+    localized_countries.each do |c|
+      if index = country_codes.index(c[1])
+        @countries[country_codes.index(c[1])] = c
+      else
+        @countries.push(c)
+      end
+    end
+    
+    @locale = input.to_s
+  end
+
+  # Returns the country name corresponding to the supplied country code
+  #  Carmen::country_name('TV') => 'Tuvalu'
+  def self.country_name(country_code)
+    search_collection(@countries, country_code, 1, 0)
+  end
+
+  # Returns the country code corresponding to the supplied country name
+  #  Carmen::country_code('Canada') => 'CA'
+  def self.country_code(country_name)
+    search_collection(@countries, country_name, 0, 1)
+  end
+
+  # Returns an array of all country codes
+  #  Carmen::country_codes => ['AF', 'AX', 'AL', ... ]
+  def self.country_codes
+    @countries.map {|c| c[1] }
+  end
+  
+  # Returns an array of all country codes
+  #  Carmen::country_name => ['Afghanistan', 'Aland Islands', 'Albania', ... ]
+  def self.country_names
+    @countries.map {|c| c[0] }
+  end
+  
+  # Returns the state name corresponding to the supplied state code within the specified country
+  #  Carmen::state_code('New Hampshire') => 'NH'
+  def self.state_name(state_code, country_code = Carmen.default_country)
+    search_collection(self.states(country_code), state_code, 1, 0)
+  end
+
+  # Returns the state code corresponding to the supplied state name within the specified country
+  #  Carmen::state_code('IL', 'US') => Illinois
+  def self.state_code(state_name, country_code = Carmen.default_country)
+    search_collection(self.states(country_code), state_name, 0, 1)
+  end
+
+  # Returns an array of state names within the specified country code
+  #  Carmen::state_names('US') => ['Alabama', 'Arkansas', ... ]
+  def self.state_names(country_code = Carmen.default_country)
+    self.states(country_code).map{|name, code| name}
+  end
+
+  # Returns an array of state codes within the specified country code
+  #   Carmen::state_codes('US') => ['AL', 'AR', ... ]
+  def self.state_codes(country_code = Carmen.default_country)
+    self.states(country_code).map{|name, code| code}
+  end
+
+  # Returns an array structure of state names and codes within the specified country code
+  #   Carmen::states('US') => [['Alabama', 'AL'], ['Arkansas', 'AR'], ... ]
+  def self.states(country_code = Carmen.default_country)
+    raise NonexistentCountry unless country_codes.include?(country_code)
+    raise StatesNotSupported unless states?(country_code)
+    search_collection(STATES, country_code, 0, 1)
+  end
+
+  # Returns whether states are supported for the given country code
+  #   Carmen::states?('US') => true
+  #   Carmen::states?('ZZ') => false
+  def self.states?(country_code)
+    STATES.any? do |array| k,v = array
+      k == country_code
+    end
+  end
+  
+  protected
+  
+  def self.search_collection(collection, value, index_to_match, index_to_retrieve)
+    return nil if collection.nil?
+    collection.each do |m|
+      return m[index_to_retrieve] if m[index_to_match] == value
+    end
+    nil
+  end
+  
+end

data/lib/carmen/action_view_helpers.rb

@@ -0,0 +1,68 @@
+module ActionView
+  module Helpers
+    module FormOptionsHelper
+    
+      # Return select and option tags for the given object and method, using state_options_for_select to generate the list of option tags.
+      def state_select(object, method, country = Carmen.default_country, options={}, html_options={})
+        InstanceTag.new(object, method, self, options.delete(:object)).to_state_select_tag(country, options, html_options)
+      end
+    
+      # Return select and option tags for the given object and method, using country_options_for_select to generate the list of option tags.
+      def country_select(object, method, priority_countries = nil, options = {}, html_options = {})
+        InstanceTag.new(object, method, self, options.delete(:object)).to_country_select_tag(priority_countries, options, html_options)
+      end
+    
+      # Returns a string of option tags containing the state names and codes for the specified country code, or nil
+      # if the states are not know for that country. Supply a state code as +selected+ to have it marked as the selected option tag.
+      def state_options_for_select(selected = nil, country = Carmen.default_country)
+        options_for_select(Carmen.states(country), selected)
+      end
+    
+      # Returns a string of option tags for pretty much any country in the world. Supply a country name as +selected+ to
+      # have it marked as the selected option tag. You can also supply a list of country codes as additional parameters, so
+      # that they will be listed above the rest of the (long) list.
+      def country_options_for_select(selected = nil, *priority_country_codes)
+        country_options = ""
+
+        unless priority_country_codes.empty?
+          priority_countries = Carmen::COUNTRIES.select do |pair| name, code = pair
+            priority_country_codes.include?(code)
+          end
+          unless priority_countries.empty?
+            country_options += options_for_select(priority_countries, selected)
+            country_options += "\n<option value=\"\" disabled=\"disabled\">-------------</option>\n"
+          end
+        end
+
+        return country_options + options_for_select(Carmen::COUNTRIES, priority_country_codes.include?(selected) ? nil : selected)
+      end
+    end
+  
+    class InstanceTag
+      def to_country_select_tag(priority_countries, options, html_options)
+        html_options = html_options.stringify_keys
+        add_default_name_and_id(html_options)
+        value = value(object)
+        opts = add_options(country_options_for_select(value, *priority_countries), options, value)
+        content_tag("select", opts, html_options)
+      end
+    
+      def to_state_select_tag(country, options, html_options)
+        html_options = html_options.stringify_keys
+        add_default_name_and_id(html_options)
+        value = value(object)
+        opts = add_options(state_options_for_select(value, country), options, value)
+        content_tag("select", opts, html_options)
+      end
+    end
+  
+    class FormBuilder
+      def country_select(method, priority_countries = nil, options = {}, html_options = {})
+        @template.country_select(@object_name, method, priority_countries, options.merge(:object => @object), html_options)
+      end
+      def state_select(method, country_code = Carmen.default_country, options = {}, html_options = {})
+        @template.state_select(@object_name, method, country_code, options.merge(:object => @object), html_options)
+      end
+    end
+  end
+end

data/rails/init.rb

@@ -0,0 +1,2 @@
+require 'carmen'
+require 'carmen/action_view_helpers'

data/test/carmen_test.rb

@@ -0,0 +1,89 @@
+require 'test/unit'
+require File.join(File.dirname(__FILE__), '../lib/carmen')
+
+class TestCarmen < Test::Unit::TestCase
+  
+  
+  def test_country_name
+    assert_equal 'United States', Carmen.country_name('US')
+  end
+  
+  def test_localized_country_name
+    Carmen.locale = :de
+    assert_equal 'Deutschland', Carmen.country_name('DE')
+  end
+  
+  def test_country_code
+    assert_equal 'CA', Carmen.country_code('Canada')
+  end
+  
+  def test_localized_country_code
+    Carmen.locale = :de
+    assert_equal 'DE', Carmen.country_code('Deutschland')
+  end
+  
+  def test_country_codes
+    assert_equal 'AF', Carmen.country_codes.first
+    assert_equal 243, Carmen.country_codes.length
+  end
+  
+  def test_country_names
+    assert_equal 'Afghanistan', Carmen.country_names.first
+    assert_equal 243, Carmen.country_names.length
+  end
+  
+  def test_state_name
+    assert_equal 'IL', Carmen.state_code('Illinois')
+    assert_equal 'MB', Carmen.state_code('Manitoba', 'CA')
+  end
+  
+  def test_state_code
+    assert_equal 'Arizona', Carmen.state_name('AZ')
+    assert_equal 'Prince Edward Island', Carmen.state_name('PE', 'CA')
+  end
+  
+  def test_states
+    assert_equal 61, Carmen.states.length
+    assert_equal ['Alabama', 'AL'], Carmen.states.first
+    assert_equal 13, Carmen.states('CA').length
+    assert_equal ['Alberta', 'AB'], Carmen.states('CA').first
+  end
+  
+  def test_state_names
+    assert_equal 61, Carmen::state_names.length
+    assert_equal 'Alabama', Carmen::state_names.first
+    assert_equal 13, Carmen.state_names('CA').length
+    assert_equal 'Alberta', Carmen.state_names('CA').first
+  end
+  
+  def test_state_codes
+    assert_equal 61, Carmen::state_codes.length
+    assert_equal 'AL', Carmen::state_codes.first
+    assert_equal 13, Carmen.state_codes('CA').length
+    assert_equal 'AB', Carmen.state_codes('CA').first
+  end
+  
+  def test_supported_states
+    assert Carmen::states?('US')
+    assert_equal Carmen::states?('ZZ'), false
+  end
+  
+  def test_invalid_country_exception
+    assert_raises Carmen::NonexistentCountry do
+      Carmen::state_codes('ZZ')
+    end
+  end
+  
+  def test_unsupported_states_exception
+    assert_raises Carmen::StatesNotSupported do
+      Carmen::state_codes('ID')
+    end
+  end
+  
+  def test_unsupported_locale
+    assert_raises Carmen::UnavailableLocale do
+      Carmen.locale = :latin
+    end
+  end
+  
+end