countries 3.0.1 → 5.0.1

data/README.markdown

@@ -2,39 +2,38 @@
 
 Countries is a collection of all sorts of useful information for every country in the ISO 3166 standard. It contains info for the following standards ISO3166-1 (countries), ISO3166-2 (states/subdivisions), ISO4217 (currency) and E.164 (phone numbers). I will add any country based data I can get access to. I hope this to be a repository for all country based information.
 
-[![Gem Version](https://badge.fury.io/rb/countries.svg)](https://badge.fury.io/rb/countries) [![Build Status](https://travis-ci.org/hexorx/countries.svg)](https://travis-ci.org/hexorx/countries) [![Code Climate](https://codeclimate.com/github/hexorx/countries.svg)](https://codeclimate.com/github/hexorx/countries)
+[![Gem Version](https://badge.fury.io/rb/countries.svg)](https://badge.fury.io/rb/countries) [![Tests](https://github.com/countries/countries/actions/workflows/tests.yml/badge.svg)](https://github.com/countries/countries/actions/workflows/tests.yml) [![Code Climate](https://codeclimate.com/github/countries/countries.svg)](https://codeclimate.com/github/countries/countries)
+ [![CodeQL](https://github.com/countries/countries/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/countries/countries/actions/workflows/codeql-analysis.yml)
+
 
 ## Installation
 
-``` bash
-gem install countries
-```
+```bash
+ gem install countries
+ ```
 
-Or you can install via Bundler if you are using Rails. Add this line to your application's Gemfile:
+ Or you can install via Bundler if you are using Rails:
 
-```ruby
-gem 'countries'
+```bash
+bundle add countries
 ```
 
-And then execute:
-
-    $ bundle
-
 ## Basic Usage
 
 Simply load a new country object using Country.new(*alpha2*) or the shortcut Country[*alpha2*]. An example works best.
 
-``` ruby
+```ruby
 c = ISO3166::Country.new('US')
 ```
 
 ## Configuration
 
-#### Country Helper
+### Country Helper
+
 Some apps might not want to constantly call `ISO3166::Country` this gem has a
 helper that can provide a `Country` class
 
-``` ruby
+```ruby
 # With global Country Helper
 c = Country['US']
 ```
@@ -43,40 +42,53 @@ c = Country['US']
 
 To Use
 
-``` ruby
+```ruby
 gem 'countries', require: 'countries/global'
 ```
 
-## Upgrading to 3.x
+## Upgrading to 4.2 and 5.x
 
-We dropped currency support via money by default, see [instructions](README.markdown#Currencies) if you are using currency featues
+In release 4.2 the `#name` attribute was deprecated in favour of `#iso_short_name` and we added the `#iso_long_name` attribute, to make it clear that these attributes use the ISO3166 names, and are not the "common names" most people might expect, eg: The ISO name for "United Kingdom" is "United Kingdom of Great Britain and Northern Ireland", but if you're building a dropdown box to select a country, you're likely expecting to see "United Kingdom" instead.
 
-## Upgrading Country Helper to > 1.2.0
-``` ruby
-gem 'countries', require: 'global'
-```
+"Common names" in English have been available in the translation data, via `#translation('en')`. As of release 4.2, a shortcut method has been added for simplicity, `#common_name`, which delegates to `#translation('en')`.
 
-has become
-``` ruby
-gem 'countries', require: 'countries/global'
-```
+For additional clarity, the `#names` method, which was an alias to `#unofficial_names` has also been deprecated, together with the finder methods that use `name` or `names` attributes.
+
+The `#name` and `#names` attributes, and corresponding finder methods were removed in 5.0.
+
+The replacement finders added in 5.0 are:
+
+- `#find_by_name` => `#find_by_any_name` - Searches all the name attributes, same as before
+- `#find_by_names` => `#find_by_unofficial_names`
+- `#find_*_by_name` => `#find_*_by_any_name`
+- `#find_*_by_names` => `#find_*_by_unofficial_names`
+
+With the addition of the new name attributes, there are now also the following finders:
+
+- `#find_by_common_name`/`#find_*_by_common_name`
+- `#find_by_iso_short_name`/`#find_*_by_iso_short_name`
+- `#find_by_iso_long_name`/`#find_*_by_iso_long_name`
+
+For translated country names, we use data from [pkg-isocodes](https://salsa.debian.org/iso-codes-team/iso-codes), via the [i18n_data](https://github.com/grosser/i18n_data) gem, and these generally correspond to the expected "common names". These names and the corresponding methods have not been changed.
+
+The 5.0 release removed support for Ruby 2.5 (EOL 2021-03-01) and 2.6 (EOL 2022-03-31)
 
 ## Selective Loading of Locales
 
 As of 2.0 you can selectively load locales to reduce memory usage in production.
 
-By default we load I18n.available_locales if I18n is present, otherwise only [:en]. This means almost any rails environment will only bring in its supported translations.
+By default we load `I18n.available_locales` if I18n is present, otherwise only `[:en]`. This means almost any Rails environment will only bring in its supported translations.
 
 You can add all the locales like this.
 
-``` ruby
+```ruby
 ISO3166.configure do |config|
   config.locales = [:af, :am, :ar, :as, :az, :be, :bg, :bn, :br, :bs, :ca, :cs, :cy, :da, :de, :dz, :el, :en, :eo, :es, :et, :eu, :fa, :fi, :fo, :fr, :ga, :gl, :gu, :he, :hi, :hr, :hu, :hy, :ia, :id, :is, :it, :ja, :ka, :kk, :km, :kn, :ko, :ku, :lt, :lv, :mi, :mk, :ml, :mn, :mr, :ms, :mt, :nb, :ne, :nl, :nn, :oc, :or, :pa, :pl, :ps, :pt, :ro, :ru, :rw, :si, :sk, :sl, :so, :sq, :sr, :sv, :sw, :ta, :te, :th, :ti, :tk, :tl, :tr, :tt, :ug, :uk, :ve, :vi, :wa, :wo, :xh, :zh, :zu]
 end
 ```
 
 or something a bit more simple
-``` ruby
+```ruby
 ISO3166.configure do |config|
   config.locales = [:en, :de, :fr, :es]
 end
@@ -86,15 +98,19 @@ end
 
 You can lookup a country or an array of countries using any of the data attributes via the find\_country\_by_*attribute* dynamic methods:
 
-``` ruby
-c    = ISO3166::Country.find_country_by_name('united states')
+```ruby
+c    = ISO3166::Country.find_country_by_iso_short_name('italy')
+c    = ISO3166::Country.find_country_by_any_name('united states')
+h    = ISO3166::Country.find_all_by(:translated_names, 'França')
 list = ISO3166::Country.find_all_countries_by_region('Americas')
 c    = ISO3166::Country.find_country_by_alpha3('can')
 ```
 
-For a list of available attributes please see ISO3166::DEFAULT_COUNTRY_HASH.
+For a list of available attributes please see `ISO3166::DEFAULT_COUNTRY_HASH`.
 Note: searches are *case insensitive and ignore accents*.
 
+_Please note that `find_by_name`, `find_by_names`, `find_*_by_name` and `find_*_by_names`  methods were removed in 5.0. See [Upgrading to 4.2 and 5.x](#upgrading-to-4-2-and-5-x) above for the new methods_
+
 ## Country Info
 
 ### Identification Codes
@@ -106,10 +122,12 @@ c.alpha3 # => "USA"
 c.gec    # => "US"
 ```
 
-###  Names & Translations
+### Names & Translations
 
 ```ruby
-c.name # => "United States"
+c.iso_long_name # => "The United States of America"
+c.iso_short_name # => "United States of America"
+c.common_name # => "United States" (This is a shortcut for c.translations('en'))
 c.unofficial_names # => ["United States of America", "Vereinigte Staaten von Amerika", "États-Unis", "Estados Unidos"]
 
 # Get the names for a country translated to its local languages
@@ -125,27 +143,34 @@ ISO3166::Country.translations         # {"DE"=>"Germany",...}
 ISO3166::Country.translations('DE')   # {"DE"=>"Deutschland",...}
 ISO3166::Country.all_translated       # ['Germany', ...]
 ISO3166::Country.all_translated('DE') # ['Deutschland', ...]
+
+# Nationality
+c.nationality # => "American"
 ```
 
 ### Subdivisions & States
 
-``` ruby
+```ruby
 c.subdivisions # => {"CO" => {"name" => "Colorado", "names" => "Colorado"}, ... }
 c.states # => {"CO" => {"name" => "Colorado", "names" => "Colorado"}, ... }
+
+# Get specific translations for the country subdivisions
+c.subdivision_names_with_codes('es') #=> [ ..., ["Nuevo Hampshire", "NH"], ["Nueva Jersey", "NJ"], ... ]
 ```
 
 ### Location
 
-``` ruby
-c.latitude # => "38 00 N"
-c.longitude # => "97 00 W"
-c.latitude_dec # => 39.44325637817383
-c.longitude_dec # => -98.95733642578125
+```ruby
+c.latitude # => "37.09024"
+c.longitude # => "-95.712891"
 
+c.world_region # => "AMER"
 c.region # => "Americas"
 c.subregion # => "Northern America"
 ```
 
+Please note that `latitude_dec` and `longitude_dec` were deprecated on release 4.2 and removed in 5.0. These attributes have been redundant for several years, since the `latitude` and `longitude` fields have been switched decimal coordinates.
+
 ### Timezones **(optional)**
 
 Add `tzinfo` to your Gemfile and ensure it's required, Countries will not do this for you.
@@ -154,15 +179,15 @@ Add `tzinfo` to your Gemfile and ensure it's required, Countries will not do thi
 gem 'tzinfo', '~> 1.2', '>= 1.2.2'
 ```
 
-``` ruby
+```ruby
 c.timezones.zone_identifiers # => ["America/New_York", "America/Detroit", "America/Kentucky/Louisville", ...]
-c.timezones.zone_info  # see [tzinfo docs]( http://www.rubydoc.info/gems/tzinfo/TZInfo/CountryInfo)
-c.timezones # see [tzinfo docs]( http://www.rubydoc.info/gems/tzinfo/TZInfo/Country)
+c.timezones.zone_info  # see [tzinfo docs](https://www.rubydoc.info/gems/tzinfo/TZInfo/CountryTimezone)
+c.timezones # see [tzinfo docs](https://www.rubydoc.info/gems/tzinfo/TZInfo/Country)
 ```
 
 ### Telephone Routing (E164)
 
-``` ruby
+```ruby
 c.country_code # => "1"
 c.national_destination_code_lengths # => 3
 c.national_number_lengths # => 10
@@ -172,38 +197,57 @@ c.national_prefix # => "1"
 
 ### Boundary Boxes
 
-``` ruby
+```ruby
 c.min_longitude # => '45'
 c.min_latitude # => '22.166667'
 c.max_longitude # => '58'
 c.max_latitude # => '26.133333'
+
+c.bounds #> {"northeast"=>{"lat"=>22.166667, "lng"=>58}, "southwest"=>{"lat"=>26.133333, "lng"=>45}}
 ```
 
 ### European Union Membership
 
-``` ruby
+```ruby
 c.in_eu? # => false
 ```
 
+### European Economic Area Membership
+
+```ruby
+c.in_eea? # => false
+```
+
+
+### European Single Market Membership
+
+```ruby
+c.in_esm? # => false
+```
+
+### Plucking multiple attributes
+
+```ruby
+ISO3166::Country.pluck(:alpha2, :iso_short_name) # => [["AD", "Andorra"], ["AE", "United Arab Emirates"], ...
+```
+
 ## Currencies
 
 To enable currencies extension please add the following to countries initializer.
 
-``` ruby
+```ruby
 ISO3166.configuration.enable_currency_extension!
 ```
 
 Please note that it requires you to add "money" dependency to your gemfile.
 
-``` ruby
+```ruby
 gem "money", "~> 6.9"
 ```
 
-**WARNING** if you have a top level class named `Money` you will conflict with this gem.  If this is a large issue we will add a feature to turn currency features off.
-
-Countries now uses the [Money](https://github.com/RubyMoney/money) gem. What this means is you now get back a Money::Currency object that gives you access to all the currency information.
+Countries now uses the [Money](https://github.com/RubyMoney/money) gem. What this means is you now get back a `Money::Currency` object that gives you access to all the currency information.
 
-``` ruby
+```ruby
 c = ISO3166::Country['us']
 c.currency.iso_code # => 'USD'
 c.currency.name # => 'United States Dollar'
@@ -212,9 +256,9 @@ c.currency.symbol # => '$'
 
 ## Address Formatting
 
-A template for formatting addresses is available through the address_format method. These templates are compatible with the [Liquid][] template system.
+A template for formatting addresses is available through the address_format method. These templates are compatible with the [Liquid](https://shopify.github.io/liquid/) template system.
 
-``` ruby
+```ruby
 c.address_format # => "{{recipient}}\n{{street}}\n{{city}} {{region}} {{postalcode}}\n{{country}}"
 ```
 
@@ -224,17 +268,17 @@ As of 2.0 countries supports loading custom countries / overriding data in its d
 
 Any country registered this way will have its data available for searching etc... If you are overriding an existing country, for cultural reasons, our code uses a simple merge, not a deep merge so you will need to __bring in all data you wish to be available__.  Bringing in an existing country will also remove it from the internal management of translations, __all registered countries will remain in memory__.
 
-``` ruby
+```ruby
 ISO3166::Data.register(
   alpha2: 'LOL',
-  name: 'Happy Country',
+  iso_short_name: 'Happy Country',
   translations: {
     'en' => 'Happy Country',
     'de' => 'glückliches Land'
   }
 )
 
-ISO3166::Country.new('LOL').name == 'Happy Country'
+ISO3166::Country.new('LOL').iso_short_name == 'Happy Country'
 ```
 
 ## Mongoid
@@ -253,38 +297,39 @@ Searching:
 
 ```ruby
 # By alpha2
-british_things = Things.where(country: 'GB')
-british_things.first.country.name    # => "United Kingdom"
+spanish_things = Things.where(country: 'ES')
+spanish_things.first.country.iso_short_name    # => "Spain"
 
 # By object
-british_things = Things.where(country: Country.find_by_name('United Kingdom')[1])
-british_things.first.country.name    # => "United Kingdom"
+spanish_things = Things.where(country: Country.find_by_iso_short_name('Spain')[1])
+spanish_things.first.country.iso_short_name    # => "Spain"
 ```
+
 Saving:
 
 ```ruby
 # By alpha2
-british_thing = Thing.new(country: 'GB')
-british_thing.save!
-british_thing.country.name    # => "United Kingdom"
+spanish_things = Thing.new(country: 'ES')
+spanish_things.save!
+spanish_things.country.iso_short_name    # => "Spain"
 
 # By object
-british_thing = Thing.new(country: Country.find_by_name('United Kingdom')[1])
-british_thing.save!
-british_thing.country.name    # => "United Kingdom"
+spanish_things = Thing.new(country: Country.find_by_iso_short_name('Spain')[1])
+spanish_things.save!
+spanish_things.country.iso_short_name    # => "Spain"
 ```
 
 Note that the database stores only the alpha2 code and rebuilds the object when queried. To return the country name by default you can override the reader method in your model:
 
-``` ruby
+```ruby
 def country
-  super.name
+  super.iso_short_name
 end
 ```
 
 ## Country Code in Emoji
 
-``` ruby
+```ruby
 c = Country['MY']
 c.emoji_flag # => "🇲🇾"
 ```
@@ -295,7 +340,7 @@ c.emoji_flag # => "🇲🇾"
 
 Any additions should be directed upstream to [pkg-isocodes](https://salsa.debian.org/iso-codes-team/iso-codes)
 
-New Bugs can be filed upstream here https://salsa.debian.org/iso-codes-team/iso-codes/issues
+Localized country name data is sourced from https://github.com/grosser/i18n_data (which is based on https://salsa.debian.org/iso-codes-team/iso-codes/). Issues regarding localized country names can be reported to https://github.com/grosser/i18n_data/issues or https://salsa.debian.org/iso-codes-team/iso-codes/issues
 If you need to correct an upstream translation please add it to the lib/countries/data/translations_corrections.yaml
 
 ```
@@ -307,7 +352,7 @@ If you need to correct an upstream translation please add it to the lib/countrie
 ```
 
 Any corrections can be applied in translations_corrections.yaml these will be injected during
-the next ```rake update_cache```
+the next `rake update_cache`.
 
 * Fork the project.
 * Make your feature addition or bug fix.
@@ -320,12 +365,8 @@ the next ```rake update_cache```
 
 ## Copyright
 
-Copyright (c) 2016 hexorx. See LICENSE for details.
+Copyright (c) 2012-2015 hexorx
+Copyright (c) 2015-2021 hexorx, rposborne
+Copyright (c) 2022 hexorx, rposborne, pmor
 
-[Teliax]: http://teliax.com
-[Centrex]: http://en.wikipedia.org/wiki/Centrex
-[CommonDataHub]: http://commondatahub.com
-[Currencies]: http://gemcutter.org/gems/currencies
-[Money]: http://gemcutter.org/gems/money
-[Liquid]: http://www.liquidmarkup.org/
-[country_select]: https://github.com/stefanpenner/country_select
+See LICENSE for details.

data/Rakefile

@@ -1,10 +1,17 @@
 #!/usr/bin/env rake
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 
 require 'rake'
 require 'rspec/core/rake_task'
+require 'yaml'
 
 ISO3166_ROOT_PATH = File.dirname(__FILE__)
+
+# Enter your API Key enabled for Geocoding API and Places API
+GOOGLE_API_KEY = 'ENTER API KEY'
+
 Dir.glob('lib/countries/tasks/*.rake').each { |r| load r }
 
 desc 'Run all examples'
@@ -14,39 +21,6 @@ end
 
 task default: [:spec]
 
-task :update_yaml_structure do
-  require 'yaml'
-
-  require 'pry'
-
-  d = Dir['lib/countries/data/subdivisions/*.yaml']
-  d.each do |file|
-    puts "checking : #{file}"
-    data = YAML.load_file(file)
-
-    data = data.each_with_object({}) do |(k, subd), a|
-      a[k] ||= {}
-      a[k]['unofficial_names'] = subd.delete('names')
-      a[k]['translations'] = { 'en' => subd['name'] }
-      a[k]['geo'] = {
-        'latitude' => subd.delete('latitude'),
-        'longitude' => subd.delete('longitude'),
-        'min_latitude' => subd.delete('min_latitude'),
-        'min_longitude' => subd.delete('min_longitude'),
-        'max_latitude' => subd.delete('max_latitude'),
-        'max_longitude' => subd.delete('max_longitude')
-      }
-
-      a[k] = a[k].merge(subd)
-    end
-    File.open(file, 'w') { |f| f.write data.to_yaml }
-    begin
-  rescue
-    puts "failed to read #{file}: #{$ERROR_INFO}"
-  end
-  end
-end
-
 desc 'Update CLDR subdivison data set'
 task :update_cldr_subdivison_data do
   require_relative './lib/countries/sources'
@@ -59,12 +33,15 @@ task :update_cache do
   require 'yaml'
   require 'i18n_data'
 
-  codes = Dir['lib/countries/data/countries/*.yaml'].map { |x| File.basename(x, File.extname(x)) }.uniq
+  codes = Dir['lib/countries/data/countries/*.yaml'].map { |x| File.basename(x, File.extname(x)) }.uniq.sort
   data = {}
 
-  corrections = YAML.load_file(File.join(File.dirname(__FILE__), 'lib', 'countries', 'data', 'translation_corrections.yaml')) || {}
+  corrections_file = File.join(File.dirname(__FILE__), 'lib', 'countries', 'data', 'translation_corrections.yaml')
+  corrections = YAML.load_file(corrections_file) || {}
 
-  language_keys = I18nData.languages.keys + ['zh_CN', 'zh_TW', 'zh_HK','bn_IN','pt_BR']
+  language_keys = I18nData.languages.keys + %w[zh_CN zh_TW zh_HK bn_IN pt_BR]
+  # Ignore locales that have bad data in i18n_data 0.16.0
+  language_keys -= %w[AY AM BA]
   language_keys.each do |locale|
     locale = locale.downcase
     begin
@@ -74,18 +51,19 @@ task :update_cache do
     end
 
     # Apply any known corrections to i18n_data
-    unless corrections[locale].nil?
-      corrections[locale].each do |alpha2, localized_name|
-        local_names[alpha2] = localized_name
-      end
+    corrections[locale]&.each do |alpha2, localized_name|
+      local_names[alpha2] = localized_name
     end
 
-    File.open(File.join(File.dirname(__FILE__), 'lib', 'countries', 'cache', 'locales', "#{locale.gsub(/_/, '-')}.json"), 'wb') { |f| f.write(local_names.to_json) }
+    out = File.join(File.dirname(__FILE__), 'lib', 'countries', 'cache', 'locales', "#{locale.gsub(/_/, '-')}.json")
+    File.binwrite(out, local_names.to_json)
   end
 
   codes.each do |alpha2|
-    data[alpha2] ||= YAML.load_file(File.join(File.dirname(__FILE__), 'lib', 'countries', 'data', 'countries', "#{alpha2}.yaml"))[alpha2]
+    country_file = File.join(File.dirname(__FILE__), 'lib', 'countries', 'data', 'countries', "#{alpha2}.yaml")
+    data[alpha2] ||= YAML.load_file(country_file)[alpha2]
   end
 
-  File.open(File.join(File.dirname(__FILE__), 'lib', 'countries', 'cache', 'countries.json'), 'wb') { |f| f.write(data.to_json) }
+  out_file = File.join(File.dirname(__FILE__), 'lib', 'countries', 'cache', 'countries.json')
+  File.binwrite(out_file, data.to_json)
 end

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'countries'

data/countries.gemspec

@@ -1,12 +1,18 @@
-# -*- encoding: utf-8 -*-
-require File.expand_path('../lib/countries/version', __FILE__)
+# frozen_string_literal: true
+
+require File.expand_path('lib/countries/version', __dir__)
 
 Gem::Specification.new do |gem|
-  gem.authors       = ['Josh Robinson', 'Joe Corcoran', 'Russell Osborne']
-  gem.email         = ['hexorx@gmail.com', 'russell@burningpony.com']
+  gem.authors       = ['Josh Robinson', 'Joe Corcoran', 'Russell Osborne', 'Pedro Moreira']
+  gem.email         = ['hexorx@gmail.com', 'russell@burningpony.com', 'pedro@codecreations.tech']
   gem.description   = 'All sorts of useful information about every country packaged as pretty little country objects. It includes data from ISO 3166'
   gem.summary       = 'Gives you a country object full of all sorts of useful information.'
-  gem.homepage      = 'http://github.com/hexorx/countries'
+  gem.homepage      = 'https://github.com/countries/countries'
+  gem.metadata      = { 'bug_tracker_uri' => 'https://github.com/countries/countries/issues',
+                        'changelog_uri' => 'https://github.com/countries/countries/blob/master/CHANGELOG.md',
+                        'source_code_uri' => 'https://github.com/countries/countries',
+                        'wiki_uri' => 'https://github.com/countries/countries/wiki',
+                        'rubygems_mfa_required' => 'true' }
 
   gem.files         = `git ls-files`.split($OUTPUT_RECORD_SEPARATOR)
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
@@ -15,10 +21,11 @@ Gem::Specification.new do |gem|
   gem.version       = Countries::VERSION.dup
   gem.license       = 'MIT'
 
-  gem.add_dependency('i18n_data', '~> 0.10.0')
-  gem.add_dependency('unicode_utils', '~> 1.4')
+  gem.required_ruby_version = '>= 2.7'
+
+  gem.add_dependency('i18n_data', '~> 0.16.0')
   gem.add_dependency('sixarm_ruby_unaccent', '~> 1.1')
-  gem.add_development_dependency('rspec', '>= 3')
   gem.add_development_dependency('activesupport', '>= 3')
   gem.add_development_dependency('nokogiri', '>= 1.8')
+  gem.add_development_dependency('rspec', '>= 3')
 end