local_postal 0.1.0

data/lib/local_postal/address.rb

@@ -0,0 +1,118 @@
+class LocalPostal::Address
+  include ActiveModel::Model
+
+  attr_accessor :name, :company
+  attr_accessor :street_address, :secondary_address, :city, :region
+  attr_accessor :postal_code
+
+  attr_reader :format, :country
+
+  validates :country, presence: true
+
+  validate :has_required_fields
+  validate :has_valid_postal_code_pattern, unless: -> { postal_code.nil? }
+  validate :has_valid_postal_code_prefix, unless: -> { postal_code.nil? }
+
+  # The 2-character ISO 3166 country code for this address.
+  #
+  # @return [String] The country's ISO code or nil when unavailable.
+  def country_code
+    cc = carmen_country
+
+    return if cc.nil?
+
+    cc.code.upcase if cc.code.is_a?(String)
+  end
+
+  # The address' lines as they should appear on the parcel.
+  #
+  # @return [Array] The address lines.
+  def lines
+    address = format.apply(formatting_values)
+    address.split("\n").reject {|line| line.strip.empty? } + [country.upcase]
+  end
+
+  # Sets the country and automatically assigns the correct format for that it
+  # belongs to.
+  #
+  # @param [String] value The name of the country.
+  # @return [String] The supplied value.
+  def country=(value)
+    @country = value
+
+    @format = case country_code
+    when nil, '' then nil
+    else LocalPostal::Format.from_country_code(country_code)
+    end
+  end
+
+  # Maps the universal fields used in the formatting rules to the more commonly
+  # used field names that Address uses.
+  #
+  # @return [Hash] Keys are formatting rule fields; values are Address fields.
+  def self.formatting_variables_lookup_table
+    {
+      :recipient => :name,
+      :organization => :company,
+      :addressLine1 => :street_address,
+      :addressLine2 => :secondary_address,
+      :postalCode => :postal_code,
+      :locality => :city,
+      :administrativeArea => :region,
+      :sortingCode => nil,
+      :dependentLocality => nil
+    }
+  end
+
+  private
+
+  # Validates that all the required fields are present.
+  def has_required_fields
+    return unless format.is_a?(LocalPostal::Format)
+
+    format.required_fields.each do |field|
+      field_name = self.class.formatting_variables_lookup_table[field.to_sym]
+      value = public_send(field_name)
+      errors.add field_name, 'is required' if "#{value}".empty?
+    end
+  end
+
+  # Validates that the postal code is in the correct format.
+  def has_valid_postal_code_pattern
+    return unless format.is_a?(LocalPostal::Format)
+
+    matches = Regexp.new(format.postal_code_pattern).match(postal_code)
+
+    errors.add(:postal_code, 'is invalid') unless matches.to_a.length > 0
+  end
+
+  # Validates that the postal code has the correct prefix, when required.
+  def has_valid_postal_code_prefix
+    return unless format.is_a?(LocalPostal::Format)
+    return if "#{format.postal_code_prefix}".empty?
+    return if postal_code.start_with?("#{format.postal_code_prefix}")
+
+    errors.add(:postal_code, 'has an invalid prefix')
+  end
+
+  # Maps the address fields to formatting variables.
+  #
+  # @return [Hash] Values that can be used to format the address.
+  def formatting_values
+    self.class.formatting_variables_lookup_table.map do |key, value|
+      value = public_send(value) unless value.nil?
+
+      [key, value]
+    end.to_h
+  end
+
+  # Looks the country up using Carmen and returns its 2-character code when
+  # available.
+  #
+  # @return [String] The country code or nil when unavailable.
+  def carmen_country
+    return unless country.is_a?(String)
+
+    Carmen::Country.named(country) || Carmen::Country.coded(country)
+  end
+end

data/lib/local_postal/format.rb

