icu_name 0.0.2

data/LICENCE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 Mark Orr
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,62 @@
+= ICU Tournament
+
+Canonicalises and matches person names with Western European characters and first and last names.
+
+== Installation
+
+For ruby 1.9.2 and above.
+
+  gem install icu_name
+
+== Names
+
+This class exists for two main purposes:
+
+* to normalise to a common format the different ways names are typed in practice
+* to be able to match two names even if they are not exactly the same
+
+To create a name object, supply both the first and second names separately to the constructor.
+
+  robert = ICU::Name.new(' robert  j ', ' FISHER ')
+
+Capitalisation, white space and punctuation will all be automatically corrected:
+
+  robert.name                                    # => 'Robert J. Fischer'
+  robert.rname                                   # => 'Fischer, Robert J.'  (reversed name)
+
+To avoid ambiguity when either the first or second names consist of multiple words, it is better to
+supply the two separately, if known. However, the full name can be supplied alone to the constructor
+and a guess will be made as to the first and last names.
+
+  bobby = ICU::Name.new(' bobby fischer ')
+  
+  bobby.first                                    # => 'Bobby'
+  bobby.last                                     # => 'Fischer'
+
+Names will match even if one is missing middle initials or if a nickname is used for one of the first names.
+
+  bobby.match('Robert J.', 'Fischer')            # => true
+
+Note that the class is aware of only common nicknames (e.g. _Bobby_ and _Robert_, _Bill_ and _William_, etc), not all possibilities.
+
+Supplying the _match_ method with strings is equivalent to instantiating a Name instance with the same
+strings and then matching it. So, for example the following are equivalent:
+
+  robert.match('R.', 'Fischer')                  # => true
+  robert.match(ICU::Name.new('R.', 'Fischer'))   # => true
+
+The inital _R_, for example, matches the first letter of _Robert_. However, nickname matches will not
+always work with initials. In the next example, the initial _R_ does not match the first letter _B_ of the
+nickname _Bobby_.
+
+  bobby.match('R. J.', 'Fischer')                # => false
+
+Some of the ways last names are canonicalised are illustrated below:
+
+  ICU::Name.new('John', 'O Reilly').last         # => "O'Reilly"
+  ICU::Name.new('dave', 'mcmanus').last          # => "McManus"
+  ICU::Name.new('pete', 'MACMANUS').last         # => "MacManus"
+
+== Author
+
+Mark Orr, rating officer for the Irish Chess Union (ICU[http://icu.ie]).

data/lib/icu_name/version.rb

@@ -0,0 +1,7 @@
+# :enddoc:
+
+module ICU
+  class Name
+    VERSION = "0.0.2"
+  end
+end

data/lib/icu_name.rb

@@ -0,0 +1,230 @@
+module ICU
+  class Name
+    attr_reader :first, :last
+
+    # Construct from one or two strings or any objects that have a to_s method.
+    def initialize(name1='', name2='')
+      @name1 = name1.to_s
+      @name2 = name2.to_s
+      canonicalize
+    end
+
+    # Return a complete name, first name first, no comma.
+    def name
+      name = ''
+      name << @first
+      name << ' ' if @first.length > 0 && @last.length > 0
+      name << @last
+      name
+    end
+
+    # Return a reversed complete name, first name last after a comma.
+    def rname
+      name = ''
+      name << @last
+      name << ', ' if @first.length > 0 && @last.length > 0
+      name << @first
+      name
+    end
+
+    # Convert object to a string.
+    def to_s
+      rname
+    end
+
+    # Match another name to this object, returning true or false.
+    def match(name1='', name2='')
+      other = Name.new(name1, name2)
+      match_first(first, other.first) && match_last(last, other.last)
+    end
+
+    private
+
+    # Canonicalise the first and last names.
+    def canonicalize
+      first, last = partition
+      @first = finish_first(first)
+      @last  = finish_last(last)
+    end
+
+    # Split one complete name into first and last parts.
+    def partition
+      if @name2.length == 0
+        # Only one imput so we must split first and last.
+        parts = @name1.split(/,/)
+        if parts.size > 1
+          last  = clean(parts.shift || '')
+          first = clean(parts.join(' '))
+        else
+          parts = clean(@name1).split(/ /)
+          last  = parts.pop || ''
+          first = parts.join(' ')
+        end
+      else
+        # Two inputs, so we are given first and last.
+        first = clean(@name1)
+        last  = clean(@name2)
+      end
+      [first, last]
+    end
+
+    # Clean up characters in any name.
+    def clean(name)
+      name.gsub!(/`/, "'")
+      name.gsub!(/[^-a-zA-Z.'\s]/, '')
+      name.gsub!(/\./, ' ')
+      name.gsub!(/\s*-\s*/, '-')
+      name.gsub!(/'+/, "'")
+      name.strip.downcase.split(/\s+/).map do |n|
+        n.sub!(/^-+/, '')
+        n.sub!(/-+$/, '')
+        n.split(/-/).map do |p|
+          p.capitalize!
+        end.join('-')
+      end.join(' ')
+    end
+
+    # Apply final touches to finish canonicalising a first name. 
+    def finish_first(names)
+      names.gsub(/([A-Z])\b/, '\1.')
+    end
+
+    # Apply final touches to finish canonicalising a last name. 
+    def finish_last(names)
+      names.gsub!(/\b([A-Z])'([a-z])/) { |m| $1 << "'" << $2.upcase}
+      names.gsub!(/\bMc([a-z])/) { |m| 'Mc' << $1.upcase}
+      names.gsub!(/\bMac([a-z])/) do |m|
+        letter = $1
+        'Mac'.concat(@name2.match("[mM][aA][cC]#{letter}") ? letter : letter.upcase)
+      end
+      names.gsub!(/\bO ([A-Z])/) { |m| "O'" << $1 }
+      names
+    end
+
+    # Match a complete first name.
+    def match_first(first1, first2)
+      # Is this one a walk in the park?
+      return true if first1 == first2
+
+      # No easy ride. Begin by splitting into individual first names.
+      first1 = split_first(first1)
+      first2 = split_first(first2)
+
+      # Get the long list and the short list.
+      long, short = first1.size >= first2.size ? [first1, first2] : [first2, first1]
+
+      # The short one must be a "subset" of the long one.
+      # An extra condition must also be satisfied.
+      extra = false
+      (0..long.size-1).each do |i|
+        lword = long.shift
+        score = match_first_name(lword, short.first)
+        if score >= 0
+          short.shift
+          extra = true if i == 0 || score == 0
+        end
+        break if short.empty? || long.empty?
+      end
+
+      # There's a match if the following is true.
+      short.empty? && extra
+    end
+
+    # Match a complete last name.
+    def match_last(last1, last2)
+      return true if last1 == last2
+      [last1, last2].each do |last|
+        last.downcase!             # MacDonaugh and Macdonaugh
+        last.gsub!(/\bmac/, 'mc')  # MacDonaugh and McDonaugh
+        last.tr!('-', ' ')         # Lowry-O'Reilly and Lowry O'Reilly
+      end
+      last1 == last2
+    end
+
+    # Split a complete first name for matching.
+    def split_first(first)
+      first.tr!('-', ' ')              # J. K. and J.-K.
+      first = first.split(/ /)         # split on spaces
+      first = [''] if first.size == 0  # in case input was empty string
+      first
+    end
+
+    # Match individual first names or initials.
+    # -1 = no match
+    #  0 = full match
+    #  1 = match involving 1 initial
+    #  2 = match involving 2 initials
+    def match_first_name(first1, first2)
+      initials = 0
+      initials+= 1 if first1.match(/^[A-Z]\.?$/)
+      initials+= 1 if first2.match(/^[A-Z]\.?$/)
+      return initials if first1 == first2
+      return 0 if initials == 0 && match_nick_name(first1, first2)
+      return -1 unless initials > 0
+      return initials if first1[0] == first2[0]
+      -1
+    end
+
+    # Match two first names that might be equivalent nicknames.
+    def match_nick_name(nick1, nick2)
+      compile_nick_names unless @@nc
+      code1 = @@nc[nick1]
+      return false unless code1
+      code1 == @@nc[nick2]
+    end
+
+    # Compile the nick names code hash when matching nick names is first attempted.
+    def compile_nick_names
+      @@nc = Hash.new
+      code = 1
+      @@nl.each do |nicks|
+        nicks.each do |n|
+          throw "duplicate name #{n}" if @@nc[n]
+          @@nc[n] = code
+        end
+        code+= 1
+      end
+    end
+
+    # A array of data for matching nicknames and also a few common misspellings.
+    @@nc = nil
+    @@nl = <<EOF.split(/\n/).reject{|x| x.length == 0 }.map{|x| x.split(' ')}
+Abdul Abul
+Alexander Alex
+Anandagopal Ananda
+Anne Ann
+Anthony Tony
+Benjamin Ben
+Catherine Cathy Cath
+Daniel Danial Danny Dan
+David Dave
+Deborah Debbie
+Des Desmond
+Eamonn Eamon
+Edward Eddie Ed
+Eric Erick Erik
+Frederick Frederic Fred
+Gerald Gerry
+Gerhard Gerard Ger
+James Jim
+Joanna Joan Joanne
+John Johnny
+Jonathan Jon
+Kenneth Ken Kenny
+Michael Mike Mick Micky
+Nicholas Nick Nicolas
+Nicola Nickie Nicky
+Patrick Pat Paddy
+Peter Pete
+Philippe Philip Phillippe Phillip
+Rick Ricky
+Robert Bob Bobby
+Samual Sam Samuel
+Stefanie Stef
+Stephen Steven Steve
+Terence Terry
+Thomas Tom Tommy
+William Will Willy Willie Bill
+EOF
+  end
+end

data/spec/icu_name_spec.rb

@@ -0,0 +1,208 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+module ICU
+  describe Name do
+    context "public methods" do
+      before(:each) do
+        @simple = Name.new('mark j l', 'orr')
+      end
+      
+      it "#first returns the first name(s)" do
+        @simple.first.should == 'Mark J. L.'
+      end
+      
+      it "#last returns the last name(s)" do
+        @simple.last.should == 'Orr'
+      end
+      
+      it "#name returns the full name with first name(s) first" do
+        @simple.name.should == 'Mark J. L. Orr'
+      end
+      
+      it "#rname returns the full name with last name(s) first" do
+        @simple.rname.should == 'Orr, Mark J. L.'
+      end
+      
+      it "#to_s is the same as rname" do
+        @simple.to_s.should == 'Orr, Mark J. L.'
+      end
+      
+      it "#match returns true if and only if two names match" do
+        @simple.match('mark j l orr').should be_true
+        @simple.match('malcolm g l orr').should be_false
+      end
+    end
+    
+    context "rdoc expample" do
+      before(:each) do
+        @robert = Name.new(' robert  j ', ' FISCHER ')
+        @bobby = Name.new(' bobby fischer ')
+      end
+      
+      it "should get Robert" do
+        @robert.name.should == 'Robert J. Fischer'
+      end
+      
+      it "should get Bobby" do
+        @bobby.last.should == 'Fischer'
+        @bobby.first.should == 'Bobby'
+      end
+      
+      it "should match Robert and Bobby" do
+        @robert.match(@bobby).should be_true
+        @robert.match('R. J.', 'Fischer').should be_true
+        @bobby.match('R. J.', 'Fischer').should be_false
+      end
+      
+      it "should canconicalise last names" do
+        Name.new('John', 'O Reilly').last.should == "O'Reilly"
+        Name.new('dave', 'mcmanus').last.should == "McManus"
+        Name.new('pete', 'MACMANUS').last.should == "MacManus"
+      end
+    end
+    
+    context "names that are already canonical" do
+      it "should not be altered" do
+        Name.new('Mark J. L.', 'Orr').name.should == 'Mark J. L. Orr'
+        Name.new('Anna-Marie J.-K.', 'Liviu-Dieter').name.should == 'Anna-Marie J.-K. Liviu-Dieter'
+      end
+    end
+    
+    context "last names beginning with a single letter followed by a quote" do
+      it "should be handled correctly" do
+        Name.new('una', "O'boyle").name.should == "Una O'Boyle"
+        Name.new('jonathan', 'd`arcy').name.should == "Jonathan D'Arcy"
+        Name.new('erwin e', "L'AMI").name.should == "Erwin E. L'Ami"
+        Name.new('cormac', "o brien").name.should == "Cormac O'Brien"
+      end
+    end
+    
+    context "last beginning with Mc" do
+      it "should be handled correctly" do
+        Name.new('shane', "mccabe").name.should == "Shane McCabe"
+        Name.new('shawn', "macDonagh").name.should == "Shawn MacDonagh"
+        Name.new('shawn', "macdonagh").name.should == "Shawn Macdonagh"
+        Name.new('bartlomiej', "macieja").name.should == "Bartlomiej Macieja"
+      end
+    end
+    
+    context "doubled barrelled names or initials" do
+      it "should be handled correctly" do
+        Name.new('anna-marie', 'den-otter').name.should == 'Anna-Marie Den-Otter'
+        Name.new('j-k', 'rowling').name.should == 'J.-K. Rowling'
+        Name.new("mark j. - l", 'ORR').name.should == 'Mark J.-L. Orr'
+        Name.new('JOHANNA', "lowry-o'REILLY").name.should == "Johanna Lowry-O'Reilly"
+        Name.new('hannah', "lowry - o reilly").name.should == "Hannah Lowry-O'Reilly"
+      end
+    end
+    
+    context "extraneous white space" do
+      it "should be handled correctly" do
+        Name.new(' mark j   l  ', "  \t\r\n   orr   \n").name.should == 'Mark J. L. Orr'
+      end
+    end
+    
+    context "extraneous full stops" do
+      it "should be handled correctly" do
+        Name.new('. mark j..l', 'orr.').name.should == 'Mark J. L. Orr'
+      end
+    end
+    
+    context "construction from a single string" do
+      before(:each) do
+        @mark1 = Name.new('ORR, mark j l')
+        @mark2 = Name.new('MARK J L ORR')
+        @oreil = Name.new("O'Reilly, j-k")
+      end
+      
+      it "should be possible in simple cases" do
+        @mark1.first.should == 'Mark J. L.'
+        @mark1.last.should == 'Orr'
+        @mark2.first.should == 'Mark J. L.'
+        @mark2.last.should == 'Orr'
+        @oreil.name.should == "J.-K. O'Reilly"
+      end
+    end
+    
+    context "construction from an instance" do
+      it "should be possible" do
+        Name.new(Name.new('ORR, mark j l')).name.should == 'Mark J. L. Orr'
+      end
+    end
+        
+    context "constuction corner cases" do
+      it "should be handled correctly" do
+        Name.new('Orr').name.should == 'Orr'
+        Name.new('Orr').rname.should == 'Orr'
+        Name.new('').name.should == ''
+        Name.new('').rname.should == ''
+        Name.new.name.should == ''
+        Name.new.rname.should == ''
+      end
+    end
+    
+    context "inputs to matching" do
+      before(:all) do
+        @mark = Name.new('Mark', 'Orr')
+        @kram = Name.new('Mark', 'Orr')
+      end
+      
+      it "should be flexible" do
+        @mark.match('Mark', 'Orr').should be_true
+        @mark.match('Mark Orr').should be_true
+        @mark.match('Orr, Mark').should be_true
+        @mark.match(@kram).should be_true
+      end
+    end
+
+    context "first name matches" do
+      it "should match when first names are the same" do
+        Name.new('Mark', 'Orr').match('Mark', 'Orr').should be_true
+      end
+      
+      it "should be flexible with regards to hyphens in double barrelled names" do
+        Name.new('J.-K.', 'Rowling').match('J. K.', 'Rowling').should be_true
+        Name.new('Joanne-K.', 'Rowling').match('Joanne K.', 'Rowling').should be_true
+      end
+      
+      it "should match initials" do
+        Name.new('M. J. L.', 'Orr').match('Mark John Legard', 'Orr').should be_true
+        Name.new('M.', 'Orr').match('Mark', 'Orr').should be_true
+        Name.new('M. J. L.', 'Orr').match('Mark', 'Orr').should be_true
+        Name.new('M.', 'Orr').match('M. J.', 'Orr').should be_true
+        Name.new('M. J. L.', 'Orr').match('M. G.', 'Orr').should be_false
+      end
+      
+      it "should not match on full names not in first position or without an exact match" do
+        Name.new('J. M.', 'Orr').match('John', 'Orr').should be_true
+        Name.new('M. J.', 'Orr').match('John', 'Orr').should be_false
+        Name.new('M. John', 'Orr').match('John', 'Orr').should be_true
+      end
+      
+      it "should handle common nicknames" do
+        Name.new('William', 'Orr').match('Bill', 'Orr').should be_true
+        Name.new('David', 'Orr').match('Dave', 'Orr').should be_true
+        Name.new('Mick', 'Orr').match('Mike', 'Orr').should be_true
+      end
+      
+      it "should not mix up nick names" do
+        Name.new('David', 'Orr').match('Bill', 'Orr').should be_false
+      end
+    end
+    
+    context "last name matches" do
+      it "should be flexible with regards to hyphens in double barrelled names" do
+        Name.new('Johanna', "Lowry-O'Reilly").match('Johanna', "Lowry O'Reilly").should be_true
+      end
+      
+      it "should be case insensitive in matches involving Macsomething and MacSomething" do
+        Name.new('Alan', 'MacDonagh').match('Alan', 'Macdonagh').should be_true
+      end
+      
+      it "should cater for the common mispelling of names beginning with Mc or Mac" do
+        Name.new('Alan', 'McDonagh').match('Alan', 'MacDonagh').should be_true
+        Name.new('Darko', 'Polimac').match('Darko', 'Polimc').should be_false
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'rspec'
+require File.expand_path(File.dirname(__FILE__) + '/../lib/icu_name')
+
+RSpec.configure do |c|
+  c.filter_run :focus => true
+  c.run_all_when_everything_filtered = true
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification 
+name: icu_name
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 2
+  version: 0.0.2
+platform: ruby
+authors: 
+- Mark Orr
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-31 00:00:00 +00:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 7
+        version: 1.0.7
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: Canonicalises and matches person names with Latin1 characters and first and last names
+email: mark.j.l.orr@googlemail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENCE
+- README.rdoc
+files: 
+- lib/icu_name/version.rb
+- lib/icu_name.rb
+- spec/icu_name_spec.rb
+- spec/spec_helper.rb
+- LICENCE
+- README.rdoc
+has_rdoc: true
+homepage: http://rubygems.org/gems/icu_name
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: icu_name
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Canonicalises and matches person names
+test_files: []
+