people_places_things 2.3.0

data/lib/people_places_things/location.rb

@@ -0,0 +1,30 @@
+module PeoplePlacesThings
+  class Location
+    attr_accessor :city, :state, :zip, :raw
+  
+    def initialize(str)
+      self.raw = str
+    
+      tokens = str.split(/\s|,/).collect {|t| t.strip}
+    
+      # try to parse last token as zip
+      #
+      self.zip = ZipCode.new(tokens.last) rescue nil
+      tokens = tokens.slice(0..-2) if self.zip
+    
+      # try to parse last token as state
+      #
+      self.state = State.new(tokens.last) rescue nil
+      tokens = tokens.slice(0..-2) if self.state
+    
+      # remainder must be city
+      #
+      self.city = tokens.join(' ').strip
+      self.city = nil if self.city.empty?
+    end
+  
+    def to_s
+      [[self.city, (self.state.to_s(:abbr) rescue nil)].compact.join(','), self.zip.to_s].compact.join(' ')
+    end
+  end
+end

data/lib/people_places_things/person_name.rb

@@ -0,0 +1,121 @@
+module PeoplePlacesThings
+  class PersonName
+    attr_accessor :first, :middle, :last, :suffix, :raw
+
+    def initialize(str, fmt = :auto_detect)
+      raise "Unsupported Format" if !PARSE_FORMATS.include?(fmt)
+    
+      if fmt == :auto_detect
+        fmt = str.include?(',') ? :last_first_middle : :first_middle_last
+      end
+    
+      self.raw = str
+    
+      parts = str.split(/\s|,/).collect {|p| p.strip}.reject {|p| PersonName.blank?(p) || p == ',' }
+  
+      if parts.size == 1
+        self.last = parts.first
+      else
+        case fmt
+          when :first_middle_last
+            if parts.size > 2 and SUPPORTED_SUFFIXES.detect {|s| s.casecmp(parts.last) == 0}
+              self.suffix = PersonName.normalize_suffix(parts.last)
+              parts.delete_at(parts.size - 1)
+            end
+        
+            self.first = parts.first if parts.size > 0
+            self.last = parts.last if parts.size > 1
+        
+            if parts.size > 2 && ODD_LAST_NAME_PREFIXES.detect {|s| s.casecmp(parts[-2]) == 0}
+              self.last = "#{parts[-2]}#{self.last}"
+              parts.delete_at(parts.size - 2)
+            end
+            
+            self.middle = parts[1..(parts.size - 2)].join(' ') if parts.size > 2
+    
+          when :last_first_middle
+            self.last = parts.first if parts.size > 0
+        
+            if parts.size > 1 && ODD_LAST_NAME_PREFIXES.detect {|s| s.casecmp(self.last) == 0}
+              self.last << parts[1]
+              parts.delete_at(1)
+            end
+
+            if parts.size > 2 and SUPPORTED_SUFFIXES.detect {|s| s.casecmp(parts[1]) == 0}
+              self.suffix = PersonName.normalize_suffix(parts[1])
+              parts.delete_at(1)
+            end
+
+            self.first = parts[1] if parts.size > 1
+            self.middle = parts[2..(parts.size - 1)].join(' ') if parts.size > 2
+        end
+      end
+    end
+  
+    def to_s(fmt = :full)
+      raise "Unsupported Format" if !OUTPUT_FORMATS.include?(fmt)
+
+      case fmt
+        when :first, :middle, :last
+          self.send(fmt)
+      
+        when :full
+          [self.first, self.middle, self.last, self.suffix].compact.join(' ')
+        
+        when :full_reverse
+          [self.last, self.first, self.middle, self.suffix].compact.join(' ')
+      
+        when :first_space_last
+          [self.first, self.last].compact.join(' ')
+      
+        when :last_space_first
+          [self.last, self.first].compact.join(' ')
+      
+        when :last_comma_first
+          [self.last, self.first].compact.join(',')
+      
+        when :last_comma_space_first
+          [(self.first ? "#{self.last}," : self.last), self.first].compact.join(' ')
+      end
+    end
+
+    def first_i
+      self.first[0,1] rescue nil
+    end
+
+    def middle_i
+      self.middle[0,1] rescue nil
+    end
+
+    def last_i
+      self.last[0,1] rescue nil
+    end
+  
+    def eql?(other, initials_only=false)
+      if other.is_a?(PersonName)
+        [:first, :middle, :last].all? do |k|
+          msg = (k != :last && initials_only) ? "#{k}_i" : k
+          me = self.send(msg)
+          them = other.send(msg)
+          me && them ? me.casecmp(them) == 0 : true
+        end
+      end
+    end
+  
+    PARSE_FORMATS = [:first_middle_last, :last_first_middle, :auto_detect]
+    OUTPUT_FORMATS = [:first, :middle, :last, :full, :full_reverse, :first_space_last, :last_space_first, :last_comma_first, :last_comma_space_first]
+
+    private
+
+    def self.blank?(string_or_nil)
+      string_or_nil.nil? || string_or_nil !~ /\S/
+    end
+  
+    def self.normalize_suffix(suffix)
+      suffix.match(/\w+/)[0] rescue suffix
+    end
+  
+    SUPPORTED_SUFFIXES = %w(II III IV V JR JR. SR SR.)
+    ODD_LAST_NAME_PREFIXES = %w(MC ST ST.)
+  end
+end

