worldwide 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94f52548c00b327fa3649904eb25487d9e029fc34512e0edc4cf42e82690845b
-  data.tar.gz: aa1b423717212544a46c9286d3ffdcb1683071fd09a9ef54a372920fe9042dc0
+  metadata.gz: 1aced99de70bc88aa872fd56bf0aea847c81bcf3b12987e031ce39a51e9dbdd0
+  data.tar.gz: de70d75e3374938d1611ef3c0541ce7d880d4dbf5ad3b45fb4dddeeb6ef75382
 SHA512:
-  metadata.gz: '08ba06ef3c1a28929ee81b7e32143b572ac5b80c869244b724a22c33ca89038e23220ecc7f6bc7cf28f56f6599f84887dabbd5d3db1dd68661991c75bd3745ff'
-  data.tar.gz: 78fc15cb9692b9086a3bf0c3627b8285cba0acd396dc8287e0a260b2dc1168dc3e9d24091123cf0907d001f44d9a04203485b5b707d1a206deeb1a0949a56afc
+  metadata.gz: e77fdb3041498e31ab8cec400ca4be14e531939e9f99fa800aae011d1a7be0e076fc6b4e65ea4ca877b98a051dc6e88994b71d27582cb083fb8c71ac0645e65f
+  data.tar.gz: bb7c2b6963ab30589320b70db8af56942ce454d01cbf6dc7f13c7da74c86964513de2711a31bd9fa07457e96fcb810f482d89e31a214acf5454f47ec21517dfc

data/CHANGELOG.md

@@ -29,6 +29,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ---
 
