icu_name 0.1.4 → 1.0.0

data/README.rdoc

@@ -23,50 +23,56 @@ To create a name object, supply both the first and second names separately to th
 
 Capitalisation, white space and punctuation will all be automatically corrected:
 
-  robert.name                                             # => 'Robert J. Fischer'
-  robert.rname                                            # => 'Fischer, Robert J.'  (reversed name)
+  robert.name                                                 # => 'Robert J. Fischer'
+  robert.rname                                                # => 'Fischer, Robert J.'  (reversed name)
 
 The input text, without any changes apart from white-space cleanup and the insertion of a comma
-(to separate the two names), is returned by the _original_ method:
+(to separate the two names), is returned by the <tt>original</tt> method:
 
-  robert.original                                         # => 'FISCHER, robert j'
+  robert.original                                             # => 'FISCHER, robert j'
 
 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 (the last distinct word becomes the last name).
+supply the two separately. If the full name is supplied alone to the constructor, without any indication
+of where the first names end, then the last distinct name is assumed to be the last name.
 
   bobby = ICU::Name.new(' bobby  fischer ')
 
-  bobby.first                                             # => 'Bobby'
-  bobby.last                                              # => 'Fischer'
+  bobby.first                                                 # => 'Bobby'
+  bobby.last                                                  # => 'Fischer'
 
-But in this case, since the names were not supplied separately, the _original_ text will not contain a comma:
+In this case, since the names were not supplied separately, the <tt>original</tt> text will not contain a comma:
 
-  bobby.original                                          # => 'bobby fischer'
+  bobby.original                                              # => 'bobby 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
+  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)
-and not all possibilities.
+The method <tt>alternatives</tt> can be used to list alternatives to a given first or last name:
 
-Supplying the _match_ method with strings is equivalent to instantiating a Name instance with the same
+  Name.new('Stephen', 'Orr').alternatives(:first)             # => ["Steve"]
+  Name.new('Michael Stephen', 'Orr').alternatives(:first)     # => ["Steve", "Mike", "Mick", "Mikey"],
+  Name.new('Mark', 'Orr').alternatives(:first)                # => []
+  
+By default the class is only aware of a few common alternatives for first names (e.g. _Bobby_ and _Robert_,
+_Bill_ and _William_, etc). However, this can be customized (see below).
+
+Supplying the <tt>match</tt> method with strings is equivalent to instantiating an 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
+  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_.
+Here the inital _R_ 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
+  bobby.match('R. J.', 'Fischer')                             # => false
 
-Some of the ways last names are canonicalised are illustrated below:
+Some other 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('John', 'O Reilly').last                      # => "O'Reilly, John"
+  ICU::Name.new('dave', 'mcmanus').last                       # => "McManus, Dave"
 
 == Characters and Encoding
 
@@ -76,40 +82,127 @@ Along with hyphens and single quotes (which represent apostophes) letters in ISO
 character plus one or more diacritics (e.g. "ł" or "Ś") are preserved, while everything
 else is removed.
 
-  ICU::Name.new('éric', 'PRIÉ').name                      # => "Éric Prié"
-  ICU::Name.new('BARTŁOMIEJ', 'śliwa').name               # => "Bartłomiej Śliwa"
-  ICU::Name.new(' 渡井美代子').name                            # => ""
+  ICU::Name.new('éric', 'PRIÉ').name                          # => "Éric Prié"
+  ICU::Name.new('BARTŁOMIEJ', 'śliwa').name                   # => "Bartłomiej Śliwa"
+  ICU::Name.new('Սմբատ', 'Լպուտյան').name                     # => ""
 
-The various accessors (_first_, _last_, _name_, _rname_, _to_s_, _original_) always return
+The various accessors (<tt>first</tt>, <tt>last</tt>, <tt>name</tt>, <tt>rname</tt>, <tt>to_s</tt>, <tt>original</tt>) always return
 strings encoded in UTF-8, no matter what the input encoding.
 
   eric = ICU::Name.new('éric'.encode("ISO-8859-1"), 'PRIÉ'.force_encoding("ASCII-8BIT"))
