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.

Changelog¶ ↑

See CHANGELOG.md

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¶ ↑

This project is only possible because of the work of many fine developers from around the world.