+## [0.12.0] - 2024-05-15
+
+- Add pry-byebug gem [#149](https://github.com/Shopify/worldwide/pull/149)
+- Introduce additional_address_fields to Region class and define them for BE, BR, CL, CO, ES, ID, MX, NL, PH, TR, VN [#148](https://github.com/Shopify/worldwide/pull/148)
+- Define format_extended attribute on 12 country regions [#150](https://github.com/Shopify/worldwide/pull/150)
+
 ## [0.11.1] - 2024-05-13
 
 - Handle blank strings for Region, country_code parameter in Zip normalization

data/Gemfile

@@ -19,6 +19,7 @@ group :development do
   gem "rubocop-shopify", require: false
   gem "rubocop", require: false
   gem "ruby-lsp", require: false
+  gem "pry-byebug", require: false
 end
 
 group :test do

data/Gemfile.lock

@@ -13,7 +13,7 @@ GIT
 PATH
   remote: .
   specs:
-    worldwide (0.11.1)
+    worldwide (0.12.0)
       activesupport (~> 7.0)
       i18n
       phonelib (~> 0.8)
@@ -36,6 +36,8 @@ GEM
     base64 (0.1.1)
     bigdecimal (3.1.4)
     builder (3.2.4)
+    byebug (11.1.3)
+    coderay (1.1.3)
     concurrent-ruby (1.2.2)
     connection_pool (2.4.1)
     drb (2.1.1)
@@ -44,6 +46,7 @@ GEM
       concurrent-ruby (~> 1.0)
     json (2.7.1)
     language_server-protocol (3.17.0.3)
+    method_source (1.1.0)
     minitest (5.17.0)
     minitest-focus (1.3.1)
       minitest (>= 4, < 6)
@@ -55,9 +58,9 @@ GEM
     mocha (2.0.2)
       ruby2_keywords (>= 0.0.5)
     mutex_m (0.1.2)
-    nokogiri (1.16.2-arm64-darwin)
+    nokogiri (1.16.5-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.16.2-x86_64-linux)
+    nokogiri (1.16.5-x86_64-linux)
       racc (~> 1.4)
     parallel (1.24.0)
     parser (3.3.0.5)
@@ -65,6 +68,12 @@ GEM
       racc
     phonelib (0.8.7)
     prettier_print (1.2.0)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
     psych (5.1.0)
       stringio
     racc (1.7.3)
@@ -122,6 +131,7 @@ DEPENDENCIES
   minitest-focus
   minitest-reporters
   mocha
+  pry-byebug
   rake (~> 13.0)
   rake-compiler
   rubocop

data/README.md

@@ -377,6 +377,8 @@ $ I18n.with_locale(:'zh-CN') { lon.single_line }
 => "英国London"
 ```
 
+Address format strings are described in detail [here](docs/address_format_strings.md).
+
 #### Validation
 
 ```ruby

data/db/data/regions/BE.yml

@@ -24,5 +24,13 @@ languages:
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{streetName}{streetNumber}_{address2}_{zip}{city}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      required: false
 emoji: "\U0001F1E7\U0001F1EA"
 timezone: Europe/Brussels

data/db/data/regions/BR.yml

@@ -19,6 +19,21 @@ languages:
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{zip}_{address1}_{address2}_{city}{province}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city} {province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{zip}_{streetName}{streetNumber}_{address2}{neighborhood}_{city}{province}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      decorator: ","
+      required: true
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      decorator: ","
+      required: false
 emoji: "\U0001F1E7\U0001F1F7"
 localized_data:
 - name: tax_credential_br

data/db/data/regions/CL/en.yml

@@ -0,0 +1,25 @@
+---
+en:
+  worldwide:
+    CL:
+      addresses:
+        neighborhood:
+          label:
+            default: Commune
+            optional: Commune (optional)
+          errors:
+            blank: Enter a commune
+            too_long: Commune is too long (maximum is 255 characters)
+            contains_emojis: Commune cannot contain emojis
+            contains_mathematical_symbols: Commune cannot contain mathematical symbols
+            contains_restricted_characters: Commune can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: Commune cannot have more than %{word_count}
+              words
+            contains_html_tags: Commune cannot contain HTML tags.
+            contains_url: Commune cannot contain URLs.
+            unknown_for_city: Enter a valid commune name for %{city}.
+            unknown_for_zip: Enter a valid commune name for %{zip}.
+            unknown_for_address: Commune may be incorrect.
+          warnings:
+            contains_too_many_words: Commune is recommended to have less than %{word_count} words

data/db/data/regions/CL.yml

@@ -14,6 +14,19 @@ week_start_day: sunday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}_{province}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{streetName}{streetNumber}_{address2}{neighborhood}_{zip}{city}_{province}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      required: false
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      required: false
 emoji: "\U0001F1E8\U0001F1F1"
 languages:
   - es

data/db/data/regions/CO.yml

@@ -15,6 +15,14 @@ week_start_day: sunday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{city}{province}{zip}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city} {province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}{neighborhood}_{city}{province}{zip}_{phone}"
+additional_address_fields:
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      required: false
 emoji: "\U0001F1E8\U0001F1F4"
 languages:
   - es

data/db/data/regions/ES.yml

@@ -21,6 +21,14 @@ languages:
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}{province}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{streetName}{streetNumber}_{address2}_{zip}{city}{province}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      required: false
 emoji: "\U0001F1EA\U0001F1F8"
 zones:
 - name: A Coruña

data/db/data/regions/ID.yml

@@ -17,6 +17,15 @@ languages:
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{city}_{province}{zip}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{city}_{province} {zip}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}{neighborhood}_{city}_{province}{zip}_{phone}"
+additional_address_fields:
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      decorator: ","
+      required: false
 emoji: "\U0001F1EE\U0001F1E9"
 zones:
 - name: Aceh

data/db/data/regions/MX.yml

@@ -15,6 +15,19 @@ week_start_day: sunday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}{province}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city} {province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{streetName}{streetNumber}_{address2}{neighborhood}_{zip}{city}{province}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      required: false
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      required: true
 emoji: "\U0001F1F2\U0001F1FD"
 languages:
   - es

data/db/data/regions/NL.yml

@@ -23,5 +23,13 @@ languages:
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{streetName}{streetNumber}_{address2}_{zip}{city}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      required: true
 emoji: "\U0001F1F3\U0001F1F1"
 timezone: Europe/Amsterdam

data/db/data/regions/PH.yml

@@ -15,6 +15,15 @@ week_start_day: sunday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}_{province}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}{neighborhood}_{zip}{city}_{province}_{phone}"
+additional_address_fields:
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      decorator: "Barangay"
+      required: true
 emoji: "\U0001F1F5\U0001F1ED"
 languages:
   - en

