<commit_before>
= 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.

== 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' ], ... }

== 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)


== Todo

* Many countries, such as Spain, have additional levels beneath 'state' that we would ideally support. Thanks to <NAME> for bringing this to my attention.
* Split the Rails-specific view helpers out into a separate gem (carmen-rails)

== Changelog
* 0.2.6 Suppress a deprecation warning in Rails 3. (anupamc)
        Remove init.rb altogether and use requires under Rails

* 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}[http://tomayko.com/writings/require-rubygems-antipattern].


== Credits

These fine characters have contributed state lists, patches, or reported bugs:

<NAME> (jacortinas)
<NAME> (ddnexus)
<NAME> (railsfreaks)
<NAME> (russjohnson)
<NAME> (dvyjones)
<NAME> (uberllama)
<NAME> (molpe)
<NAME> (dimaspriyanto)
<NAME> (sharnik)
<NAME> (grobie)
<NAME> (namxam)
<NAME> (bowsersenior)
<NAME> (andriytyurnikov)
lonestarsoftware<commit_msg>Update README for 0.2.6<commit_after>
= 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.

== 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' ], ... }

== 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)


== Todo

* Many countries, such as Spain, have additional levels beneath 'state' that we would ideally support. Thanks to <NAME> 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
* 0.2.6 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}[http://tomayko.com/writings/require-rubygems-antipattern].


== Credits

These fine characters have contributed state lists, patches, or reported bugs:

<NAME> (jacortinas)
<NAME> (ddnexus)
<NAME> (railsfreaks)
<NAME> (russjohnson)
<NAME> (dvyjones)
<NAME> (uberllama)
<NAME> (molpe)
<NAME> (dimaspriyanto)
<NAME> (sharnik)
<NAME> (grobie)
<NAME> (namxam)
<NAME> (bowsersenior)
<NAME> (andriytyurnikov)
<NAME> (anupamc)
<NAME> (orthodoc)
lonestarsoftware
{'fraction_non_alphanumeric': 0.11561275881365417, 'fraction_numerical': 0.006155567991046447, 'mean_word_length': 4.557213930348259, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 67, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3565200', 'n_tokens_mistral': 2814, 'n_tokens_neox': 2688, 'n_words': 1108}