addressing 1.0.0 → 2.0.1

data/lib/addressing/address_format.rb

@@ -1,20 +1,31 @@
 # frozen_string_literal: true
 
 module Addressing
+  # Provides address format information for countries.
+  #
+  # Address formats define which fields are used, their order, requirements,
+  # and formatting rules for postal addresses in different countries.
+  #
+  # @example Get address format for Brazil
+  #   format = Addressing::AddressFormat.get('BR')
+  #   format.used_fields      # => ["given_name", "family_name", ...]
+  #   format.required_fields  # => ["address_line1", "locality", ...]
   class AddressFormat
     class << self
-      # The instantiated address formats, keyed by country code.
-      @@address_formats = {}
-
+      # Gets the address format for the provided country code.
+      #
+      # @param country_code [String] ISO 3166-1 alpha-2 country code
+      # @return [AddressFormat] Address format instance
       def get(country_code)
         country_code = country_code.upcase
+        @address_formats ||= {}
 
-        unless @@address_formats.key?(country_code)
+        unless @address_formats.key?(country_code)
           definition = process_definition(definitions[country_code] || {country_code: country_code})
-          @@address_formats[country_code] = new(definition)
+          @address_formats[country_code] = new(definition)
         end
 
-        @@address_formats[country_code]
+        @address_formats[country_code]
       end
 
       def all
@@ -27,7 +38,7 @@ module Addressing
       private
 
       def definitions
-        @@definitions ||= Marshal.load(File.read(File.expand_path("../../../data/address_formats.dump", __FILE__).to_s))
+        @definitions ||= Marshal.load(File.read(File.expand_path("../../../data/address_formats.dump", __FILE__).to_s))
       end
 
       def process_definition(definition)