data/lib/people_places_things/phone_number.rb

@@ -0,0 +1,48 @@
+module PeoplePlacesThings
+  class PhoneNumber
+    attr_accessor :country_code, :area_code, :number, :exchange, :suffix, :raw
+  
+    def initialize(str)
+      extract = str.strip.match(/^([-+()\d ]+)$/)[0].gsub(/[^\d]/, '') rescue nil
+      raise "Unsupported Format" if !extract || extract.length < 10 || extract.length > 11
+
+      if extract.length == 11
+        self.country_code = extract.slice!(0..0)
+      else
+        self.country_code = '1'
+      end
+    
+      raise "Unsupported Format" if self.country_code != '1'
+    
+      self.area_code = extract.slice!(0..2)
+    
+      self.number = extract.dup
+
+      self.exchange = extract.slice!(0..2)
+    
+      self.suffix = extract
+
+      raise "Unsupported Format" if !self.exchange || !self.suffix
+    end
+  
+    def to_s(fmt = :full_formatted)
+      raise "Unsupported Format" if !OUTPUT_FORMATS.include?(fmt)
+
+      case fmt
+        when :full_digits
+          "#{self.country_code}#{self.area_code}#{self.exchange}#{self.suffix}"
+        
+        when :local_digits
+          "#{self.exchange}#{self.suffix}"
+        
+        when :full_formatted
+          "#{self.country_code} (#{self.area_code}) #{self.exchange}-#{self.suffix}"
+        
+        when :local_formatted
+          "#{self.exchange}-#{self.suffix}"
+      end
+    end
+  
+    OUTPUT_FORMATS = [:full_digits, :local_digits, :full_formatted, :local_formatted]
+  end
+end

data/lib/people_places_things/state.rb

@@ -0,0 +1,83 @@
+module PeoplePlacesThings
+  class State
+    attr_accessor :sym, :raw
+  
+    def initialize(str)
+      self.raw = str
+      token = str.strip.downcase
+    
+      if FORWARD.has_key?(token.to_sym)
+        self.sym = token.to_sym
+      elsif REVERSE.has_key?(token)
+        self.sym = REVERSE[token]
+      end
+    
+      raise "Unsupported Format" if !self.sym
+    end
+  
+    def to_s(fmt = :full)
+      raise "Unsupported Format" if !OUTPUT_FORMATS.include?(fmt)
+      fmt == :full ? FORWARD[self.sym].capitalize : self.sym.to_s.upcase
+    end
+  
+    OUTPUT_FORMATS = [:abbr, :full]
+  
+    private
+
+    FORWARD = {
+      :al => "alabama",
+    	:ak => "alaska",
+    	:az => "arizona",
+    	:ar => "arkansas",
+    	:ca => "california",
+    	:co => "colorado",
+    	:ct => "connecticut",
+    	:de => "delaware",
+    	:dc => "district of columbia",
+    	:fl => "florida",
+    	:ga => "georgia",
+    	:hi => "hawaii",
+    	:id => "idaho",
+    	:il => "illinois",
+    	:in => "indiana",
+    	:ia => "iowa",
+    	:ks => "kansas",
+    	:ky => "kentucky",
+    	:la => "louisiana",
+    	:me => "maine",
+    	:md => "maryland",
+    	:ma => "massachusetts",
+    	:mi => "michigan",
+    	:mn => "minnesota",
+    	:ms => "mississippi",
+    	:mo => "missouri",
+    	:mt => "montana",
+    	:ne => "nebraska",
+    	:nv => "nevada",
+    	:nh => "new hampshire",
+    	:nj => "new jersey",
+    	:nm => "new mexico",
+    	:ny => "new york",
+    	:nc => "north carolina",
+    	:nd => "north dakota",
+    	:oh => "ohio",
+    	:ok => "oklahoma",
+    	:or => "oregon",
+    	:pa => "pennsylvania",
+    	:ri => "Rhode island",
+    	:sc => "south carolina",
+    	:sd => "south dakota",
+    	:tn => "tennessee",
+    	:tx => "texas",
+    	:ut => "utah",
+    	:vt => "vermont",
+    	:va => "virginia",
+    	:wa => "washington",
+    	:wv => "west virginia",
+    	:wi => "wisconsin",
+    	:wy => "wyoming",
+  	}
+	
+  	REVERSE = FORWARD.inject({}) {|r, f| r[f[1]] = f[0]; r}
+  end
+end

