addressing 2.0.1 → 2.2.0

data/lib/addressing/country.rb

@@ -17,26 +17,6 @@ module Addressing
   #   list = Addressing::Country.list('en')
   class Country
     class << self
-      AVAILABLE_LOCALES = [
-        "af", "ak", "am", "ar", "ar-LY", "ar-SA", "as", "az", "ba", "be", "bg",
-        "bn", "bn-IN", "bs", "ca", "chr", "cs", "cv", "cy", "da", "de",
-        "de-AT", "de-CH", "dsb", "el", "el-polyton", "en", "en-001", "en-AU",
-        "en-CA", "en-EE", "en-GE", "en-LT", "en-LV", "en-UA", "es", "es-419",
-        "es-AR", "es-BO", "es-CL", "es-CO", "es-CR", "es-DO", "es-EC", "es-GT",
-        "es-HN", "es-MX", "es-NI", "es-PA", "es-PE", "es-PR", "es-PY", "es-SV",
-        "es-US", "es-VE", "et", "eu", "fa", "fa-AF", "fi", "fil", "fr",
-        "fr-BE", "fr-CA", "ga", "gd", "gl", "gu", "he", "hi", "hi-Latn", "hr",
-        "hsb", "hu", "hy", "id", "ig", "is", "it", "ja", "ka", "kk", "kk-Arab",
-        "km", "ko", "ko-KP", "kok", "ky", "lo", "lt", "lv", "mk", "ml", "mn",
-        "mr", "ms", "my", "ne", "nl", "nn", "no", "or", "pa", "pl", "ps",
-        "ps-PK", "pt", "pt-PT", "qu", "rm", "ro", "ro-MD", "ru", "ru-UA",
-        "shn", "si", "sk", "sl", "so", "sq", "sr", "sr-Cyrl-BA", "sr-Cyrl-ME",
-        "sr-Cyrl-XK", "sr-Latn", "sr-Latn-BA", "sr-Latn-ME", "sr-Latn-XK",
-        "sv", "sw", "sw-CD", "sw-KE", "ta", "te", "th", "tk", "tr", "uk", "ur",
-        "ur-IN", "uz", "vi", "yue", "yue-Hans", "zh", "zh-Hant", "zh-Hant-HK",
-        "zu"
-      ]
-
       # Gets a Country instance for the provided country code.
       #
       # @param country_code [String] ISO 3166-1 alpha-2 country code
@@ -49,17 +29,9 @@ module Addressing
 
         raise UnknownCountryError.new(country_code) unless base_definitions.key?(country_code)
 
-        locale = Locale.resolve(AVAILABLE_LOCALES, locale, fallback_locale)
-        definitions = load_definitions(locale)
+        locale = Locale.resolve(available_locales, locale, fallback_locale)
 
-        new(
-          country_code: country_code,
-          name: definitions[country_code],
-          three_letter_code: base_definitions[country_code][0],
-          numeric_code: base_definitions[country_code][1],
-          currency_code: base_definitions[country_code][2],
-          locale: locale
-        )
+        build(country_code, load_definitions(locale)[country_code], locale)
       end
 
       # Gets all Country instances.
@@ -68,21 +40,11 @@ module Addressing
       # @param fallback_locale [String] Fallback locale if requested locale is unavailable
       # @return [Hash<String, Country>] Hash of country code => Country instance
       def all(locale = "en", fallback_locale = "en")
-        locale = Locale.resolve(AVAILABLE_LOCALES, locale, fallback_locale)
-        definitions = load_definitions(locale)
-
-        definitions.map do |country_code, country_name|
-          country = new(
-            country_code: country_code,
-            name: country_name,
-            three_letter_code: base_definitions[country_code][0],
-            numeric_code: base_definitions[country_code][1],
-            currency_code: base_definitions[country_code][2],
-            locale: locale
-          )
+        locale = Locale.resolve(available_locales, locale, fallback_locale)
 
-          [country_code, country]
-        end.to_h
+        load_definitions(locale).to_h do |country_code, country_name|
+          [country_code, build(country_code, country_name, locale)]
+        end
       end
 
       # Gets a list of country codes and names.
@@ -91,289 +53,41 @@ module Addressing
       # @param fallback_locale [String] Fallback locale if requested locale is unavailable
       # @return [Hash<String, String>] Hash of country code => country name
       def list(locale = "en", fallback_locale = "en")
