countries 3.0.1 → 5.0.1

data/lib/countries/country/emoji.rb

@@ -1,5 +1,4 @@
-#!/bin/env ruby
-# encoding: utf-8
+# frozen_string_literal: true
 
 module ISO3166
   module Emoji
@@ -32,8 +31,11 @@ module ISO3166
       'z' => '🇿'
     }.freeze
 
+    # @return [String] the emoji flag for this country
+    #
+    # The emoji flag for this country, using Unicode Regional Indicator characters. e.g: "U+1F1FA U+1F1F8" for 🇺🇸
     def emoji_flag
-      alpha2.downcase.chars.map { |c| CODE_POINTS[c] }.join('')
+      alpha2.downcase.chars.map { |c| CODE_POINTS[c] }.join
     end
   end
 end

data/lib/countries/country/finder_methods.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ISO3166
+  module CountryFinderMethods
+    FIND_BY_REGEX = /^find_(all_)?(country_|countries_)?by_(.+)/.freeze
+    SEARCH_TERM_FILTER_REGEX = /\(|\)|\[\]|,/.freeze
+
+    def search(query)
+      country = new(query.to_s.upcase)
+      country&.valid? ? country : nil
+    end
+
+    def [](query)
+      search(query)
+    end
+
+    def find_all_by(attribute, val)
+      attributes, lookup_value = parse_attributes(attribute, val)
+
+      ISO3166::Data.cache.select do |_, v|
+        country = Country.new(v)
+        attributes.any? do |attr|
+          Array(country.send(attr)).any? do |n|
+            lookup_value === cached(n) { parse_value(n) }
+          end
+        end
+      end
+    end
+
+    def method_missing(method_name, *arguments)
+      matches = method_name.to_s.match(FIND_BY_REGEX)
+      return_all = matches[1]
+      super unless matches
+
+      countries = find_by(matches[3], arguments[0], matches[2])
+      return_all ? countries : countries.last
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      matches = method_name.to_s.match(FIND_BY_REGEX)
+      if matches && matches[3]
+        instance_methods.include?(matches[3].to_sym)
+      else
+        super
+      end
+    end
+
+    protected
+
+    def find_by(attribute, value, obj = nil)
+      find_all_by(attribute.downcase, value).map do |country|
+        obj.nil? ? country : new(country.last)
+      end
+    end
+
+    def parse_attributes(attribute, val)
+      raise "Invalid attribute name '#{attribute}'" unless searchable_attribute?(attribute.to_sym)
+
+      attributes = Array(attribute.to_s)
+      if attribute.to_s == 'any_name'
+        attributes = %w[iso_long_name iso_short_name unofficial_names translated_names]
+      end
+
+      [attributes, parse_value(val)]
+    end
+
+    def parse_value(value)
+      value = value.gsub(SEARCH_TERM_FILTER_REGEX, '') if value.respond_to?(:gsub)
+      strip_accents(value)
+    end
+
+    def searchable_attribute?(attribute)
+      searchable_attributes.include?(attribute.to_sym)
+    end
+
+    def searchable_attributes
+      # Add name and names until we complete the deprecation of the finders
+      instance_methods - UNSEARCHABLE_METHODS + [:name, :names, :any_name]
+    end
+  end
+end

data/lib/countries/country.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 module ISO3166
   class Country
     extend CountryClassMethods
+    extend CountryFinderMethods
     include Emoji
     attr_reader :data
 
@@ -28,8 +31,8 @@ module ISO3166
     alias zip postal_code
     alias zip? postal_code
     alias postal_code? postal_code
+    alias zip_format postal_code_format
     alias languages languages_official
-    alias names unofficial_names
 
     def ==(other)
       other.respond_to?(:alpha2) && other.alpha2 == alpha2
@@ -47,14 +50,12 @@ module ISO3166
       to_s <=> other.to_s
     end
 
-    def start_of_week
-      data['start_of_week']
-    end
-
+    #  +true+ if this Country has any Subdivisions.
     def subdivisions?
       !subdivisions.empty?
     end
 