data/lib/people_places_things/street_address.rb

@@ -0,0 +1,180 @@
+module PeoplePlacesThings
+  class StreetAddress
+    attr_accessor :number, :pre_direction, :name, :suffix, :post_direction, :unit_type, :unit, :raw
+  
+    def initialize(str)
+      tokens = str.split(/[\s,]/).select {|s| !s.empty?}
+    
+      # Check the first token for leading numericality.  If so, set number to the first token, and delete it
+      #
+      if tokens.first =~ /(^\d+.*)/
+        self.number = $1
+        tokens.shift
+      end
+    
+      # If at least two tokens remain, check next-to-last token as unit type.  If so, set unit_type and unit, and delete the tokens
+      #
+      if tokens.size > 1 
+        self.unit_type = StreetAddress.find_token(tokens[-2], UNIT_TYPES)
+        if self.unit_type
+          self.unit = tokens[-1]
+          tokens.slice!(tokens.size - 2, 2)
+        end
+      end
+    
+      # If at least one token remains, check last token for directionality.  If so, set post_direction and delete the token
+      #
+      if tokens.size > 0
+        self.post_direction = StreetAddress.find_token(tokens[-1], DIRECTIONS)
+        if self.post_direction
+          post_direction_token = tokens[-1]
+          tokens.slice!(tokens.size - 1)
+        end
+      end
+    
+      # If at least one token remains, check last token for suffix.  If so, self set.suffix and delete the token
+      #
+      if tokens.size > 0
+        self.suffix = StreetAddress.find_token(tokens[-1], SUFFIXES)
+        tokens.slice!(tokens.size - 1) if self.suffix
+      end
+    
+      # If at least two tokens remain, check first for directionality. If so, set pre_direction and delete token
+      #
+      if tokens.size > 1
+        self.pre_direction = StreetAddress.find_token(tokens.first, DIRECTIONS)
+        tokens.shift if self.pre_direction
+      end
+    
+      # if any tokens remain, set joined remaining tokens as name, otherwise, set name to post_direction, if set, and set post_direction to nil
+      #
+      if tokens.size > 0
+        self.name = tokens.join(' ')
+      else
+        self.name = post_direction_token
+        self.post_direction = nil
+      end
+    
+      validate_parts
+    end
+  
+    def to_s
+      parts = []
+      parts << self.number if self.number
+      parts << DIRECTIONS[self.pre_direction].first if self.pre_direction
+      parts << self.name if self.name
+      parts << SUFFIXES[self.suffix].first if self.suffix
+      parts << DIRECTIONS[self.post_direction].first if self.post_direction
+      parts << UNIT_TYPES[self.unit_type].first if self.unit_type
+      parts << self.unit if self.unit
+      parts.join(' ')
+    end
+  
+    def self.string_for(symbol, form)
+      raise "Requested unknown form \"#{type}\" for :#{symbol}" if !SUPPORTED_FORMS.include?(form)
+    
+      val = DIRECTIONS[symbol] || SUFFIXES[symbol] || UNIT_TYPES[symbol]
+
+      if val
+        val = ((val[SUPPORTED_FORMS.index(form)] rescue nil) || (val.first rescue val))
+      end
+    
+      val
+    end
+  
+    private
+  
+    def validate_parts
+      [:pre_direction, :suffix, :post_direction, :unit_type].each do |p|
+        if self.send(p)
+          legal_values = p == :suffix ? SUFFIXES : p == :unit_type ? UNIT_TYPES : DIRECTIONS
+          raise "Invalid #{p.to_s} \"#{self.send(p)}\"" if !legal_values.include?(self.send(p))
+        end
+      end
+    end
+  
+    def self.find_token(token, values)
+      values.keys.each do |k|
+        return k if values[k].detect {|v| v.casecmp(token) == 0}
+      end
+    
+      nil
+    end
+  
+    DIRECTIONS = {
+      :north => %w(north n n.),
+      :northeast => %w(northeast ne ne. n.e.),
+      :east => %w(east e e.),
+      :southeast => %w(southeast se se. s.e.),
+      :south => %w(south s s.),
+      :southwest => %w(southwest sw sw. s.w.),
+      :west => %w(west w w.),
+      :northwest => %w(northwest nw nw. n.w.)
+    }
+  
+    SUFFIXES = {
+    	:alley => %w(alley al al.),
+    	:avenue => %w(avenue ave ave. av av.),
+    	:beach => %w(beach bch bch.),
+    	:bend => %w(bend),
+    	:boulevard => %w(boulevard blvd blvd. blv blv.),
+    	:center => %w(center ctr ctr.),
+    	:circle => %w(circle cir cir.),
+    	:cliff => %w(cliff clf clf.),
+    	:club => %w(club),
+    	:condo => %w(condo con con.),
+    	:court => %w(court ct ct. cor cor.),
+    	:cove => %w(cove),
+    	:creek => %w(creek crk crk.),
+    	:crossing => %w(crossing xing xing. crs crs.),
+    	:drive => %w(drive dr dr.),
+    	:extension => %w(extension ext ext.),
+    	:freeway => %w(freeway fwy fwy.),
+    	:gardens => %w(gardens gdns gdns.),
+    	:glen => %w(glen gl gl.),
+    	:green => %w(green grn grn.),
+    	:heights => %w(heights hts hts.),
+    	:highway => %w(highway hwy hwy. hgwy hgwy.),
+    	:hill => %w(hill),
+    	:knoll => %w(knoll knl knl.),
+    	:lake => %w(lake),
+    	:lane => %w(lane ln ln.),
+    	:landing => %w(landing lndg lndg.),
+    	:loop => %w(loop),
+    	:meadows => %w(meadows mdws mdws.),
+    	:manor => %w(manor mnr mnr.),
+    	:mountain => %w(mountain mtn mtn. mnt mnt.),
+    	:oaks => %w(oaks),
+    	:oval => %w(oval),
+    	:park => %w(park pk pk. prk prk.),
+    	:parkway => %w(parkway pkwy pkwy. pky pky.),
+    	:pier => %w(pier),
+    	:place => %w(place pl pl.),
+    	:plaza => %w(plaza plz plz.),
+    	:point => %w(point pt pt. pnt pnt.),
+    	:ridge => %w(ridge ri ri.),
+    	:road => %w(road rd rd.),
+    	:row => %w(row),
+    	:run => %w(run),
+    	:springs => %w(springs spgs spgs.),
+    	:square => %w(square sq sq.),
+    	:street => %w(street st st.),
+    	:station => %w(station sta sta.),
+    	:terrace => %w(terrace ter ter. te te.),
+    	:turnpike => %w(turnpike tpke tpke.),
+    	:trace => %w(trace trc trc.),
+    	:trail => %w(trail trl trl. tl tl.),
+    	:valley => %w(valley vly vly.),
+    	:walk => %w(walk),
+    	:way => %w(way)
+    }
+  
+    UNIT_TYPES = {
+      :suite => %w(suite ste ste.),
+      :number => %w(number # nbr nbr.),
+      :apartment => %w(apartment apt apt.)
+    }
+  
+    SUPPORTED_FORMS = [:long, :short]
+  end
+end