-        locale = Locale.resolve(AVAILABLE_LOCALES, locale, fallback_locale)
-        definitions = load_definitions(locale)
+        locale = Locale.resolve(available_locales, locale, fallback_locale)
 
-        definitions.map do |country_code, country_name|
-          [country_code, country_name]
-        end.to_h
+        load_definitions(locale).dup
       end
 
       protected
 
+      def build(country_code, name, locale)
+        base_definition = base_definitions[country_code]
+
+        new(
+          country_code: country_code,
+          name: name,
+          three_letter_code: base_definition["three_letter_code"],
+          numeric_code: base_definition["numeric_code"],
+          currency_code: base_definition["currency_code"],
+          locale: locale
+        )
+      end
+
       # Loads the country definitions for the provided locale.
       def load_definitions(locale)
-        @definitions ||= {}
-        unless @definitions.key?(locale)
-          filename = File.join(File.expand_path("../../../data/country", __FILE__).to_s, "#{locale}.json")
-          @definitions[locale] = JSON.parse(File.read(filename))
-        end
+        Addressing.data_source.fetch("country/#{locale}")
+      end
 
-        @definitions[locale]
+      # Gets the locales that have country names, one data file each.
+      def available_locales
+        Addressing.data_source.names("country")
       end
 
       # Gets the base country definitions.
       #
-      # Contains data common to all locales: three letter code, numeric code.
+      # Contains data common to all locales: three letter code, numeric code, currency code.
       def base_definitions