-  eric.rname                                              # => "Prié, Éric"
-  eric.rname.encoding.name                                # => "UTF-8"
-  eric.original                                           # => "PRIÉ, éric"
-  eric.original.encoding.name                             # => "UTF-8"
+  eric.rname                                                  # => "Prié, Éric"
+  eric.rname.encoding.name                                    # => "UTF-8"
+  eric.original                                               # => "PRIÉ, éric"
+  eric.original.encoding.name                                 # => "UTF-8"
 
 Accented letters can be transliterated into their US-ASCII counterparts by setting the
-_chars_ option, which is available in all accessors. For example:
+<tt>:chars</tt> option, which is available in all accessors. For example:
 
-  eric.rname(:chars => "US-ASCII")                        # => "Prie, Eric"
-  eric.original(:chars => "US-ASCII")                     # => "PRIE, eric"
+  eric.rname(:chars => "US-ASCII")                            # => "Prie, Eric"
+  eric.original(:chars => "US-ASCII")                         # => "PRIE, eric"
 
 Also possible is the preservation of ISO-8859-1 characters, but the transliteration of
 all other accented characters:
 
   joe = Name.new('Józef', 'Żabiński')
-  joe.rname                                               # => "Żabiński, Józef"
-  joe.rname(:chars => "ISO-8859-1")                       # => "Zabinski, Józef"
-  joe.rname(:chars => "US-ASCII")                         # => "Zabinski, Jozef"
+  joe.rname                                                   # => "Żabiński, Józef"
+  joe.rname(:chars => "ISO-8859-1")                           # => "Zabinski, Józef"
+  joe.rname(:chars => "US-ASCII")                             # => "Zabinski, Jozef"
 
 Note that the character encoding of the strings returned is still UTF-8 in all cases.
 The same option also relaxes the need for accented characters to match exactly:
 
-  eric.match('Eric', 'Prie')                              # => false
-  eric.match('Eric', 'Prie', :chars => "US-ASCII")        # => true
-  joe.match('Józef', 'Zabinski')                          # => false
-  joe.match('Józef', 'Zabinski', :chars => "ISO-8859-1")  # => true
+  eric.match('Eric', 'Prie')                                  # => false
+  eric.match('Eric', 'Prie', :chars => "US-ASCII")            # => true
+  joe.match('Józef', 'Zabinski')                              # => false
+  joe.match('Józef', 'Zabinski', :chars => "ISO-8859-1")      # => true
+
+== Customization of Alternative Names
+
+We saw above how _Bobby_ and _Robert_ were able to match because, by default, the
+matcher is aware of some common English nicknames. These name alternatives can be
+customised to handle additional nick names and other types of alternative names
+such as common spelling mistakes and name changes.
+
+The alternative names are specified in two YAML files, one for first names and
+one for last names. Each YAML file represents an array and each element in the
+array is an array representing a set of alternative names. Here, for example,
+are some of the default first name alternatives:
+
+  [Anthony, Tony]
+  [James, Jim, Jimmy]
+  [Michael, Mike, Mick, Mikey]
+  [Robert, Bob, Bobby]
+  [Stephen, Steve]
+  [Steven, Steve]
+  [Thomas, Tom, Tommy]
+  [William, Will, Willy, Willie, Bill]
+
+The first of these means that _Anthony_ and _Tony_ are considered equivalent and can match.
+
+  Name.new("Tony", "Miles").match("Anthony", "Miles")         # => true
+
+Note that both _Steven_ and _Stephen_ match _Steve_ but, because they don't occur in the
+same group, they don't match each other.
+
+  Name.new("Steven", "Hanly").match("Steve", "Hanly")         # => true
+  Name.new("Stephen", "Hanly").match("Steve", "Hanly")        # => true
+  Name.new("Stephen", "Hanly").match("Steven", "Hanly")       # => false
+
+To customize alternative name behaviour, prepare YAML files with your chosen alternatives
+and then replace the default alternatives like this:
+
+  Name.load_alternatives(:first, "my_first_name_alternatives.yaml")
+  Name.load_alternatives(:last, "my_last_name_alternatives.yaml")
+
+An example of one way in which you might want to customize the alternatives is to
+cater for common spelling mistakes such as _Steven_ and _Stephen_. These two names
+don't match by default, but you can make them so by replacing the two default rules:
+
+  [Stephen, Steve]
+  [Steven, Steve]
+
+with the following single rule:
+
+  [Stephen, Steven, Steve]
+
+so that now:
+
+  Name.new("Stephen", "Hanly").match("Steven", "Hanly")       # => true
+
+Another use is to cater for English and Irish versions of the same name. For example,
+for last names:
+
+  [Murphy, Murchadha]
+
+or for first names, including spelling variations:
+
+  [Patrick, Pat, Paddy, Padraig, Padraic, Padhraig, Padhraic]
+
+== Conditional Alternatives
+
+Normally, entries in the two YAML files are just lists of alternative names. There is one
+exception to this however, when one of the entries (it doesn't matter which one but,
+by convention, the last one) is a regular expression. Here is an example that might
+be added to the last name alternatives:
+
+  [Quinn, Benjamin, !ruby/regexp /^(Debbie|Deborah)$/]
+
+What this means is that the last names _Quinn_ and _Benjamin_ match but only when the
+first name matches the regular expression.
+
+  Name.new("Debbie", "Quinn").match("Debbie", "Benjamin")     # => true
+  Name.new("Mark", "Quinn").match("Mark", "Benjamin")         # => false
+
+Another example, this time for first names, is:
+
+  [Sean, John, !ruby/regexp /^Bradley$/]
+
+This caters for an individual who is known by two normally unrelated first names.
+We only want these two names to match for that individual and no others.
+
+  Name.new("John", "Bradley").match("Sean", "Bradley")        # => true
+  Name.new("John", "Alfred").match("Sean", "Alfred")          # => false
 
 == Author
 

