countries 4.2.0 → 4.2.1

data/lib/countries/configuration.rb

@@ -24,6 +24,19 @@ module ISO3166
       @loaded_locales = []
     end
 
+    # Enables the integration with the {Money}[https://github.com/RubyMoney/money] gem
+    #
+    # Please note that it requires you to add "money" gem to your gemfile.
+    #
+    #   gem "money", "~> 6.9"
+    #
+    # *WARNING* if you have a top level class named +Money+ you will conflict with this gem.
+    #
+    # @example
+    #   c = ISO3166::Country['us']
+    #   c.currency.iso_code # => 'USD'
+    #   c.currency.name # => 'United States Dollar'
+    #   c.currency.symbol # => '$'
     def enable_currency_extension!
       require 'countries/country/currency_methods'
       ISO3166::Country.prepend(ISO3166::CountryCurrencyMethods)

data/lib/countries/country/currency_methods.rb

@@ -1,8 +1,11 @@
 require 'money'
 
 module ISO3166
-  # Optional extension which allows you to get back a Money::Currency object with all the currency info
+  # Optional extension which allows you to get back a +Money::Currency+ object with all the currency info.
+  # This requires enabling the integration with the {Money}[https://github.com/RubyMoney/money] gem (See {ISO3166::Configuration#enable_currency_extension!})
   module CountryCurrencyMethods
+
+    # @return [Money::Currency] The currency data for this Country's +currency_code+
     def currency
       Money::Currency.find(data['currency_code'])
     end

data/lib/countries/country/emoji.rb

@@ -32,6 +32,9 @@ 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('')
     end

data/lib/countries/country.rb

@@ -65,14 +65,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'])
@@ -81,20 +79,25 @@ 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
@@ -103,20 +106,24 @@ module ISO3166
       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
 
+    # @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
 
-    # TODO: Looping through locale langs could be be very slow across multiple countries
+    # @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
@@ -124,10 +131,13 @@ 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
 
+    # @return [String] This Country's ISO Short Name
+    # @deprecated Use {#iso_short_name} instead.
     def name
       if RUBY_VERSION =~ /^3\.\d\.\d/
         warn "DEPRECATION WARNING: The Country#name method has been deprecated. Please use Country#iso_short_name instead or refer to the README file for more information on this change.", uplevel: 1, category: :deprecated
@@ -137,6 +147,8 @@ module ISO3166
       iso_short_name
     end
 
+    # @return [Array<String>] Array of unofficial, slang names or aliases for this Country
+    # @deprecated Use {#unofficial_names} instead.
     def names
       if RUBY_VERSION =~ /^3\.\d\.\d/
         warn "DEPRECATION WARNING: The Country#names method has been deprecated. Please use Country#unofficial_names instead or refer to the README file for more information on this change.", uplevel: 1, category: :deprecated
@@ -146,6 +158,94 @@ module ISO3166
       unofficial_names
     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/IL.yaml

@@ -55,8 +55,6 @@ IL:
     reduced: []
     super_reduced:
     parking:
-  postal_code: true
-  postal_code_format: "\\d{5}(?:\\d{2})?"
   unofficial_names:
   - Israel
   - Israël

data/lib/countries/data/countries/KH.yaml

@@ -36,7 +36,7 @@ KH:
   nationality: Cambodian
   number: '116'
   postal_code: true
-  postal_code_format: "\\d{5}"
+  postal_code_format: "\\d{5,6}"
   region: Asia
   start_of_week: monday
   subregion: South-Eastern Asia

data/lib/countries/data/countries/TW.yaml

@@ -42,7 +42,7 @@ TW:
   nationality: Taiwanese
   number: '158'
   postal_code: true
-  postal_code_format: "\\d{3}(?:\\d{2})?"
+  postal_code_format: "\\d{3}(?:\\d{2,3})?"
   region: Asia
   start_of_week: monday
   subregion: Eastern Asia

data/lib/countries/data.rb

@@ -1,5 +1,4 @@
 module ISO3166
-  ##
   # Handles building the in memory store of countries data
   class Data
     @@cache_dir = [File.dirname(__FILE__), 'cache']
@@ -24,6 +23,9 @@ module ISO3166
         @@cache_dir = value
       end
 
+      # Registers a new Country with custom data.
+      # If you are overriding an existing country, this does not perform a deep merge so you will need to __bring in all data you wish to be available__.
+      # Overriding an existing country will also remove it from the internal management of translations.
       def register(data)
         alpha2 = data[:alpha2].upcase
         @@registered_data[alpha2] = deep_stringify_keys(data)
