addressing 2.0.1 → 2.2.0

data/data/subdivision/GT.json

@@ -0,0 +1,71 @@
+{
+	"country_code": "GT",
+	"subdivisions": {
+		"16": {
+			"name": "Alta Verapaz"
+		},
+		"15": {
+			"name": "Baja Verapaz"
+		},
+		"04": {
+			"name": "Chimaltenango"
+		},
+		"20": {
+			"name": "Chiquimula"
+		},
+		"02": {
+			"name": "El Progreso"
+		},
+		"05": {
+			"name": "Escuintla"
+		},
+		"01": {
+			"name": "Guatemala"
+		},
+		"13": {
+			"name": "Huehuetenango"
+		},
+		"18": {
+			"name": "Izabal"
+		},
+		"21": {
+			"name": "Jalapa"
+		},
+		"22": {
+			"name": "Jutiapa"
+		},
+		"17": {
+			"name": "Petén"
+		},
+		"09": {
+			"name": "Quetzaltenango"
+		},
+		"14": {
+			"name": "Quiché"
+		},
+		"11": {
+			"name": "Retalhuleu"
+		},
+		"03": {
+			"name": "Sacatepéquez"
+		},
+		"12": {
+			"name": "San Marcos"
+		},
+		"06": {
+			"name": "Santa Rosa"
+		},
+		"07": {
+			"name": "Sololá"
+		},
+		"10": {
+			"name": "Suchitepéquez"
+		},
+		"08": {
+			"name": "Totonicapán"
+		},
+		"19": {
+			"name": "Zacapa"
+		}
+	}
+}

data/data/subdivision/IT.json

@@ -149,6 +149,10 @@
 			"code": "FR",
 			"name": "Frosinone"
 		},
+		"OT": {
+			"code": "OT",
+			"name": "Gallura Nord-Est Sardegna"
+		},
 		"GE": {
 			"code": "GE",
 			"name": "Genova"
@@ -217,6 +221,10 @@
 			"code": "MT",
 			"name": "Matera"
 		},
+		"VS": {
+			"code": "VS",
+			"name": "Medio Campidano"
+		},
 		"ME": {
 			"code": "ME",
 			"name": "Messina"
@@ -245,6 +253,10 @@
 			"code": "NU",
 			"name": "Nuoro"
 		},
+		"OG": {
+			"code": "OG",
+			"name": "Ogliastra"
+		},
 		"OR": {
 			"code": "OR",
 			"name": "Oristano"
@@ -359,7 +371,7 @@
 		},
 		"SU": {
 			"code": "SU",
-			"name": "Sud Sardegna"
+			"name": "Sulcis Iglesiente"
 		},
 		"TA": {
 			"code": "TA",

data/data/subdivision/KY.json

@@ -1,8 +1,8 @@
 {
 	"country_code": "KY",
 	"subdivisions": {
-		"Cayman Brac": {},
-		"Grand Cayman": {},
-		"Little Cayman": {}
+		"Cayman Brac": [],
+		"Grand Cayman": [],
+		"Little Cayman": []
 	}
 }

data/data/subdivision/NG.json

@@ -83,7 +83,7 @@
 			"name": "Niger"
 		},
 		"OG": {
-			"name": "Ogun State"
+			"name": "Ogun"
 		},
 		"ON": {
 			"name": "Ondo"

data/data/subdivision/RU.json

@@ -240,10 +240,6 @@
 			"name": "Tyva Republits",
 			"local_name": "Республика Тыва"
 		},
-		"UD": {
-			"name": "Udmurtskaja Respublika",
-			"local_name": "Республика Удмуртия"
-		},
 		"KK": {
 			"name": "Khakasiya Republits",
 			"local_name": "Республика Хакасия"
@@ -308,6 +304,10 @@
 			"name": "Tyumenskaya oblast'",
 			"local_name": "Тюменская область"
 		},
+		"UD": {
+			"name": "Udmurtskaja Respublika",
+			"local_name": "Удмуртская Республика"
+		},
 		"ULY": {
 			"name": "Ulyanovskaya oblast'",
 			"local_name": "Ульяновская область"

data/data/subdivision/TH.json

@@ -26,10 +26,6 @@
 			"name": "Khon Kaen",
 			"local_name": "ขอนแก่น"
 		},
