lite-address 1.0.0

data/lib/lite/address/format.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'snail' unless defined?(Snail)
+
+module Lite
+  module Address
+
+    FORMAT_KEYS = %i[
+      number
+      street street2
+      street_type street_type2 redundant_street_type
+      unit_prefix unit
+      prefix prefix2
+      suffix suffix2
+      city
+      state
+      postal_code postal_code_ext
+      country list regexp
+    ].freeze
+
+    class Format < Struct.new(*FORMAT_KEYS, keyword_init: true)
+
+      def country_code
+        country.alpha2
+      end
+
+      def country_name
+        country.name
+      end
+
+      def intersection?
+        !!street && !!street2
+      end
+
+      def full_postal_code
+        return if postal_code.nil?
+
+        @full_postal_code ||= [postal_code, postal_code_ext].compact.join('-')
+      end
+
+      def line1(str = +'')
+        parts = intersection? ? intersection_line1 : address_line1
+        str + parts.compact.join(' ').strip
+      end
+
+      def line2(str = +'')
+        str += [city, state].compact.join(', ')
+        str << " #{full_postal_code}" if postal_code
+        str.strip
+      end
+
+      def state_name
+        list.subdivision_map[state]
+      end
+
+      def to_h
+        @to_h ||= Lite::Address::FORMAT_KEYS.each_with_object({}) do |key, hash|
+          hash[key] = public_send(key)
+        end
+      end
+
+      def to_s(format = :default)
+        case format
+        when :line1 then line1
+        when :line2 then line2
+        else [line1, line2].reject(&:empty?).join(', ')
+        end
+      end
+
+      def to_snail(options = {})
+        Snail.new(snail_params.merge(options)).to_s
+      end
+
+      def to_ukey
+        Lite::Address::Ukey.generate(to_s)
+      end
+
+      def ==(other)
+        to_s == other.to_s
+      end
+
+      alias alpha2 country_code
+      alias state_code state
+
+      private
+
+      # rubocop:disable Metrics/AbcSize, Naming/VariableNumber
+      def address_line1
+        parts = []
+        parts << number
+        parts << prefix
+        parts << street
+        parts << street_type unless redundant_street_type
+        parts << suffix
+        parts << unit_prefix
+        # http://pe.usps.gov/cpim/ftp/pubs/Pub28/pub28.pdf pg28
+        parts << (unit_prefix ? unit : "\# #{unit}") if unit
+        parts
+      end
+
+      def snail_params
+        {
+          line_1: line1,
+          city: city,
+          region: state,
+          postal_code: full_postal_code,
+          country: country_code
+        }
+      end
+
+      def intersection_line1
+        parts = []
+        parts << prefix
+        parts << street
+        parts << street_type
+        parts << suffix
+        parts << 'and'
+        parts << prefix2
+        parts << street2
+        parts << street_type2
+        parts << suffix2
+        parts
+      end
+      # rubocop:enable Metrics/AbcSize, Naming/VariableNumber
+
+    end
+
+  end
+end