data/config/first_alternatives.yaml

@@ -0,0 +1,36 @@
+---
+  - [Alexander, Alex]
+  - [Andrew, Andy]
+  - [Anthony, Tony]
+  - [Benjamin, Ben]
+  - [Catherine, Cathy, Cath]
+  - [Daniel, Danny, Dan]
+  - [David, Dave]
+  - [Deborah, Debbie]
+  - [Des, Desmond]
+  - [Edward, Eddie, Eddy, Ed]
+  - [Frederick, Fred]
+  - [Frederic, Fred]
+  - [Gerald, Gerry]
+  - [Gerard, Gerry]
+  - [James, Jim, Jimmy]
+  - [John, Johnny]
+  - [Jonathan, Jon]
+  - [Kenneth, Ken, Kenny]
+  - [Michael, Mike, Mick, Mikey]
+  - [Nic, Nick, Nicolas]
+  - [Nicola, Nickie, Nicky]
+  - [Patrick, Pat]
+  - [Patricia, Patty, Pat]
+  - [Peter, Pete]
+  - [Philip, Phil]
+  - [Phillip, Phil]
+  - [Rick, Ricky]
+  - [Robert, Bob, Bobby]
+  - [Samual, Sam]
+  - [Samuel, Sam]
+  - [Stephen, Steve]
+  - [Steven, Steve]
+  - [Terence, Terry]
+  - [Thomas, Tom, Tommy]
+  - [William, Will, Willy, Willie, Bill]

data/config/last_alternatives.yaml

@@ -0,0 +1 @@
+--- []

data/config/test_first_alts.yaml