-		"38": {
-			"name": "Bueng Kan",
-			"local_name": "จังหวัด บึงกาฬ"
-		},
 		"22": {
 			"name": "Chanthaburi",
 			"local_name": "จันทบุรี"
@@ -51,7 +47,7 @@
 			"local_name": "ชัยภูมิ"
 		},
 		"86": {
-			"name": "Chumpon",
+			"name": "Chumphon",
 			"local_name": "ชุมพร"
 		},
 		"57": {
@@ -110,6 +106,10 @@
 			"name": "Nan",
 			"local_name": "น่าน"
 		},
+		"38": {
+			"name": "Bueng Kan",
+			"local_name": "บึงกาฬ"
+		},
 		"31": {
 			"name": "Buri Ram",
 			"local_name": "บุรีรัมย์"
@@ -143,7 +143,7 @@
 			"local_name": "พังงา"
 		},
 		"93": {
-			"name": "Phattalung",
+			"name": "Phatthalung",
 			"local_name": "พัทลุง"
 		},
 		"66": {
@@ -267,7 +267,7 @@
 			"local_name": "สุโขทัย"
 		},
 		"72": {
-			"name": "Suphanburi",
+			"name": "Suphan Buri",
 			"local_name": "สุพรรณบุรี"
 		},
 		"84": {

data/data/subdivision/TR.json

@@ -8,7 +8,7 @@
 			"name": "Adıyaman"
 		},
 		"03": {
-			"name": "Afyon"
+			"name": "Afyonkarahisar"
 		},
 		"04": {
 			"name": "Ağrı"

data/data/subdivision/TV.json

@@ -10,7 +10,7 @@
 		"NMA": {
 			"name": "Nanumea"
 		},
-		"Niulakita": {},
+		"Niulakita": [],
 		"NIT": {
 			"name": "Niutao"
 		},

data/data/subdivision/VE.json

@@ -32,7 +32,7 @@
 			"name": "Dependencias Federales"
 		},
 		"A": {
-			"name": "Distrito Federal"
+			"name": "Distrito Capital"
 		},
 		"I": {
 			"name": "Falcón"
@@ -40,6 +40,9 @@
 		"J": {
 			"name": "Guárico"
 		},
+		"X": {
+			"name": "La Guaira"
+		},
 		"K": {
 			"name": "Lara"
 		},
@@ -67,9 +70,6 @@
 		"T": {
 			"name": "Trujillo"
 		},
-		"X": {
-			"name": "La Guaira"
-		},
 		"U": {
 			"name": "Yaracuy"
 		},

data/data/subdivision/VN.json

@@ -60,7 +60,7 @@
 		},
 		"79": {
 			"name": "Ho Chi Minh City",
-			"local_name": "Thành phố Hồ Chí Minh"
+			"local_name": "Hồ Chí Minh"
 		},
 		"46": {
 			"name": "Hue City",

data/lib/addressing/address.rb

@@ -28,7 +28,7 @@ module Addressing
 
     # Creates a new Address instance.
     #
-    # @param country_code [String] ISO 3166-1 alpha-2 country code
+    # @param country_code [String] ISO 3166-1 alpha-2 country code, stored in uppercase
     # @param administrative_area [String] Top-level administrative subdivision (state, province, etc.)
     # @param locality [String] City or locality
     # @param dependent_locality [String] Dependent locality (neighborhood, suburb, district, etc.)
@@ -43,7 +43,7 @@ module Addressing
     # @param family_name [String] Family name (last name)
     # @param locale [String] Locale code for the address
     def initialize(country_code: "", administrative_area: "", locality: "", dependent_locality: "", postal_code: "", sorting_code: "", address_line1: "", address_line2: "", address_line3: "", organization: "", given_name: "", additional_name: "", family_name: "", locale: "und")
-      @country_code = country_code
+      self.country_code = country_code
       @administrative_area = administrative_area
       @locality = locality
       @dependent_locality = dependent_locality
@@ -95,6 +95,10 @@ module Addressing
 
     protected
 
-    attr_writer(*FIELDS)
+    attr_writer(*(FIELDS - [:country_code]))
+
+    def country_code=(value)
+      @country_code = value.is_a?(String) ? value.upcase : value
+    end
   end
 end

data/lib/addressing/address_format.rb

@@ -8,9 +8,35 @@ module Addressing
   #
   # @example Get address format for Brazil
   #   format = Addressing::AddressFormat.get('BR')
-  #   format.used_fields      # => ["given_name", "family_name", ...]
-  #   format.required_fields  # => ["address_line1", "locality", ...]
+  #   format.used_fields        # => ["given_name", "family_name", ...]
+  #   format.required_fields    # => ["address_line1", "locality", ...]
+  #   format.subdivision_fields # => ["administrative_area", "locality"]
   class AddressFormat
+    # The subdivision fields, ordered from the top level down.
+    SUBDIVISION_FIELDS = [
+      AddressField::ADMINISTRATIVE_AREA,
+      AddressField::LOCALITY,
+      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.
       #
@@ -18,58 +44,65 @@ 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",
-          subdivision_depth: 0
-        }
+        # 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
 
-    attr_reader :country_code, :locale, :format, :local_format, :required_fields, :uppercase_fields, :default_values, :administrative_area_type, :locality_type, :dependent_locality_type, :postal_code_type, :postal_code_pattern, :postal_code_prefix, :subdivision_depth
+    attr_reader :country_code, :locale, :format, :local_format, :required_fields, :uppercase_fields, :default_values, :administrative_area_type, :locality_type, :dependent_locality_type, :postal_code_type, :postal_code_pattern, :postal_code_prefix
+
+    # The subdivision fields for which there is predefined subdivision data.
+    #
+    # This is more precise than #used_subdivision_fields, which returns all
+    # subdivision fields used by the format regardless of whether data exists.
+    #
+    # @return [Array<String>] e.g. ["administrative_area", "locality"]
+    attr_reader :subdivision_fields
+
+    # The number of subdivision fields with predefined data used by the format.
+    #
+    # @deprecated Use #subdivision_fields instead.
+    # @return [Integer]
+    def subdivision_depth
+      (subdivision_fields & used_subdivision_fields).size
+    end
 
     def initialize(definition = {})
       # Validate the presence of required properties.
@@ -87,13 +120,16 @@ module Addressing
         uppercase_fields: [],
         default_values: {},
         postal_code_pattern: nil,
-        postal_code_prefix: nil,
-        subdivision_depth: 0
+        postal_code_prefix: nil
       }.merge(definition)
 
