nameable_record 0.2.0 → 1.0.0

data/lib/nameable_record/name.rb

@@ -1,31 +1,28 @@
 module NameableRecord
+
   class Name
+
     attr_reader :first, :middle, :last, :prefix, :suffix
 
-    def initialize( last, first, prefix=nil, middle=nil, suffix=nil )
-      @first, @middle, @last, @prefix, @suffix = first, middle, last, prefix, suffix
-
-      @name_pattern_map = {
-          /%l/ => last || "",
-          /%f/ => first || "",
-          /%m/ => middle || "",
-          /%p/ => prefix || "",
-          /%s/ => suffix || "",
-      }
-
-      @@predefined_patterns = {
-        :full => " %l, %f %s",
-        :full_with_middle => " %l, %f %m %s",
-        :full_with_prefix => " %l, %p %f %s",
-        :full_sentence => "%p %f %l %s",
-        :full_sentence_with_middle => "%p %f %m %l %s"
-      }
+    def initialize( *args )
+      @last, @first, @prefix, @middle, @suffix = args
 
       self.freeze
     end
 
-    # Creates a name based on pattern provided.  Defaults to given + additional
-    # given + family names concatentated.
+    def ==( another_name )
+      return false unless another_name.is_a?( self.class )
+
+      %w(last first middle suffix prefix).map do |attr|
+        another_name.send( attr ) == send( attr )
+      end.all? { |r| r == true }
+    end
+
+    def eql?( another_name )
+      self == another_name
+    end
+
+    # Creates a name based on pattern provided.  Defaults to last, first.
     #
     # Symbols:
     #   %l - last name
@@ -34,19 +31,46 @@ module NameableRecord
     #   %p - prefix
     #   %s - suffix
     #
-    def to_s( pattern="" )
-      if pattern.is_a?( Symbol )
-        to_return = @@predefined_patterns[pattern]
-      else
-        to_return = pattern
-      end
-      to_return = @@predefined_patterns[:full] if to_return.empty?
+    def to_s( pattern='%l, %f' )
+      pattern = PREDEFINED_PATTERNS[pattern] if pattern.is_a?( Symbol )
 
-      @name_pattern_map.each do |pat, replacement|
-        to_return = to_return.gsub( pat, replacement )
+      PATTERN_MAP.inject( pattern ) do |name, mapping|
+        name = name.gsub( mapping.first,
+                          (send( mapping.last ) || '') )
       end
-
-      to_return.strip
     end