data/lib/lite/address/list.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'yaml' unless defined?(YAML)
+
+module Lite
+  module Address
+    class List
+
+      attr_reader :country
+
+      def initialize(country)
+        @country = country
+      end
+
+      def cardinal_codes
+        @cardinal_codes ||= cardinal_types.invert
+      end
+
+      def cardinal_types
+        @cardinal_types ||= begin
+          file_path = File.expand_path('types/cardinal.yml', File.dirname(__FILE__))
+          YAML.load_file(file_path)
+        end
+      end
+
+      def street_types
+        @street_types ||= begin
+          file_path = File.expand_path('types/street.yml', File.dirname(__FILE__))
+          YAML.load_file(file_path)
+        end
+      end
+
+      def street_type_regexps
+        @street_type_regexps ||= street_types.each_with_object({}) do |(type, abbr), hash|
+          hash[abbr] = /\b(?:#{abbr}|#{::Regexp.quote(type)})\b/ix
+        end
+      end
+
+      def subdivision_codes
+        @subdivision_codes ||= subdivision_names.invert
+      end
+
+      def subdivision_map
+        @subdivision_map ||= country.subdivisions.transform_values(&:name)
+      end
+
+      def subdivision_names
+        @subdivision_names ||= country.subdivisions.each_with_object({}) do |(code, sub), hash|
+          hash[sub.name.downcase] = code
+        end
+      end
+
+      def unit_abbr_regexps
+        # http://pe.usps.com/text/pub28/pub28c2_003
+        @unit_abbr_regexps ||= unit_abbr_numbered_regexps.merge(unit_abbr_unnumbered_regexps)
+      end
+
+      def unit_abbr_numbered_regexps
+        @unit_abbr_numbered_regexps ||= {
+          'Apt' => /(?:ap|dep)(?:ar)?t(?:me?nt)?/i,
+          'PO Box' => /p\W*[om]\W*b(?:ox)?/i,
+          'Bldg' => /bu?i?ldi?n?g/i,
+          'Dept' => /dep(artmen)?t/i,
+          'Floor' => /flo*r?/i,
+          'Hanger' => /ha?nga?r/i,
+          'Lot' => /lo?t/i,
+          'Room' => /ro*m/i,
+          'Pier' => /pier/i,
+          'Slip' => /slip/i,
+          'Space' => /spa?ce?/i,
+          'Stop' => /stop/i,
+          'Drawer' => /drawer/i,
+          'Suite' => /su?i?te/i,
+          'Trailer' => /tra?i?le?r/i,
+          'Box' => /\w*(?<!po\W)box/i,
+          'Unit' => /uni?t/i
+        }
+      end
+
+      def unit_abbr_unnumbered_regexps
+        @unit_abbr_unnumbered_regexps ||= {
+          'Basement' => /ba?se?me?n?t/i,
+          'Front' => /fro?nt/i,
+          'Lobby' => /lo?bby/i,
+          'Lower' => /lowe?r/i,
+          'Office' => /off?i?ce?/i,
+          'PH' => /pe?n?t?ho?u?s?e?/i,
+          'Rear' => /rear/i,
+          'Side' => /side/i,
+          'Upper' => /uppe?r/i
+        }
+      end
+
+      alias state_codes subdivision_codes
+      alias state_map subdivision_map
+      alias state_names subdivision_names
+
+    end
+  end
+end

data/lib/lite/address/parser.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'countries' unless defined?(ISO3166::Country)
+
+module Lite
+  module Address
+    class Parser
+
+      LOOKUPS = %i[any formal informal intersectional].freeze
+      CAPITALIZATION_PARTS = %w[street street_type street2 street_type2 city unit_prefix].freeze
+      STREET_POSITIONS = ['', '1', '2'].freeze
+
+      attr_reader :address, :country_code
+
+      def initialize(address, country_code: 'US')
+        @address = sanitize_address(address)
+        @country_code = sanitize_country_code(country_code)
+      end
+
+      class << self
+
+        LOOKUPS.each do |method_name|
+          define_method(method_name) do |address, args = {}|
+            instance = new(address, country_code: args.delete(:country_code) || 'US')
+            instance.public_send(method_name, args)
+          end
+        end
+
+      end
+
+      def any(args = {})
+        return intersectional(args) if regexp.corner.match(address)
+
+        formal(args) || informal(args)
+      end
+
+      def formal(args = {})
+        return unless (match = regexp.formal_address.match(address))
+
+        map = match_map(match)
+        generate_address(map, args)
+      end
+
+      def informal(args = {})
+        return unless (match = regexp.informal_address.match(address))
+
+        map = match_map(match)
+        generate_address(map, args)
+      end
+
+      def intersectional(args = {})
+        return unless (match = regexp.intersectional_address.match(address))
+
+        map = match_map(match)
+        intersectional_submatch(match, map, 'street')
+        intersectional_submatch(match, map, 'street_type')
+        intersectional_rematch(match, map, 'street_type')
+
+        generate_address(map, args)
+      end
+
+      protected
+
+      def country
+        @country ||= ISO3166::Country.new(country_code)
+      end
+
+      def list
+        @list ||= Lite::Address::List.new(country)
+      end
+
+      def regexp
+        @regexp ||= Lite::Address::Regexp.new(list)
+      end
+
+      private
+
+      def sanitize_address(value)
+        value.delete_prefix('(').delete_suffix(')')
+      end
+
+      def sanitize_country_code(value)
+        value.to_s.upcase
+      end
+
+      def match_map(match)
+        match.names.each_with_object({}) do |name, hash|
+          hash[name] = match[name] if match[name]
+        end
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      def normalization_map
+        @normalization_map ||= {
+          'prefix' => list.cardinal_types,
+          'prefix1' => list.cardinal_types,
+          'prefix2' => list.cardinal_types,
+          'suffix' => list.cardinal_types,
+          'suffix1' => list.cardinal_types,
+          'suffix2' => list.cardinal_types,
+          'street_type' => list.street_types,
+          'street_type1' => list.street_types,
+          'street_type2' => list.street_types,
+          'state' => list.subdivision_names
+        }
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def intersectional_submatch(match, map, part)
+        parts = regexp.intersectional_address.named_captures
+        parts = parts[part].filter_map { |i| match[i.to_i] }
+        map[part] = parts[0] if parts[0]
+        map["#{part}2"] = parts[1] if parts[1]
+      end
+
+      def intersectional_rematch(_match, map, part)
+        return unless map[part] && (!map["#{part}2"] || (map[part] == map["#{part}2"]))
+
+        type = map[part].dup
+        return unless type.gsub!(/s\W*$/i, '') && (/\A#{regexp.public_send(part)}\z/io =~ type)
+
+        map[part] = map["#{part}2"] = type
+      end
+
+      def address_strip_chars(map)
+        map.each do |key, string|
+          string.strip!
+
+          if key == 'number'
+            string.gsub!(%r{[^\w\s\-\#&/.]}, '')
+          else
+            string.gsub!(%r{[^\w\s\-\#&/]}, '')
+          end
+        end
+      end
+
+      def address_redundantize_street_type(map)
+        map['redundant_street_type'] = false
+        return unless map['street'] && !map['street_type']
+
+        match = regexp.street.match(map['street'])
+        map['street_type'] = match['street_type'] if match
+        map['redundant_street_type'] = true
+      end
+
+      def address_abbreviate_unit_prefixes(map)
+        list.unit_abbr_regexps.each do |abbr, regex|
+          regex.match(map['unit_prefix']) do |_match|
+            map['unit_prefix'] = abbr
+          end
+        end
+      end
+
+      def address_normalize_values(map)
+        normalization_map.each do |key, hash|
+          next unless (map_key = map[key])
+
+          mapping = hash[map_key.downcase]
+          map[key] = mapping if mapping
+        end
+      end
+
+      def address_avoid_redundant_street_type(map)
+        STREET_POSITIONS.each do |suffix|
+          street = map["street#{suffix}"]
+          street_type = map["street_type#{suffix}"]
+          next if !street || !street_type
+
+          type_regexp = list.street_type_regexps[street_type.downcase]
+          next unless type_regexp.match(street)
+
+          map.delete("street_type#{suffix}")
+        end
+      end
+
+      def address_expand_cardinals(map)
+        return unless map['city']
+
+        map['city'].gsub!(/^(#{regexp.cardinal_code})\s+(?=\S)/o) do |match|
+          "#{list.cardinal_codes[match[0].upcase]} "
+        end
+      end
+
+      def address_fix_dirty_ordinals(map)
+        # Sometimes parcel data will have addresses like "1 1ST ST" as "1 1 ST ST"
+        return unless map['street']
+
+        map['street'].gsub!(/\A(\d+\s+st|\d+\s+nd|\d+\s+rd|\d+\s+th)\z/i) do |match|
+          match.gsub!(/\s+/, '')
+        end
+      end
+
+      def address_capitalize_parts(map)
+        CAPITALIZATION_PARTS.each do |k|
+          map[k] = map[k].split.map(&:capitalize).join(' ') if map[k]
+        end
+      end
+
+      def generate_address(map, args = {})
+        address_strip_chars(map)
+        address_redundantize_street_type(map)
+        address_abbreviate_unit_prefixes(map)
+        address_normalize_values(map)
+        address_avoid_redundant_street_type(map) if args[:avoid_redundant_street_type]
+        address_expand_cardinals(map)
+        address_fix_dirty_ordinals(map)
+        address_capitalize_parts(map)
+
+        map.merge!(country: country, list: list, regexp: regexp)
+        Lite::Address::Format.new(map)
+      end
+
+    end
+  end
+end

data/lib/lite/address/regexp.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Lite
+  module Address
+    class Regexp
+
+      attr_reader :list
+
+      def initialize(list)
+        @list = list
+      end
+
+      def avoid_unit
+        @avoid_unit ||= /(?:[^\#\w]+|\Z)/ix
+      end
+
+      def cardinal_code
+        @cardinal_code ||= begin
+          values = list.cardinal_codes.keys
+          ::Regexp.new(values.join('|'), ::Regexp::IGNORECASE)
+        end
+      end
+
+      def cardinal_type
+        @cardinal_type ||= begin
+          values = list.cardinal_types.each_with_object([]) do |(key, val), array|
+            array << key
+            array << [::Regexp.quote(val.gsub(/(\w)/, '\1.')), ::Regexp.quote(val)]
+          end
+
+          ::Regexp.new(values.join('|'), ::Regexp::IGNORECASE)
+        end
+      end
+
+      def city_state
+        @city_state ||= /(?:(?<city> [^\d,]+?)\W+(?<state> #{subdivision}))/ix
+      end
+
+      def corner
+        @corner ||= /(?:\band\b|\bat\b|&|@)/ix
+      end
+
+      def formal_address
+        @formal_address ||= /\A[^\w\x23]*
+          #{number} \W*
+          #{street}\W+
+          (?:#{unit}\W+)?
+          #{place}\W*\z
+        /ix
+      end
+
+      def informal_address
+        @informal_address ||= /\A\s*
+          (?:#{unit} #{separator} #{place})?
+          (?:#{number})? \W*
+          #{street} #{avoid_unit}
+          (?:#{unit} #{separator})?
+          (?:#{place})?
+        /ix
+      end
+
+      def intersectional_address
+        @intersectional_address ||= /\A\W*
+          #{street}\W*?
+          \s+#{corner}\s+
+          #{street}\W+
+          #{place}\W*\z
+        /ix
+      end
+
+      # rubocop:disable Lint/MixedRegexpCaptureTypes
+      def number
+        # Utah and Wisconsin have a more elaborate system of block numbering
+        # http://en.wikipedia.org/wiki/House_number#Block_numbers
+        @number ||= /(?<number>(n|s|e|w)?\d+[.-]?\d*)(?=\D)/ix
+      end
+      # rubocop:enable Lint/MixedRegexpCaptureTypes
+
+      def place
+        @place ||= /(?:#{city_state}\W*)? (?:#{postal_code})?/ix
+      end
+
+      def postal_code
+        @postal_code ||= /(?:(?<postal_code>\d{5})(?:-?(?<postal_code_ext>\d{4}))?)/ix
+      end
+
+      def separator
+        @separator ||= /(?:\W+|\Z)/ix
+      end
+
+      def street
+        @street ||= /(?:
+          (?:
+            (?<street> #{cardinal_type})\W+
+            (?<street_type> #{street_type})\b
+          )
+          | (?:(?<prefix> #{cardinal_type})\W+)?
+          (?:
+            (?<street> [^,]*\d)
+            (?:[^\w,]* (?<suffix> #{cardinal_type})\b)
+            |
+            (?<street> [^,]+)
+            (?:[^\w,]+(?<street_type> #{street_type})\b)
+            (?:[^\w,]+(?<suffix> #{cardinal_type})\b)?
+            |
+            (?<street> [^,]+?)
+            (?:[^\w,]+(?<street_type> #{street_type})\b)?
+            (?:[^\w,]+(?<suffix> #{cardinal_type})\b)?
+          )
+        )/ix
+      end
+
+      def street_type
+        @street_type ||= begin
+          values = (list.street_types.keys + list.street_types.values).uniq
+          ::Regexp.new(values.join('|'), ::Regexp::IGNORECASE)
+        end
+      end
+
+      def subdivision
+        @subdivision ||= begin
+          values = list.subdivision_codes.flatten.map { |code| ::Regexp.quote(code) }
+          ::Regexp.new("\b#{values.join('|')}\b", ::Regexp::IGNORECASE)
+        end
+      end
+
+      def unit
+        @unit ||= %r{
+          (?:
+            (?:
+              (?:#{unit_numbered} \W*)
+              | (?<unit_prefix> \#)\W*
+            )
+            (?<unit> [\w/-]+)
+          ) | #{unit_unnumbered}
+        }ix
+      end
+
+      def unit_numbered
+        @unit_numbered ||= begin
+          values = list.unit_abbr_numbered_regexps.values
+          /(?<unit_prefix>#{values.join('|')})(?![a-z])/ix
+        end
+      end
+
+      def unit_unnumbered
+        @unit_unnumbered ||= begin
+          values = list.unit_abbr_unnumbered_regexps.values
+          /(?<unit_prefix>#{values.join('|')})\b/ix
+        end
+      end
+
+    end
+  end
+end