Carmen- A simple collection of geographic names and abbreviations for Ruby¶ ↑

This library will work as a drop in replacement for the official Rails country_select and its various forks. The idea is to provide a single library for all geographic naming concerns, and unify them under a consistent API.

States are supported for the following countries: Australia, Brazil, Canada, Cuba, Denmark, Germany, India, Italy, Mexico, New Zealand, Norway, Spain, Ukraine, and United States.

API documentation is available.

Installation¶ ↑

gem install carmen

If you’re in Rails 2.3 or earlier, place this in your environment.rb:

config.gem 'carmen'

If you’re in Rails 3, put this in your Gemfile:

gem "carmen"

Get a list of all countries¶ ↑

Carmen.countries => […, ['Germany', 'DE'], …, ['United States', 'US'], …]
Carmen.countries(:locale => 'de') => […, ['Deutschland', 'DE'], …, ['Vereinigte Staaten von Amerika', 'US'], …]

State list retrieval¶ ↑

Carmen::states('US') => [['Alabama', 'AL'], ['Arkansas', 'AR'], ... ]
Carmen::states => [['Alabama', 'AL'], ['Arkansas', 'AR'], ... ] # uses default country
Carmen::state_names('US') => ['Alabama', 'Arkansas', ... ]
Carmen::state_codes('US') => ['AL', 'AR', ... ]

Abbreviation handling¶ ↑

Carmen::country_name('US') => 'United States'
Carmen::country_code('Canada') => 'CA'
Carmen::state_code('Illinois') => 'IL'
Carmen::state_code('Manitoba', 'CA') => 'MB'
Carmen::state_name('AZ') => 'Arizona'

Default Country¶ ↑

Methods that take a country code argument will use the default country if none is provided. The default default country is ‘US’. You can change it to any country code:

Carmen.default_country = 'CA'

Adding country and state exclusion to Carmen¶ ↑

This fork lets you exclude specific countries and/or states from Carmen. Simply set the appropriate class variables and the exclusion will take effect.

Excluding Countries¶ ↑

Countries to exclude are specified as an array of country codes:

Carmen.excluded_countries = [ 'AF', 'ST', 'ZW', ... ]

Excluding States¶ ↑

States to exclude are specified via a hash, with keys being the country’s code, and values being the states to exclude from that country:

Carmen.excluded_states = { 'US' => [ 'AA', 'AP', 'PW', ... ], 'DE' => [ 'BW', 'TH' ], ... }

Adding Priority Countries¶ ↑

It can be useful to show a few countries first in the list, before any others. This can be done like so:

Carmen.priority_countries = %w(US CA)

Localization¶ ↑

You can switch between different localizations of the countries list, by setting the locale value (default is :en):

Carmen.default_locale = :de

Methods that return country names also take an optional options hash as the last argument, which can be use to override the default locale for a single call:

Carmen::country_name('US') => 'United States'
Carmen::country_name('US', :locale => :de) => 'Vereinigte Staaten von Amerika'

Currently included localizations are: English (:en), German (:de), Hindi (:hi), Netherlands (:nl)

Rails view helpers¶ ↑

Carmen ships with replacements for state_select and country_select. Usage is simple:

<%= form_for @address do |f| %>
  <%= f.label :country, "Country" %> <%= f.country_select(:country, "US") %>
  <%= submit_tag "Create" %>
<% end %>

Todo¶ ↑

• Many countries, such as Spain, have additional levels beneath ‘state’ that we would ideally support. Thanks to Alberto Molpeceres for bringing this to my attention.

• Split the Rails-specific view helpers out into a separate gem (carmen-rails)

• Move regex matching into an optional module.

Changelog¶ ↑

master¶ ↑

• Add Saint Barthelemy (BL) and Saint Martin (French Part) (MF) (nengxu)

• Add Japanese countries localization (bonsaiben)

• Prevent Carmen::state_name(‘NO’,‘NO’) from crashing (mhourahine)

• Change “Taiwan, Province of China” to “Taiwan” (camilleroux)

• Add spanish translation for countries (federomero)

0.2.8¶ ↑

• Use a shorter name for US Armed Forces States (cgs)

• Added Gujarat to the list of states in India (swaroopch)

• Added American Samoa to the list of US States

• Added Dutch country translations (Arie)

• Added Kosovo to German Translation (Christopher Thorpe)

• Added the ability to list countries at the top of the list (jjthrash)

• Added country names in Hindi (sukeerthiadiga)

0.2.7¶ ↑

• Fix a gemspec disaster.

0.2.6 (pulled)¶ ↑

• Suppress a deprecation warning in Rails 3 (anupamc)

• Remove init.rb altogether and use requires under Rails

• Added Indian states and union territories (orthodoc)

0.2.5¶ ↑

• Data corrections (mikepinde)

0.2.4¶ ↑

• Fixed autoloading under Rails 3

0.2.2¶ ↑

• Added state and country exclusion (kalafut)

0.2.1¶ ↑

• Added regions for New Zealand (yehezkielbs)

0.2.0¶ ↑

• Merge in Maximilian Schulz’s locale fork, refactor internals to better support locales, and update documentation.

• Remove Carmen::STATES and Carmen::COUNTRIES constants in favor of module instance variables and proper accessors.

• Add a test_helper and remove dependency on RubyGems.

0.1.3¶ ↑

• DEPRECATE Carmen::COUNTRIES in favor of Carmen.countries

Development notes¶ ↑

The plugin does not require rubygems anywhere in the test or libraries, so if you are having trouble with load errors running the tests, prepend your command with RUBYOPT=rubygems. More info.

Credits¶ ↑

These fine characters have contributed state lists, or patches:

• Jose Angel Cortinas (jacortinas)

• Domizio Demichelis (ddnexus)

• Thiago Jackiw (railsfreaks)

• Russ Johnson (russjohnson)

• Henrik Hodne (dvyjones)

• Yuval Kordov (uberllama)

• Alberto Molpeceres (molpe)

• Dimas Priyanto (dimaspriyanto)

• Wojtek Ogrodowczyk (sharnik)

• Tobias Schmidt (grobie)

• Maximilian Schulz (namxam)

• Mani Tadayon (bowsersenior)

• Andriy Tyurnikov (andriytyurnikov)

• Anupam Choudhury (anupamc)

• Biswajit Dutta Baruah (orthodoc)

• Chris Sepic (cgs)

• Swaroop C H (swaroopch)

• Gerhard Lazu (gerhard)

• Arie (Arie)

• Christopher Thorpe (ChristopherThorpe)

• Jimmy Thrasher (jjthrash)

• Sukeerthi Adiga (sukeerthiadiga)

• Camille Roux (camilleroux)

• Federico Romero (federomero)

• Mike Hourahine (mhourahine)

• Benjamin Sullivan (bonsaiben)

• lonestarsoftware

• mikepinde

• kalafut

• yehezkielbs

• nengxu

If I missed your name in this list, please let me know and I will add it. I tried to find everyone that has sent in patches or found bugs, but I may have missed a few folks.