+    # @return [Array<ISO3166::Subdivision>] the list of subdivisions for this Country.
     def subdivisions
       @subdivisions ||= if data['subdivisions']
                           self.class.create_subdivisions(data['subdivisions'])
@@ -63,33 +64,51 @@ module ISO3166
                         end
     end
 
+    # @param locale [String] The locale to use for translations.
+    # @return [Array<Array>] This Country's subdivision pairs of names and codes.
     def subdivision_names_with_codes(locale = 'en')
       subdivisions.map { |k, v| [v.translations[locale] || v.name, k] }
     end
 
     alias states subdivisions
 
+    # +true+ if this country is a member of the European Union.
     def in_eu?
       data['eu_member'].nil? ? false : data['eu_member']
     end
 
+    # +true+ if this country is a member of the European Economic Area.
     def in_eea?
       data['eea_member'].nil? ? false : data['eea_member']
     end
 
+    # +true+ if this country is a member of the European Single Market.
+    def in_esm?
+      data['esm_member'].nil? ? in_eea? : data['esm_member']
+    end
+
     def to_s
-      data['name']
+      data['iso_short_name']
     end
 
+    # @return [Array<String>] the list of names for this Country in all loaded locales.
     def translated_names
       data['translations'].values
     end
 
+    # @param locale [String] The locale to use for translations.
+    # @return [String] the name of this Country in the selected locale.
     def translation(locale = 'en')
       data['translations'][locale.to_s.downcase]
     end
 
-    # TODO: Looping through locale langs could be be very slow across multiple countries
+    # @return [String] the “common name” of this Country in English.
+    def common_name
+      ISO3166.configuration.locales = ISO3166.configuration.locales.append(:en).uniq
+      translation('en')
+    end
+
+    # @return [Array<String>] TThe list of names for this Country, in this Country's locales.
     def local_names
       ISO3166.configuration.locales = (ISO3166.configuration.locales + languages.map(&:to_sym)).uniq
       reload
@@ -97,10 +116,99 @@ module ISO3166
       @local_names ||= languages.map { |language| translations[language] }
     end
 
+    # @return [String] The name for this Country, in this Country's locale.
     def local_name
       @local_name ||= local_names.first
     end
 
+    # @!attribute alpha2
+    #   @return [String] the ISO3166 alpha-2 code for this Country
+    #
+    # @!attribute alpha3
+    #   @return [String] the ISO3166 alpha-3 code for this Country
+    #
+    # @!attribute address_format
+    #   @return [String] a template for formatting addresses in this Country.
+    #
+    # @!attribute continent
+    #   @return [String] the continent for this Country
+    #
+    # @!attribute country_code
+    #   @return [String] the country calling code for this Country
+    #
+    # @!attribute currency_code
+    #   @return [String] the ISO 4217 currency code for this Country
+    #
+    # @!attribute gec
+    #   @return [String] the "Geopolitical Entities and Codes", formerly FIPS 10-4 code for this Country
+    #
+    # @!attribute geo
+    #   @return [Hash] the hash of coordinates for this Country.
+    #
+    # @!attribute international_prefix
+    #   @return [String] the phone prefix used in this Country for dialing international numbers
+    #
+    # @!attribute ioc
+    #   @return [String] The International Olympic Committee code for for this Country
+    #
+    # @!attribute national_destination_code_lengths
+    #   @return [Array<Integer>] Lengths of phone number destination codes
+    #
+    # @!attribute national_number_lengths
+    #   @return [Array<Integer>] Lengths of phone numbers
+    #
+    # @!attribute national_prefix
+    #   @return [String] the phone prefix used in this Country for dialing national numbers
+    #
+    # @!attribute nanp_prefix
+    #   @return [String] the NANP prefix code
+    #
+    # @!attribute nationality
+    #   @return [String] the nationality for this Country, in English
+    #
+    # @!attribute number
+    #   @return [String] The ISO 3166-1 numeric code for this Country
+    #
+    # @!attribute languages_official
+    #   @return [Array<String>] the list of official languages (locale codes) for this Country
+    #
+    # @!attribute languages_spoken
+    #   @return [Array<String>] the list of spoken languages (locale codes) for this Country
+    #
+    # @!attribute translations
+    #   @return [Hash] The hash of country name translations for this Country.
+    #
+    # @!attribute postal_code
+    #   @return [Boolean] Does this Country uses postal codes in addresses
+    #
+    # @!attribute postal_code_format
+    #   @return [String] The regex for valid postal codes in this Country
+    #
+    # @!attribute region
+    #   @return [String] The Region this country is in. Approximately matches the United Nations geoscheme
+    #
+    # @!attribute unofficial_names
+    #   @return [Array<String>] Array of unofficial, slang names or aliases for this Country
+    #
+    # @!attribute start_of_week
+    # @return [String] The starting day of the week ( +'monday'+ or +'sunday'+ )
+    #
+    # @!attribute subregion
+    #   @return [String] The Subegion this country is in. Approximately matches the United Nations geoscheme's Subregions
+    #
+    # @!attribute un_locode
+    #   @return [String] The UN/LOCODE prefix for this Country
+    #
+    # @!attribute vat_rates
+    #   @return [Hash] the hash of VAT Rates for this Country
+    #
+    # @!attribute world_region
+    #   @return [String] The "World Region" this country is in: +"AMER"+ , +"APAC"+ or +"EMEA"+
+
+
+
+    private
+
     def reload
       @data = if @country_data_or_code.is_a?(Hash)
                 @country_data_or_code