@@ -0,0 +1,41 @@
+---
+  - [Abdul, Abul]
+  - [Alexander, Alex]
+  - [Anandagopal, Ananda]
+  - [Andrew, Andy]
+  - [Anne, Ann]
+  - [Anthony, Tony]
+  - [Benjamin, Ben]
+  - [Catherine, Cathy, Cath]
+  - [Daniel, Danial, Danny, Dan]
+  - [David, Dave]
+  - [Deborah, Debbie]
+  - [Des, Desmond]
+  - [Eamonn, Eamon]
+  - [Edward, Eddie, Eddy, Ed]
+  - [Eric, Erick, Erik]
+  - [Frederick, Frederic, Fred]
+  - [Gerald, Gerry]
+  - [Gerhard, Gerard, Ger, Gerry]
+  - [James, Jim, Jimmy]
+  - [Joanna, Joan, Joanne]
+  - [John, Johnny]
+  - [Jonathan, Jon]
+  - [Kenneth, Ken, Kenny]
+  - [Michael, Mike, Mick, Micky, Mickie, Mikey]
+  - [Nicholas, Nick, Nicolas]
+  - [Nicola, Nickie, Nicky]
+  - [Patrick, Pat, Paddy, Padraig, Padraic, Padhraig, Padhraic]
+  - [Patricia, Paddy, Patty, Pat]
+  - [Peter, Pete]
+  - [Philippe, Philip, Phillippe, Phillip]
+  - [Rick, Ricky]
+  - [Robert, Bob, Bobby]
+  - [Samual, Sam, Samuel]
+  - [Stef, Stefan, Stephan, Stefen, Stephen]
+  - [Steffy, Stefanie, Stephanie, Stefenie, Stephenie]
+  - [Stephen, Steve, Steven]
+  - [Terence, Terry]
+  - [Thomas, Tom, Tommy]
+  - [William, Will, Willy, Willie, Bill]
+  - [Sean, John, !ruby/regexp /^Bradley$/]

data/config/test_last_alts.yaml

@@ -0,0 +1,5 @@
+---
+  - [Ffrench, French]
+  - [Murchadha, Murphy]
+  - [Quinn, Benjamin, !ruby/regexp /^(Debbie|Deborah)$/]
+  - ["O'Siochru", King, !ruby/regexp /^Mairead$/]

data/lib/icu_name/name.rb

@@ -5,31 +5,42 @@ require 'active_support/core_ext/string/multibyte'
 
 module ICU
   class Name
+    # Revert to the default sets of alternative names.
+    def self.reset_alternatives
+      @@alts = Hash.new
+      @@cmps = Hash.new
+    end
+
+    # Perform a reset when the class is first loaded.
+    self.reset_alternatives
 
-    # Construct from one or two strings or any objects that have a to_s method.
+    # Construct a new name from one or two strings or any objects that have a to_s method.
     def initialize(name1='', name2='')
       @name1 = Util.to_utf8(name1.to_s)
       @name2 = Util.to_utf8(name2.to_s)
       originalize
       canonicalize
+      @first.freeze
+      @last.freeze
+      @original.freeze
     end
-    
+
     # Original text getter.
     def original(opts={})
       return transliterate(@original, opts[:chars]) if opts[:chars]
-      @original
+      @original.dup
     end
 
     # First name getter.
     def first(opts={})
       return transliterate(@first, opts[:chars]) if opts[:chars]
-      @first
+      @first.dup
     end
 
     # Last name getter.
     def last(opts={})
       return transliterate(@last, opts[:chars]) if opts[:chars]
-      @last
+      @last.dup
     end
 
     # Return a complete name, first name first, no comma.
@@ -50,7 +61,7 @@ module ICU
       name
     end
 
-    # Convert object to a string.
+    # Convert to a string (same as rname).
     def to_s(opts={})
       rname(opts)
     end
@@ -61,6 +72,17 @@ module ICU
       match_first(first(opts), other.first(opts)) && match_last(last(opts), other.last(opts))
     end
 
+    # Load a set of first or last name alternatives. If the YAML file name is absent,
+    # the default set is loaded. <tt>type</tt> should be <tt>:first</tt> or <tt>:last</tt>.
+    def self.load_alternatives(type, file=nil)
+      compile_alts(check_type(type), file, true)
+    end
+
+    # Show first name or last name alternatives.
+    def alternatives(type)
+      get_alts(check_type(type))
+    end
+
     # :stopdoc:
     private
 
@@ -70,7 +92,7 @@ module ICU
       @original.strip!
       @original.gsub!(/\s+/, ' ')
     end