@@ -0,0 +1,79 @@
+class LocalPostal::Format
+  include ActiveModel::Model
+
+  attr_accessor *%i[
+    administrative_area_type
+    dependent_locality_type
+    format
+    locale
+    locality_type
+    postal_code_pattern
+    postal_code_prefix
+    postal_code_type
+    required_fields
+    translations
+    uppercase_fields
+  ]
+
+  # Constructs an instance of LocalPostal::Format from the supplied JSON file.
+  #
+  # @param [String] path The full pathname of the JSON file.
+  # @return [LocalPostal::Format] The new LocalPostal::Format instance.
+  def self.from_json(path)
+    raw_json = File.read(path)
+    parsed_json = JSON.parse(raw_json)
+
+    new(parsed_json)
+  end
+
+  # Constructs an instance of LocalPostal::Format by looking up the supplied
+  # country code in config/formats/*.json.
+  #
+  # @param [String] code The 2-character country code.
+  # @raise [ArgumentError] If the code is not exactly 2 characters.
+  # @raise [ArgumentError] If the supplied country code is not supported.
+  # @return [LocalPostal::Format] The new LocalPostal::Format instance.
+  def self.from_country_code(code)
+    code = "#{code}".upcase
+
+    fail ArgumentError, "#{code} is an invalid code", caller if code.length != 2
+
+    path = File.join(LocalPostal.root, 'config', 'formats', "#{code}.json")
+
+    fail ArgumentError, "#{code} unsupported", caller unless File.file?(path)
+
+    from_json(path)
+  end
+
+  # Applies the formatting to the supplied values.
+  #
+  # @param [Hash] values The address' field values.
+  # @return [String] The address properly formatted for its country.
+  def apply(values)
+    values = values.map do |key, value|
+      key = key.upcase if uppercase_fields.include?(key)
+      value = "#{value}".upcase if uppercase_fields.include?("#{key}")
+
+      [key, value]
+    end
+
+    formatted_string % values.to_h
+  end
+
+  # Converts the format provided in the JSON files into a valid Ruby formatted
+  # String that can be parsed using the modulus operator and a Hash.
+  #
+  # @return [String] A formatted string.
+  def formatted_string
+    format.dup.tap do |str|
+      variables.each {|v| str.gsub!("%#{v}", "%{#{v}}") }
+    end
+  end
+
+  # All of the variables found in the format.
+  #
+  # @return [Array] Variable names as Strings.
+  def variables
+    format.scan(/(%\w+)/).flatten.map {|v| v[1..v.length] }
+  end
+end

data/lib/local_postal/version.rb

@@ -0,0 +1,3 @@
+module LocalPostal
+  VERSION = '0.1.0'
+end

data/lib/local_postal.rb

@@ -0,0 +1,18 @@
+require 'yaml'
+require 'json'
+require 'carmen'
+require 'active_model'
+
+module LocalPostal
+  autoload :Address, 'local_postal/address'
+  autoload :Format, 'local_postal/format'
+  autoload :VERSION, 'local_postal/version'
+
+  # Gets the path that the gem was installed in. This is used mainly to read
+  # configuration files.
+  #
+  # @return [String] The path the gem is installed in.
+  def self.root
+    @root ||= File.expand_path(File.join('..', '..'), __FILE__)
+  end
+end

data/lib/tasks/list_supported_countries.rake

@@ -0,0 +1,21 @@
+desc 'Lists all the countries that are supported'
+task :list_supported_countries do
+  require 'local_postal'
+
+  files = Dir[File.join(LocalPostal.root, 'config', 'formats', '*.json')]
+
+  countries = files.sort.map do |file|
+    country_code = File.basename(file, File.extname(file))
+    country = Carmen::Country.coded(country_code)
+    name = country ? country.name : nil
+
+    { country_code => name }
+  end
+
+  total = Carmen::Country.all.count
+
+  print "# #{countries.count} of #{total} countries are supported as of "
+  puts Time.now.strftime('%B %d, %Y')
+  puts
+  puts countries.to_yaml
+end

data/lib/tasks/list_unique_format_variables.rake

@@ -0,0 +1,12 @@
+desc 'Lists all of the unique formatting variables'
+task :list_unique_format_variables do
+  require 'local_postal'
+
+  files = Dir[File.join(LocalPostal.root, 'config', 'formats', '*.json')]
+  formats = files.map {|file| LocalPostal::Format.from_json(file) }
+
+  variables = formats.map {|f| f.variables }.flatten
+  variables = variables.compact.uniq
+
+  puts variables.to_yaml
+end

data/lib/tasks/list_unique_formatting_rules.rake