-        @base_definitions ||= {
-          "AC" => ["ASC", nil, "SHP"],
-          "AD" => ["AND", "020", "EUR"],
-          "AE" => ["ARE", "784", "AED"],
-          "AF" => ["AFG", "004", "AFN"],
-          "AG" => ["ATG", "028", "XCD"],
-          "AI" => ["AIA", "660", "XCD"],
-          "AL" => ["ALB", "008", "ALL"],
-          "AM" => ["ARM", "051", "AMD"],
-          "AO" => ["AGO", "024", "AOA"],
-          "AQ" => ["ATA", "010", nil],
-          "AR" => ["ARG", "032", "ARS"],
-          "AS" => ["ASM", "016", "USD"],
-          "AT" => ["AUT", "040", "EUR"],
-          "AU" => ["AUS", "036", "AUD"],
-          "AW" => ["ABW", "533", "AWG"],
-          "AX" => ["ALA", "248", "EUR"],
-          "AZ" => ["AZE", "031", "AZN"],
-          "BA" => ["BIH", "070", "BAM"],
-          "BB" => ["BRB", "052", "BBD"],
-          "BD" => ["BGD", "050", "BDT"],
-          "BE" => ["BEL", "056", "EUR"],
-          "BF" => ["BFA", "854", "XOF"],
-          "BG" => ["BGR", "100", "EUR"],
-          "BH" => ["BHR", "048", "BHD"],
-          "BI" => ["BDI", "108", "BIF"],
-          "BJ" => ["BEN", "204", "XOF"],
-          "BL" => ["BLM", "652", "EUR"],
-          "BM" => ["BMU", "060", "BMD"],
-          "BN" => ["BRN", "096", "BND"],
-          "BO" => ["BOL", "068", "BOB"],
-          "BQ" => ["BES", "535", "USD"],
-          "BR" => ["BRA", "076", "BRL"],
-          "BS" => ["BHS", "044", "BSD"],
-          "BT" => ["BTN", "064", "BTN"],
-          "BV" => ["BVT", "074", "NOK"],
-          "BW" => ["BWA", "072", "BWP"],
-          "BY" => ["BLR", "112", "BYN"],
-          "BZ" => ["BLZ", "084", "BZD"],
-          "CA" => ["CAN", "124", "CAD"],
-          "CC" => ["CCK", "166", "AUD"],
-          "CD" => ["COD", "180", "CDF"],
-          "CF" => ["CAF", "140", "XAF"],
-          "CG" => ["COG", "178", "XAF"],
-          "CH" => ["CHE", "756", "CHF"],
-          "CI" => ["CIV", "384", "XOF"],
-          "CK" => ["COK", "184", "NZD"],
-          "CL" => ["CHL", "152", "CLP"],
-          "CM" => ["CMR", "120", "XAF"],
-          "CN" => ["CHN", "156", "CNY"],
-          "CO" => ["COL", "170", "COP"],
-          "CP" => ["CPT", nil, nil],
-          "CR" => ["CRI", "188", "CRC"],
-          "CU" => ["CUB", "192", "CUP"],
-          "CV" => ["CPV", "132", "CVE"],
-          "CW" => ["CUW", "531", "XCG"],
-          "CX" => ["CXR", "162", "AUD"],
-          "CY" => ["CYP", "196", "EUR"],
-          "CZ" => ["CZE", "203", "CZK"],
-          "DE" => ["DEU", "276", "EUR"],
-          "DG" => ["DGA", nil, "USD"],
-          "DJ" => ["DJI", "262", "DJF"],
-          "DK" => ["DNK", "208", "DKK"],
-          "DM" => ["DMA", "212", "XCD"],
-          "DO" => ["DOM", "214", "DOP"],
-          "DZ" => ["DZA", "012", "DZD"],
-          "EA" => [nil, nil, "EUR"],
-          "EC" => ["ECU", "218", "USD"],
-          "EE" => ["EST", "233", "EUR"],
-          "EG" => ["EGY", "818", "EGP"],
-          "EH" => ["ESH", "732", "MAD"],
-          "ER" => ["ERI", "232", "ERN"],
-          "ES" => ["ESP", "724", "EUR"],
-          "ET" => ["ETH", "231", "ETB"],
-          "FI" => ["FIN", "246", "EUR"],
-          "FJ" => ["FJI", "242", "FJD"],
-          "FK" => ["FLK", "238", "FKP"],
-          "FM" => ["FSM", "583", "USD"],
-          "FO" => ["FRO", "234", "DKK"],
-          "FR" => ["FRA", "250", "EUR"],
-          "GA" => ["GAB", "266", "XAF"],
-          "GB" => ["GBR", "826", "GBP"],
-          "GD" => ["GRD", "308", "XCD"],
-          "GE" => ["GEO", "268", "GEL"],
-          "GF" => ["GUF", "254", "EUR"],
-          "GG" => ["GGY", "831", "GBP"],
-          "GH" => ["GHA", "288", "GHS"],
-          "GI" => ["GIB", "292", "GIP"],
-          "GL" => ["GRL", "304", "DKK"],
-          "GM" => ["GMB", "270", "GMD"],
-          "GN" => ["GIN", "324", "GNF"],
-          "GP" => ["GLP", "312", "EUR"],
-          "GQ" => ["GNQ", "226", "XAF"],
-          "GR" => ["GRC", "300", "EUR"],
-          "GS" => ["SGS", "239", "GBP"],
-          "GT" => ["GTM", "320", "GTQ"],
-          "GU" => ["GUM", "316", "USD"],
-          "GW" => ["GNB", "624", "XOF"],
-          "GY" => ["GUY", "328", "GYD"],
-          "HK" => ["HKG", "344", "HKD"],
-          "HM" => ["HMD", "334", "AUD"],
-          "HN" => ["HND", "340", "HNL"],
-          "HR" => ["HRV", "191", "EUR"],
-          "HT" => ["HTI", "332", "USD"],
-          "HU" => ["HUN", "348", "HUF"],
-          "IC" => [nil, nil, "EUR"],
-          "ID" => ["IDN", "360", "IDR"],
-          "IE" => ["IRL", "372", "EUR"],
-          "IL" => ["ISR", "376", "ILS"],
-          "IM" => ["IMN", "833", "GBP"],
-          "IN" => ["IND", "356", "INR"],
-          "IO" => ["IOT", "086", "USD"],
-          "IQ" => ["IRQ", "368", "IQD"],
-          "IR" => ["IRN", "364", "IRR"],
-          "IS" => ["ISL", "352", "ISK"],
-          "IT" => ["ITA", "380", "EUR"],
-          "JE" => ["JEY", "832", "GBP"],
-          "JM" => ["JAM", "388", "JMD"],
-          "JO" => ["JOR", "400", "JOD"],
-          "JP" => ["JPN", "392", "JPY"],
-          "KE" => ["KEN", "404", "KES"],
-          "KG" => ["KGZ", "417", "KGS"],
-          "KH" => ["KHM", "116", "KHR"],
-          "KI" => ["KIR", "296", "AUD"],
-          "KM" => ["COM", "174", "KMF"],
-          "KN" => ["KNA", "659", "XCD"],
-          "KP" => ["PRK", "408", "KPW"],
-          "KR" => ["KOR", "410", "KRW"],
-          "KW" => ["KWT", "414", "KWD"],
-          "KY" => ["CYM", "136", "KYD"],
-          "KZ" => ["KAZ", "398", "KZT"],
-          "LA" => ["LAO", "418", "LAK"],
-          "LB" => ["LBN", "422", "LBP"],
-          "LC" => ["LCA", "662", "XCD"],
-          "LI" => ["LIE", "438", "CHF"],
-          "LK" => ["LKA", "144", "LKR"],
-          "LR" => ["LBR", "430", "LRD"],
-          "LS" => ["LSO", "426", "LSL"],
-          "LT" => ["LTU", "440", "EUR"],
-          "LU" => ["LUX", "442", "EUR"],
-          "LV" => ["LVA", "428", "EUR"],
-          "LY" => ["LBY", "434", "LYD"],
-          "MA" => ["MAR", "504", "MAD"],
-          "MC" => ["MCO", "492", "EUR"],
-          "MD" => ["MDA", "498", "MDL"],
-          "ME" => ["MNE", "499", "EUR"],
-          "MF" => ["MAF", "663", "EUR"],
-          "MG" => ["MDG", "450", "MGA"],
-          "MH" => ["MHL", "584", "USD"],
-          "MK" => ["MKD", "807", "MKD"],
-          "ML" => ["MLI", "466", nil],
-          "MM" => ["MMR", "104", "MMK"],
-          "MN" => ["MNG", "496", "MNT"],
-          "MO" => ["MAC", "446", "MOP"],
-          "MP" => ["MNP", "580", "USD"],
-          "MQ" => ["MTQ", "474", "EUR"],
-          "MR" => ["MRT", "478", "MRU"],
-          "MS" => ["MSR", "500", "XCD"],
-          "MT" => ["MLT", "470", "EUR"],
-          "MU" => ["MUS", "480", "MUR"],
-          "MV" => ["MDV", "462", "MVR"],
-          "MW" => ["MWI", "454", "MWK"],
-          "MX" => ["MEX", "484", "MXN"],
-          "MY" => ["MYS", "458", "MYR"],
-          "MZ" => ["MOZ", "508", "MZN"],
-          "NA" => ["NAM", "516", "NAD"],
-          "NC" => ["NCL", "540", "XPF"],
-          "NE" => ["NER", "562", "XOF"],
-          "NF" => ["NFK", "574", "AUD"],
-          "NG" => ["NGA", "566", "NGN"],
-          "NI" => ["NIC", "558", "NIO"],
-          "NL" => ["NLD", "528", "EUR"],
-          "NO" => ["NOR", "578", "NOK"],
-          "NP" => ["NPL", "524", "NPR"],
-          "NR" => ["NRU", "520", "AUD"],
-          "NU" => ["NIU", "570", "NZD"],
-          "NZ" => ["NZL", "554", "NZD"],
-          "OM" => ["OMN", "512", "OMR"],
-          "PA" => ["PAN", "591", "USD"],
-          "PE" => ["PER", "604", "PEN"],
-          "PF" => ["PYF", "258", "XPF"],
-          "PG" => ["PNG", "598", "PGK"],
-          "PH" => ["PHL", "608", "PHP"],
-          "PK" => ["PAK", "586", "PKR"],
-          "PL" => ["POL", "616", "PLN"],
-          "PM" => ["SPM", "666", "EUR"],
-          "PN" => ["PCN", "612", "NZD"],
-          "PR" => ["PRI", "630", "USD"],
-          "PS" => ["PSE", "275", "ILS"],
-          "PT" => ["PRT", "620", "EUR"],
-          "PW" => ["PLW", "585", "USD"],
-          "PY" => ["PRY", "600", "PYG"],
-          "QA" => ["QAT", "634", "QAR"],
-          "RE" => ["REU", "638", "EUR"],
-          "RO" => ["ROU", "642", "RON"],
-          "RS" => ["SRB", "688", "RSD"],
-          "RU" => ["RUS", "643", "RUB"],
-          "RW" => ["RWA", "646", "RWF"],
-          "SA" => ["SAU", "682", "SAR"],
-          "SB" => ["SLB", "090", "SBD"],
-          "SC" => ["SYC", "690", "SCR"],
-          "SD" => ["SDN", "729", "SDG"],
-          "SE" => ["SWE", "752", "SEK"],
-          "SG" => ["SGP", "702", "SGD"],
-          "SH" => ["SHN", "654", "SHP"],
-          "SI" => ["SVN", "705", "EUR"],
-          "SJ" => ["SJM", "744", "NOK"],
-          "SK" => ["SVK", "703", "EUR"],
-          "SL" => ["SLE", "694", "SLE"],
-          "SM" => ["SMR", "674", "EUR"],
-          "SN" => ["SEN", "686", "XOF"],
-          "SO" => ["SOM", "706", "SOS"],
-          "SR" => ["SUR", "740", "SRD"],
-          "SS" => ["SSD", "728", "SSP"],
-          "ST" => ["STP", "678", "STN"],
-          "SV" => ["SLV", "222", "USD"],
-          "SX" => ["SXM", "534", "XCG"],
-          "SY" => ["SYR", "760", "SYP"],
-          "SZ" => ["SWZ", "748", "SZL"],
-          "TA" => ["TAA", nil, "GBP"],
-          "TC" => ["TCA", "796", "USD"],
-          "TD" => ["TCD", "148", "XAF"],
-          "TF" => ["ATF", "260", "EUR"],
-          "TG" => ["TGO", "768", "XOF"],
-          "TH" => ["THA", "764", "THB"],
-          "TJ" => ["TJK", "762", "TJS"],
-          "TK" => ["TKL", "772", "NZD"],
-          "TL" => ["TLS", "626", "USD"],
-          "TM" => ["TKM", "795", "TMT"],
-          "TN" => ["TUN", "788", "TND"],
-          "TO" => ["TON", "776", "TOP"],
-          "TR" => ["TUR", "792", "TRY"],
-          "TT" => ["TTO", "780", "TTD"],
-          "TV" => ["TUV", "798", "AUD"],
-          "TW" => ["TWN", "158", "TWD"],
-          "TZ" => ["TZA", "834", "TZS"],
-          "UA" => ["UKR", "804", "UAH"],
-          "UG" => ["UGA", "800", "UGX"],
-          "UM" => ["UMI", "581", "USD"],
-          "US" => ["USA", "840", "USD"],
-          "UY" => ["URY", "858", "UYU"],
-          "UZ" => ["UZB", "860", "UZS"],
-          "VA" => ["VAT", "336", "EUR"],
-          "VC" => ["VCT", "670", "XCD"],
-          "VE" => ["VEN", "862", "VES"],
-          "VG" => ["VGB", "092", "USD"],
-          "VI" => ["VIR", "850", "USD"],
-          "VN" => ["VNM", "704", "VND"],
-          "VU" => ["VUT", "548", "VUV"],
-          "WF" => ["WLF", "876", "XPF"],
-          "WS" => ["WSM", "882", "WST"],
-          "XK" => ["XKK", "983", "EUR"],
-          "YE" => ["YEM", "887", "YER"],
-          "YT" => ["MYT", "175", "EUR"],
-          "ZA" => ["ZAF", "710", "ZAR"],
-          "ZM" => ["ZMB", "894", "ZMW"],
-          "ZW" => ["ZWE", "716", "ZWG"]
-        }
+        Addressing.data_source.fetch("countries")
       end
     end
 

