addressing 2.0.1 → 2.2.0

data/lib/addressing/field_violation.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Addressing
+  # One field of an address that breaks a rule of the address format for its
+  # country, together with the kind of rule it breaks. A blank country code is
+  # also a field violation.
+  #
+  # field is the field as a symbol, such as :postal_code. kind is one of:
+  #
+  # - :blank, the field must not be blank.
+  # - :present, the field must be blank.
+  # - :invalid, the value matches no predefined subdivision or does not match
+  #   the postal code pattern.
+  #
+  # The kinds match the error types of Rails.
+  FieldViolation = Data.define(:field, :kind)
+end

data/lib/addressing/lazy_subdivisions.rb

@@ -1,33 +1,34 @@
 # frozen_string_literal: true
 
 module Addressing
+  # The children of a subdivision, loaded on first access.
+  #
+  # Behaves like the hash that Subdivision.all returns for the same parents.
   class LazySubdivisions
+    extend Forwardable
+    include Enumerable
+
+    def_delegators :subdivisions, :each, :size, :keys, :values, :key?, :include?, :member?, :[], :fetch, :select, :filter, :reject
+
     def initialize(parents)
       @parents = parents
-      @subdivisions = {}
-      @initialized = false
     end
 
-    def [](key)
-      do_initialize unless @initialized
-      @subdivisions[key]
+    # Checks for children without building them.
+    def empty?
+      @subdivisions ? @subdivisions.empty? : !Subdivision.any?(@parents)
     end
 
-    def any?
-      do_initialize unless @initialized
-      @subdivisions.any?
-    end
+    def any?(*args, &block)
+      return subdivisions.any?(*args, &block) if block || args.any?
 
-    def empty?
-      do_initialize unless @initialized
-      @subdivisions.empty?
+      !empty?
     end
 
     private
 
-    def do_initialize
-      @initialized = true
-      @subdivisions = Subdivision.all(@parents)
+    def subdivisions
+      @subdivisions ||= Subdivision.all(@parents)
     end
   end
 end

data/lib/addressing/locale.rb

@@ -2,228 +2,6 @@
 
 module Addressing
   class Locale