-    
+
     # Transliterate characters to ASCII or Latin1.
     def transliterate(str, chars='US-ASCII')
       case chars
@@ -154,6 +176,10 @@ module ICU
       names
     end
 
+    # Check the type argument to the public methods.
+    def check_type(type) self.class.instance_eval { check_type(type) }; end
+    def self.check_type(type) type = type.to_s == "last" ? :last : :first; end
+
     # Match a complete first name.
     def match_first(first1, first2)
       # Is this one a walk in the park?
@@ -166,8 +192,9 @@ module ICU
       # 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.
+      # The short one must be a "subset" of the long one. An extra condition must also be satisfied:
+      # either there has to be at least one match not involving initials or the first names must match.
+      # For example "M. J." matches "Mark" but not  "John".
       extra = false
       (0..long.size-1).each do |i|
         lword = long.shift
@@ -186,6 +213,7 @@ module ICU
     # Match a complete last name.
     def match_last(last1, last2)
       return true if last1 == last2
+      return true if match_alt(:last, last1, last2)
       [last1, last2].each do |last|
         last.downcase!            # case insensitive
         last.gsub!(/\bmac/, 'mc') # MacDonaugh and McDonaugh
@@ -211,74 +239,73 @@ module ICU
       initials = 0
       initials+= 1 if first1.match(/^[A-Z\u{c0}-\u{de}]\.?$/)
       initials+= 1 if first2.match(/^[A-Z\u{c0}-\u{de}]\.?$/)
-      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]
+      return initials if first1 == first2                             # "W." and "W." or "William" and "William"
+      return 0 if initials == 0 && match_alt(:first, first1, first2)  # "William"" and "Bill"
+      return -1 unless initials > 0                                   # "William" and "Patricia"
+      return initials if first1[0] == first2[0]                       # "W." and "William" or "W." and "W"
       -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]
+    # Match two names that might be equivalent due to nicknames, misspellings, changed married names etc.
+    def match_alt(type, nam1, nam2)
+      self.class.compile_alts(type)
+      return false unless nams = @@alts[type][nam1]
+      return false unless cond = nams[nam2]
+      return true if cond == true
+      cond.match(type == :first ? @last : @first)
     end
 
-    # Compile the nick names code hash when matching nick names is first attempted.
-    def compile_nick_names
-      @@nc = Hash.new
+    # Return an array of alternative first or second names (not including the original name).
+    # Allow for double barrelled last names or multiple first names.
+    def get_alts(type)
+      self.class.compile_alts(type)
+      name = self.send(type)
+      names = name.split(/[- ]/)
+      names.push(name) if names.length > 1
+      target = type == :first ? @last : @first
+      alts = Array.new
+      names.each do |n|
+        next unless @@alts[type][n]
+        @@alts[type][n].each_pair do |k, v|
+          alts.push k if v == true || v.match(target)
+        end
+      end
+      alts
+    end
+
+    # Compile an alternative names hash (for either first names or last names) before matching is first attempted.
+    def self.compile_alts(type, file=nil, force=false)
+      return if @@alts[type] && !force
+      file ||= File.expand_path(File.dirname(__FILE__) + "/../../config/#{type}_alternatives.yaml")
+      data = YAML.load(File.open file)
+      @@cmps[type] ||= 0
+      @@alts[type] = Hash.new
       code = 1
-      @@nl.each do |nicks|
-        nicks.each do |n|
-          throw "duplicate name #{n}" if @@nc[n]
-          @@nc[n] = code
+      data.each do |alts|
+        cond = true
+        alts.reject! do |a|
+          if a.instance_of?(Regexp)
+            cond = a
+          else
+            false
+          end
+        end
+        alts.each do |name|
+          alts.each do |other|
+            unless other == name
+              @@alts[type][name] ||= Hash.new
+              @@alts[type][name][other] = cond
+            end
+          end
         end
         code+= 1
       end
+      @@cmps[type] += 1
     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