data/lib/addressing/data_source.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Addressing
+  class << self
+    # The data source that the reference data is read from.
+    #
+    # @api private
+    attr_writer :data_source
+
+    # @api private
+    # @return [DataSource]
+    def data_source
+      @data_source ||= DataSource.new(DataSource::DEFAULT_DIR)
+    end
+  end
+
+  # Reads the reference data: the JSON files that the data sync writes.
+  #
+  # Each instance has its own cache, so a new instance reads the files again.
+  #
+  # @api private
+  class DataSource
+    # The data directory that ships with the gem.
+    DEFAULT_DIR = File.expand_path("../../data", __dir__)
+
+    def initialize(dir)
+      @dir = dir
+      @cache = {}
+    end
+
+    # Gets the dataset with the provided name.
+    #
+    # The parsed JSON is passed to the block, and the result of the block is
+    # cached, so each dataset is read and processed once per data source.
+    # A missing dataset gives nil, which is cached as well. Malformed JSON
+    # raises, because the data files are never edited by hand.
+    #
+    # @param name [String] Path relative to the data directory, without extension (e.g. "country/en")
+    # @yieldparam json [Hash, Array] The parsed dataset
+    # @return [Object, nil] The result of the block, or the parsed dataset without a block
+    # @raise [JSON::ParserError] if the dataset is malformed
+    def fetch(name)
+      return @cache[name] if @cache.key?(name)
+
+      dir, basename = File.split(name)
+      return @cache[name] = nil unless filenames(dir).include?("#{basename}.json")
+
+      json = JSON.parse(File.read(File.join(@dir, "#{name}.json"), encoding: "UTF-8"))
+      @cache[name] = block_given? ? yield(json) : json
+    end
+
+    # Gets the names of the datasets in a directory, without the directory.
+    #
+    # @param dir [String] Directory relative to the data directory (e.g. "country")
+    # @return [Array<String>] Sorted names (e.g. ["af", "ak", ...])
+    def names(dir)
+      (@names ||= {})[dir] ||= filenames(dir).filter_map { |filename| File.basename(filename, ".json") if filename.end_with?(".json") }.sort.freeze
+    end
+
+    private
+
+    # Gets the file names in a directory of the data directory.
+    #
+    # A dataset exists only when its name matches a file name exactly, so
+    # that a lookup gives the same result on a case-insensitive file system.
+    # The listing is cached like the datasets, so a file added later is not
+    # seen by this instance.
+    def filenames(dir)
+      (@filenames ||= {})[dir] ||= begin
+        path = File.join(@dir, dir)
+        Dir.exist?(path) ? Dir.children(path).to_set : Set.new
+      end
+    end
+  end
+end