data/db/data/regions/TR/en.yml

@@ -0,0 +1,25 @@
+---
+en:
+  worldwide:
+    TR:
+      addresses:
+        neighborhood:
+          label:
+            default: District
+            optional: District (optional)
+          errors:
+            blank: Enter a district
+            too_long: District is too long (maximum is 255 characters)
+            contains_emojis: District cannot contain emojis
+            contains_mathematical_symbols: District cannot contain mathematical symbols
+            contains_restricted_characters: District can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: District cannot have more than %{word_count}
+              words
+            contains_html_tags: District cannot contain HTML tags.
+            contains_url: District cannot contain URLs.
+            unknown_for_city: Enter a valid district name for %{city}.
+            unknown_for_zip: Enter a valid district name for %{zip}.
+            unknown_for_address: District may be incorrect.
+          warnings:
+            contains_too_many_words: District is recommended to have less than %{word_count} words

data/db/data/regions/TR.yml

@@ -16,6 +16,14 @@ week_start_day: monday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}{neighborhood}_{zip}{city}_{phone}"
+additional_address_fields:
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      required: false
 emoji: "\U0001F1F9\U0001F1F7"
 languages:
   - tr

data/db/data/regions/TW/en.yml

@@ -0,0 +1,25 @@
+---
+en:
+  worldwide:
+    TW:
+      addresses:
+        neighborhood:
+          label:
+            default: District
+            optional: District (optional)
+          errors:
+            blank: Enter a district
+            too_long: District is too long (maximum is 255 characters)
+            contains_emojis: District cannot contain emojis
+            contains_mathematical_symbols: District cannot contain mathematical symbols
+            contains_restricted_characters: District can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: District cannot have more than %{word_count}
+              words
+            contains_html_tags: District cannot contain HTML tags.
+            contains_url: District cannot contain URLs.
+            unknown_for_city: Enter a valid district name for %{city}.
+            unknown_for_zip: Enter a valid district name for %{zip}.
+            unknown_for_address: District may be incorrect.
+          warnings:
+            contains_too_many_words: District is recommended to have less than %{word_count} words

data/db/data/regions/TW.yml

@@ -17,6 +17,8 @@ week_start_day: sunday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{city}{zip}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{neighborhood}{city}{zip}_{phone}"
 emoji: "\U0001F1F9\U0001F1FC"
 languages:
   - "zh-TW"

data/db/data/regions/VN/en.yml

@@ -0,0 +1,25 @@
+---
+en:
+  worldwide:
+    VN:
+      addresses:
+        neighborhood:
+          label:
+            default: Ward
+            optional: Ward (optional)
+          errors:
+            blank: Enter a ward
+            too_long: Ward is too long (maximum is 255 characters)
+            contains_emojis: Ward cannot contain emojis
+            contains_mathematical_symbols: Ward cannot contain mathematical symbols
+            contains_restricted_characters: Ward can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: Ward cannot have more than %{word_count}
+              words
+            contains_html_tags: Ward cannot contain HTML tags.
+            contains_url: Ward cannot contain URLs.
+            unknown_for_city: Enter a valid ward name for %{city}.
+            unknown_for_zip: Enter a valid ward name for %{zip}.
+            unknown_for_address: Ward may be incorrect.
+          warnings:
+            contains_too_many_words: Ward is recommended to have less than %{word_count} words

data/db/data/regions/VN.yml

@@ -13,6 +13,15 @@ week_start_day: monday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{city}{zip}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{city} {zip}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{neighborhood}_{city}{zip}_{phone}"
+additional_address_fields:
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      decorator: ", Quận"
+      required: false
 emoji: "\U0001F1FB\U0001F1F3"
 languages:
   - fr

data/db/data/regions/_default/en.yml

@@ -63,6 +63,42 @@ en:
             unknown_for_address: Address line 1 may be incorrect.
           warnings:
             contains_too_many_words: Address line 1 is recommended to have less than %{word_count} words