-Andrew Andy
-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
+    # Return the number of YAML file compilations (for testing).
+    def self.alt_compilations(type)
+      @@cmps[check_type(type)] || 0
+    end
   end
 end

data/lib/icu_name/version.rb

@@ -2,6 +2,6 @@
 
 module ICU
   class Name
-    VERSION = "0.1.4"
+    VERSION = "1.0.0"
   end
 end

data/spec/name_spec.rb

@@ -3,6 +3,17 @@ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
 module ICU
   describe Name do
+    def load_alt_test(*types)
+      types.each do |type|
+        file = File.expand_path(File.dirname(__FILE__) + "/../config/test_#{type}_alts.yaml")
+        Name.load_alternatives(type, file)
+      end
+    end
+
+    def alt_compilations(type)
+      Name.alt_compilations(type)
+    end
+
     context "public methods" do
       before(:each) do
         @simple = Name.new('mark j l', 'ORR')
@@ -68,7 +79,7 @@ module ICU
       it "characters and encoding" do
         ICU::Name.new('éric', 'PRIÉ').name.should == "Éric Prié"
         ICU::Name.new('BARTŁOMIEJ', 'śliwa').name.should == "Bartłomiej Śliwa"
-        ICU::Name.new(' 渡井美代子').name.should == ""
+        ICU::Name.new('Սմբատ', 'Լպուտյան').name.should == ""
         eric = Name.new('éric'.encode("ISO-8859-1"), 'PRIÉ'.force_encoding("ASCII-8BIT"))
         eric.rname.should == "Prié, Éric"
         eric.rname.encoding.name.should == "UTF-8"
@@ -244,7 +255,7 @@ module ICU
         @opt = { :chars => "US-ASCII" }
       end
 
-      it "should be a no-op for names that already ASCII" do
+      it "should be a no-op for names that are already ASCII" do
         name = Name.new('Mark J. L.', 'Orr')
         name.first(@opt).should == 'Mark J. L.'
         name.last(@opt).should == 'Orr'
@@ -325,6 +336,21 @@ module ICU
         Name.new('Mick', 'Orr').match('Mike', 'Orr').should be_true
       end
 
+      it "should handle ambiguous nicknames" do
+        Name.new('Gerry', 'Orr').match('Gerald', 'Orr').should be_true
+        Name.new('Gerry', 'Orr').match('Gerard', 'Orr').should be_true
+        Name.new('Gerard', 'Orr').match('Gerald', 'Orr').should be_false
+      end
+
+      it "should by default be cautious about misspellings" do
+        Name.new('Steven', 'Brady').match('Stephen', 'Brady').should be_false
+        Name.new('Philip', 'Short').match('Phillip', 'Short').should be_false
+      end
+
+      it "should by default have no conditional matches" do
+        Name.new('Sean', 'Bradley').match('John', 'Bradley').should be_false
+      end
+
       it "should not mix up nick names" do
         Name.new('David', 'Orr').match('Bill', 'Orr').should be_false
       end
@@ -343,6 +369,11 @@ module ICU
         Name.new('Alan', 'McDonagh').match('Alan', 'MacDonagh').should be_true
         Name.new('Darko', 'Polimac').match('Darko', 'Polimc').should be_false
       end
+
+      it "should by defaut have no conditional matches" do
+        Name.new('Debbie', 'Quinn').match('Debbie', 'Benjamin').should be_false
+        Name.new('Mairead', "O'Siochru").match('Mairead', 'King').should be_false
+      end
     end
 
     context "matches involving accented characters" do
@@ -361,5 +392,173 @@ module ICU
         Name.new('Èric-K.', 'Cantona').match('E. K.', 'Cantona', :chars => "US-ASCII").should be_true
       end
     end