+
+    PREDEFINED_PATTERNS = {
+      :full                      => "%l, %f %s",
+      :full_with_middle          => "%l, %f %m %s",
+      :full_with_prefix          => "%l, %p %f %s",
+      :full_sentence             => "%p %f %l %s",
+      :full_sentence_with_middle => "%p %f %m %l %s"
+    }.freeze
+
+    PATTERN_MAP = {
+       /%l/ => :last,
+       /%f/ => :first,
+       /%m/ => :middle,
+       /%p/ => :prefix,
+       /%s/ => :suffix
+    }.freeze
+
+    PREFIX_BASE =  %w(Mr Mrs Miss Dr General)  # The order of this matters because of PREFIXES_CORRECTIONS
+    SUFFIX_BASE =  %w(Jr III V IV Esq) # The order of this matters because of SUFFIXES_CORRECTIONS
+
+    PREFIXES    = PREFIX_BASE.map { |p| [p, "#{p}.", p.upcase, "#{p.upcase}.", p.downcase, "#{p.downcase}."] }.flatten.sort
+    SUFFIXES    = SUFFIX_BASE.map { |p| [p, "#{p}.", p.upcase, "#{p.upcase}.", p.downcase, "#{p.downcase}."] }.flatten.sort
+
+    PREFIXES_CORRECTIONS = Hash[*PREFIX_BASE.map do |base|
+                             PREFIXES.grep( /#{base}/i ).map { |p| [p,base] }
+                           end.flatten]
+
+    SUFFIXES_CORRECTIONS = Hash[*SUFFIX_BASE.map do |base|
+                             SUFFIXES.grep( /#{base}/i ).map { |p| [p,base] }
+                           end.flatten]
+
   end
-end
+
+end
+

data/lib/nameable_record/name_recognition.rb

@@ -0,0 +1,119 @@
+module NameableRecord::NameRecognition
+
+  def surnames
+    @surnames ||= surnames_from_file
+  end
+
+  def given_names
+    @given_names ||= given_names_from_file
+  end
+
+  %w(downcase upcase).each do |desired_case|
+    define_method "surnames_all_#{desired_case}" do
+      surnames.map( &desired_case.to_sym )
+    end
+
+    define_method "given_names_all_#{desired_case}" do
+      given_names.map( &desired_case.to_sym )
+    end
+
+    define_method "all_name_words_#{desired_case}" do
+      (surnames + given_names + prefixes + suffixes + initials_downcase).map { |n| n.send( desired_case ) }.uniq
+    end
+  end
+
+  def human_name?( name, lowest_affirmative_probabilty=100, disqualifying_words=[]  )
+    probability_is_human_name( name, disqualifying_words ) >= lowest_affirmative_probabilty
+  end
+
+  def probability_is_human_name( name, disqualifying_words=[] )
+    if name.match( /^[a-zA-Z]*\s*[a-zA-Z]{2}$/ )
+      return probability_from_last_and_intials( name, :last_name_first => true )
+    elsif name.match( /^[a-zA-Z]{2}\s*[a-zA-Z]*$/ )
+      return probability_from_last_and_intials( name, :last_name_first => false )
+    end
+
+    name_parts = split_and_clean_name( name )
+
+    return 0 if ((default_disqualifying_words + disqualifying_words) & name_parts).size > 0
+
+    score = (100 - ((name_parts.size - (name_parts & all_name_words_downcase).size) * points_per_additional_word))
+    score < 0 ? 0 : score
+  end
+
+  def default_disqualifying_words
+    %w(
+      corporation
+      corp
+      co
+      llc
+      ltd
+    )
+  end
+
+private
+
+  def points_per_additional_word
+    20
+  end
+
+  def probability_from_last_and_intials( name, options )
+    name_parts = split_and_clean_name( name )
+
+    last_name = options[:last_name_first] ? name_parts.first : name_parts.last
+
+    return ([last_name] & surnames_all_downcase).size == 1 ?
+             100 :
+             50
+  end
+
+  def split_and_clean_name( name )
+    name.split( ' ' ).compact.map { |p| p.strip.downcase }
+  end
+
+  def prefixes
+    NameableRecord::Name::PREFIXES
+  end
+
+  def suffixes
+    NameableRecord::Name::SUFFIXES
+  end
+
+  def initials_downcase
+    alphabet_downcase + alphabet_downcase.map { |l| "#{l}." }
+  end
+
+  def alphabet_downcase
+    ('a'..'z').to_a
+  end
+
+  def surnames_from_file
+    File.open( surnames_file_path, 'r' ) { |f| f.readlines }.map { |n| n.strip }
+  end
+
+  def surnames_file_path
+    File.join File.dirname(__FILE__),
+              'data',
+               surnames_file_name
+  end
+
+  def surnames_file_name
+    'surnames.txt'
+  end
+
+  def given_names_from_file
+    File.open( given_names_file_path, 'r' ) { |f| f.readlines }.map { |n| n.strip }
+  end
+
+  def given_names_file_path
+    File.join File.dirname(__FILE__),
+              'data',
+               given_names_file_name
+  end
+
+  def given_names_file_name
+    'given-names.txt'
+  end
+
+end
+

data/lib/nameable_record/name_recognizer.rb

@@ -0,0 +1,10 @@
+module NameableRecord
+
+  class NameRecognizer
+
+    include NameableRecord::NameRecognition
+
+  end
+
+end
+

data/lib/nameable_record/railtie.rb

@@ -0,0 +1,14 @@
+require 'rails'
+
+module NameableRecord
+
+  class Railtie < ::Rails::Railtie
+
+    initializer "nameable_record.initialize" do
+      ActiveRecord::Base.send( :include, NameableRecord::ActiveRecordExtensions ) if defined?( ActiveRecord::Base )
+    end
+
+  end
+
+end
+

data/lib/nameable_record/version.rb

@@ -0,0 +1,4 @@
+module NameableRecord
+  VERSION = "1.0.0"
+end
+

data/lib/nameable_record.rb

@@ -1,10 +1,12 @@
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
-require 'nameable_record/active_record_extensions'
-require 'nameable_record/name'
+require "nameable_record/railtie" if defined?( ::Rails )
+require "nameable_record/version"
 
 module NameableRecord
-  VERSION = '0.1.0'
+
+  autoload :ActiveRecordExtensions, 'nameable_record/active_record_extensions'
+  autoload :Name,                   'nameable_record/name'
+  autoload :NameRecognition,        'nameable_record/name_recognition'
+  autoload :NameRecognizer,         'nameable_record/name_recognizer'
+
 end
 
-ActiveRecord::Base.send( :include, NameableRecord::ActiveRecordExtensions ) if defined?( ActiveRecord::Base )

data/nameable_record.gemspec

@@ -1,57 +1,32 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
 # -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "nameable_record/version"
 
 Gem::Specification.new do |s|
-  s.name = %q{nameable_record}
-  s.version = "0.2.0"
+  s.name        = "nameable_record"
+  s.version     = NameableRecord::VERSION
+  s.authors     = ["Jason Harrelson"]
+  s.email       = ["jason@lookforwardenterprises.com"]
+  s.homepage    = "https://github.com/midas/nameable_record"
+  s.summary     = %q{Abstracts the ActiveRecord composed_of pattern for names.}
+  s.description = %q{Abstracts the ActiveRecord composed_of pattern for names.  Also provides other convenience utilieis for working with human names.}
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["C. Jason Harrelson"]
-  s.date = %q{2010-10-02}
-  s.description = %q{Encapsulates the composed of pattern for names into any easy to use library.}
-  s.email = %q{jason@lookforwardenterprises.com}
-  s.extra_rdoc_files = [
-    "LICENSE",
-     "README.rdoc"
-  ]
-  s.files = [
-    ".document",
-     ".gitignore",
-     "LICENSE",
-     "README.rdoc",
-     "Rakefile",
-     "VERSION",
-     "lib/nameable_record.rb",
-     "lib/nameable_record/active_record_extensions.rb",
-     "lib/nameable_record/name.rb",
-     "nameable_record.gemspec",
-     "spec/nameable_record_spec.rb",
-     "spec/spec.opts",
-     "spec/spec_helper.rb"
-  ]
-  s.homepage = %q{http://github.com/midas/nameable_record}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
-  s.summary = %q{Encapsulates the composed of pattern for names into any easy to use library.}
-  s.test_files = [
-    "spec/nameable_record_spec.rb",
-     "spec/spec_helper.rb"
-  ]
+  s.rubyforge_project = "nameable_record"
 
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
+  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"]
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
-    else
-      s.add_dependency(%q<rspec>, [">= 1.2.9"])
-    end
-  else
-    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+  # specify any dependencies here; for example:
+  %w(
+    gem-dandy
+    rspec
+    rails
+  ).each do |development_dependency|
+    s.add_development_dependency development_dependency
   end
+
+  # s.add_runtime_dependency "rest-client"
 end
 

data/script/environment.rb

@@ -0,0 +1,17 @@
+ActiveRecord::Base.configurations = YAML::load( IO.read( File.dirname(__FILE__) + '/../spec/database.yml' ) )
+ActiveRecord::Base.establish_connection( 'test' )
+
+silence_stream STDOUT do
+
+  ActiveRecord::Schema.define :version => 1 do
+    create_table :users, :force => true do |t|
+      t.string :name_first, :anem_last, :name_middle, :name_prefix, :name_suffix
+    end
+  end
+
+end
+
+class User < ActiveRecord::Base
+  has_name :name
+end
+

data/spec/database.yml

@@ -0,0 +1,4 @@
+test:
+  :adapter: sqlite3
+  :database: ":memory:"
+

data/spec/lib/nameable_record/active_record_extensions_spec.rb

@@ -0,0 +1,43 @@
+require 'spec_helper'
+require 'rails_spec_helper'
+
+describe NameableRecord::ActiveRecordExtensions do
+
+  let :user do
+    User.new
+  end
+
+  let :name do
+    NameableRecord::Name.new *name_parts
+  end
+
+  context 'setting the composed of fields from a NameableRecord::Name instance' do
+
+    before :each do
+      user.name = name
+    end
+
+    it '#name_last' do
+      user.name_last.should == 'Smith'
+    end
+
+    it '#name_first' do
+      user.name_first.should == 'John'
+    end
+
+    it '#name_middle' do
+      user.name_middle.should == 'Jacob'
+    end
+
+    it '#name_prefix' do
+      user.name_prefix.should == 'Mr.'
+    end
+
+    it '#name_suffix' do
+      user.name_suffix.should == 'III'
+    end
+
+  end
+
+end
+

data/spec/lib/nameable_record/name_recognition_sharedspec.rb

@@ -0,0 +1,182 @@
+require 'spec_helper'
+
+shared_examples_for 'any name recognition' do
+
+  context '#surnames' do
+
+    subject { recognition_instance.surnames.size }
+
+    it { should == 9527 }
+
+  end
+
+  context '#surnames_all_downcase' do
+
+    subject { recognition_instance.surnames_all_downcase.first }
+
+    it { should == 'aaron' }
+
+  end
+
+  context '#surnames_all_upcase' do
+
+    subject { recognition_instance.surnames_all_upcase.first }
+
+    it { should == 'AARON' }
+
+  end
+
+  context '#human_name?' do
+
+    context 'when the name matches the pattern {last name} {first initial}{middle initial}' do
+
+      subject { recognition_instance.human_name?( 'HOMER SA' ) }
+
+      it { should be_true }
+
+    end
+
+    context 'when the name matches the pattern {first initial}{middle initial} {last name}' do
+
+      subject { recognition_instance.human_name?( 'SA HOMER' ) }
+
+      it { should be_true }
+
+    end
+
+    context 'when the middle initial has no .' do
+
+      subject { recognition_instance.human_name?( 'HOMER STEPHEN A' ) }
+
+      it { should be_true }
+
+    end
+
+    context 'when the middle initial has a .' do
+
+      subject { recognition_instance.human_name?( 'HOMER STEPHEN A.' ) }
+
+      it { should be_true }
+
+    end
+
+    context 'when the name is an 80% match' do
+
+      subject { recognition_instance.human_name?( 'CUP STEPHEN A' ) }
+
+      it { should be_false }
+
+    end
+
+    context 'when the name is less an 80% match with a 70% threshold' do
+
+      subject { recognition_instance.human_name?( 'CUP STEPHEN A', 80 ) }
+
+      it { should be_true }
+
+    end
+
+  end
+
+  context '#given_names' do
+
+    subject { recognition_instance.given_names.size }
+
+    it { should == 5678 }
+
+  end
+
+  context '#given_names_all_downcase' do
+
+    subject { recognition_instance.given_names_all_downcase.first }
+
+    it { should == 'aj' }
+
+  end
+
+  context '#given_names_all_upcase' do
+
+    subject { recognition_instance.given_names_all_upcase.first }
+
+    it { should == 'AJ' }
+
+  end
+
+  context '#all_name_words_downcase' do
+
+    subject { recognition_instance.all_name_words_downcase.size }
+
+    it { should == 14297 }
+
+  end
+
+  context '#all_name_words_upcase' do
+
+    subject { recognition_instance.all_name_words_upcase.size }
+
+    it { should == 14297 }
+
+  end
+
+  context '#prefixes' do
+
+    subject { recognition_instance.send( :prefixes ).sort }
+
+    it { should == ["DR", "DR.", "Dr", "Dr.", "GENERAL", "GENERAL.", "General", "General.", "MISS", "MISS.", "MR", "MR.", "MRS", "MRS.", "Miss", "Miss.", "Mr", "Mr.", "Mrs", "Mrs.", "dr", "dr.", "general", "general.", "miss", "miss.", "mr", "mr.", "mrs", "mrs."] }
+
+  end
+
+  context '#suffixes' do
+
+    subject { recognition_instance.send( :suffixes ).sort }
+
+    it { should == ["ESQ", "ESQ.", "Esq", "Esq.", "III", "III", "III.", "III.", "IV", "IV", "IV.", "IV.", "JR", "JR.", "Jr", "Jr.", "V", "V", "V.", "V.", "esq", "esq.", "iii", "iii.", "iv", "iv.", "jr", "jr.", "v", "v."] }
+
+  end
+
+  context '#probability_is_human_name' do
+
+    context 'when all words are a name part' do
+
+      subject { recognition_instance.probability_is_human_name( 'Mr. Charles Langford III' ) }
+
+      it { should == 100 }
+
+    end
+
+    context 'when there is one word that is not a name part' do
+
+      subject { recognition_instance.probability_is_human_name( 'Introducing Mr. Charles Langford III' ) }
+
+      it { should == 80 }
+
+    end
+
+    context 'when there are two words that are not a name part' do
+
+      subject { recognition_instance.probability_is_human_name( 'Home of Mr. Charles Langford III' ) }
+
+      it { should == 60 }
+
+    end
+
+    context 'when there are five words that are not a name part' do
+
+      subject { recognition_instance.probability_is_human_name( 'This is the home of Mr. Charles Langford III' ) }
+
+      it { should == 0 }
+
+    end
+
+    context 'when there are six words that are not a name part' do
+
+      subject { recognition_instance.probability_is_human_name( 'It is at the home of Mr. Charles Langford III' ) }
+
+      it { should == 0 }
+
+    end
+
+  end
+
+end
+

data/spec/lib/nameable_record/name_recognition_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+require File.expand_path( "#{File.dirname __FILE__}/name_recognition_sharedspec" )
+
+describe NameableRecord::NameRecognition do
+
+  class SomeClass
+    include NameableRecord::NameRecognition
+  end
+
+  let :recognition_instance do
+    SomeClass.new
+  end
+
+  it_should_behave_like 'any name recognition'
+
+end
+

data/spec/lib/nameable_record/name_recognizer_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+require File.expand_path( "#{File.dirname __FILE__}/name_recognition_sharedspec" )
+
+describe NameableRecord::NameRecognizer do
+
+  let :recognition_instance do
+    described_class.new
+  end
+
+  it 'should include the NameRecognition module' do
+    described_class.should include NameableRecord::NameRecognition
+  end
+
+  it_should_behave_like 'any name recognition'
+
+end
+