+        street_name:
+          label:
+            default: Street
+            optional: Street (optional)
+          errors:
+            blank: Enter a street name
+            too_long: Street is too long (maximum is 255 characters)
+            contains_emojis: Street cannot contain emojis
+            contains_mathematical_symbols: Street cannot contain mathematical symbols
+            contains_restricted_characters: Street can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: Street cannot have more than %{word_count} words
+            contains_html_tags: Street cannot contain HTML tags.
+            contains_url: Street cannot contain URLs.
+            street_unknown_for_zip: Enter a valid street name for %{zip}.
+            unknown_for_address: Street may be incorrect.
+          warnings:
+            contains_too_many_words: Street is recommended to have less than %{word_count} words
+        street_number:
+          label:
+            default: Building number
+            optional: Building number (optional)
+          errors:
+            blank: Enter a building number
+            too_long: Building number is too long (maximum is 255 characters)
+            contains_emojis: Building number cannot contain emojis
+            contains_mathematical_symbols: Building number cannot contain mathematical symbols
+            contains_restricted_characters: Building number can only contain letters,
+              numbers, local characters, and special characters
+            contains_html_tags: Building number cannot contain HTML tags.
+            contains_url: Building number cannot contain URLs.
+            building_number_invalid: Building number couldn't be located for %{street},
+              %{zip}.
+            unknown_for_address: Building number may be incorrect.
+          warnings:
+            contains_too_many_words: Building number is recommended to have less than %{word_count} words
         address2:
           label:
             default: Apartment, suite, etc.
@@ -83,9 +119,28 @@ en:
             building_number_invalid: Building number couldn't be located for %{street},
               %{zip}.
             unknown_for_address: Address line 2 may be incorrect.
-
           warnings:
             contains_too_many_words: Address line 2 is recommended to have less than %{word_count} words
+        neighborhood:
+          label:
+            default: Neighborhood
+            optional: Neighborhood (optional)
+          errors:
+            blank: Enter a neighborhood
+            too_long: Neighborhood is too long (maximum is 255 characters)
+            contains_emojis: Neighborhood cannot contain emojis
+            contains_mathematical_symbols: Neighborhood cannot contain mathematical symbols
+            contains_restricted_characters: Neighborhood can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: Neighborhood cannot have more than %{word_count}
+              words
+            contains_html_tags: Neighborhood cannot contain HTML tags.
+            contains_url: Neighborhood cannot contain URLs.
+            unknown_for_city: Enter a valid neighborhood name for %{city}.
+            unknown_for_zip: Enter a valid neighborhood name for %{zip}.
+            unknown_for_address: Neighborhood may be incorrect.
+          warnings:
+            contains_too_many_words: Neighborhood is recommended to have less than %{word_count} words
         city:
           label:
             default: City

data/docs/address_format_strings.md