+
+    context "configuring new first name alternatives" do
+      before(:all) do
+        load_alt_test(:first)
+      end
+
+      it "should match some spelling errors" do
+        Name.new('Steven', 'Brady').match('Stephen', 'Brady').should be_true
+        Name.new('Philip', 'Short').match('Phillip', 'Short').should be_true
+      end
+
+      it "should handle conditional matches" do
+        Name.new('Sean', 'Collins').match('John', 'Collins').should be_false
+        Name.new('Sean', 'Bradley').match('John', 'Bradley').should be_true
+      end
+    end
+
+    context "configuring new last name alternatives" do
+      before(:all) do
+        load_alt_test(:last)
+      end
+
+      it "should match some spelling errors" do
+        Name.new('William', 'Ffrench').match('William', 'French').should be_true
+      end
+
+      it "should handle conditional matches" do
+        Name.new('Mark', 'Quinn').match('Mark', 'Benjamin').should be_false
+        Name.new('Debbie', 'Quinn').match('Debbie', 'Benjamin').should be_true
+        Name.new('Oisin', "O'Siochru").match('Oisin', 'King').should be_false
+        Name.new('Mairead', "O'Siochru").match('Mairead', 'King').should be_true
+      end
+
+      it "should allow some awesome matches" do
+        Name.new('debbie quinn').match('Deborah', 'Benjamin').should be_true
+        Name.new('french, william').match('Bill', 'Ffrench').should be_true
+        Name.new('Oissine', 'Murphy').match('Oissine', 'Murchadha').should be_true
+      end
+    end
+
+    context "configuring new first and new last name alternatives" do
+      before(:all) do
+        load_alt_test(:first, :last)
+      end
+
+      it "should allow some awesome matches" do
+        Name.new('french, steven').match('Stephen', 'Ffrench').should be_true
+        Name.new('Patrick', 'Murphy').match('Padraic', 'Murchadha').should be_true
+      end
+    end
+
+    context "reverting to the default configuration" do
+      before(:all) do
+        load_alt_test(:first, :last)
+      end
+
+      it "should not match so boldly after reverting" do
+        Name.new('french, steven').match('Stephen', 'Ffrench').should be_true
+        Name.load_alternatives(:first)
+        Name.new('Patrick', 'Murphy').match('Padraic', 'Murchadha').should be_false
+        Name.new('Patrick', 'Murphy').match('Patrick', 'Murchadha').should be_true
+        Name.load_alternatives(:last)
+        Name.new('Patrick', 'Murphy').match('Patrick', 'Murchadha').should be_false
+      end
+    end
+
+    context "name alternatives with default configuration" do
+      it "should show common nicknames" do
+        Name.new('William', 'Ffrench').alternatives(:first).should =~ %w{Bill Willy Willie Will}
+        Name.new('Bill', 'Ffrench').alternatives(:first).should =~ %w{William Willy Will Willie}
+        Name.new('Steven', 'Ffrench').alternatives(:first).should =~ %w{Steve}
+        Name.new('Stephen', 'Ffrench').alternatives(:first).should =~ %w{Steve}
+        Name.new('Michael Stephen', 'Ffrench').alternatives(:first).should =~ %w{Steve Mike Mick Mikey}
+        Name.new('Stephen M.', 'Ffrench').alternatives(:first).should =~ %w{Steve}
+        Name.new('S.', 'Ffrench').alternatives(:first).should =~ []
+        Name.new('Sean', 'Bradley').alternatives(:first).should =~ []
+      end
+
+      it "should not have any last name alternatives" do
+        Name.new('William', 'Ffrench').alternatives(:last).should =~ []
+        Name.new('Mairead', "O'Siochru").alternatives(:last).should =~ []
+        Name.new('Oissine', 'Murphy').alternatives(:last).should =~ []
+        Name.new('Debbie', 'Quinn').alternatives(:last).should =~ []
+      end
+    end
+
+    context "name alternatives with more adventurous configuration" do
+      before(:all) do
+        load_alt_test(:first, :last)
+      end
+
+      it "should show additional nicknames" do
+        Name.new('Steven', 'Ffrench').alternatives(:first).should =~ %w{Stephen Steve}
+        Name.new('Stephen', 'Ffrench').alternatives(:first).should =~ %w{Stef Stefan Stefen Stephan Steve Steven}
+        Name.new('Stephen Mike', 'Ffrench').alternatives(:first).should =~ %w{Michael Mick Mickie Micky Mikey Stef Stefan Stefen Stephan Steve Steven}
+        Name.new('Sean', 'Bradley').alternatives(:first).should =~ %w{John}
+        Name.new('Sean', 'McDonagh').alternatives(:first).should =~ []
+        Name.new('John', 'Bradley').alternatives(:first).should =~ %w{Sean Johnny}
+      end
+
+      it "should have some last name alternatives" do
+        Name.new('William', 'Ffrench').alternatives(:last).should =~ %w{French}
+        Name.new('Mairead', "O'Siochru").alternatives(:last).should =~ %w{King}
+        Name.new('Oissine', 'Murphy').alternatives(:last).should =~ %w{Murchadha}
+        Name.new('Debbie', 'Quinn').alternatives(:last).should =~ %w{Benjamin}
+        Name.new('Mark', 'Quinn').alternatives(:last).should =~ []
+        Name.new('Debbie', 'Quinn-French').alternatives(:last).should =~ %w{Benjamin Ffrench}
+      end
+    end
+
+    context "number of alternative compilations" do
+      before(:all) do
+        Name.reset_alternatives
+      end
+
+      it "should be no more than necessary" do
+        alt_compilations(:first).should == 0
+        alt_compilations(:last).should == 0
+        Name.new('William', 'Ffrench').match('Bill', 'French')
+        alt_compilations(:first).should == 1
+        alt_compilations(:last).should == 1
+        Name.new('Debbie', 'Quinn').match('Deborah', 'Benjamin')
+        alt_compilations(:first).should == 1
+        alt_compilations(:last).should == 1
+        load_alt_test(:first)
+        alt_compilations(:first).should == 2
+        alt_compilations(:last).should == 1
+        load_alt_test(:last)
+        alt_compilations(:first).should == 2
+        alt_compilations(:last).should == 2
+        Name.new('William', 'Ffrench').match('Bill', 'French')
+        Name.new('Debbie', 'Quinn').match('Deborah', 'Benjamin')
+        Name.new('Mark', 'Orr').alternatives(:first)
+        Name.new('Mark', 'Orr').alternatives(:last)
+        alt_compilations(:first).should == 2
+        alt_compilations(:last).should == 2
+      end
+    end
+
+    context "immutability" do
+      before(:each) do
+        @mark = ICU::Name.new('Màrk', 'Orr')
+      end
+
+      it "there are no setters" do
+        lambda { @mark.first = "Malcolm" }.should raise_error(/undefined/)
+        lambda { @mark.last = "Dickie" }.should raise_error(/undefined/)
+        lambda { @mark.original = "mark orr" }.should raise_error(/undefined/)
+      end
+
+      it "should prevent accidentally access to the instance variables" do
+        @mark.first.downcase!
+        @mark.first.should == "Màrk"
+        @mark.last.downcase!
+        @mark.last.should == "Orr"
+        @mark.original.downcase!
+        @mark.original.should == "Orr, Màrk"
+      end
+
+      it "should prevent accidentally access to the instance variables when transliterating" do
+        @mark.first(:chars => "US-ASCII").downcase!
+        @mark.first.should == "Màrk"
+        @mark.last(:chars => "US-ASCII").downcase!
+        @mark.last.should == "Orr"
+        @mark.original(:chars => "US-ASCII").downcase!
+        @mark.original.should == "Orr, Màrk"
+      end
+    end
   end
 end

metadata

@@ -3,10 +3,10 @@ name: icu_name
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
-  - 0
   - 1
-  - 4
-  version: 0.1.4
+  - 0
+  - 0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Mark Orr
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-23 00:00:00 +00:00
+date: 2011-04-16 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -138,6 +138,10 @@ files:
 - spec/name_spec.rb
 - spec/spec_helper.rb
 - spec/util_spec.rb
+- config/first_alternatives.yaml
+- config/last_alternatives.yaml
+- config/test_first_alts.yaml
+- config/test_last_alts.yaml
 - LICENCE
 - README.rdoc
 has_rdoc: true