data/lib/countries/data/countries/AD.yaml

@@ -1,13 +1,33 @@
 ---
 AD:
-  continent: Europe
   alpha2: AD
   alpha3: AND
+  continent: Europe
   country_code: '376'
+  currency_code: EUR
+  gec: AN
+  geo:
+    latitude: 42.506285
+    longitude: 1.521801
+    max_latitude: 42.655791
+    max_longitude: 1.786639
+    min_latitude: 42.4287488
+    min_longitude: 1.4087052
+    bounds:
+      northeast:
+        lat: 42.655791
+        lng: 1.786639
+      southwest:
+        lat: 42.4287488
+        lng: 1.4087052
   international_prefix: '00'
   ioc: AND
-  gec: AN
-  name: Andorra
+  iso_long_name: The Principality of Andorra
+  iso_short_name: Andorra
+  languages_official:
+  - ca
+  languages_spoken:
+  - ca
   national_destination_code_lengths:
   - 2
   national_number_lengths:
@@ -16,36 +36,16 @@ AD:
   - 8
   - 9
   national_prefix: None
+  nationality: Andorran
   number: '020'
+  postal_code: true
+  postal_code_format: AD[1-7]0\d
   region: Europe
+  start_of_week: monday
   subregion: Southern Europe
-  world_region: EMEA
   un_locode: AD
-  nationality: Andorran
-  postal_code: true
   unofficial_names:
   - Andorre
   - Andorra
   - アンドラ
-  languages_official:
-  - ca
-  languages_spoken:
-  - ca
-  geo:
-    latitude: 42.506285
-    latitude_dec: '42.5506591796875'
-    longitude: 1.521801
-    longitude_dec: '1.5762332677841187'
-    max_latitude: 42.655791
-    max_longitude: 1.786639
-    min_latitude: 42.4287488
-    min_longitude: 1.4087052
-    bounds:
-      northeast:
-        lat: 42.655791
-        lng: 1.786639
-      southwest:
-        lat: 42.4287488
-        lng: 1.4087052
-  currency_code: EUR
-  start_of_week: monday
+  world_region: EMEA

data/lib/countries/data/countries/AE.yaml

@@ -1,6 +1,5 @@
 ---
 AE:
-  continent: Asia
   address_format: |-
     {{recipient}}
     {{street}}
@@ -8,11 +7,32 @@ AE:
     {{country}}
   alpha2: AE
   alpha3: ARE
+  continent: Asia
   country_code: '971'
+  currency_code: AED
+  gec: AE
+  geo:
+    latitude: 23.424076
+    longitude: 53.847818
+    max_latitude: 26.0765
+    max_longitude: 56.4395001
+    min_latitude: 22.6315138
+    min_longitude: 51.4723
+    bounds:
+      northeast:
+        lat: 26.0765
+        lng: 56.4395001
+      southwest:
+        lat: 22.6315138
+        lng: 51.4723
   international_prefix: '00'
   ioc: UAE