+      # Backwards compatibility: derive the subdivision fields from a depth.
+      definition[:subdivision_fields] ||= SUBDIVISION_FIELDS.first(definition[:subdivision_depth] || 0)
+
       AddressField.assert_all_exist(definition[:required_fields])
       AddressField.assert_all_exist(definition[:uppercase_fields])
       AddressField.assert_all_exist(definition[:default_values].keys)
+      AddressField.assert_all_exist(definition[:subdivision_fields])
 
       @country_code = definition[:country_code]
       @locale = definition[:locale]
@@ -102,35 +138,22 @@ module Addressing
       @required_fields = definition[:required_fields]
       @uppercase_fields = definition[:uppercase_fields]
       @default_values = definition[:default_values]
-      @subdivision_depth = definition[:subdivision_depth]
-
-      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
+      @subdivision_fields = definition[:subdivision_fields]
+
+      # 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
@@ -138,42 +161,15 @@ 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.
+    #
+    # Note that a country might use a subdivision field without having
+    # predefined subdivisions for it, see #subdivision_fields.
     def used_subdivision_fields
-      fields = [
-        AddressField::ADMINISTRATIVE_AREA,
-        AddressField::LOCALITY,
-        AddressField::DEPENDENT_LOCALITY
-      ]
-
-      # Remove fields not used by the format.
-      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
+      SUBDIVISION_FIELDS & used_fields
     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