addressing 2.1.0 → 2.2.0

data/lib/addressing/subdivision.rb

@@ -16,7 +16,53 @@ module Addressing
   # @example Get subdivisions for a Brazilian state
   #   municipalities = Addressing::Subdivision.all(['BR', 'CE'])
   class Subdivision
+    # The subdivision chain of an address.
+    #
+    # subdivisions holds the matched predefined subdivisions, ordered from the
+    # administrative area downward. unmatched_level is the position, in the
+    # values given to Subdivision.chain, of the value that matched no
+    # predefined subdivision, or nil when there was none.
+    Chain = Data.define(:subdivisions, :unmatched_level)
+
     class << self
+      # Resolves the subdivision chain for the values of the subdivision levels.
+      #
+      # The walk goes down the levels and stops at the first empty value, at
+      # the first value that matches no predefined subdivision, or at a
+      # subdivision without children.
+      #
+      # @param country_code [String] Country code
+      # @param values [Array<String, nil>] Values in level order (administrative area, locality, dependent locality)
+      # @return [Chain]
+      #
+      # @example
+      #   chain = Addressing::Subdivision.chain("BR", ["CE", "Fortaleza"])
+      #   chain.subdivisions.map(&:code) # => ["CE", "Fortaleza"]
+      #   chain.unmatched_level          # => nil
+      def chain(country_code, values)
+        parents = [country_code.upcase]
+        subdivisions = []
+
+        # Nothing to match against.
+        return Chain.new(subdivisions: subdivisions, unmatched_level: nil) if load_definitions(parents).empty?
+
+        values.each_with_index do |value, level|
+          # This level is empty, so there can be no sublevels.
+          break if Blank.blank?(value)
+
+          subdivision = get(value, parents)
+          return Chain.new(subdivisions: subdivisions, unmatched_level: level) if subdivision.nil?
+
+          subdivisions << subdivision
+          # No predefined subdivisions below this level, stop here.
+          break unless subdivision.children?
+
+          parents += [value]
+        end
+
+        Chain.new(subdivisions: subdivisions, unmatched_level: nil)
+      end
+
       # Gets a Subdivision instance by ID and parent hierarchy.
       #
       # @param id [String] Subdivision ID
@@ -24,7 +70,10 @@ module Addressing
       # @return [Subdivision, nil] Subdivision instance or nil if not found
       def get(id, parents)
         definitions = load_definitions(parents)
-        create_subdivision_from_definitions(id, definitions)
+        # No matching definition found.
+        return nil unless definitions.dig("subdivisions", id)
+
+        create_subdivision_from_definitions(id, definitions, load_parent(definitions))
       end
 
       # Returns all subdivision instances for the provided parents.
@@ -35,9 +84,18 @@ module Addressing
         definitions = load_definitions(parents)
         return {} if definitions.empty?
 
-        definitions["subdivisions"].each_with_object({}) do |(id, definition), subdivisions|
-          subdivisions[id] = create_subdivision_from_definitions(id, definitions)
-        end
+        # The siblings share one parent, so it is loaded once.
+        parent = load_parent(definitions)
+        definitions["subdivisions"].keys.to_h { |id| [id, create_subdivision_from_definitions(id, definitions, parent)] }
+      end
+
+      # Checks whether there are subdivisions for the provided parents, without building them.
+      #
+      # @api private
+      # @param parents [Array<String>] Parent hierarchy (e.g., ['BR'] or ['BR', 'CE'])
+      # @return [Boolean]
+      def any?(parents)
+        !load_definitions(parents).fetch("subdivisions", {}).empty?
       end
 
       # Returns a list of subdivisions for the provided parents.
@@ -47,83 +105,65 @@ module Addressing
 
         use_local_name = Locale.match_candidates(locale, definitions["locale"] || "")
 
-        definitions["subdivisions"].each_with_object({}) do |(id, definition), subdivisions|
-          subdivisions[id] = use_local_name ? definition["local_name"] : definition["name"]
-        end
+        definitions["subdivisions"].transform_values { |definition| use_local_name ? definition["local_name"] : definition["name"] }
       end
 