-    ALIASES = {
-      "az-AZ" => "az-Latn-AZ",
-      "bs-BA" => "bs-Latn-BA",
-      "ha-GH" => "ha-Latn-GH",
-      "ha-NE" => "ha-Latn-NE",
-      "ha-NG" => "ha-Latn-NG",
-      "in" => "id",
-      "in-ID" => "id-ID",
-      "iw" => "he",
-      "iw-IL" => "he-IL",
-      "kk-KZ" => "kk-Cyrl-KZ",
-      "ks-IN" => "ks-Arab-IN",
-      "ky-KG" => "ky-Cyrl-KG",
-      "mn-MN" => "mn-Cyrl-MN",
-      "mo" => "ro-MD",
-      "ms-BN" => "ms-Latn-BN",
-      "ms-MY" => "ms-Latn-MY",
-      "ms-SG" => "ms-Latn-SG",
-      "no" => "nb",
-      "no-NO" => "nb-NO",
-      "no-NO-NY" => "nn-NO",
-      "pa-IN" => "pa-Guru-IN",
-      "pa-PK" => "pa-Arab-PK",
-      "sh" => "sr-Latn",
-      "sh-BA" => "sr-Latn-BA",
-      "sh-CS" => "sr-Latn-RS",
-      "sh-YU" => "sr-Latn-RS",
-      "shi-MA" => "shi-Tfng-MA",
-      "sr-BA" => "sr-Cyrl-BA",
-      "sr-ME" => "sr-Latn-ME",
-      "sr-RS" => "sr-Cyrl-RS",
-      "sr-XK" => "sr-Cyrl-XK",
-      "tl" => "fil",
-      "tl-PH" => "fil-PH",
-      "tzm-MA" => "tzm-Latn-MA",
-      "ug-CN" => "ug-Arab-CN",
-      "uz-AF" => "uz-Arab-AF",
-      "uz-UZ" => "uz-Latn-UZ",
-      "vai-LR" => "vai-Vaii-LR",
-      "zh-CN" => "zh-Hans-CN",
-      "zh-HK" => "zh-Hant-HK",
-      "zh-MO" => "zh-Hant-MO",
-      "zh-SG" => "zh-Hans-SG",
-      "zh-TW" => "zh-Hant-TW"
-    }.freeze
-
-    PARENTS = {
-      "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",
-      "en-KI" => "en-001",
-      "en-KN" => "en-001",
-      "en-KY" => "en-001",
-      "en-LC" => "en-001",
-      "en-LR" => "en-001",
-      "en-LS" => "en-001",
-      "en-MG" => "en-001",
-      "en-MO" => "en-001",
-      "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",
-      "en-SZ" => "en-001",
-      "en-TC" => "en-001",
-      "en-TK" => "en-001",
-      "en-TO" => "en-001",
-      "en-TT" => "en-001",
-      "en-TV" => "en-001",
-      "en-TZ" => "en-001",
-      "en-UG" => "en-001",
-      "en-VC" => "en-001",
-      "en-VG" => "en-001",
-      "en-VU" => "en-001",
-      "en-WS" => "en-001",
-      "en-ZA" => "en-001",
-      "en-ZM" => "en-001",
-      "en-ZW" => "en-001",
-      "es-AR" => "es-419",
-      "es-BO" => "es-419",
-      "es-BR" => "es-419",
-      "es-BZ" => "es-419",
-      "es-CL" => "es-419",
-      "es-CO" => "es-419",
-      "es-CR" => "es-419",
-      "es-CU" => "es-419",
-      "es-DO" => "es-419",
-      "es-EC" => "es-419",
-      "es-GT" => "es-419",
-      "es-HN" => "es-419",
-      "es-MX" => "es-419",
-      "es-NI" => "es-419",
-      "es-PA" => "es-419",
-      "es-PE" => "es-419",
-      "es-PR" => "es-419",
-      "es-PY" => "es-419",
-      "es-SV" => "es-419",
-      "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-GQ" => "pt-PT",
-      "pt-GW" => "pt-PT",
-      "pt-LU" => "pt-PT",
-      "pt-MO" => "pt-PT",
-      "pt-MZ" => "pt-PT",
-      "pt-ST" => "pt-PT",
-      "pt-TL" => "pt-PT",
-      "az-Arab" => "und",
-      "az-Cyrl" => "und",
-      "bal-Latn" => "und",
-      "blt-Latn" => "und",
-      "bs-Cyrl" => "und",
-      "byn-Latn" => "und",
-      "en-Dsrt" => "und",
-      "en-Shaw" => "und",
-      "iu-Latn" => "und",
-      "kk-Arab" => "und",
-      "ks-Deva" => "und",
-      "ku-Arab" => "und",
-      "ky-Arab" => "und",
-      "ky-Latn" => "und",
-      "ml-Arab" => "und",
-      "mn-Mong" => "und",
-      "mni-Mtei" => "und",
-      "ms-Arab" => "und",
-      "pa-Arab" => "und",
-      "sat-Deva" => "und",
-      "sd-Deva" => "und",
-      "sd-Khoj" => "und",
-      "sd-Sind" => "und",
-      "so-Arab" => "und",
-      "sr-Latn" => "und",
-      "sw-Arab" => "und",
-      "tg-Arab" => "und",
-      "uz-Arab" => "und",
-      "uz-Cyrl" => "und",
-      "yue-Hans" => "und",
-      "zh-Hant" => "und",
-      "zh-Hant-MO" => "zh-Hant-HK"
-    }.freeze
-
     # Checks whether two locales match.
     def self.match(first_locale, second_locale)
       return false if first_locale.to_s.empty? || second_locale.to_s.empty?
@@ -238,12 +16,7 @@ module Addressing
     def self.match_candidates(first_locale, second_locale)
       return false if first_locale.to_s.empty? || second_locale.to_s.empty?
 
-      first_locale = canonicalize(first_locale)
-      second_locale = canonicalize(second_locale)
-      first_locale_candidates = candidates(first_locale)
-      second_locale_candidates = candidates(second_locale)
-
-      (first_locale_candidates & second_locale_candidates).any?
+      (candidates(canonicalize(first_locale)) & candidates(canonicalize(second_locale))).any?
     end
 
     # Resolves the locale from the available locales.
@@ -254,14 +27,7 @@ module Addressing
     # If no candidate is found in the list, an error is raised.
     def self.resolve(available_locales, locale, fallback_locale = nil)
       locale = canonicalize(locale)
-      resolved_locale = nil
-
-      candidates(locale, fallback_locale).each do |candidate|
-        if available_locales.include?(candidate)
-          resolved_locale = candidate
-          break
-        end
-      end
+      resolved_locale = candidates(locale, fallback_locale).find { |candidate| available_locales.include?(candidate) }
 
       # No locale could be resolved, stop here.
       raise UnknownLocaleError.new(locale) if resolved_locale.nil?