-  gec: AE
-  name: United Arab Emirates
+  iso_long_name: The United Arab Emirates
+  iso_short_name: United Arab Emirates
+  languages_official:
+  - ar
+  languages_spoken:
+  - ar
   national_destination_code_lengths:
   - 2
   national_number_lengths:
@@ -20,18 +40,13 @@ AE:
   - 8
   - 9
   national_prefix: '0'
+  nationality: Emirian
   number: '784'
+  postal_code: false
   region: Asia
+  start_of_week: monday
   subregion: Western Asia
-  world_region: EMEA
   un_locode: AE
-  nationality: Emirian
-  vat_rates:
-    standard: 5
-    reduced: []
-    super_reduced: 
-    parking: 
-  postal_code: false
   unofficial_names:
   - United Arab Emirates
   - الإمارات العربية المتحدة
@@ -40,25 +55,9 @@ AE:
   - Emiratos Árabes Unidos
   - アラブ首長国連邦
   - Verenigde Arabische Emiraten
-  languages_official:
-  - ar
-  languages_spoken:
-  - ar
-  geo:
-    latitude: 23.424076
-    latitude_dec: '23.684776306152344'
-    longitude: 53.847818
-    longitude_dec: '54.536643981933594'
-    max_latitude: 26.0765
-    max_longitude: 56.4395001
-    min_latitude: 22.6315138
-    min_longitude: 51.4723
-    bounds:
-      northeast:
-        lat: 26.0765
-        lng: 56.4395001
-      southwest:
-        lat: 22.6315138
-        lng: 51.4723
-  currency_code: AED
-  start_of_week: sunday
+  vat_rates:
+    standard: 5
+    reduced: []
+    super_reduced:
+    parking:
+  world_region: EMEA

data/lib/countries/data/countries/AF.yaml

@@ -1,43 +1,14 @@
 ---
 AF:
-  continent: Asia
   alpha2: AF
   alpha3: AFG
+  continent: Asia
   country_code: '93'
-  international_prefix: '00'
-  ioc: AFG
+  currency_code: AFN
   gec: AF
-  name: Afghanistan
-  national_destination_code_lengths:
-  - 2
-  national_number_lengths:
-  - 8
-  - 9
-  national_prefix: '0'
-  number: '004'
-  region: Asia
-  subregion: Southern Asia
-  world_region: APAC
-  un_locode: AF
-  nationality: Afghan
-  postal_code: true
-  unofficial_names:
-  - Afghanistan
-  - Afganistán
-  - アフガニスタン
-  languages_official:
-  - ps
-  - uz
-  - tk
-  languages_spoken:
-  - ps
-  - uz
-  - tk
   geo:
     latitude: 33.93911
-    latitude_dec: '33.833248138427734'
     longitude: 67.709953
-    longitude_dec: '66.02528381347656'
     max_latitude: 38.49087670000001
     max_longitude: 74.8898619
     min_latitude: 29.3772
@@ -49,5 +20,34 @@ AF:
       southwest:
         lat: 29.3772
         lng: 60.5170005
-  currency_code: AFN
+  international_prefix: '00'
+  ioc: AFG
+  iso_long_name: The Islamic Republic of Afghanistan
+  iso_short_name: Afghanistan
+  languages_official:
+  - ps
+  - uz
+  - tk
+  languages_spoken:
+  - ps
+  - uz
+  - tk
+  national_destination_code_lengths:
+  - 2
+  national_number_lengths:
+  - 8
+  - 9
+  national_prefix: '0'
+  nationality: Afghan
+  number: '004'
+  postal_code: true
+  postal_code_format: "\\d{4}"
+  region: Asia
   start_of_week: monday
+  subregion: Southern Asia
+  un_locode: AF
+  unofficial_names:
+  - Afghanistan
+  - Afganistán
+  - アフガニスタン
+  world_region: APAC

data/lib/countries/data/countries/AG.yaml

@@ -1,26 +1,46 @@
 ---
 AG:
