addressing 1.0.0 → 2.0.1

data/lib/addressing/subdivision.rb

@@ -1,25 +1,36 @@
 # frozen_string_literal: true
 
 module Addressing
+  # Represents administrative subdivisions within countries.
+  #
+  # Subdivisions can be hierarchical with up to three levels:
+  # Administrative Area -> Locality -> Dependent Locality
+  #
+  # @example Get subdivisions for Brazil
+  #   states = Addressing::Subdivision.all(['BR'])
+  #   states.each do |code, state|
+  #     puts "#{code}: #{state.name}"
+  #     municipalities = state.children
+  #   end
+  #
+  # @example Get subdivisions for a Brazilian state
+  #   municipalities = Addressing::Subdivision.all(['BR', 'CE'])
   class Subdivision
     class << self
-      # Subdivision definitions.
-      @@definitions = {}
-
-      # Parent subdivisions.
+      # Gets a Subdivision instance by ID and parent hierarchy.
       #
-      # Used as a cache to speed up instantiating subdivisions with the same
-      # parent. Contains only parents instead of all instantiated subdivisions
-      # to minimize duplicating the data in $this->definitions, thus reducing
-      # memory usage.
-      @@parents = {}
-
+      # @param id [String] Subdivision ID
+      # @param parents [Array<String>] Parent hierarchy (e.g., ['BR'] or ['BR', 'CE'])
+      # @return [Subdivision, nil] Subdivision instance or nil if not found
       def get(id, parents)
         definitions = load_definitions(parents)
         create_subdivision_from_definitions(id, definitions)
       end
 
       # Returns all subdivision instances for the provided parents.
+      #
+      # @param parents [Array<String>] Parent hierarchy (e.g., ['BR'] or ['BR', 'CE'])
+      # @return [Hash<String, Subdivision>] Hash of subdivision ID => Subdivision instance
       def all(parents)
         definitions = load_definitions(parents)
         return {} if definitions.empty?
@@ -57,9 +68,10 @@ module Addressing
           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]
+          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 depth.
@@ -73,12 +85,13 @@ module Addressing
 
       # 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]
+        if @definitions.key?(group)
+          return @definitions[group]
         end
 
-        @@definitions[group] = {}
+        @definitions[group] = {}
 
         # If there are predefined subdivisions at this level, try to load them.
         if has_data(parents)
@@ -86,12 +99,12 @@ module Addressing
 
           if File.exist?(filename)
             raw_definition = File.read(filename)
-            @@definitions[group] = JSON.parse(raw_definition)
-            @@definitions[group] = process_definitions(@@definitions[group])
+            @definitions[group] = JSON.parse(raw_definition)
+            @definitions[group] = process_definitions(@definitions[group])
           end
         end
 
-        @@definitions[group]
+        @definitions[group]
       end
 
       # Processes the loaded definitions.
@@ -164,13 +177,14 @@ module Addressing
           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)
+          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]
+          definition["parent"] = @parents[parent_group][parent_id]
         end
 
         # Prepare children.

data/lib/addressing/version.rb

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

data/lib/addressing.rb

@@ -6,6 +6,7 @@ require "digest"
 require "json"
 
 # modules
+require "addressing/exceptions"
 require "addressing/enum"
 require "addressing/address"
 require "addressing/address_field"
@@ -23,14 +24,6 @@ require "addressing/postal_label_formatter"
 require "addressing/subdivision"
 require "addressing/version"
 
-module Addressing
-  class Error < StandardError; end
-
-  class UnknownCountryError < Error; end
-
-  class UnknownLocaleError < Error; end
-end
-
 if defined?(ActiveSupport.on_load)
   ActiveSupport.on_load(:active_record) do
     require "addressing/model"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: addressing
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Robin van der Vleuten
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-21 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies: []
 description:
 email: robinvdvleuten@gmail.com
@@ -22,12 +22,14 @@ files:
 - data/address_formats.dump
 - data/address_formats.json
 - data/country/af.json
+- data/country/ak.json
 - data/country/am.json
 - data/country/ar-LY.json
 - data/country/ar-SA.json
 - data/country/ar.json
 - data/country/as.json
 - data/country/az.json
+- data/country/ba.json
 - data/country/be.json
 - data/country/bg.json
 - data/country/bn-IN.json
@@ -36,6 +38,7 @@ files:
 - data/country/ca.json
 - data/country/chr.json
 - data/country/cs.json
+- data/country/cv.json
 - data/country/cy.json
 - data/country/da.json
 - data/country/de-AT.json
@@ -47,8 +50,11 @@ files:
 - data/country/en-001.json
 - data/country/en-AU.json
 - data/country/en-CA.json
-- data/country/en-ID.json
-- data/country/en-MV.json
+- data/country/en-EE.json
+- data/country/en-GE.json
+- data/country/en-LT.json
+- data/country/en-LV.json
+- data/country/en-UA.json
 - data/country/en.json
 - data/country/es-419.json
 - data/country/es-AR.json
@@ -96,6 +102,7 @@ files:
 - data/country/it.json
 - data/country/ja.json
 - data/country/ka.json
+- data/country/kk-Arab.json
 - data/country/kk.json
 - data/country/km.json
 - data/country/ko-KP.json
@@ -122,10 +129,13 @@ files:
 - data/country/ps.json
 - data/country/pt-PT.json
 - data/country/pt.json
+- data/country/qu.json
+- data/country/rm.json
 - data/country/ro-MD.json
 - data/country/ro.json
 - data/country/ru-UA.json
 - data/country/ru.json
+- data/country/shn.json
 - data/country/si.json
 - data/country/sk.json
 - data/country/sl.json
@@ -712,6 +722,7 @@ files:
 - 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/lazy_subdivisions.rb
 - lib/addressing/locale.rb
@@ -735,14 +746,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Addressing library powered by CLDR and Google's address data