@@ -304,54 +70,39 @@ module Addressing
     # 1) sr-Latn
     # 2) sr
     def self.candidates(locale, fallback_locale = nil)
-      locale = replace_alias(locale)
-      candidates = [locale]
-
-      while (parent = parent(locale))
-        candidates << parent
-        locale = parent
-      end
-
-      if fallback_locale
-        candidates << fallback_locale
-
-        while (parent = parent(fallback_locale))
-          candidates << parent
-          fallback_locale = parent
-        end
-      end
-
+      candidates = lineage(replace_alias(locale))
+      candidates += lineage(fallback_locale) if fallback_locale
       candidates.uniq
     end
 
+    # Gets the given locale followed by its parents.
+    def self.lineage(locale)
+      lineage = [locale]
+      lineage << locale while (locale = parent(locale))
+      lineage
+    end
+    private_class_method :lineage
+
     # Gets the parent for the given locale.
     def self.parent(locale)
-      parent = nil
-
-      if PARENTS.key?(locale)
-        parent = PARENTS[locale]
-      elsif locale.include?("-")
-        locale_parts = locale.split("-")
-        locale_parts.pop
-        parent = locale_parts.join("-")
-      end
+      parent = definitions["parents"].fetch(locale) { locale.include?("-") ? locale.rpartition("-").first : nil }
 
       # The library doesn't have data for the empty `und` locale, it
       # is more user friendly to use the configured fallback instead.
-      if parent == "und"
-        parent = nil
-      end
-
-      parent
+      (parent == "und") ? nil : parent
     end
 
     # Replaces a locale alias with the real locale.
     #
     # For example, "zh-CN" is replaced with "zh-Hans-CN".
     def self.replace_alias(locale)
-      return locale if locale.to_s.empty? || !ALIASES.key?(locale)
+      definitions["aliases"].fetch(locale, locale)
+    end
 
-      ALIASES[locale]
+    # Gets the locale aliases and parents.
+    def self.definitions
+      Addressing.data_source.fetch("locale")
     end
+    private_class_method :definitions
   end
 end

data/lib/addressing/model.rb

@@ -2,95 +2,36 @@
 
 module Addressing
   module Model
+    # The error message for each kind of field violation.
+    FIELD_VIOLATION_MESSAGES = {
+      blank: "should not be blank",
+      present: "should be blank",
+      invalid: "should be valid"
+    }.freeze
+    private_constant :FIELD_VIOLATION_MESSAGES
+
     def validates_address_format(
-      fields: [:country_code, :administrative_area, :locality, :dependent_locality, :postal_code, :sorting_code, :address_line1, :address_line2, :organization, :given_name, :additional_name, :family_name, :locale], field_overrides: nil, verify_postal_code: true, **options
+      fields: Address::FIELDS, field_overrides: nil, verify_postal_code: true, **options
     )
       fields = Array(fields)
       field_overrides ||= FieldOverrides.new({})
 
-      options[:if] ||= -> { fields.any? { |f| changes.key?(f.to_s) } } unless options[:unless]
-
-      class_eval do
-        validate :verify_address_format, **options
-
-        define_method :verify_address_format do
-          values = fields.each_with_object({}) { |f, v| v[f] = send(f) if respond_to?(f) }
-          address = Address.new(**values)
-
-          return unless address.country_code.present?
-
-          address_format = AddressFormat.get(address.country_code)
-
-          # Validate the presence of required fields.
-          AddressFormatHelper.required_fields(address_format, field_overrides).each do |required_field|
-            next unless address.send(required_field).blank?
-
-            errors.add(required_field, "should not be blank")
-          end
-
-          used_fields = address_format.used_fields - field_overrides.hidden_fields
-
-          # Validate the absence of unused fields.
-          unused_fields = AddressField.all.values - used_fields
-          unused_fields.each do |unused_field|
-            next if address.send(unused_field).blank?
-
-            errors.add(unused_field, "should be blank")
-          end
-
-          # Validate subdivisions.
-          subdivisions = verify_subdivisions(address, address_format, field_overrides)
-
-          # Validate postal code.
-          verify_postal_code(address.postal_code, subdivisions, address_format) if used_fields.include?(AddressField::POSTAL_CODE) && verify_postal_code
-        end
-
-        define_method :verify_subdivisions do |address, address_format, field_overrides|
-          # No predefined subdivisions exist, nothing to validate against.
-          return [] if address_format.subdivision_depth < 1
-
-          subdivisions, _parents = address_format.used_subdivision_fields.each_with_index.inject([[], []]) do |(subdivisions, parents), (field, index)|
-            # The field is empty or validation is disabled.
-            break [subdivisions, parents] if address.send(field).blank? || field_overrides.hidden_fields.include?(field)
-
-            parents << ((index > 0) ? address.send(address_format.used_subdivision_fields[index - 1]) : address_format.country_code)
-            subdivision = Subdivision.get(address.send(field), parents)
-            if subdivision.nil?
-              errors.add(field, "should be valid")
-              break [subdivisions, parents]
-            end
-
-            subdivisions << subdivision
-            # No predefined subdivisions below this level, stop here.
-            break [subdivisions, parents] if subdivision.children.empty?
-
-            [subdivisions, parents]
-          end
-
-          subdivisions
-        end
-
-        define_method :verify_postal_code do |postal_code, subdivisions, address_format|
-          # Nothing to validate.
-          return if postal_code.blank?
+      # Without change tracking, as on a plain ActiveModel class, validate every time.
+      options[:if] ||= -> { !respond_to?(:changes) || fields.any? { |f| changes.key?(f.to_s) } } unless options[:unless]
 