@@ -42,7 +53,7 @@ module Addressing
 
       def generic_definition
         {
-          format: "%given_name %family_name\n%organization\n%address_line1\n%address_line2\n\address_line3\n%locality",
+          format: "%given_name %family_name\n%organization\n%address_line1\n%address_line2\n%address_line3\n%locality",
           required_fields: [
             "address_line1", "locality"
           ],

data/lib/addressing/country.rb

@@ -1,34 +1,55 @@
 # frozen_string_literal: true
 
 module Addressing
+  # Provides country information including names, codes, currency, and timezones.
+  #
+  # Country names are available in over 250 locales powered by CLDR data.
+  #
+  # @example Get a country by code
+  #   brazil = Addressing::Country.get('BR')
+  #   brazil.name          # => "Brazil"
+  #   brazil.currency_code # => "BRL"
+  #
+  # @example Get all countries
+  #   countries = Addressing::Country.all('fr-FR')
+  #
+  # @example Get a simple list of countries
+  #   list = Addressing::Country.list('en')
   class Country
     class << self
-      @@definitions = {}
-
-      @@available_locales = [
-        "af", "am", "ar", "ar-LY", "ar-SA", "as", "az", "be", "bg", "bn",
-        "bn-IN", "bs", "ca", "chr", "cs", "cy", "da", "de", "de-AT", "de-CH",
-        "dsb", "el", "el-polyton", "en", "en-001", "en-AU", "en-CA", "en-ID",
-        "en-MV", "es", "es-419", "es-AR", "es-BO", "es-CL", "es-CO", "es-CR",
-        "es-DO", "es-EC", "es-GT", "es-HN", "es-MX", "es-NI", "es-PA", "es-PE",
-        "es-PR", "es-PY", "es-SV", "es-US", "es-VE", "et", "eu", "fa", "fa-AF",
-        "fi", "fil", "fr", "fr-BE", "fr-CA", "ga", "gd", "gl", "gu", "he",
-        "hi", "hi-Latn", "hr", "hsb", "hu", "hy", "id", "ig", "is", "it", "ja",
-        "ka", "kk", "km", "ko", "ko-KP", "kok", "ky", "lo", "lt", "lv", "mk",
-        "ml", "mn", "mr", "ms", "my", "ne", "nl", "nn", "no", "or", "pa", "pl",
-        "ps", "ps-PK", "pt", "pt-PT", "ro", "ro-MD", "ru", "ru-UA", "si", "sk",
-        "sl", "so", "sq", "sr", "sr-Cyrl-BA", "sr-Cyrl-ME", "sr-Cyrl-XK",
-        "sr-Latn", "sr-Latn-BA", "sr-Latn-ME", "sr-Latn-XK", "sv", "sw",
-        "sw-CD", "sw-KE", "ta", "te", "th", "tk", "tr", "uk", "ur", "ur-IN",
-        "uz", "vi", "yue", "yue-Hans", "zh", "zh-Hant", "zh-Hant-HK", "zu"
+      AVAILABLE_LOCALES = [
+        "af", "ak", "am", "ar", "ar-LY", "ar-SA", "as", "az", "ba", "be", "bg",
+        "bn", "bn-IN", "bs", "ca", "chr", "cs", "cv", "cy", "da", "de",
+        "de-AT", "de-CH", "dsb", "el", "el-polyton", "en", "en-001", "en-AU",
+        "en-CA", "en-EE", "en-GE", "en-LT", "en-LV", "en-UA", "es", "es-419",
+        "es-AR", "es-BO", "es-CL", "es-CO", "es-CR", "es-DO", "es-EC", "es-GT",
+        "es-HN", "es-MX", "es-NI", "es-PA", "es-PE", "es-PR", "es-PY", "es-SV",
+        "es-US", "es-VE", "et", "eu", "fa", "fa-AF", "fi", "fil", "fr",
+        "fr-BE", "fr-CA", "ga", "gd", "gl", "gu", "he", "hi", "hi-Latn", "hr",
+        "hsb", "hu", "hy", "id", "ig", "is", "it", "ja", "ka", "kk", "kk-Arab",
+        "km", "ko", "ko-KP", "kok", "ky", "lo", "lt", "lv", "mk", "ml", "mn",
+        "mr", "ms", "my", "ne", "nl", "nn", "no", "or", "pa", "pl", "ps",
+        "ps-PK", "pt", "pt-PT", "qu", "rm", "ro", "ro-MD", "ru", "ru-UA",
+        "shn", "si", "sk", "sl", "so", "sq", "sr", "sr-Cyrl-BA", "sr-Cyrl-ME",
+        "sr-Cyrl-XK", "sr-Latn", "sr-Latn-BA", "sr-Latn-ME", "sr-Latn-XK",
+        "sv", "sw", "sw-CD", "sw-KE", "ta", "te", "th", "tk", "tr", "uk", "ur",
+        "ur-IN", "uz", "vi", "yue", "yue-Hans", "zh", "zh-Hant", "zh-Hant-HK",
+        "zu"
       ]
 
+      # Gets a Country instance for the provided country code.
+      #
+      # @param country_code [String] ISO 3166-1 alpha-2 country code
+      # @param locale [String] Locale for the country name (default: "en")
+      # @param fallback_locale [String] Fallback locale if requested locale is unavailable
+      # @return [Country] Country instance
+      # @raise [UnknownCountryError] if the country code is not recognized
       def get(country_code, locale = "en", fallback_locale = "en")
         country_code = country_code.upcase
 
-        raise UnknownCountryError, country_code unless base_definitions.key?(country_code)
+        raise UnknownCountryError.new(country_code) unless base_definitions.key?(country_code)
 
-        locale = Locale.resolve(@@available_locales, locale, fallback_locale)
+        locale = Locale.resolve(AVAILABLE_LOCALES, locale, fallback_locale)
         definitions = load_definitions(locale)
 
         new(
@@ -41,8 +62,13 @@ module Addressing
         )
       end
 
+      # Gets all Country instances.
+      #
+      # @param locale [String] Locale for country names (default: "en")
+      # @param fallback_locale [String] Fallback locale if requested locale is unavailable
+      # @return [Hash<String, Country>] Hash of country code => Country instance
       def all(locale = "en", fallback_locale = "en")
-        locale = Locale.resolve(@@available_locales, locale, fallback_locale)
+        locale = Locale.resolve(AVAILABLE_LOCALES, locale, fallback_locale)
         definitions = load_definitions(locale)
 
         definitions.map do |country_code, country_name|
@@ -59,8 +85,13 @@ module Addressing
         end.to_h
       end
 
+      # Gets a list of country codes and names.
+      #
+      # @param locale [String] Locale for country names (default: "en")
+      # @param fallback_locale [String] Fallback locale if requested locale is unavailable
+      # @return [Hash<String, String>] Hash of country code => country name
       def list(locale = "en", fallback_locale = "en")
-        locale = Locale.resolve(@@available_locales, locale, fallback_locale)
+        locale = Locale.resolve(AVAILABLE_LOCALES, locale, fallback_locale)
         definitions = load_definitions(locale)
 
         definitions.map do |country_code, country_name|
@@ -72,19 +103,20 @@ module Addressing
 
       # Loads the country definitions for the provided locale.
       def load_definitions(locale)
-        unless @@definitions.key?(locale)
+        @definitions ||= {}
+        unless @definitions.key?(locale)
           filename = File.join(File.expand_path("../../../data/country", __FILE__).to_s, "#{locale}.json")
-          @@definitions[locale] = JSON.parse(File.read(filename))
+          @definitions[locale] = JSON.parse(File.read(filename))
         end
 
-        @@definitions[locale]
+        @definitions[locale]
       end
 
       # Gets the base country definitions.
       #
       # Contains data common to all locales: three letter code, numeric code.
       def base_definitions
-        @@base_definitions ||= {
+        @base_definitions ||= {
           "AC" => ["ASC", nil, "SHP"],
           "AD" => ["AND", "020", "EUR"],
           "AE" => ["ARE", "784", "AED"],
@@ -107,7 +139,7 @@ module Addressing
           "BD" => ["BGD", "050", "BDT"],
           "BE" => ["BEL", "056", "EUR"],
           "BF" => ["BFA", "854", "XOF"],
-          "BG" => ["BGR", "100", "BGN"],
+          "BG" => ["BGR", "100", "EUR"],
           "BH" => ["BHR", "048", "BHD"],
           "BI" => ["BDI", "108", "BIF"],
           "BJ" => ["BEN", "204", "XOF"],
@@ -234,7 +266,7 @@ module Addressing
           "MG" => ["MDG", "450", "MGA"],
           "MH" => ["MHL", "584", "USD"],
           "MK" => ["MKD", "807", "MKD"],
-          "ML" => ["MLI", "466", "XOF"],
+          "ML" => ["MLI", "466", nil],
           "MM" => ["MMR", "104", "MMK"],
           "MN" => ["MNG", "496", "MNT"],
           "MO" => ["MAC", "446", "MOP"],
@@ -272,7 +304,7 @@ module Addressing
           "PM" => ["SPM", "666", "EUR"],
           "PN" => ["PCN", "612", "NZD"],
           "PR" => ["PRI", "630", "USD"],
-          "PS" => ["PSE", "275", "JOD"],
+          "PS" => ["PSE", "275", "ILS"],
           "PT" => ["PRT", "620", "EUR"],
           "PW" => ["PLW", "585", "USD"],
           "PY" => ["PRY", "600", "PYG"],
@@ -340,7 +372,7 @@ module Addressing
           "YT" => ["MYT", "175", "EUR"],
           "ZA" => ["ZAF", "710", "ZAR"],
           "ZM" => ["ZMB", "894", "ZMW"],
-          "ZW" => ["ZWE", "716", "USD"]
+          "ZW" => ["ZWE", "716", "ZWG"]
         }
       end
     end

data/lib/addressing/default_formatter.rb

@@ -2,8 +2,13 @@
 
 module Addressing
   class DefaultFormatter
+    DEFAULT_LOCALE = "en"
+    FORMAT_PLACEHOLDER_PATTERN = /%[a-z1-9_]+/
+    LEADING_TRAILING_PUNCTUATION_PATTERN = /\A[ \-,]+|[ \-,]+\z/
+    MULTIPLE_SPACES_PATTERN = /\s\s+/
+
     DEFAULT_OPTIONS = {
-      locale: "en",
+      locale: DEFAULT_LOCALE,
       html: true,
       html_tag: "p",
       html_attributes: {translate: "no"}
@@ -13,6 +18,7 @@ module Addressing
       assert_options(default_options)
 
       @default_options = self.class::DEFAULT_OPTIONS.merge(default_options)
+      @country_list_cache = {}
     end
 
     def format(address, options = {})
@@ -33,7 +39,7 @@ module Addressing
       view = render_view(view)
 
       replacements = view.map { |key, element| ["%#{key}", element] }.to_h
-      output = format_string.gsub(/%[a-z1-9_]+/) { |m| replacements[m] }
+      output = format_string.gsub(FORMAT_PLACEHOLDER_PATTERN) { |m| replacements[m] }
       output = clean_output(output)
 
       if options[:html]
@@ -49,7 +55,7 @@ module Addressing
 
     # Builds the view for the given address.
     def build_view(address, address_format, options)
-      countries = Country.list(options[:locale])
+      countries = country_list(options[:locale])
       values = values(address, address_format).merge({"country" => countries.key?(address.country_code) ? countries[address.country_code] : address.country_code})
       used_fields = address_format.used_fields + ["country"]
 
@@ -58,6 +64,11 @@ module Addressing
       end.to_h
     end
 
+    # Gets the country list for a locale, with caching.
+    def country_list(locale)
+      @country_list_cache[locale] ||= Country.list(locale)
+    end
+
     # Renders the given view.
     def render_view(view)
       view.map do |key, element|
@@ -90,27 +101,34 @@ module Addressing
 
     # Removes empty lines, leading punctuation, excess whitespace.
     def clean_output(output)
-      output.split("\n").map { |line| line.gsub(/\A[ \-,]+|[ \-,]+\z/, "").strip.gsub(/\s\s+/, " ") }.reject(&:empty?).join("\n")
+      output.split("\n").map { |line| line.gsub(LEADING_TRAILING_PUNCTUATION_PATTERN, "").strip.gsub(MULTIPLE_SPACES_PATTERN, " ") }.reject(&:empty?).join("\n")
     end
 
     # Gets the address values used to build the view.
     def values(address, address_format)
-      values = AddressField.all.map { |_, field| [field, address.send(field)] }.to_h
+      values = extract_address_values(address)
+      resolve_subdivision_values(values, address, address_format)
+      values
+    end
+
+    # Extracts all address field values.
+    def extract_address_values(address)
+      AddressField.all.map { |_, field| [field, address.send(field)] }.to_h
+    end
+
+    # Resolves subdivision values to their display codes.
+    def resolve_subdivision_values(values, address, address_format)
       subdivision_fields = address_format.used_subdivision_fields
 
       # Replace the subdivision values with the names of any predefined ones.
       subdivision_fields.each_with_index.inject([{}, []]) do |(original_values, parents), (field, index)|
-        if values[field].nil?
-          # This level is empty, so there can be no sublevels.
-          break
-        end
+        # This level is empty, so there can be no sublevels.
+        break if values[field].nil?
 
         parents << ((index > 0) ? original_values[subdivision_fields[index - 1]] : address.country_code)
 
         subdivision = Subdivision.get(values[field], parents)
-        if subdivision.nil?
-          break
-        end
+        break if subdivision.nil?
 
         # Remember the original value so that it can be used for parents.
         original_values[field] = values[field]
@@ -119,15 +137,11 @@ module Addressing
         use_local_name = Locale.match_candidates(address.locale, subdivision.locale)
         values[field] = use_local_name ? subdivision.local_code : subdivision.code
 
-        if !subdivision.children?
-          # The current subdivision has no children, stop.
-          break
-        end
+        # The current subdivision has no children, stop.
+        break unless subdivision.children?
 
         [original_values, parents]
       end
-
-      values
     end
 
     private
@@ -142,7 +156,7 @@ module Addressing
         end
       end
 
-      if options.key?(:html) && !options[:html].is_a?(TrueClass) && !options[:html].is_a?(FalseClass)
+      if options.key?(:html) && ![true, false].include?(options[:html])
         raise ArgumentError, "The option `html` must be a boolean."
       end
 

data/lib/addressing/enum.rb

@@ -3,15 +3,14 @@
 module Addressing
   class Enum
     class << self
-      @@values = {}
-
       # Gets all available values.
       def all
-        if !@@values.key?(name)
-          @@values[name] = constants.map { |constant| [constant, const_get(constant)] }.to_h
+        @values ||= {}
+        if !@values.key?(name)
+          @values[name] = constants.map { |constant| [constant, const_get(constant)] }.to_h
         end
 
-        @@values[name]
+        @values[name]
       end
 
       # Gets the key of the provided value.

data/lib/addressing/exceptions.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Addressing
+  # Base error class for all Addressing errors
+  class Error < StandardError; end
+
+  # Raised when an unknown country code is provided
+  class UnknownCountryError < Error
+    def initialize(country_code)
+      super("Unknown country code: #{country_code}")
+      @country_code = country_code
+    end
+
+    attr_reader :country_code
+  end
+
+  # Raised when an unknown locale is provided
+  class UnknownLocaleError < Error
+    def initialize(locale)
+      super("Unknown locale: #{locale}")
+      @locale = locale
+    end
+
+    attr_reader :locale
+  end
+
+  # Raised when an invalid argument is provided
+  class InvalidArgumentError < Error; end
+end

data/lib/addressing/field_override.rb

@@ -14,20 +14,13 @@ module Addressing
       AddressField.assert_all_exist(definition.keys)
       FieldOverride.assert_all_exist(definition.values)
 
-      @hidden_fields = []
-      @optional_fields = []
-      @required_fields = []
+      # Group fields by their override type
+      grouped = definition.group_by { |_field, override| override }
+        .transform_values { |pairs| pairs.map(&:first) }
 
-      definition.each do |field, override|
-        case override
-        when FieldOverride::HIDDEN
-          @hidden_fields << field
-        when FieldOverride::OPTIONAL
-          @optional_fields << field
-        when FieldOverride::REQUIRED
-          @required_fields << field
-        end
-      end
+      @hidden_fields = grouped[FieldOverride::HIDDEN] || []
+      @optional_fields = grouped[FieldOverride::OPTIONAL] || []
+      @required_fields = grouped[FieldOverride::REQUIRED] || []
     end
   end
 end

data/lib/addressing/locale.rb

@@ -52,36 +52,49 @@ module Addressing
       "en-150" => "en-001",
       "en-AG" => "en-001",
       "en-AI" => "en-001",
+      "en-AT" => "en-150",
       "en-AU" => "en-001",
       "en-BB" => "en-001",
+      "en-BE" => "en-150",
       "en-BM" => "en-001",
       "en-BS" => "en-001",
       "en-BW" => "en-001",
       "en-BZ" => "en-001",
       "en-CC" => "en-001",
+      "en-CH" => "en-150",
       "en-CK" => "en-001",
       "en-CM" => "en-001",
       "en-CX" => "en-001",
       "en-CY" => "en-001",
+      "en-CZ" => "en-150",
+      "en-DE" => "en-150",
       "en-DG" => "en-001",
+      "en-DK" => "en-150",
       "en-DM" => "en-001",
       "en-ER" => "en-001",
+      "en-ES" => "en-150",
+      "en-FI" => "en-150",
       "en-FJ" => "en-001",
       "en-FK" => "en-001",
       "en-FM" => "en-001",
+      "en-FR" => "en-150",
       "en-GB" => "en-001",
       "en-GD" => "en-001",
       "en-GG" => "en-001",
       "en-GH" => "en-001",
       "en-GI" => "en-001",
       "en-GM" => "en-001",
+      "en-GS" => "en-001",
       "en-GY" => "en-001",
       "en-HK" => "en-001",
+      "en-HU" => "en-150",
+      "en-ID" => "en-001",
       "en-IE" => "en-001",
       "en-IL" => "en-001",
       "en-IM" => "en-001",
       "en-IN" => "en-001",
       "en-IO" => "en-001",
+      "en-IT" => "en-150",
       "en-JE" => "en-001",
       "en-JM" => "en-001",
       "en-KE" => "en-001",
@@ -96,24 +109,33 @@ module Addressing
       "en-MS" => "en-001",
       "en-MT" => "en-001",
       "en-MU" => "en-001",
+      "en-MV" => "en-001",
       "en-MW" => "en-001",
       "en-MY" => "en-001",
       "en-NA" => "en-001",
       "en-NF" => "en-001",
       "en-NG" => "en-001",
+      "en-NL" => "en-150",
+      "en-NO" => "en-150",
       "en-NR" => "en-001",
       "en-NU" => "en-001",
       "en-NZ" => "en-001",
       "en-PG" => "en-001",
       "en-PK" => "en-001",
+      "en-PL" => "en-150",
       "en-PN" => "en-001",
+      "en-PT" => "en-150",
       "en-PW" => "en-001",
+      "en-RO" => "en-150",
       "en-RW" => "en-001",
       "en-SB" => "en-001",
       "en-SC" => "en-001",
       "en-SD" => "en-001",
+      "en-SE" => "en-150",
       "en-SG" => "en-001",
       "en-SH" => "en-001",
+      "en-SI" => "en-150",
+      "en-SK" => "en-150",
       "en-SL" => "en-001",
       "en-SS" => "en-001",
       "en-SX" => "en-001",
@@ -132,15 +154,6 @@ module Addressing
       "en-ZA" => "en-001",
       "en-ZM" => "en-001",
       "en-ZW" => "en-001",
-      "en-AT" => "en-150",
-      "en-BE" => "en-150",
-      "en-CH" => "en-150",
-      "en-DE" => "en-150",
-      "en-DK" => "en-150",
-      "en-FI" => "en-150",
-      "en-NL" => "en-150",
-      "en-SE" => "en-150",
-      "en-SI" => "en-150",
       "es-AR" => "es-419",
       "es-BO" => "es-419",
       "es-BR" => "es-419",
@@ -163,12 +176,13 @@ module Addressing
       "es-US" => "es-419",
       "es-UY" => "es-419",
       "es-VE" => "es-419",
+      "hi-Latn" => "und",
+      "ht" => "fr-HT",
       "nb" => "no",
       "nn" => "no",
       "pt-AO" => "pt-PT",
       "pt-CH" => "pt-PT",
       "pt-CV" => "pt-PT",
-      "pt-FR" => "pt-PT",
       "pt-GQ" => "pt-PT",
       "pt-GW" => "pt-PT",
       "pt-LU" => "pt-PT",
@@ -184,7 +198,6 @@ module Addressing
       "byn-Latn" => "und",
       "en-Dsrt" => "und",
       "en-Shaw" => "und",
-      "hi-Latn" => "und",
       "iu-Latn" => "und",
       "kk-Arab" => "und",
       "ks-Deva" => "und",
@@ -251,7 +264,7 @@ module Addressing
       end
 
       # No locale could be resolved, stop here.
-      raise UnknownLocaleError, locale if resolved_locale.nil?
+      raise UnknownLocaleError.new(locale) if resolved_locale.nil?
 
       resolved_locale
     end

data/lib/addressing/model.rb

@@ -20,12 +20,6 @@ module Addressing
           return unless address.country_code.present?
 
           address_format = AddressFormat.get(address.country_code)
-          address_format.used_fields
-
-          return unless address.country_code.present?
-
-          address_format = AddressFormat.get(address.country_code)
-          address_format.used_fields
 
           # Validate the presence of required fields.
           AddressFormatHelper.required_fields(address_format, field_overrides).each do |required_field|

data/lib/addressing/postal_label_formatter.rb

@@ -3,7 +3,7 @@
 module Addressing
   class PostalLabelFormatter < DefaultFormatter
     DEFAULT_OPTIONS = {
-      locale: "en",
+      locale: DEFAULT_LOCALE,
       html: false,
       html_tag: "p",
       html_attributes: {translate: "no"},