Indirizzo 0.1.0

data/.gitignore

@@ -0,0 +1,7 @@
+coverage/
+coverage.data
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.rvmrc

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 1.9.2
+branches:
+  only:
+    - master

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Indirizzo.gemspec

@@ -0,0 +1,28 @@
+Gem::Specification.new do |s|
+  s.name = %q{Indirizzo}
+  s.version = "0.1.0"
+
+  s.authors = [%q{Dave Worth}]
+  s.date = %q{2011-12-14}
+  s.description = %q{Indirizzo is simply an extraction of the US Street Address parsing code from Geocoder::US}
+  s.email = %q{dave@highgroove.com}
+
+  s.homepage = %q{http://github.com/daveworth/indirizzo}
+  s.licenses = [%q{LGPL}]
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.9.2}
+  s.summary = %q{Indirizzo is simply an extraction of the US Street Address parsing code from Geocoder::US}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+
+  s.add_development_dependency('rake')
+  s.add_development_dependency('cover_me')
+  s.add_development_dependency('awesome_print')
+end

data/LICENSE.txt

@@ -0,0 +1,165 @@
+		   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/README.md

@@ -0,0 +1,56 @@
+# Introduction
+
+Indirizzo is a simple extraction of the Address class (along with the numbers
+and constants handling code) from [Geocommons](http://geocommons.com/)'
+[Geocoder::US 2.0](https://github.com/geocommons/geocoder) gem.
+
+[![Build Status](https://secure.travis-ci.org/daveworth/Indirizzo.png)](http://travis-ci.org/daveworth/Indirizzo)
+
+## Background
+
+My motivation for creating this extraction is the dearth of high-quality,
+flexible, street address parsing gems available to the Ruby community.  After
+digging into Ruby-Toolbox looking for alternatives I came up with tools based on
+the Perl
+[GEO::StreetAddress::US](http://search.cpan.org/~sderle/Geo-StreetAddress-US-0.99/US.pm)
+such as [street\_address](https://github.com/astevens/street_address).  The
+street_address gem ended up being much to restrictive for my needs and my
+continued searching brought me to the Geocoder::US gem.  Regrettably the
+constraints of needing a SQLite3 database for proper geocoding added overhead to
+my simple needs. I simply need to parse addresses that may, or may not, be
+"complete" or "well-formed".  Thus Indirizzo was born.
+
+## Usage
+
+```ruby
+require 'Indirizzo'
+Indirizzo::Address.new("some address")
+```
+
+## License
+
+Indirizzo is a direct derivative of [Geocoder::US 2.0](https://github.com/geocommons/geocoder)
+
+Geocoder::US 2.0 was based on earlier work by Schuyler Erle on
+a Perl module of the same name. You can find it at
+[http://search.cpan.org/~sderle/](http://search.cpan.org/~sderle/).
+
+Geocoder::US 2.0 was written by Schuyler Erle, of Entropy Free LLC,
+with the gracious support of FortiusOne, Inc. Please send bug reports,
+patches, kudos, etc. to patches at geocoder.us.
+
+Copyright (c) 2009 FortiusOne, Inc.
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+

data/Rakefile

@@ -0,0 +1,31 @@
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+namespace :cover_me do
+  desc "Generates and opens code coverage report."
+  task :report do
+    require 'cover_me'
+    CoverMe.complete!
+  end
+end
+
+task :test do
+  Rake::Task['cover_me:report'].invoke
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/indirizzo.rb

@@ -0,0 +1 @@
+require 'Indirizzo/Address'

data/lib/indirizzo/address.rb

@@ -0,0 +1,286 @@
+require 'indirizzo/constants'
+
+module Indirizzo
+  # Defines the matching of parsed address tokens.
+  Match = {
+    # FIXME: shouldn't have to anchor :number and :zip at start/end
+    :number   => /^(\d+\W|[a-z]+)?(\d+)([a-z]?)\b/io,
+    :street   => /(?:\b(?:\d+\w*|[a-z'-]+)\s*)+/io,
+    :city     => /(?:\b[a-z'-]+\s*)+/io,
+    :state    => Regexp.new(State.regexp.source + "\s*$", Regexp::IGNORECASE),
+    :zip      => /(\d{5})(?:-\d{4})?\s*$/o,
+    :at       => /\s(at|@|and|&)\s/io,
+    :po_box => /\b[P|p]*(OST|ost)*\.*\s*[O|o|0]*(ffice|FFICE)*\.*\s*[B|b][O|o|0][X|x]\b/
+  }
+
+  # The Address class takes a US street address or place name and
+  # constructs a list of possible structured parses of the address
+  # string.
+  class Address
+    attr_accessor :text
+    attr_accessor :prenum, :number, :sufnum
+    attr_accessor :street
+    attr_accessor :city
+    attr_accessor :state
+    attr_accessor :zip, :plus4
+
+    # Takes an address or place name string as its sole argument.
+    def initialize (text)
+      raise ArgumentError, "no text provided" unless text and !text.empty?
+      if text.class == Hash
+        @text = ""
+        assign_text_to_address text
+      else
+        @text = clean text
+        parse
+      end
+    end
+
+    # Removes any characters that aren't strictly part of an address string.
+    def clean (value)
+      value.strip \
+           .gsub(/[^a-z0-9 ,'&@\/-]+/io, "") \
+           .gsub(/\s+/o, " ")
+    end
+
+    def assign_text_to_address(text)
+      if !text[:address].nil?
+        @text = clean text[:address]
+        parse
+      else
+        @street = []
+        @prenum = text[:prenum]
+        @sufnum = text[:sufnum]
+        if !text[:street].nil?
+          @street = text[:street].scan(Match[:street])
+        end
+        @number = ""
+        if !@street.nil?
+          if text[:number].nil?
+             @street.map! { |single_street|
+               single_street.downcase!
+               @number = single_street.scan(Match[:number])[0].reject{|n| n.nil? || n.empty?}.first.to_s
+               single_street.sub! @number, ""
+               single_street.sub! /^\s*,?\s*/o, ""
+              }
+         else
+            @number = text[:number].to_s
+          end
+         @street = expand_streets(@street)
+          street_parts
+        end
+        @city = []
+        if !text[:city].nil?
+          @city.push(text[:city])
+          @text = text[:city].to_s
+        else
+          @city.push("")
+        end
+        if !text[:region].nil?
+         # @state = []
+         @state = text[:region]
+          if @state.length > 2
+           # full_state = @state.strip # special case: New York
+            @state = State[@state]
+          end
+        elsif !text[:country].nil?
+          @state = text[:country]
+        elsif !text[:state].nil?
+          @state = text[:state]
+        end
+
+        @zip = text[:postal_code]
+        @plus4 = text[:plus4]
+        if !@zip
+           @zip = @plus4 = ""
+        end
+      end
+    end
+
+    # Expands a token into a list of possible strings based on
+    # the Geocoder::US::Name_Abbr constant, and expands numerals and
+    # number words into their possible equivalents.
+    def expand_numbers (string)
+      if /\b\d+(?:st|nd|rd|th)?\b/o.match string
+        match = $&
+        num = $&.to_i
+      elsif Ordinals.regexp.match string
+        num = Ordinals[$&]
+        match = $&
+      elsif Cardinals.regexp.match string
+        num = Cardinals[$&]
+        match = $&
+      end
+      strings = []
+      if num and num < 100
+        [num.to_s, Ordinals[num], Cardinals[num]].each {|replace|
+          strings << string.sub(match, replace)
+        }
+      else
+        strings << string
+      end
+      strings
+    end
+
+    def parse_zip(regex_match, text)
+      idx = text.rindex(regex_match)
+      text[idx...idx+regex_match.length] = ""
+      text.sub! /\s*,?\s*$/o, ""
+      @zip, @plus4 = @zip.map {|s|s.strip}
+      text
+    end
+
+    def parse_state(regex_match, text)
+      idx = text.rindex(regex_match)
+      text[idx...idx+regex_match.length] = ""
+      text.sub! /\s*,?\s*$/o, ""
+      @full_state = @state[0].strip # special case: New York
+      @state = State[@full_state]
+      text
+    end
+
+    def parse_number(regex_match, text)
+      # FIXME: What if this string appears twice?
+      idx = text.index(regex_match)
+      text[idx...idx+regex_match.length] = ""
+      text.sub! /^\s*,?\s*/o, ""
+      @prenum, @number, @sufnum = @number.map {|s| s and s.strip}
+      text
+    end
+
+    def parse
+      text = @text.clone.downcase
+
+      @zip = text.scan(Match[:zip])[-1]
+      if @zip
+        text = parse_zip($&, text)
+      else
+        @zip = @plus4 = ""
+      end
+
+      @state = text.scan(Match[:state])[-1]
+      if @state
+        text = parse_state($&, text)
+      else
+        @full_state = ""
+        @state = ""
+      end
+
+      @number = text.scan(Match[:number])[0]
+      # FIXME: 230 Fish And Game Rd, Hudson NY 12534
+      if @number # and not intersection?
+        text = parse_number($&, text)
+      else
+        @prenum = @number = @sufnum = ""
+      end
+
+      # FIXME: special case: Name_Abbr gets a bit aggressive
+      # about replacing St with Saint. exceptional case:
+      # Sault Ste. Marie
+
+      # FIXME: PO Box should geocode to ZIP
+      @street = text.scan(Match[:street])
+      @street = expand_streets(@street)
+      # SPECIAL CASE: 1600 Pennsylvania 20050
+      @street << @full_state if @street.empty? and @state.downcase != @full_state.downcase
+
+      @city = text.scan(Match[:city])
+      if !@city.empty?
+        @city = [@city[-1].strip]
+        add = @city.map {|item| item.gsub(Name_Abbr.regexp) {|m| Name_Abbr[m]}} 
+        @city |= add
+        @city.map! {|s| s.downcase}
+        @city.uniq!
+      else
+        @city = []
+      end
+
+      # SPECIAL CASE: no city, but a state with the same name. e.g. "New York"
+      @city << @full_state if @state.downcase != @full_state.downcase
+    end
+
+    def expand_streets(street)
+      if !street.empty? && !street[0].nil?
+        street.map! {|s|s.strip}
+        add = street.map {|item| item.gsub(Name_Abbr.regexp) {|m| Name_Abbr[m]}}
+        street |= add
+        add = street.map {|item| item.gsub(Std_Abbr.regexp) {|m| Std_Abbr[m]}}
+        street |= add
+        street.map! {|item| expand_numbers(item)}
+        street.flatten!
+        street.map! {|s| s.downcase}
+        street.uniq!
+      else
+        street = []
+      end
+      street
+    end
+
+    def street_parts
+      strings = []
+      # Get all the substrings delimited by whitespace
+      @street.each {|string|
+        tokens = string.split(" ")
+        strings |= (0...tokens.length).map {|i|
+                   (i...tokens.length).map {|j| tokens[i..j].join(" ")}}.flatten
+      }
+      strings = remove_noise_words(strings)
+
+      # Try a simpler case of adding the @number in case everything is an abbr.
+      strings += [@number] if strings.all? {|s| Std_Abbr.key? s or Name_Abbr.key? s}
+      strings.uniq
+    end
+
+    def remove_noise_words(strings)
+      # Don't return strings that consist solely of abbreviations.
+      # NOTE: Is this a micro-optimization that has edge cases that will break?
+      # Answer: Yes, it breaks on simple things like "Prairie St" or "Front St"
+      prefix = Regexp.new("^" + Prefix_Type.regexp.source + "\s*", Regexp::IGNORECASE)
+      suffix = Regexp.new("\s*" + Suffix_Type.regexp.source + "$", Regexp::IGNORECASE)
+      predxn = Regexp.new("^" + Directional.regexp.source + "\s*", Regexp::IGNORECASE)
+      sufdxn = Regexp.new("\s*" + Directional.regexp.source + "$", Regexp::IGNORECASE)
+      good_strings = strings.map {|s|
+        s = s.clone
+        s.gsub!(predxn, "")
+        s.gsub!(sufdxn, "")
+        s.gsub!(prefix, "")
+        s.gsub!(suffix, "")
+        s
+      }
+      good_strings.reject! {|s| s.empty?}
+      strings = good_strings if !good_strings.empty? {|s| not Std_Abbr.key?(s) and not Name_Abbr.key?(s)}
+      strings
+    end
+
+    def city_parts
+      strings = []
+      @city.map {|string|
+        tokens = string.split(" ")
+        strings |= (0...tokens.length).to_a.reverse.map {|i|
+                   (i...tokens.length).map {|j| tokens[i..j].join(" ")}}.flatten
+      }
+      # Don't return strings that consist solely of abbreviations.
+      # NOTE: Is this a micro-optimization that has edge cases that will break?
+      # Answer: Yes, it breaks on "Prairie"
+      good_strings = strings.reject {|s| Std_Abbr.key? s}
+      strings = good_strings if !good_strings.empty?
+      strings.uniq
+    end
+
+    def city= (strings)
+      # NOTE: This will still fail on: 100 Broome St, 33333 (if 33333 is
+      # Broome, MT or what)
+      strings = expand_streets(strings) # fix for "Mountain View" -> "Mountain Vw"
+      match = Regexp.new('\s*\b(?:' + strings.join("|") + ')\b\s*$', Regexp::IGNORECASE)
+      @street = @street.map {|string| string.gsub(match, '')}.select {|s|!s.empty?}
+    end
+
+    def po_box?
+      !Match[:po_box].match(@text).nil?
+    end
+
+    def intersection?
+      !Match[:at].match(@text).nil?
+    end
+  end
+end