data/lib/addressing/default_formatter.rb

@@ -4,8 +4,10 @@ module Addressing
   class DefaultFormatter
     DEFAULT_LOCALE = "en"
     FORMAT_PLACEHOLDER_PATTERN = /%[a-z1-9_]+/
+    FORMAT_SPLIT_PATTERN = /(#{FORMAT_PLACEHOLDER_PATTERN})/
     LEADING_TRAILING_PUNCTUATION_PATTERN = /\A[ \-,]+|[ \-,]+\z/
     MULTIPLE_SPACES_PATTERN = /\s\s+/
+    HTML_TAG_PATTERN = /\A[a-z][a-z0-9-]*\z/i
 
     DEFAULT_OPTIONS = {
       locale: DEFAULT_LOCALE,
@@ -22,9 +24,8 @@ module Addressing
     end
 
     def format(address, options = {})
-      assert_options(options)
-
       options = @default_options.merge(options)
+      assert_options(options)
       address_format = AddressFormat.get(address.country_code)
 
       # Add the country to the bottom or the top of the format string,
@@ -38,8 +39,8 @@ module Addressing
       view = build_view(address, address_format, options)
       view = render_view(view)
 
-      replacements = view.map { |key, element| ["%#{key}", element] }.to_h
-      output = format_string.gsub(FORMAT_PLACEHOLDER_PATTERN) { |m| replacements[m] }
+      replacements = view.transform_keys { |key| "%#{key}" }
+      output = insert_values(format_string, replacements)
       output = clean_output(output)
 
       if options[:html]
@@ -56,12 +57,12 @@ module Addressing
     # Builds the view for the given address.
     def build_view(address, address_format, options)
       countries = country_list(options[:locale])
-      values = values(address, address_format).merge({"country" => countries.key?(address.country_code) ? countries[address.country_code] : address.country_code})
+      values = values(address, address_format).merge("country" => countries.fetch(address.country_code, address.country_code))
       used_fields = address_format.used_fields + ["country"]
 
-      used_fields.map do |field|
+      used_fields.to_h do |field|
         [field, {html: options[:html], html_tag: "span", html_attributes: {class: field.tr("_", "-")}, value: values[field]}]
-      end.to_h
+      end
     end
 
     # Gets the country list for a locale, with caching.
@@ -71,16 +72,16 @@ module Addressing
 
     # Renders the given view.
     def render_view(view)
-      view.map do |key, element|
-        next [key, ""] if element[:value].empty?
+      view.transform_values do |element|
+        next "" if element[:value].empty?
 
         if element[:html]
           element[:value] = CGI.escapeHTML(element[:value])
-          next [key, render_html_element(element)]
+          next render_html_element(element)
         end
 
-        [key, element[:value].gsub(/<\/?[^>]*>/, "")]
-      end.to_h
+        element[:value].gsub(/<\/?[^>]*>/, "")
+      end
     end
 
     def render_html_element(element)
@@ -99,6 +100,39 @@ module Addressing
       end.join(" ")
     end
 
+    # Inserts the rendered address fields into the format string.
+    #
+    # Empty fields need special handling. When one falls between two values,
+    # keep the separator before it and discard the one after it.
+    def insert_values(format_string, replacements)
+      format_string.split("\n", -1).map do |line|
+        rendered = +""
+        separator = ""
+        skipped = false
+
+        line.split(FORMAT_SPLIT_PATTERN, -1).each do |part|
+          unless replacements.key?(part)
+            # A separator before an empty field usually belongs to
+            # the value that came before it, so keep that one.
+            separator = part unless skipped
+            next
+          end
+
+          if replacements[part].empty?
+            skipped = true
+            next
+          end
+
+          rendered << separator if !rendered.empty? || !skipped
+          rendered << replacements[part]
+          separator = ""
+          skipped = false
+        end
+
+        rendered
+      end.join("\n")
+    end
+
     # Removes empty lines, leading punctuation, excess whitespace.
     def clean_output(output)
       output.split("\n").map { |line| line.gsub(LEADING_TRAILING_PUNCTUATION_PATTERN, "").strip.gsub(MULTIPLE_SPACES_PATTERN, " ") }.reject(&:empty?).join("\n")
@@ -113,42 +147,27 @@ module Addressing
 
     # Extracts all address field values.
     def extract_address_values(address)
-      AddressField.all.map { |_, field| [field, address.send(field)] }.to_h
+      AddressField.all.values.to_h { |field| [field, address.send(field)] }
     end
 
-    # Resolves subdivision values to their display codes.
+    # Replaces the subdivision values with the codes of any predefined ones.
     def resolve_subdivision_values(values, address, address_format)
-      subdivision_fields = address_format.used_subdivision_fields
+      fields = address_format.subdivision_fields
+      chain = Subdivision.chain(address.country_code, values.values_at(*fields))
 
-      # Replace the subdivision values with the names of any predefined ones.
-      subdivision_fields.each_with_index.inject([{}, []]) do |(original_values, parents), (field, index)|
-        # This level is empty, so there can be no sublevels.
-        break if values[field].nil?
-
-        parents << ((index > 0) ? original_values[subdivision_fields[index - 1]] : address.country_code)
-
-        subdivision = Subdivision.get(values[field], parents)
+      fields.zip(chain.subdivisions) do |field, subdivision|
         break if subdivision.nil?
 
-        # Remember the original value so that it can be used for parents.
-        original_values[field] = values[field]
-
         # Replace the value with the expected code.
         use_local_name = Locale.match_candidates(address.locale, subdivision.locale)
         values[field] = use_local_name ? subdivision.local_code : subdivision.code
-
-        # The current subdivision has no children, stop.
-        break unless subdivision.children?
-
-        [original_values, parents]
       end
     end
 
-    private
-
     # Validates the provided options.
     #
     # Ensures the absence of unknown keys, correct data types and values.
+    # A subclass with more options extends this and calls super.
     def assert_options(options)
       options.each do |option, value|
         unless self.class::DEFAULT_OPTIONS.key?(option)
@@ -163,6 +182,15 @@ module Addressing
       if options.key?(:html_attributes) && !options[:html_attributes].is_a?(Hash)
         raise ArgumentError, "The option `html_attributes` must be a hash."
       end
+
+      # The tag is written into the markup as is, so only allow a tag name.
+      if options.key?(:html_tag) && !HTML_TAG_PATTERN.match?(options[:html_tag].to_s)
+        raise ArgumentError, "The option `html_tag` must be an HTML tag name."
+      end
+
+      if options.key?(:locale) && !options[:locale].is_a?(String)
+        raise ArgumentError, "The option `locale` must be a string."
+      end
     end
   end
 end

data/lib/addressing/enum.rb

@@ -5,12 +5,8 @@ module Addressing
     class << self
       # Gets all available values.
       def all
-        @values ||= {}
-        if !@values.key?(name)
-          @values[name] = constants.map { |constant| [constant, const_get(constant)] }.to_h
-        end
-
-        @values[name]
+        # Each subclass has its own @all.
+        @all ||= constants.to_h { |constant| [constant, const_get(constant)] }
       end
 
       # Gets the key of the provided value.