@@ -0,0 +1,32 @@
+desc 'Lists all of the address formatting rules that are unique'
+task :list_unique_formatting_rules do
+  require 'local_postal'
+
+  files = Dir[File.join(LocalPostal.root, 'config', 'formats', '*.json')]
+  formats = files.map {|file| LocalPostal::Format.from_json(file) }
+
+  rules = {
+    administrative_area_type: [],
+    dependent_locality_type: [],
+    format: [],
+    locale: [],
+    locality_type: [],
+    postal_code_pattern: [],
+    postal_code_prefix: [],
+    postal_code_type: [],
+    required_fields: [],
+    translations: [],
+    uppercase_fields: []
+  }
+
+  formats.each do |format|
+    rules.keys.each do |key|
+      value = format.public_send(key)
+      rules[key] << value unless value.nil?
+    end
+  end
+
+  rules.keys.each {|key| rules[key] = rules[key].flatten.uniq }
+
+  puts rules.to_yaml
+end

data/local_postal.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'local_postal/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'local_postal'
+  spec.version = LocalPostal::VERSION
+  spec.authors = ['Travis Haynes']
+  spec.email = ['travis@hi5dev.com']
+  spec.summary = 'Provides localized formating for postal addresses.'
+  spec.license = 'MIT'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+
+  spec.bindir = 'exe'
+
+  spec.executables = spec.files.grep(%r{^#{spec.bindir}/}) do |f|
+    File.basename(f)
+  end
+
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'carmen', '~> 1.0.2'
+  spec.add_dependency 'activemodel', '~> 4.2.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.10'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'faker'
+  spec.add_development_dependency 'byebug'
+end

metadata

@@ -0,0 +1,361 @@
+--- !ruby/object:Gem::Specification
+name: local_postal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Travis Haynes
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-09-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: carmen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.2
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- travis@hi5dev.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- config/formats/AC.json
+- config/formats/AD.json
+- config/formats/AE.json
+- config/formats/AF.json
+- config/formats/AG.json
+- config/formats/AI.json
+- config/formats/AL.json
+- config/formats/AM.json
+- config/formats/AR.json
+- config/formats/AS.json
+- config/formats/AT.json
+- config/formats/AU.json
+- config/formats/AX.json
+- config/formats/AZ.json
+- config/formats/BA.json
+- config/formats/BB.json
+- config/formats/BD.json
+- config/formats/BE.json
+- config/formats/BF.json
+- config/formats/BG.json
+- config/formats/BH.json
+- config/formats/BJ.json
+- config/formats/BL.json
+- config/formats/BM.json
+- config/formats/BN.json
+- config/formats/BO.json
+- config/formats/BR.json
+- config/formats/BS.json
+- config/formats/BT.json
+- config/formats/BY.json
+- config/formats/CA.json
+- config/formats/CC.json
+- config/formats/CD.json
+- config/formats/CH.json
+- config/formats/CI.json
+- config/formats/CL.json
+- config/formats/CN.json
+- config/formats/CO.json
+- config/formats/CR.json
+- config/formats/CV.json
+- config/formats/CX.json
+- config/formats/CY.json
+- config/formats/CZ.json
+- config/formats/DE.json
+- config/formats/DK.json
+- config/formats/DO.json
+- config/formats/DZ.json
+- config/formats/EC.json
+- config/formats/EE.json
+- config/formats/EG.json
+- config/formats/EH.json
+- config/formats/ES.json
+- config/formats/ET.json
+- config/formats/FI.json
+- config/formats/FK.json
+- config/formats/FM.json
+- config/formats/FO.json
+- config/formats/FR.json
+- config/formats/GB.json
+- config/formats/GE.json
+- config/formats/GF.json
+- config/formats/GG.json
+- config/formats/GI.json
+- config/formats/GL.json
+- config/formats/GN.json
+- config/formats/GP.json
+- config/formats/GR.json
+- config/formats/GS.json
+- config/formats/GT.json
+- config/formats/GU.json
+- config/formats/GW.json
+- config/formats/HK.json
+- config/formats/HN.json
+- config/formats/HR.json
+- config/formats/HT.json
+- config/formats/HU.json
+- config/formats/ID.json
+- config/formats/IE.json
+- config/formats/IL.json
+- config/formats/IM.json
+- config/formats/IN.json
+- config/formats/IO.json
+- config/formats/IQ.json
+- config/formats/IR.json
+- config/formats/IS.json
+- config/formats/IT.json
+- config/formats/JE.json
+- config/formats/JM.json
+- config/formats/JO.json
+- config/formats/JP.json
+- config/formats/KE.json
+- config/formats/KG.json
+- config/formats/KH.json
+- config/formats/KI.json
+- config/formats/KM.json
+- config/formats/KN.json
+- config/formats/KR.json
+- config/formats/KW.json
+- config/formats/KY.json
+- config/formats/KZ.json
+- config/formats/LA.json
+- config/formats/LB.json
+- config/formats/LI.json
+- config/formats/LK.json
+- config/formats/LR.json
+- config/formats/LS.json
+- config/formats/LT.json
+- config/formats/LU.json
+- config/formats/LV.json
+- config/formats/MA.json
+- config/formats/MC.json
+- config/formats/MD.json
+- config/formats/ME.json
+- config/formats/MF.json
+- config/formats/MG.json
+- config/formats/MH.json
+- config/formats/MK.json
+- config/formats/MM.json
+- config/formats/MN.json
+- config/formats/MO.json
+- config/formats/MP.json
+- config/formats/MQ.json
+- config/formats/MR.json
+- config/formats/MT.json
+- config/formats/MU.json
+- config/formats/MV.json
+- config/formats/MW.json
+- config/formats/MX.json
+- config/formats/MY.json
+- config/formats/MZ.json
+- config/formats/NC.json
+- config/formats/NE.json
+- config/formats/NF.json
+- config/formats/NG.json
+- config/formats/NI.json
+- config/formats/NL.json
+- config/formats/NO.json
+- config/formats/NP.json
+- config/formats/NR.json
+- config/formats/NZ.json
+- config/formats/OM.json
+- config/formats/PA.json
+- config/formats/PE.json
+- config/formats/PF.json
+- config/formats/PG.json
+- config/formats/PH.json
+- config/formats/PK.json
+- config/formats/PL.json
+- config/formats/PM.json
+- config/formats/PN.json
+- config/formats/PR.json
+- config/formats/PT.json
+- config/formats/PW.json
+- config/formats/PY.json
+- config/formats/QA.json
+- config/formats/RE.json
+- config/formats/RO.json
+- config/formats/RS.json
+- config/formats/RU.json
+- config/formats/RW.json
+- config/formats/SA.json
+- config/formats/SC.json
+- config/formats/SE.json
+- config/formats/SG.json
+- config/formats/SH.json
+- config/formats/SI.json
+- config/formats/SJ.json
+- config/formats/SK.json
+- config/formats/SM.json
+- config/formats/SN.json
+- config/formats/SO.json
+- config/formats/SR.json
+- config/formats/ST.json
+- config/formats/SV.json
+- config/formats/SZ.json
+- config/formats/TA.json
+- config/formats/TC.json
+- config/formats/TH.json
+- config/formats/TJ.json
+- config/formats/TM.json
+- config/formats/TN.json
+- config/formats/TR.json
+- config/formats/TV.json
+- config/formats/TW.json
+- config/formats/TZ.json
+- config/formats/UA.json
+- config/formats/UM.json
+- config/formats/US.json
+- config/formats/UY.json
+- config/formats/UZ.json
+- config/formats/VA.json
+- config/formats/VC.json
+- config/formats/VE.json
+- config/formats/VG.json
+- config/formats/VI.json
+- config/formats/VN.json
+- config/formats/WF.json
+- config/formats/XK.json
+- config/formats/YT.json
+- config/formats/ZA.json
+- config/formats/ZM.json
+- config/formats/ZZ.json
+- lib/local_postal.rb
+- lib/local_postal/address.rb
+- lib/local_postal/format.rb
+- lib/local_postal/version.rb
+- lib/tasks/list_supported_countries.rake
+- lib/tasks/list_unique_format_variables.rake
+- lib/tasks/list_unique_formatting_rules.rake
+- local_postal.gemspec
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Provides localized formating for postal addresses.
+test_files: []