@@ -0,0 +1,111 @@
+# Address format strings
+
+## Introduction <!-- omit in toc -->
+
+Worldwide defines different address format strings that control the layout of address elements for each country region.
+
+Each format string has a different syntax, and is meant for use in different scenarios.
+
+This page aims to document these syntaxes, their usage and limitations for those who need to create/edit them.
+
+**⚠️ Warning:** You shouldn't parse these format strings yourself, but instead make use of the higher-level libraries that already consume these strings. This document is meant for those creating the higher-level libraries, or for those who need to make changes to these format strings.
+
+## Table of Contents <!-- omit in toc -->
+
+- [Address format strings](#address-format-strings)
+  - [`edit`](#edit)
+    - [English description](#english-description)
+    - [Grammar](#grammar)
+  - [`show`](#show)
+    - [English description](#english-description-1)
+    - [Grammar](#grammar-1)
+    - [Limitations](#limitations)
+      - [No escaping of special characters](#no-escaping-of-special-characters)
+      - [No space-less formats](#no-space-less-formats)
+      - [No free-standing prefix/suffix characters](#no-free-standing-prefixsuffix-characters)
+      - [No special concatenation characters](#no-special-concatenation-characters)
+
+## `edit`
+
+The `edit` address format string controls the layout of elements within an address input form for a country region.
+
+e.g., `{company}_{address1}_{address2}_{city}_{country}{province}{zip}_{phone}`
+
+![Example address input form formatted using the `edit` address format](images/edit.png)
+
+**⚠️ Warning:** There's a lot more to creating an address form than just the layout of the fields (error messages, optionality, placeholders, etc.) You probably shouldn't parse `edit` yourself; use a pre-existing, higher-level library instead. This document is meant for those creating the higher-level libraries.
+
+### English description
+
+1. Fields are specified by wrapping the field name in curly braces: `{field_name}`
+2. Lines of fields are separated by an underscore `_`
+
+### Grammar
+
+Below is the EBNF ([extended Backus-Naur form](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form)) for `edit` address format strings:
+
+```
+EditFormatString ::= Lines
+Lines ::= Line (LineSeparator Lines)?
+LineSeparator ::= '_'
+Line ::= Field+
+Field ::= '{' Identifier '}'
+Identifier ::= [a-zA-Z0-9_]+
+```
+
+## `show`
+
+The `show` address format string controls how addresses should be rendered as part of a UI.
+
+e.g., `{firstName} {lastName}_{company}_{address1}_{address2}_{city} {province} {zip}_{country}_{phone}`
+
+![Example address formatted using the `show` address format](images/show.png)
+
+### English description
+
+1. Fields are specified by wrapping the field name in curly braces: `{field_name}`
+2. Lines of fields are separated by an underscore `_`
+3. Fields are separated by an space character
+4. Other characters are permitted as prefixes/suffixes of a field
+   * Note: the prefix of a field is separated from the suffix of a preceding field by the space character separating the fields
+
+### Grammar
+
+Below is the EBNF ([extended Backus-Naur form](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form)) for `show` address format strings:
+
+```
+ShowFormatString ::= Lines
+Lines ::= Line (LineSeparator Lines)?
+LineSeparator ::= '_'
+Line ::= PrefixedSuffixedField (FieldSeparator PrefixedSuffixedField)*
+FieldSeparator ::= ' '
+PrefixedSuffixedField ::= (Prefix? Field Suffix?)
+Field ::= '{' Identifier '}'
+Identifier ::= [a-zA-Z0-9_]+
+Prefix ::= Text
+Suffix ::= Text
+Text ::= [^_{} ]+
+```
+
+### Limitations
+
+There are a number of limitations to the `show` syntax that cannot cover the complexity of the world's address formatting.
+
+#### No escaping of special characters
+
+There is no support for escaping special characters: `{`, `}`, `_`, `<space>`
+
+#### No space-less formats
+
+Since the fields are space-separated, there is no way to specify a non-separator space character.
+However, many languages (e.g., English) are space-delimited, so libraries using the `show` string end up concatenatiing the fields together using spaces, even if the language doesn't require spaces (e.g., Japanese).
+
+#### No free-standing prefix/suffix characters
+
+There is no way to specify prefix/suffix characters that will be included regardless of the provided values.
+Any characters besides a field name are either prefixes or suffixes of a field, and therefore if a value for the field is not provided, the associated prefix/suffix characters are also not provided.
+
+#### No special concatenation characters
+
+There is no way to specify characters other than space characters for concatenating two fields.
+For example, in Brazil, when the `city` and `province` fields are formatted adjacent to one another, instead of a space between the fields, ` - ` should be used. These concatenation characters are neither a prefix nor a suffix of either field, so cannot be specified in this format's syntax.

data/lib/worldwide/field.rb

@@ -11,7 +11,10 @@ module Worldwide
       :last_name,
       :company,
       :address1,
+      :street_name,
+      :street_number,
       :address2,
+      :neighborhood,
       :city,
       :province,
       :zip,

data/lib/worldwide/region.rb

@@ -19,6 +19,7 @@ module Worldwide
       :example_city,
       :flag,
       :format,
+      :format_extended,
       :group,
       :group_name,
       :cldr_code,
@@ -32,6 +33,7 @@ module Worldwide
       :zip_example,
       :zip_regex,
       :zip_requirement,
+      :additional_address_fields,
     ]
 
     # A region may have more than one parent.
@@ -73,6 +75,12 @@ module Worldwide
     #   - show: how to arrange the fields when formatting an address for display
     attr_accessor :format
 
+    # Hash of strings denoting how to format an address in this region, including substitute and/or additional fields.
+    # The format is described in https://shopify.engineering/handling-addresses-from-all-around-the-world
+    #   - edit: the fields to present on an address input form
+    #   - show: how to arrange the fields when formatting an address for display
+    attr_accessor :format_extended
+
     # The string that results from appending " Countries" to the adjectival form of the {group_name}
     # @example
     #   Worldwide.region(code: "CA").group == "North American Countries"
@@ -189,6 +197,9 @@ module Worldwide
     # If true, then the province is optional for addresses in this region.
     attr_accessor :province_optional
 
+    # A hash of additional address fields and the rules for concatening them into the standard fields
+    attr_accessor :additional_address_fields
+
     def initialize(
       alpha_three: nil,
       continent: false,
@@ -224,11 +235,13 @@ module Worldwide
       @tax_rate = tax_rate
       @use_zone_code_as_short_name = use_zone_code_as_short_name
 
+      @additional_address_fields = {}
       @building_number_required = false
       @building_number_may_be_in_address2 = false
       @currency = nil
       @flag = nil
       @format = {}
+      @format_extended = {}
       @group = nil
       @group_name = nil
       @languages = []

data/lib/worldwide/regions_loader.rb

@@ -95,6 +95,7 @@ module Worldwide
     end
 
     def apply_territory_attributes(region, spec)
+      region.additional_address_fields = spec["additional_address_fields"] || {}
       region.building_number_required = spec["building_number_required"] || false
       region.building_number_may_be_in_address2 = spec["building_number_may_be_in_address2"] || false
       currency_code = spec["currency"]
@@ -102,6 +103,7 @@ module Worldwide
       region.currency = Worldwide.currency(code: currency_code) unless currency_code.nil?
       region.flag = spec["emoji"]
       region.format = spec["format"]
+      region.format_extended = spec["format_extended"] || {}
       region.group = spec["group"]
       region.group_name = spec["group_name"]
       region.hide_provinces_from_addresses = spec["hide_provinces_from_addresses"] || false

data/lib/worldwide/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Worldwide
-  VERSION = "0.11.1"
+  VERSION = "0.12.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: worldwide
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.12.0
 platform: ruby
 authors:
 - Shopify
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-05-13 00:00:00.000000000 Z
+date: 2024-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -6552,6 +6552,7 @@ files:
 - db/data/regions/CI.yml
 - db/data/regions/CK.yml
 - db/data/regions/CL.yml
+- db/data/regions/CL/en.yml
 - db/data/regions/CM.yml
 - db/data/regions/CN.yml
 - db/data/regions/CN/bg-BG.yml
@@ -7947,9 +7948,11 @@ files:
 - db/data/regions/TN.yml
 - db/data/regions/TO.yml
 - db/data/regions/TR.yml
+- db/data/regions/TR/en.yml
 - db/data/regions/TT.yml
 - db/data/regions/TV.yml
 - db/data/regions/TW.yml
+- db/data/regions/TW/en.yml
 - db/data/regions/TZ.yml
 - db/data/regions/UA.yml
 - db/data/regions/UG.yml
@@ -8061,6 +8064,7 @@ files:
 - db/data/regions/VE.yml
 - db/data/regions/VG.yml
 - db/data/regions/VN.yml
+- db/data/regions/VN/en.yml
 - db/data/regions/VU.yml
 - db/data/regions/WF.yml
 - db/data/regions/WS.yml
@@ -8171,6 +8175,9 @@ files:
 - db/data/regions/_default/zh-TW.yml
 - db/data/world.yml
 - db/extant_outcodes.yml
+- docs/address_format_strings.md
+- docs/images/edit.png
+- docs/images/show.png
 - formats.md
 - lib/worldwide.rb
 - lib/worldwide/address.rb