addressing 2.1.0 → 2.2.0

data/lib/addressing/address_format.rb

@@ -19,6 +19,24 @@ module Addressing
       AddressField::DEPENDENT_LOCALITY
     ].freeze
 
+    # The defaults for every address format, including the fallback for
+    # countries without a definition.
+    GENERIC_DEFINITION = {
+      format: "%given_name %family_name\n%organization\n%address_line1\n%address_line2\n%address_line3\n%locality",
+      required_fields: [
+        "address_line1", "locality"
+      ].freeze,
+      uppercase_fields: [
+        "locality"
+      ].freeze,
+      subdivision_fields: [].freeze,
+      administrative_area_type: "province",
+      locality_type: "city",
+      dependent_locality_type: "suburb",
+      postal_code_type: "postal"
+    }.freeze
+    private_constant :GENERIC_DEFINITION
+
     class << self
       # Gets the address format for the provided country code.
       #
@@ -26,53 +44,45 @@ module Addressing
       # @return [AddressFormat] Address format instance
       def get(country_code)
         country_code = country_code.upcase
-        @address_formats ||= {}
-
-        unless @address_formats.key?(country_code)
-          definition = process_definition(definitions[country_code] || {country_code: country_code})
-          @address_formats[country_code] = new(definition)
-        end
-
-        @address_formats[country_code]
+        # Unknown country codes often come from user input, so they are not cached.
+        address_formats.fetch(country_code) { new(process_definition(country_code: country_code)) }
       end
 
       def all
-        definitions.map do |country_code, definition|
-          definition = process_definition(definition)
-          [country_code, new(definition)]
-        end.to_h
+        address_formats.dup
       end
 
       private
 
-      def definitions
-        @definitions ||= Marshal.load(File.read(File.expand_path("../../../data/address_formats.dump", __FILE__).to_s))
+      # Gets the address formats by country code.
+      #
+      # All are built when the data is loaded, so that every call returns
+      # the same instance for a country.
+      def address_formats
+        Addressing.data_source.fetch("address_formats") do |definitions|
+          definitions.to_h do |country_code, definition|
+            definition = definition.transform_keys(&:to_sym)
+            definition[:default_values] = definition[:default_values].transform_keys(&:to_sym) if definition[:default_values]
+
+            [country_code, new(process_definition(definition))]
+          end
+        end
       end
 
       def process_definition(definition)
         # Merge-in defaults.
-        definition = generic_definition.merge(definition)
+        definition = GENERIC_DEFINITION.merge(definition)
 
         # Always require the given name and family name.
-        definition[:required_fields] << AddressField::GIVEN_NAME
-        definition[:required_fields] << AddressField::FAMILY_NAME
-        definition
-      end
+        definition[:required_fields] = definition[:required_fields] | [AddressField::GIVEN_NAME, AddressField::FAMILY_NAME]
 
-      def generic_definition
-        {
-          format: "%given_name %family_name\n%organization\n%address_line1\n%address_line2\n%address_line3\n%locality",
-          required_fields: [
-            "address_line1", "locality"
-          ],
-          uppercase_fields: [
-            "locality"
-          ],
-          administrative_area_type: "province",
-          locality_type: "city",
-          dependent_locality_type: "suburb",
-          postal_code_type: "postal"
-        }
+        # The address formats are shared, so callers must not be able to
+        # change their field lists.
+        [:required_fields, :uppercase_fields, :subdivision_fields].each do |key|
+          definition[key] = definition[key].dup.freeze
+        end
+
+        definition
       end
     end
 
@@ -130,33 +140,20 @@ module Addressing
       @default_values = definition[:default_values]
       @subdivision_fields = definition[:subdivision_fields]
 
-      if used_fields.include?(AddressField::ADMINISTRATIVE_AREA)
-        if definition[:administrative_area_type]
-          AdministrativeAreaType.assert_exists(definition[:administrative_area_type])
-          @administrative_area_type = definition[:administrative_area_type]
-        end
-      end
-
-      if used_fields.include?(AddressField::LOCALITY)
-        if definition[:locality_type]
-          LocalityType.assert_exists(definition[:locality_type])
-          @locality_type = definition[:locality_type]
-        end
-      end
-
-      if used_fields.include?(AddressField::DEPENDENT_LOCALITY)
-        if definition[:dependent_locality_type]
-          DependentLocalityType.assert_exists(definition[:dependent_locality_type])
-          @dependent_locality_type = definition[:dependent_locality_type]
-        end
+      # A type is only set when the format uses its field.
+      {
+        administrative_area_type: [AddressField::ADMINISTRATIVE_AREA, AdministrativeAreaType],
+        locality_type: [AddressField::LOCALITY, LocalityType],
+        dependent_locality_type: [AddressField::DEPENDENT_LOCALITY, DependentLocalityType],
+        postal_code_type: [AddressField::POSTAL_CODE, PostalCodeType]
+      }.each do |key, (field, type)|
+        next unless definition[key] && used_fields.include?(field)
+
+        type.assert_exists(definition[key])
+        instance_variable_set(:"@#{key}", definition[key])
       end
 
       if used_fields.include?(AddressField::POSTAL_CODE)
-        if definition[:postal_code_type]
-          PostalCodeType.assert_exists(definition[:postal_code_type])
-          @postal_code_type = definition[:postal_code_type]
-        end
-
         @postal_code_pattern = definition[:postal_code_pattern]
         @postal_code_prefix = definition[:postal_code_prefix]
       end
@@ -164,9 +161,7 @@ module Addressing
 
     # Gets the list of used fields.
     def used_fields
-      @used_fields ||= AddressField.all.filter_map do |key, value|
-        value if @format.include?("%" + value)
-      end
+      @used_fields ||= AddressField.all.values.select { |field| @format.include?("%#{field}") }
     end
 
     # Gets the list of used subdivision fields.