-  continent: North America
   alpha2: AG
   alpha3: ATG
+  continent: North America
   country_code: '1'
-  nanp_prefix: '1268'
+  currency_code: XCD
+  gec: AC
+  geo:
+    latitude: 17.060816
+    longitude: -61.796428
+    max_latitude: 17.7499946
+    max_longitude: -61.6394
+    min_latitude: 16.9018
+    min_longitude: -62.38100009999999
+    bounds:
+      northeast:
+        lat: 17.7499946
+        lng: -61.6394
+      southwest:
+        lat: 16.9018
+        lng: -62.38100009999999
   international_prefix: '011'
   ioc: ANT
-  gec: AC
-  name: Antigua and Barbuda
+  iso_long_name: Antigua and Barbuda
+  iso_short_name: Antigua and Barbuda
+  languages_official:
+  - en
+  languages_spoken:
+  - en
+  nanp_prefix: '1268'
   national_destination_code_lengths:
   - 3
   national_number_lengths:
   - 10
   national_prefix: '1'
-  number: 028
+  nationality: Antiguan, Barbudan
+  number: '028'
+  postal_code: false
   region: Americas
+  start_of_week: monday
   subregion: Caribbean
-  world_region: AMER
   un_locode: AG
-  nationality: Antiguan, Barbudan
-  postal_code: false
   unofficial_names:
   - Antigua and Barbuda
   - Antigua und Barbuda
@@ -28,25 +48,4 @@ AG:
   - Antigua y Barbuda
   - アンティグア・バーブーダ
   - Antigua en Barbuda
-  languages_official:
-  - en
-  languages_spoken:
-  - en
-  geo:
-    latitude: 17.060816
-    latitude_dec: '17.09273910522461'
-    longitude: -61.796428
-    longitude_dec: "-61.81040954589844"
-    max_latitude: 17.7499946
-    max_longitude: -61.6394
-    min_latitude: 16.9018
-    min_longitude: -62.38100009999999
-    bounds:
-      northeast:
-        lat: 17.7499946
-        lng: -61.6394
-      southwest:
-        lat: 16.9018
-        lng: -62.38100009999999
-  currency_code: XCD
-  start_of_week: monday
+  world_region: AMER

data/lib/countries/data/countries/AI.yaml

@@ -1,38 +1,14 @@
 ---
 AI:
-  continent: North America
   alpha2: AI
   alpha3: AIA
+  continent: North America
   country_code: '1'
-  nanp_prefix: '1264'
-  international_prefix: '011'
-  ioc: 
+  currency_code: XCD
   gec: AV
-  name: Anguilla
-  national_destination_code_lengths:
-  - 3
-  national_number_lengths:
-  - 10
-  national_prefix: '1'
-  number: '660'
-  region: Americas
-  subregion: Caribbean
-  world_region: AMER
-  un_locode: AI
-  nationality: Anguillian
-  postal_code: true
-  unofficial_names:
-  - Anguilla
-  - アンギラ
-  languages_official:
-  - en
-  languages_spoken:
-  - en
   geo:
     latitude: 18.220554
-    latitude_dec: '18.22646713256836'
     longitude: -63.06861499999999
-    longitude_dec: "-63.0473518371582"
     max_latitude: 18.6332326
     max_longitude: -62.91999999999999
     min_latitude: 18.1465043
@@ -44,5 +20,29 @@ AI:
       southwest:
         lat: 18.1465043
         lng: -63.4803
-  currency_code: XCD
+  international_prefix: '011'
+  ioc:
+  iso_long_name: Anguilla
+  iso_short_name: Anguilla
+  languages_official:
+  - en
+  languages_spoken:
+  - en
+  nanp_prefix: '1264'
+  national_destination_code_lengths:
+  - 3
+  national_number_lengths:
+  - 10
+  national_prefix: '1'
+  nationality: Anguillian
+  number: '660'
+  postal_code: true
+  postal_code_format: "(?:AI-)?2640"
+  region: Americas
   start_of_week: monday
+  subregion: Caribbean
+  un_locode: AI
+  unofficial_names:
+  - Anguilla
+  - アンギラ
+  world_region: AMER