@@ -32,6 +34,7 @@ module ISO3166
         @@cache = cache.merge(@@registered_data)
       end
 
+      # Removes a country from the loaded data
       def unregister(alpha2)
         alpha2 = alpha2.to_s.upcase
         @@cache.delete(alpha2)
@@ -42,6 +45,7 @@ module ISO3166
         update_cache
       end
 
+      # Resets the loaded data and cache
       def reset
         @@cache = {}
         @@registered_data = {}

data/lib/countries/global.rb

@@ -1,5 +1,17 @@
 require 'countries'
 
+# Some apps might not want to constantly call +ISO3166::Country+. This gem has a helper that can provide a Country class
+#
+# With global Country Helper enabled
+#
+#   c = Country['US']
+#
+# This will conflict with any existing Country constant
+#
+# To Use
+#
+#   gem 'countries', require: 'countries/global'
+#
 class Country < ISO3166::Country
 
 end

data/lib/countries/mongoid.rb

@@ -5,6 +5,7 @@ module ISO3166
     end
 
     class << self
+      # Convert an +ISO3166::Country+ to the data that is stored by Mongoid.
       def mongoize(country)
         if country.is_a?(self) && !country.data.nil?
           country.alpha2
@@ -13,10 +14,12 @@ module ISO3166
         end
       end
 
+      # Get the object as it was stored with Mongoid, and instantiate an +ISO3166::Country+.
       def demongoize(alpha2)
         new(alpha2)
       end
 
+      # Convert an +ISO3166::Country+ to the data that is stored by Mongoid.
       def evolve(country)
         mongoize(country)
       end

data/lib/countries/sources/cldr/downloader.rb

@@ -4,8 +4,11 @@ require 'nokogiri'
 require 'fileutils'
 require 'json'
 
+# Support code to allow updating subdivision data from the Unicode CLDR repository
 module Sources
+  # Support code to allow updating subdivision data from the Unicode CLDR repository
   module CLDR
+    # Downloads data from the Unicode CLDR repository
     module Downloader
       module_function
 

data/lib/countries/sources/cldr/subdivision.rb

@@ -1,5 +1,6 @@
 module Sources
   module CLDR
+    # Auxiliary Subdivision class to support loading Unicode CLDR data to update local files
     class Subdivision
       attr_reader :xml, :language_code
       def initialize(language_code:, xml:)

data/lib/countries/sources/cldr/subdivision_updater.rb

@@ -5,6 +5,7 @@ require 'pry'
 
 module Sources
   module CLDR
+    # Updates local subdivision files with data from the Unicode CLDR repository
     class SubdivisionUpdater
       def call
         d = Dir['./tmp/cldr/trunk/common/subdivisions/*.xml']

data/lib/countries/sources/local/cached_loader.rb

@@ -1,5 +1,7 @@
 module Sources
+  # Support code to allow updating subdivision data from the Unicode CLDR repository
   module Local
+    # Loader for locally-cached data, to allow merging Unicode CLDR data with existing local data
     class CachedLoader
       attr_reader :klass
       def initialize(klass)

data/lib/countries/sources/local/subdivision.rb

@@ -1,5 +1,6 @@
 module Sources
   module Local
+    # Auxiliary Subdivision class to support loading the local subdivision data to be updated with Unicode CLDR data
     class Subdivision
       attr_reader :code
       def initialize(code)

data/lib/countries/timezones.rb

@@ -1,6 +1,8 @@
-# Extend Country class with support for timezones
 module ISO3166
-  # Extend Country class with support for timezones
+  # Extend Country class with support for timezones. Requires the  {tzinfo}[https://github.com/tzinfo/tzinfo] gem
+  #
+  #   gem 'tzinfo'
+  #
   module TimezoneExtensions
     def timezones
       @tz_country ||= TZInfo::Country.get(alpha2)

data/lib/countries/translations.rb

@@ -1,9 +1,8 @@
 module ISO3166
   # Extend the hash class to allow locale lookup fall back behavior
   #
-  # ex:
-  # if a country has translations for pt, and the user looks up `pt-br` fallback
-  # to `pt` to prevent from showing nil values
+  # E.g. if a country has translations for +pt+, and the user looks up +pt-br+ fallback
+  # to +pt+ to prevent from showing nil values
   class Translations < Hash
     def [](locale)
       super(locale) || super(locale.to_s.sub(/-.*/, ''))

data/lib/countries/version.rb

@@ -1,3 +1,3 @@
 module Countries
-  VERSION = '4.2.0'.freeze
+  VERSION = '4.2.1'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: countries
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 4.2.1
 platform: ruby
 authors:
 - Josh Robinson