@@ -177,25 +172,4 @@ module Addressing
       SUBDIVISION_FIELDS & used_fields
     end
   end
-
-  class AddressFormatHelper
-    class << self
-      # Gets the required fields.
-      #
-      # Applies field overrides to the required fields
-      # specified by the address format.
-      def required_fields(address_format, field_overrides)
-        required_fields = address_format.required_fields
-        required_fields -= field_overrides.optional_fields
-        required_fields -= field_overrides.hidden_fields
-
-        if field_overrides.required_fields
-          required_fields += field_overrides.required_fields
-          required_fields = required_fields.uniq
-        end
-
-        required_fields
-      end
-    end
-  end
 end

data/lib/addressing/address_validator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Addressing
+  # Validates an address against the address format of its country.
+  #
+  # @example
+  #   address = Addressing::Address.new(country_code: "US", administrative_area: "XX")
+  #   Addressing::AddressValidator.validate(address)
+  #   # => [#<data Addressing::FieldViolation field=:address_line1, kind=:blank>, ...]
+  class AddressValidator
+    private_class_method :new
+
+    class << self
+      # Returns the field violations of the address.
+      #
+      # The rules, in the order in which their violations are reported:
+      #
+      # 1. Every required field is present. The field overrides make fields
+      #    optional, hidden or required.
+      # 2. Every field that the format does not use, or that is hidden, is blank.
+      # 3. The subdivision levels match the predefined subdivisions, from the
+      #    administrative area down. A hidden level ends the check.
+      # 4. The postal code matches the whole pattern, ignoring case. The pattern
+      #    comes from the last subdivision in the subdivision chain that has
+      #    one, and otherwise from the address format.
+      #
+      # An address without a country code gives a single :blank violation on
+      # the country code. Without a country there is no address format to
+      # check the other fields against.
+      #
+      # @param address [Address] The address to validate
+      # @param field_overrides [FieldOverrides] Overrides of the fields of the address format
+      # @param verify_postal_code [Boolean] Whether to check the postal code against its pattern
+      # @return [Array<FieldViolation>] The field violations, empty when the address is valid
+      def validate(address, field_overrides: FieldOverrides.new({}), verify_postal_code: true)
+        return [violation(:country_code, :blank)] if blank?(address.country_code)
+
+        address_format = AddressFormat.get(address.country_code)
+        violations = []
+
+        required_fields(address_format, field_overrides).each do |field|
+          violations << violation(field, :blank) if blank?(address.send(field))
+        end
+
+        used_fields = address_format.used_fields - field_overrides.hidden_fields
+
+        (AddressField.all.values - used_fields).each do |field|
+          violations << violation(field, :present) unless blank?(address.send(field))
+        end
+
+        subdivision_fields = address_format.subdivision_fields
+        # A hidden level is not validated, and neither are the levels below it.
+        subdivision_values = subdivision_fields.map { |field| address.send(field) unless field_overrides.hidden_fields.include?(field) }
+        chain = Subdivision.chain(address_format.country_code, subdivision_values)
+
+        violations << violation(subdivision_fields[chain.unmatched_level], :invalid) if chain.unmatched_level
+
+        if verify_postal_code && used_fields.include?(AddressField::POSTAL_CODE) && !valid_postal_code?(address.postal_code, chain.subdivisions, address_format)
+          violations << violation(AddressField::POSTAL_CODE, :invalid)
+        end
+
+        violations
+      end
+
+      private
+
+      def violation(field, kind)
+        FieldViolation.new(field: field.to_sym, kind: kind)
+      end
+
+      # Whether the postal code matches the pattern of the last subdivision in
+      # the chain that has one, or else the pattern of the address format.
+      def valid_postal_code?(postal_code, subdivisions, address_format)
+        # Nothing to validate.
+        return true if blank?(postal_code)
+
+        pattern = subdivisions.inject(address_format.postal_code_pattern) do |pattern, subdivision|
+          blank?(subdivision.postal_code_pattern) ? pattern : subdivision.postal_code_pattern
+        end
+        return true unless pattern
+
+        # The pattern must match the provided value completely.
+        match = postal_code.match(Regexp.new(pattern, "i"))
+        !match.nil? && match[0] == postal_code
+      end
+
+      # Applies the field overrides to the required fields of the address format.
+      def required_fields(address_format, field_overrides)
+        required_fields = address_format.required_fields - field_overrides.optional_fields - field_overrides.hidden_fields
+        (required_fields + field_overrides.required_fields).uniq
+      end
+
+      def blank?(value)
+        Blank.blank?(value)
+      end
+    end
+  end
+end

data/lib/addressing/blank.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Addressing
+  # Decides whether a value is blank.
+  module Blank
+    # Matches a value that holds nothing but whitespace, Unicode included.
+    PATTERN = /\A[[:space:]]*\z/
+    private_constant :PATTERN
+
+    # Whether the value is blank. Follows ActiveSupport's blank?, and uses it
+    # when it is loaded.
+    def self.blank?(value)
+      return value.blank? if value.respond_to?(:blank?)
+
+      case value
+      when String then blank_string?(value)
+      when nil, false then true
+      else value.respond_to?(:empty?) && value.empty?
+      end
+    end
+
+    def self.blank_string?(value)
+      PATTERN.match?(value)
+    rescue Encoding::CompatibilityError
+      # The value has an encoding that is not compatible with ASCII.
+      Regexp.new(PATTERN.source.encode(value.encoding), PATTERN.options | Regexp::FIXEDENCODING).match?(value)
+    end
+    private_class_method :blank_string?
+  end
+
+  private_constant :Blank
+end