-      protected
-
-      # Checks whether predefined subdivisions exist for the provided parents.
-      def has_data(parents)
-        country_code = parents[0]
-
-        subdivision_fields = AddressFormat.get(country_code).subdivision_fields
-        return false if subdivision_fields.empty?
-
-        if parents.size > 1
-          # After the first level it is possible for predefined subdivisions
-          # to exist at a given level, but not for that specific parent.
-          # That's why the parent definition has the most precise answer.
-          grandparents = parents.dup
-          parent_id = grandparents.pop
-          parent_group = build_group(grandparents.dup)
-          @definitions ||= {}
-
-          if @definitions.dig(parent_group, "subdivisions", parent_id)
-            definition = @definitions[parent_group]["subdivisions"][parent_id]
-            return !!definition["has_children"]
-          else
-            # The parent definition wasn't loaded previously, fallback to
-            # guessing based on the count of subdivision data fields.
-            return parents.size <= subdivision_fields.size
-          end
-        end
-
-        # The first level has always data.
-        true
-      end
+      # Gets the key of the subdivision group for the provided parents.
+      #
+      # The key names the data file of the subdivision group. The data sync
+      # names the files with it, so this is the only home of the naming rule.
+      #
+      # @api private
+      # @param parents [Array<String>] Parent hierarchy (e.g., ['BR'] or ['BR', 'CE'])
+      # @return [String]
+      def group_key(parents)
+        raise ArgumentError, "The parents argument must not be empty." if parents.empty?
 
-      # Loads the subdivision definitions for the provided parents.
-      def load_definitions(parents)
-        @definitions ||= {}
-        group = build_group(parents.dup)
-        if @definitions.key?(group)
-          return @definitions[group]
-        end
+        # Country codes are matched case-insensitively, subdivision IDs are not.
+        country_code = parents[0].upcase
+        subdivision_ids = parents.drop(1)
 
-        @definitions[group] = {}
+        return country_code if subdivision_ids.empty?
 
-        # If there are predefined subdivisions at this level, try to load them.
-        if has_data(parents)
-          filename = File.join(File.expand_path("../../../data/subdivision", __FILE__).to_s, "#{group}.json")
+        # The second parent is an ISO code, it can be used as-is.
+        return "#{country_code}-#{subdivision_ids[0]}" if subdivision_ids.length == 1 && subdivision_ids[0].length <= 3
 
-          if File.exist?(filename)
-            @definitions[group] = process_definitions(parse_definitions(File.read(filename)))
-          end
-        end
+        # A dash per key allows the depth to be guessed later.
+        # Hash the remaining keys to ensure that the group is ASCII safe.
+        country_code + "-" * subdivision_ids.length + Digest::SHA1.hexdigest(subdivision_ids.join("-"))
+      end
 
-        @definitions[group]
+      # Gets the parents of a subdivision group from its definitions.
+      #
+      # @api private
+      # @param definitions [Hash] Definitions of a subdivision group
+      # @return [Array<String>]
+      def parents_of(definitions)
+        # The 'parents' key is omitted when it contains just the country code.
+        definitions["parents"] || [definitions["country_code"]]
       end
 
-      # Parses a raw definition file.
+      protected
+
+      # Loads the subdivision definitions for the provided parents.
       #
-      # Malformed JSON is treated as if the file didn't exist.
-      def parse_definitions(raw_definition)
-        definitions = JSON.parse(raw_definition)
-        definitions.is_a?(Hash) ? definitions : {}
-      rescue JSON::ParserError
-        {}
+      # A subdivision group without a data file has no definitions.
+      def load_definitions(parents)
+        Addressing.data_source.fetch("subdivision/#{group_key(parents)}") { |definitions| process_definitions(definitions) } || {}
       end
 
       # Processes the loaded definitions.
       #
       # Adds keys and values that were removed from the JSON files for brevity.
       def process_definitions(definitions)
-        # Malformed definitions are treated as if they didn't exist.
-        return {} unless definitions["subdivisions"].is_a?(Hash)
+        # Definitions of the wrong shape are treated as if they didn't exist.
+        # The data verifier reports them, malformed JSON raises in the data source.
+        return {} unless definitions.is_a?(Hash) && definitions["subdivisions"].is_a?(Hash)
 
         definitions["subdivisions"].each do |id, definition|
+          # Upstream writes a definition without keys as an empty JSON array.
+          definition = definitions["subdivisions"][id] = {} unless definition.is_a?(Hash)
+
           # Add common keys from the root level.
           definition["country_code"] = definitions["country_code"]
           definition["id"] = id
@@ -144,7 +184,7 @@ module Addressing
 
           # The code and local_code values are only specified if they
           # don't match the name and local_name ones.
-          if !definition.key?("code") && definition.key?("name")
+          if !definition.key?("code")
             definition["code"] = definition["name"]
           end
 
@@ -156,66 +196,23 @@ module Addressing
         definitions
       end
 
-      # Builds a group from the provided parents.
-      #
-      # Used for storing a country's subdivisions of a specific level.
-      def build_group(parents)
-        raise ArgumentError, "The parents argument must not be empty." if parents.empty?
-
-        return parents[0] if parents.length == 1
-
-        # The second parent is an ISO code, it can be used as-is.
-        return parents.join("-") if parents.length == 2 && parents[1].length <= 3
-
-        country_code = parents.shift
-        group = country_code
-
-        # A dash per key allows the depth to be guessed later.
-        group += "-" * parents.length
-        # Hash the remaining keys to ensure that the group is ASCII safe.
-        group + Digest::SHA1.hexdigest(parents.join("-"))
+      # Loads the parent of a subdivision group, if known.
+      def load_parent(definitions)
+        parents = parents_of(definitions)
+        get(parents[-1], parents[0...-1]) if parents.size > 1
       end
 
       # Creates a subdivision object from the provided definitions.
