{"id":13483671,"url":"https://github.com/carmen-ruby/carmen","last_synced_at":"2025-04-12T15:36:08.379Z","repository":{"id":524454,"uuid":"152987","full_name":"carmen-ruby/carmen","owner":"carmen-ruby","description":"A repository of geographic regions for Ruby","archived":false,"fork":false,"pushed_at":"2022-01-31T18:44:57.000Z","size":1360,"stargazers_count":1169,"open_issues_count":19,"forks_count":276,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-10-29T20:32:55.177Z","etag":null,"topics":["countries","geographic-data","iso3166","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carmen-ruby.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-03-17T19:18:42.000Z","updated_at":"2024-10-18T14:07:43.000Z","dependencies_parsed_at":"2022-07-07T21:23:45.787Z","dependency_job_id":null,"html_url":"https://github.com/carmen-ruby/carmen","commit_stats":null,"previous_names":["jim/carmen"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carmen-ruby%2Fcarmen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carmen-ruby%2Fcarmen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carmen-ruby%2Fcarmen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carmen-ruby%2Fcarmen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carmen-ruby","download_url":"https://codeload.github.com/carmen-ruby/carmen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248590279,"owners_count":21129774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["countries","geographic-data","iso3166","ruby"],"created_at":"2024-07-31T17:01:14.024Z","updated_at":"2025-04-12T15:36:08.340Z","avatar_url":"https://github.com/carmen-ruby.png","language":"Ruby","readme":"# Carmen\n\n\u003e A repository of geographic regions for Ruby\n\n[![Build Status](https://secure.travis-ci.org/carmen-ruby/carmen.svg?branch=master)](http://travis-ci.org/carmen-ruby/carmen)\n\nCarmen features the following:\n\n* Clean API\n* Complete countries \u0026 regions data from the iso-codes Debian package\n* A sane approach to internationalization\n\n# How to Use Carmen\n\nCarmen is designed to make it easy to access Country and region data.\nYou can query for a country by name or code:\n\n    require 'carmen'\n    include Carmen\n\n    us = Country.named('United States')\n    =\u003e \u003c#Carmen::Country name=\"United States\"\u003e\n\nA Country object has some attributes that may be useful:\n\n    us.alpha_2_code\n    =\u003e 'US'\n\n    us.alpha_3_code\n    =\u003e 'USA'\n\n    us.numeric_code\n    =\u003e '840'\n\n    us.code # alias for alpha_2_code\n    =\u003e 'US'\n\n    us.official_name\n    =\u003e \"United States of America\"\n\nYou can use separate finder methods for searching by each attribute (recommended):\n\n    gb = Country.alpha_2_coded('GB')\n    =\u003e \u003c#Carmen::Country name=\"United Kingdom\"\u003e\n\n    ru = Country.alpha_3_coded('RUS')\n    =\u003e \u003c#Carmen::Country name=\"Russian Federation\"\u003e\n\n    ad = Country.numeric_coded('020') # Note a string here! Alias: numerically_coded\n    =\u003e \u003c#Carmen::Country name=\"Andorra\"\u003e\n\n__NOTICE:__ Please note, that in `numeric_coded` you should pass a 3-symbol zero padded string. Be aware of the fact, that Ruby interprets integers with leading zero as octal number (`020 == 16 # =\u003e true`).\n\nYou can query country by any code in single method (not recommended, and will be deprecated):\n\n    us = Country.coded('US')\n    =\u003e \u003c#Carmen::Country name=\"United States\"\u003e\n\n    us = Country.coded('USA')\n    =\u003e \u003c#Carmen::Country name=\"United States\"\u003e\n\n    us = Country.coded('840') # Note a string here\n    =\u003e \u003c#Carmen::Country name=\"United States\"\u003e\n\nA `Country` (and its subregions) can contain subregions. In the US these are states, but other countries have other types of regions:\n\n    us.subregions?\n    =\u003e true\n\n    us.subregions.first\n      =\u003e \u003c#Carmen::Region name=\"Alabama\" type=\"state\"\u003e\n\n`Country#subregions` returns a `RegionCollection`, which can be queried\nsimilarly to a `Country` to find, for instance, a specific state:\n\n    illinois = us.subregions.coded('IL')\n    =\u003e \u003c#Carmen::Region \"Illinois\"\u003e\n\nYou can also find all subregions with a specific type:\n\n    states = us.subregions.typed('state')\n    =\u003e [\u003c#Carmen::Region name=\"Alaska\" type=\"state\"\u003e, \u003c#Carmen::Region name=\"Alabama\" type=\"state\"\u003e, ...]\n\nSubregions support a smaller set of attributes than countries:\n\n    illinois.name\n      =\u003e \"Illinois\"\n\n    illinois.code\n    =\u003e \"IL\"\n\n    illinois.type\n    =\u003e \"state\"\n\nSome subregions may contain additional subregions. An example of this is Spain:\n\n    spain = Country.named('Spain')\n    andalucia = spain.subregions.first\n    =\u003e \u003c#Carmen::Region name=\"Andalucía\" type=\"autonomous community\"\u003e\n\n    andalucia.subregions?\n    =\u003e true\n\n    andalucia.subregions.first\n    =\u003e \u003c#Carmen::Region name=\"Almería\" type=\"province\"\u003e\n\n## How Carmen organizes data\n\nIn order to facilitate support for I18n, Carmen stores the structure of regions\nseparately from the strings that represent a region's names. The default data\nthat ships with Carmen is in the iso_data and locale directories,\nrespectively.\n\n## Overriding structural data\n\nYou might want to tweak the data that Carmen provides for a variety of reasons. Carmen\nmaintains an array of paths to load data from in: `Carmen.data_paths`. The structure of\nfiles in each of these paths should mirror those in the `iso_data` path Carmen ships with.\n\nTo add a new country to the system, you would create a directory (let's use `my_data` as an example),\nand create a `world.yml` file inside it. Then add the path to Carman:\n\n    Carmen.append_data_path File.expand_path('../my_data', __FILE__)\n\nElements within the data files are identified using their `code` values (or, in the case of countries, `alpha_2_code`). Create a new block for the country you wish to add inside `my_data/world.yml`:\n\n    ---\n    - alpha_2_code: ZZ\n      alpha_3_code: ZZZ\n      numeric_code: \"999\"\n      type: country\n\nNow, modify the fields you wish to change, and delete the others. Be sure to specify `alpha_2_code` for countries and `code` for subregions, as those values are used internally by Carmen to match your customized data with the corresponding data in the default dataset.\n\nNow, Carmen will reflect your personal view of the world:\n\n    Carmen::Country.coded('ZZ').type\n    =\u003e \"country\"\n\nYou will also want to create a localization file with the names for the new\nregion. See the section 'Customizing an existing locale', below.\n\n### Modifying existing elements\n\nExisting regions can be modified by copying their existing data block into\na new file at the correct overlay path, and modifying the values as desired.\n\n### Disabling elements\n\nIt is also possible to remove an element from the dataset by setting its `_enabled` value to [anything YAML considers false](http://yaml.org/type/bool.html), such as 'false' or 'no':\n\n    - alpha_2_code: EU\n      _enabled: false\n\nThis will cause Carmen to not return that element from any query:\n\n    Carmen::Country.coded('EU')\n    =\u003e nil\n\n## Localization\n\nCarmen ships with very simple I18n support. You can tell Carmen to use your own\nI18n backend:\n\n    Carmen.i18n_backend = YourI18nBackend.new\n\nThe object used as a backend must respond to `t` with a single argument (the\nkey being looked up). This key will look something like `world.us.il.name`.\n\n## Setting the locale\n\nIf you use the built in I18n support, you can set the locale:\n\n    Carmen.i18n_backend.locale = :es\n\nEach region is assigned\na localization key based on the formula world.PARENT\\_CODE.CODE. The\nkey used for the United States is `world.us`.\n\n## Customizing an existing locale\n\nThe library ships with a set of YAML files that contain localizations of many\ncountry names (and some states). If you want to override any of these values,\ncreate a YAML file that contains a nested hash structure, where each segment of\nthe key is a hash:\n\n    en:\n      world:\n        us:\n          official_name: These Crazy States\n\nThis file can live anywhere, but it is recommended that it be stored in\na structure similar to the one Carmen uses for its locale storage.\n\nTo tell Carmen to load this file, add the directory it is contained in to the\nset of locale paths used by the backend:\n\n    Carmen.i18n_backend.append_locale_path('/path/to/your/locale/files')\n\nIf you are using your own backend, then follow the steps necessary to have it\nload your additional files instead.\n\n\n## Contributing to Carmen\n\nPlease read [Contributing Data](https://github.com/jim/carmen/wiki/Contributing-Data) before making any changes to the project's data. It will save you (and me) a bunch of time!\n\n## Extensions\n\n[Jacob Morris](https://github.com/jacobsimeon) has created [a plugin for Carmen that adds support for demonyms](https://github.com/jacobsimeon/carmen-demonyms).\n\n[Cyle Hunter](https://github.com/nozpheratu) has created [a plugin that adds ISO 4217 currency names to Carmen::Country](https://github.com/nozpheratu/carmen-iso-4217).\n","funding_links":[],"categories":["Country Data","Ruby","ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarmen-ruby%2Fcarmen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarmen-ruby%2Fcarmen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarmen-ruby%2Fcarmen/lists"}