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, China, Cuba, Denmark, Germany, India, Italy, Mexico, the Netherlands, 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", :require => '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.

Vibhuti/carmen