-      def create_subdivision_from_definitions(id, definitions)
-        if !definitions.dig("subdivisions", id)
-          # No matching definition found.
-          return nil
-        end
-
+      def create_subdivision_from_definitions(id, definitions, parent)
         definition = definitions["subdivisions"][id]
-        # The 'parents' key is omitted when it contains just the country code.
-        definitions["parents"] = [definitions["country_code"]] unless definitions.key?("parents")
-        parents = definitions["parents"]
-
-        definition["parent"] = nil
-
-        # Load the parent, if known.
-        if parents.size > 1
-          grandparents = parents.dup
-          parent_id = grandparents.pop
-          parent_group = build_group(grandparents.dup)
-          @parents ||= {}
-
-          if !@parents.dig(parent_group, parent_id)
-            @parents[parent_group] ||= {}
-            @parents[parent_group][parent_id] = get(parent_id, grandparents)
-          end
-
-          definition["parent"] = @parents[parent_group][parent_id]
-        end
+        parents = parents_of(definitions)
 
         # Prepare children.
-        if definition["has_children"]
-          children_parents = parents.dup
-          children_parents << id
-
-          definition["children"] = LazySubdivisions.new(children_parents)
-        end
+        children = definition["has_children"] ? LazySubdivisions.new(parents + [id]) : {}
 
         new(
           id: id,
-          parent: definition["parent"],
+          parent: parent,
           country_code: definition["country_code"],
           locale: definition["locale"],
           code: definition["code"],
@@ -223,7 +220,7 @@ module Addressing
           name: definition["name"],
           local_name: definition["local_name"],
           postal_code_pattern: definition["postal_code_pattern"],
-          children: definition["children"] || {}
+          children: children
         )
       end
     end

data/lib/addressing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Addressing
-  VERSION = "2.1.0"
+  VERSION = "2.2.0"
 end

data/lib/addressing.rb

@@ -3,22 +3,28 @@
 # stdlib
 require "cgi"
 require "digest"
+require "forwardable"
 require "json"
 
 # modules
 require "addressing/exceptions"
 require "addressing/enum"
+require "addressing/blank"
 require "addressing/address"
 require "addressing/address_field"
 require "addressing/address_format"
+require "addressing/address_validator"
 require "addressing/administrative_area_type"
 require "addressing/country"
+require "addressing/data_source"
 require "addressing/default_formatter"
 require "addressing/dependent_locality_type"
 require "addressing/field_override"
+require "addressing/field_violation"
 require "addressing/lazy_subdivisions"
 require "addressing/locale"
 require "addressing/locality_type"
+require "addressing/model"
 require "addressing/postal_code_type"
 require "addressing/postal_label_formatter"
 require "addressing/subdivision"
@@ -26,7 +32,6 @@ require "addressing/version"
 
 if defined?(ActiveSupport.on_load)
   ActiveSupport.on_load(:active_record) do
-    require "addressing/model"
     extend Addressing::Model
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: addressing
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Robin van der Vleuten
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies: []
 description:
 email: robinvdvleuten@gmail.com
@@ -19,8 +19,9 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
-- data/address_formats.dump
+- data/UPSTREAM_VERSION
 - data/address_formats.json
+- data/countries.json
 - data/country/af.json
 - data/country/ak.json
 - data/country/am.json
@@ -169,6 +170,7 @@ files:
 - data/country/zh-Hant.json
 - data/country/zh.json
 - data/country/zu.json
+- data/locale.json
 - data/subdivision/AD.json
 - data/subdivision/AE.json
 - data/subdivision/AM.json
@@ -719,13 +721,17 @@ files:
 - lib/addressing/address.rb
 - lib/addressing/address_field.rb
 - lib/addressing/address_format.rb
+- lib/addressing/address_validator.rb
 - lib/addressing/administrative_area_type.rb
+- lib/addressing/blank.rb
 - lib/addressing/country.rb
+- lib/addressing/data_source.rb
 - lib/addressing/default_formatter.rb
 - lib/addressing/dependent_locality_type.rb
 - lib/addressing/enum.rb
 - lib/addressing/exceptions.rb
 - lib/addressing/field_override.rb
+- lib/addressing/field_violation.rb
 - lib/addressing/lazy_subdivisions.rb
 - lib/addressing/locale.rb
 - lib/addressing/locality_type.rb