-          pattern = subdivisions.inject(address_format.postal_code_pattern) do |pattern, subdivision|
-            subdivision_pattern = subdivision.postal_code_pattern
-            next pattern if subdivision_pattern.blank?
+      validate :validate_address_format, **options
 
-            subdivision_pattern
-          end
+      # A method rather than a block, so that a later call, in a subclass for
+      # example, replaces the configuration of an earlier one.
+      define_method :validate_address_format do
+        values = fields.each_with_object({}) { |f, v| v[f] = send(f) if respond_to?(f) }
+        address = Address.new(**values)
 
-          if pattern
-            # The pattern must match the provided value completely.
-            match = postal_code.match(Regexp.new(pattern.gsub("\\\\", "\\").to_s, "i"))
-            if match.nil? || match[0] != postal_code
-              errors.add(AddressField::POSTAL_CODE, "should be valid")
-              nil
-            end
-          end
+        AddressValidator.validate(address, field_overrides: field_overrides, verify_postal_code: verify_postal_code).each do |violation|
+          errors.add(violation.field, violation.kind, message: FIELD_VIOLATION_MESSAGES.fetch(violation.kind))
         end
       end
+      private :validate_address_format
     end
   end
 end

data/lib/addressing/postal_label_formatter.rb

@@ -2,28 +2,30 @@
 
 module Addressing
   class PostalLabelFormatter < DefaultFormatter
-    DEFAULT_OPTIONS = {
-      locale: DEFAULT_LOCALE,
-      html: false,
-      html_tag: "p",
-      html_attributes: {translate: "no"},
-      origin_country: ""
-    }
+    DEFAULT_OPTIONS = DefaultFormatter::DEFAULT_OPTIONS.merge(html: false, origin_country: "")
 
     protected
 
-    def build_view(address, address_format, options)
-      raise ArgumentError, "The origin_country option cannot be empty." if options[:origin_country].empty?
+    # The origin country has no default, so format raises until it is given,
+    # to the constructor or to format.
+    def assert_options(options)
+      super
+
+      return unless options.key?(:origin_country)
+
+      origin_country = options[:origin_country]
+      raise ArgumentError, "The option `origin_country` must be a non-empty string." unless origin_country.is_a?(String) && !origin_country.empty?
+    end
 
+    def build_view(address, address_format, options)
       view = super
-      view = view.map do |key, element|
+      view.each do |key, element|
         # Uppercase fields where required by the format.
         element[:value] = element[:value].upcase if address_format.uppercase_fields.include?(key)
-        [key, element]
-      end.to_h
+      end
 
       # Handle international mailing.
-      if address.country_code != options[:origin_country]
+      if address.country_code != options[:origin_country].upcase
         # Prefix the postal code.
         field = AddressField::POSTAL_CODE
 
@@ -37,8 +39,7 @@ module Addressing
         # transit, it is desirable for the name of the country of
         # destination to be added in an internationally known language.
         country = view["country"][:value]
-        english_countries = Country.list("en")
-        english_country = english_countries[address.country_code]
+        english_country = country_list("en")[address.country_code]
 
         if country != english_country
           country += " - #{english_country}"