openjournals-nameable 1.1.4

data/lib/nameable/assets.rb

@@ -0,0 +1,6 @@
+module Nameable
+  module Assets
+    GENDER_TABLE    = File.expand_path(File.join('..', '..', '..', 'data', 'yob2016.txt'), __FILE__)
+    ETHNICITY_TABLE = File.expand_path(File.join('..', '..', '..', 'data', 'app_c.csv'), __FILE__)
+  end
+end

data/lib/nameable/error.rb

@@ -0,0 +1,4 @@
+module Nameable
+  class InvalidNameError < StandardError
+  end
+end

data/lib/nameable/extensions.rb

@@ -0,0 +1,5 @@
+class Object
+  def Nameable(name)
+    Nameable::Latin.new.parse(name).to_s
+  end
+end

data/lib/nameable/latin/patterns.rb

@@ -0,0 +1,39 @@
+module Nameable
+  class Latin
+    # Regex's to match the detritus that people add to their names
+    module Patterns
+      PREFIX = {
+        'Capt.'  => /^\(*(capt\.*|captain)\)*$/i,
+        'Dame'   => /^\(*(dame)\)*$/i,
+        'Dr.'    => /^\(*(dr\.*|doctor)\)*$/i,
+        'Fr.'    => /^\(*(fr\.*|friar|father)\)*$/i,
+        'Hon.'	 => /^\(*(hon\.*|honorable)\)*$/i,
+        'Imam'   => /^\(*(imam)\)*$/i,
+        'Ofc.'   => /^\(*(ofc\.*|officer)\)*$/i,
+        'Mr.'    => /^\(*(mr\.*|mister)\)*$/i,
+        'Mrs.'   => /^\(*(mrs\.*|misses)\)*$/i,
+        'Ms.'    => /^\(*(ms\.*|miss)\)*$/i,
+        'Rev.'   => /^\(*(rev\.*|reverend)\)*$/i,
+        'Master' => /^\(*(master)\)*$/i,
+        'Rabbi'  => /^\(*(rabbi)\)*$/i,
+        'Sir'    => /^\(*(sir)\)*$/i
+      }.freeze
+
+      SUFFIX = {
+        'Sr.'   => /^\(*(sr\.?|senior)\)*$/i,
+        'Jr.'   => /^\(*(jr\.?|junior)\)*$/i,
+        'Esq.'  => /^\(*(esq\.?|esquire)\)*$/i,
+        'Ph.D.' => /^\(*(p\.?h\.?d\.?)\)*$/i
+      }.freeze
+
+      SUFFIX_GENERATIONAL_ROMAN = /^\(*[IVX.]+\)*$/i
+      SUFFIX_ACADEMIC = /^(APR|RPh|MD|MA|DMD|DDS|PharmD|EngD|DPhil|JD|DD|DO|BA|BS|BSc|BE|BFA|MA|MS|MSc|MFA|MLA|MBA)$/i
+      SUFFIX_PROFESSIONAL = /^(PE|CSA|CPA|CPL|CME|CEng|OFM|CSV)$/i
+      SUFFIX_ABBREVIATION = /^[A-Z]\.?[A-Z]\.?[A-Z]?\.?$/ # 2-3 characters, possibly separated with '.'
+
+      # http://www.onlineaspect.com/2009/08/17/splitting-names/
+      LAST_NAME_PRE_DANGLERS = /^(mc|vere|von|van|der|da|de|del|della|di|da|pietro|vanden|du|st|la|ter|ten)$/i
+      O_LAST_NAME_PRE_CONCATS = /^(o'|o`|o")$/i
+    end
+  end
+end

data/lib/nameable/latin.rb

@@ -0,0 +1,251 @@
+require 'csv'
+require 'nameable/error'
+require 'nameable/latin/patterns'
+
+module Nameable
+  class Latin
+    @@first_names = {}
+    @@last_names = {}
+
+    attr_accessor :prefix, :first, :middle, :last, :suffix
+
+    def initialize(*args)
+      if args.size == 1 && args.first.class == Hash
+        parts = args.first
+        @prefix = parts[:prefix]  ? parts[:prefix]  : nil
+        @first  = parts[:first]   ? parts[:first]   : nil
+        @middle = parts[:middle]  ? parts[:middle]  : nil
+        @last   = parts[:last]    ? parts[:last]    : nil
+        @suffix = parts[:suffix]  ? parts[:suffix]  : nil
+      else
+        @first = args.shift unless args.empty?
+        @middle = args.shift if args.size >= 2 # Only grab a middle name if we've got a last name left
+        @last = args.shift unless args.empty?
+      end
+    end
+
+    ##
+    # name is an Array
+    def extract_prefix(name)
+      return unless name && name.size > 1 && @prefix.nil? && @first.nil?
+      Nameable::Latin::Patterns::PREFIX.each do |pretty, regex|
+        next unless name.first =~ regex
+        @prefix = pretty
+        name.delete(name.first)
+        break
+      end
+    end
+
+    ##
+    # name is an Array
+    def extract_suffix(name)
+      return unless name && name.size >= 3
+
+      (name.size - 1).downto(2) do |n|
+        suff = nil
+
+        Nameable::Latin::Patterns::SUFFIX.each_pair do |pretty, regex|
+          suff = pretty if name[n] =~ regex
+        end
+
+        if name[n] =~ Nameable::Latin::Patterns::SUFFIX_ACADEMIC ||
+           name[n] =~ Nameable::Latin::Patterns::SUFFIX_PROFESSIONAL ||
+           name[n] =~ Nameable::Latin::Patterns::SUFFIX_GENERATIONAL_ROMAN
+          suff = name[n].upcase.delete('.')
+        end
+
+        if !suff &&
+           name.join != name.join.upcase &&
+           name[n].length > 1 &&
+           name[n] =~ Nameable::Latin::Patterns::SUFFIX_ABBREVIATION
+          suff = name[n].upcase.delete('.')
+        end
+
+        if suff
+          @suffix = @suffix ? "#{suff}, #{@suffix}" : suff
+          name.delete_at(n)
+        end
+      end
+    end
+
+    ##
+    # name is an Array
+    def extract_first(name)
+      return unless name && name.size >= 1
+
+      @first = name.first
+      name.delete_at(0)
+
+      @first.capitalize! unless @first =~ /[a-z]/ && @first =~ /[A-Z]/
+    end
+
+    ##
+    # name is an Array
+    def extract_last(name)
+      return unless name && name.size >= 1
+
+      @last = name.last.gsub(/['`"]+/, "'").gsub(/-+/, '-')
+      name.delete_at(name.size - 1)
+
+      @last.capitalize! unless @last =~ /[a-z]/ && @last =~ /[A-Z]/
+    end
+
+    ##
+    # name is an Array
+    def extract_middle(name)
+      return unless name && name.size >= 1
+
+      (name.size - 1).downto(0) do |n|
+        next unless name[n]
+
+        if name[n] =~ Nameable::Latin::Patterns::LAST_NAME_PRE_DANGLERS
+          @last = "#{name[n].downcase.capitalize} #{@last}"
+          @last.gsub!('Van Der', 'van der')
+          @last.gsub!('Van De', 'van de')
+        elsif name[n] =~ Nameable::Latin::Patterns::O_LAST_NAME_PRE_CONCATS
+          @last = "O'#{@last}"
+        elsif name[n] =~ /\-/ && n > 0 && name[n - 1]
+          @last = "#{name[n - 1].delete('-')}-#{@last}"
+          name[n - 1] = nil
+        else
+          @middle = @middle ? "#{name[n]} #{@middle}" : name[n]
+        end
+
+        name.delete_at(n)
+      end
+
+      @middle.capitalize! if @middle && !(@middle =~ /[a-z]/ && @middle =~ /[A-Z]/)
+      @middle = "#{@middle}." if @middle && @middle.size == 1
+    end
+
+    def parse(name)
+      raise InvalidNameError unless name
+      if name.class == String
+        if name.index(',')
+          name = "#{Regexp.last_match(2)} #{Regexp.last_match(1)}" if name =~ /^([a-z]+)\s*,\s*,*([^,]*)/i
+        end
+
+        name = name.strip.split(/\s+/)
+      end
+
+      name = name.first.split(/[^[:alnum:]]+/) if name.size == 1 && name.first.split(/[^[:alnum:]]+/)
+
+      extract_prefix(name)
+      extract_suffix(name)
+      extract_first(name)
+      extract_last(name)
+      extract_middle(name)
+
+      raise InvalidNameError, "A parseable name was not found. #{name.inspect}" unless @first
+
+      self
+    end
+
+    # http://www.ssa.gov/oact/babynames/limits.html
+    def load_huge_gender_table(gender_table = Nameable::Assets::GENDER_TABLE)
+      ranked = {}
+
+      CSV.read(gender_table).each do |first, gender, rank|
+        first.downcase!
+        gender.downcase!
+        ranked[first] = {} unless ranked[first]
+        ranked[first][gender] = rank.to_i
+      end
+
+      ranked.each do |first, ranks|
+        if ranks['m'] && !ranks['f']
+          @@first_names[first] = :male
+        elsif !ranks['m'] && ranks['f']
+          @@first_names[first] = :female
+        elsif ranks['m'] && ranks['f']
+          @@first_names[first] = ranks['m'] > ranks['f'] ? :male : :female
+        end
+      end
+    end
+
+    # http://www.census.gov/genealogy/www/data/2000surnames/index.html
+    def load_huge_ethnicity_table
+      CSV.read(File.expand_path(File.join('..', '..', '..', 'data', 'app_c.csv'), __FILE__)).each do |name, rank, count, _prop100k, _cum_prop100k, pctwhite, pctblack, pctapi, pctaian, pct2prace, pcthispanic|
+        next if name == 'name'
+        @@last_names[name.downcase] = {
+          rank: rank.to_i,
+          count: count.to_i,
+          percent_white: pctwhite.to_f,
+          percent_black: pctblack.to_f,
+          percent_asian_pacific_islander: pctapi.to_f,
+          percent_american_indian_alaska_native: pctaian.to_f,
+          percent_two_or_more_races: pct2prace.to_f,
+          percent_hispanic: pcthispanic.to_f
+        }
+      end
+    end
+
+    def gender
+      return @gender if @gender
+      load_huge_gender_table unless @@first_names && !@@first_names.empty?
+      @gender = @@first_names[@first.to_s.downcase] ? @@first_names[@first.to_s.downcase] : :unknown
+      @gender
+    end
+
+    def ethnicity
+      return @ethnicity if @ethnicity
+      load_huge_ethnicity_table unless @@last_names && !@@last_names.empty?
+      @ethnicity = @last && @@last_names[@last.downcase] ? @@last_names[@last.downcase] : :unknown
+      @ethnicity
+    end
+
+    def male?
+      gender == :male
+    end
+
+    def female?
+      gender == :female
+    end
+
+    def to_s
+      [@prefix, @first, @middle, @last].compact.join(' ') + (@suffix ? ", #{@suffix}" : '')
+    end
+
+    def to_name
+      to_nameable
+    end
+
+    def to_fullname
+      to_s
+    end
+
+    def to_prefix
+      @prefix
+    end
+
+    def to_firstname
+      @first
+    end
+
+    def to_lastname
+      @last
+    end
+
+    def to_middlename
+      @middle
+    end
+
+    def to_suffix
+      @suffix
+    end
+
+    def to_nameable
+      [@first, @last].compact.join(' ')
+    end
+
+    def to_hash
+      {
+        prefix: @prefix,
+        first: @first,
+        middle: @middle,
+        last: @last,
+        suffix: @suffix
+      }
+    end
+  end
+end

data/lib/nameable/version.rb

@@ -0,0 +1,3 @@
+module Nameable
+  VERSION = '1.1.4'.freeze
+end

data/lib/nameable.rb

@@ -0,0 +1,11 @@
+require 'nameable/version'
+require 'nameable/error'
+require 'nameable/assets'
+require 'nameable/latin'
+require 'nameable/extensions'
+
+module Nameable
+  def self.parse(name)
+    Nameable::Latin.new.parse(name)
+  end
+end

data/nameable.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'nameable/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'openjournals-nameable'
+  spec.version       = Nameable::VERSION
+  spec.authors       = ['Chris Horn']
+  spec.email         = ['chorn@chorn.com']
+  spec.summary       = 'Parse names into components.'
+  spec.description   = 'A library that provides parsing and output of person names, as well as Gender & Ethnicity matching.'
+  spec.homepage      = 'https://github.com/chorn/nameable'
+  spec.license       = 'MIT'
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 1.9'
+
+  signing_key = File.expand_path '~/.certs/chorn@chorn.com-rubygems.key'
+  if File.file?(signing_key)
+    spec.signing_key = signing_key
+    spec.cert_chain = ['certs/chorn.pem']
+  end
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 3.6'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'codeclimate-test-reporter'
+end

data/spec/nameable/extensions_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Object do
+  it 'returns a string' do
+    expect(Nameable('Chris Horn')).to be_a(String)
+  end
+
+  it 'raises an exception' do
+    expect { Nameable(nil) }.to raise_error Nameable::InvalidNameError
+  end
+end

data/spec/nameable/latin_spec.rb

@@ -0,0 +1,192 @@
+require 'spec_helper'
+
+shared_examples :generalized_parsing do |input, outputs|
+  let(:nameable) { Nameable::Latin.new.parse(input) }
+
+  it "#parse ``#{input}''" do
+    expect(nameable.prefix).to eq outputs[0]
+    expect(nameable.first).to eq outputs[1]
+    expect(nameable.middle).to eq outputs[2]
+    expect(nameable.last).to eq outputs[3]
+    expect(nameable.suffix).to eq outputs[4]
+  end
+end
+
+describe Nameable::Latin do
+  describe '.new' do
+    it "doesn't raise" do
+      expect { Nameable::Latin.new }.to_not raise_error
+    end
+  end
+
+  describe '#parse' do
+    context 'with a single word name' do
+      it_behaves_like :generalized_parsing, 'Chris', [nil, 'Chris', nil, nil, nil]
+    end
+
+    context 'with a simple first and last name' do
+      it_behaves_like :generalized_parsing, 'Chris Horn', [nil, 'Chris', nil, 'Horn', nil]
+    end
+
+    context 'with an uppercase first and last name' do
+      it_behaves_like :generalized_parsing, 'CHRIS HORN', [nil, 'Chris', nil, 'Horn', nil]
+    end
+
+    context 'with a lowercase first and last name' do
+      it_behaves_like :generalized_parsing, 'chris horn', [nil, 'Chris', nil, 'Horn', nil]
+    end
+
+    context 'with a mixed case first and last name' do
+      it_behaves_like :generalized_parsing, 'DeChris Horn', [nil, 'DeChris', nil, 'Horn', nil]
+    end
+
+    context 'with last name, first name' do
+      it_behaves_like :generalized_parsing, 'Horn, Chris', [nil, 'Chris', nil, 'Horn', nil]
+    end
+
+    context 'with last name, first name,' do
+      it_behaves_like :generalized_parsing, 'Horn, Chris,', [nil, 'Chris', nil, 'Horn', nil]
+    end
+
+    context 'with first middle last name' do
+      it_behaves_like :generalized_parsing, 'Chris Derp Horn', [nil, 'Chris', 'Derp', 'Horn', nil]
+    end
+
+    context 'with all uppercase first middle last name' do
+      it_behaves_like :generalized_parsing, 'CHRIS DERP HORN', [nil, 'Chris', 'Derp', 'Horn', nil]
+    end
+
+    context 'with all lowercase first middle last name' do
+      it_behaves_like :generalized_parsing, 'chris derp horn', [nil, 'Chris', 'Derp', 'Horn', nil]
+    end
+
+    context 'with all mixed case first middle last name' do
+      it_behaves_like :generalized_parsing, 'DeChris LeDerp ZeHorn', [nil, 'DeChris', 'LeDerp', 'ZeHorn', nil]
+    end
+
+    context 'with first last suffix' do
+      it_behaves_like :generalized_parsing, 'Chris Horn DRP', [nil, 'Chris', nil, 'Horn', 'DRP']
+    end
+
+    context 'with prefix first last suffix' do
+      it_behaves_like :generalized_parsing, 'Mr. Chris Horn DRP', ['Mr.', 'Chris', nil, 'Horn', 'DRP']
+    end
+
+    %w[Dame Rabbi Imam Master Sir].each do |prefix|
+      it_behaves_like :generalized_parsing, "#{prefix} Chris Horn", [prefix, 'Chris', nil, 'Horn', nil]
+    end
+
+    context 'with a normalizing prefix' do
+      %w[Mr Mr. Mister].each do |prefix|
+        it_behaves_like :generalized_parsing, "#{prefix} Chris Horn", ['Mr.', 'Chris', nil, 'Horn', nil]
+      end
+
+      %w[Mrs Mrs. Misses].each do |prefix|
+        it_behaves_like :generalized_parsing, "#{prefix} Chris Horn", ['Mrs.', 'Chris', nil, 'Horn', nil]
+      end
+
+      %w[Ms Ms. Miss].each do |prefix|
+        it_behaves_like :generalized_parsing, "#{prefix} Chris Horn", ['Ms.', 'Chris', nil, 'Horn', nil]
+      end
+
+      %w[Dr Dr. Doctor].each do |prefix|
+        it_behaves_like :generalized_parsing, "#{prefix} Chris Horn", ['Dr.', 'Chris', nil, 'Horn', nil]
+      end
+
+      %w[Rev Rev. Reverend].each do |prefix|
+        it_behaves_like :generalized_parsing, "#{prefix} Chris Horn", ['Rev.', 'Chris', nil, 'Horn', nil]
+      end
+
+      %w[Fr Fr. Friar Father].each do |prefix|
+        it_behaves_like :generalized_parsing, "#{prefix} Chris Horn", ['Fr.', 'Chris', nil, 'Horn', nil]
+      end
+
+      %w[Hon Hon. Honorable].each do |prefix|
+        it_behaves_like :generalized_parsing, "#{prefix} Chris Horn", ['Hon.', 'Chris', nil, 'Horn', nil]
+      end
+
+      %w[Capt Capt. Captain].each do |prefix|
+        it_behaves_like :generalized_parsing, "#{prefix} Chris Horn", ['Capt.', 'Chris', nil, 'Horn', nil]
+      end
+
+      %w[Ofc Ofc. Officer].each do |prefix|
+        it_behaves_like :generalized_parsing, "#{prefix} Chris Horn", ['Ofc.', 'Chris', nil, 'Horn', nil]
+      end
+    end
+
+    context 'with a normalizing suffix' do
+      %w[Sr Sr. Senior].each do |suffix|
+        it_behaves_like :generalized_parsing, "Chris Horn #{suffix}", [nil, 'Chris', nil, 'Horn', 'Sr.']
+      end
+
+      %w[Jr Jr. Junior].each do |suffix|
+        it_behaves_like :generalized_parsing, "Chris Horn #{suffix}", [nil, 'Chris', nil, 'Horn', 'Jr.']
+      end
+
+      %w[Esq Esq. Esquire].each do |suffix|
+        it_behaves_like :generalized_parsing, "Chris Horn #{suffix}", [nil, 'Chris', nil, 'Horn', 'Esq.']
+      end
+
+      %w[PHD PhD Ph.D Ph.D. P.H.D.].each do |suffix|
+        it_behaves_like :generalized_parsing, "Chris Horn #{suffix}", [nil, 'Chris', nil, 'Horn', 'Ph.D.']
+      end
+
+      %w[
+        ii III iv V VI ix Xiii APR RPh MD MA DMD DDS PharmD EngD DPhil
+        JD DD DO BA BS BSc BE BFA MA MS MSc MFA MLA MBA PE CSA CPA CPL CME CEng OFM CSV
+      ].each do |suffix|
+        it_behaves_like :generalized_parsing, "Chris Horn #{suffix}", [nil, 'Chris', nil, 'Horn', suffix.upcase]
+      end
+    end
+
+    context 'with a multi word last name' do
+      %w[mc vere von van da de del della di da pietro vanden du st la ter ten].each do |prefix|
+        it_behaves_like :generalized_parsing, "Chris #{prefix} Horn", [nil, 'Chris', nil, "#{prefix.downcase.capitalize} Horn", nil]
+      end
+    end
+
+    context 'with van der Something last name' do
+      it_behaves_like :generalized_parsing, 'Dr. Ellert van der Velden DRP', ['Dr.', 'Ellert', nil, 'van der Velden', 'DRP']
+    end
+
+    context 'with van de Something last name' do
+      it_behaves_like :generalized_parsing, 'Dr. Sil C. van de Leemput DRP', ['Dr.', 'Sil', 'C.', 'van de Leemput', 'DRP']
+    end
+
+    context "with an o'last-name" do
+      ["O'Horn", 'O`Horn', "O' Horn"].each do |last|
+        it_behaves_like :generalized_parsing, "Chris #{last}", [nil, 'Chris', nil, "O'Horn", nil]
+      end
+    end
+
+    context 'with a hyphenated last name' do
+      ['Horn - Derp', 'Horn-Derp',  'Horn--Derp', 'Horn -- Derp'].each do |last|
+        it_behaves_like :generalized_parsing, "Chris #{last}", [nil, 'Chris', nil, 'Horn-Derp', nil]
+      end
+    end
+  end
+
+  context 'gender' do
+    it 'Chris is more likely to be male' do
+      expect(Nameable::Latin.new.parse('Chris Horn').male?).to be true
+    end
+
+    it 'Janine is more likely to be female' do
+      expect(Nameable::Latin.new.parse('Janine Horn').female?).to be true
+    end
+
+    it 'Derp has :unknown gender' do
+      expect(Nameable::Latin.new.parse('Derp Horn').gender).to eq(:unknown)
+    end
+  end
+
+  context 'ethnicity' do
+    it 'Horn has a hash of ethnicity results' do
+      expect(Nameable::Latin.new.parse('Chris Horn').ethnicity).to be_a Hash
+    end
+
+    it "Horn's census :percent_white > 80% " do
+      expect(Nameable::Latin.new.parse('Chris Horn').ethnicity[:percent_white]).to be >= 80
+    end
+  end
+end

data/spec/nameable_spec.rb

@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe Nameable do
+  it '.parse' do
+    expect(Nameable.parse('Chris Horn')).to be_a(Nameable::Latin)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'bundler/setup'
+Bundler.require(:test)
+require 'simplecov'
+SimpleCov.start
+
+require 'nameable'
+
+RSpec.configure do |config|
+end