Canonicalises and matches person names with Western European characters.
Note: version 1.1.0 dropped support for characters beyond codepoint 255 and became independent of activesupport and i18n.
Tested with ruby 1.9.2, 1.9.3, 2.0.0 and 2.2.0.
gem install icu_name
This class exists for two main purposes:
to normalise to a common format the different ways Irish person names are typed in practice
to be able to match two names even if they are not exactly the same in their original form
To create a name object, supply both the first and second names separately to the constructor.
robert = ::.(' 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)
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
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 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 = ::.(' bobby fischer ') bobby.first # => 'Bobby' bobby.last # => 'Fischer'
In this case, since the names were not supplied separately, the
original text will not contain a comma:
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
alternatives can be used to list alternatives to a
given first or last name:
Name.new('Stephen', 'Orr').alternatives(:first) # => ["Steve"] Name.new('Michael Stephen', 'Orr').alternatives(:first) # => ["Steve", "Mike", "Mick", "Mikey"], Name.new('Oissine', 'Murphy').alternatives(:last) # => ["Murchadha"], Name.new('Mark', 'Orr').alternatives(:first) # => 
By default the class uses a set of first and last name alternatives curated for the ICU. However, this can be customized (see below).
match 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(::.('R.', 'Fischer')) # => true
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
Some other ways last names are canonicalised are illustrated below:
::.('John', 'O Reilly'). # => "O'Reilly, John" ::.('dave', 'mcmanus'). # => "McManus, Dave"
Characters and Encoding
The class can only cope with Latin characters, including those with diacritics (accents). Hyphens, single quotes (which represent apostophes) and letters in the ISO-8859-1 range (e.g. “a”, “è”, “Ö”) are preserved, while everything else is removed (unsupported).
::.('éric', 'PRIÉ'). # => "Éric Prié" ::.('BARTŁOMIEJ', 'śliwa'). # => "Bartomiej Liwa" ::.('Սմբատ', 'Լպուտյան'). # => ""
The various accessors (
original) always return strings encoded in UTF-8, no matter
what the input encoding.
eric = ::.('é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"
Accented letters can be transliterated into their US-ASCII counterparts by
:chars option, which is available in all
accessors. For example:
eric.rname(:chars => "US-ASCII") # => "Prie, Eric" eric.original(:chars => "US-ASCII") # => "PRIE, eric"
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
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 nicknames and other types of alternative names such as common spelling errors and player name changes.
The alternative names consist of two arrays, one for first names and one for last names. Each array element is itself an array of strings representing a set of equivalent names. Here, for example, are some of the default first name alternatives:
["Anthony", "Tony"] ["James", "Jim", "Jimmy", "Jamie"] ["Robert", "Bob", "Bobby"] ["Stephen", "Steve", "Steven"] ["Thomas", "Tom", "Tommy"]
The first of these means that Anthony and Tony are considered equivalent and can match.
::.("Tony", "Miles").("Anthony", "Miles") # => true
To change alternative name behaviour, you can replace the default alternatives with a customized set perhaps stored in a database or a YAML file, as illustrated below:
::. data = YAML.load(File open "my_last_name_alternatives.yaml") ::.(:last, data) data = YAML.load(File open "my_first_name_alternatives.yaml") ::.(:first, data)
Note that without the call to
reset_alternatives, the new
loaded alternatives add to, rather than replace, the defaults.
Other uses of alternatives is to cater for English and Irish versions of the same name, for example (last names):
or for variations including spelling variations, for example (first names):
[Patrick, Pat, Paddy, Padraig, Padraic, Padhraig, Padhraic]
Normally, entries in the two arrays 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", /^(Debbie|Deborah)$/]
What this means is that the last names Quinn and Benjamin match but only when the first name matches the given regular expression. In this case it caters for a female whose last name changed after marriage.
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", /^Bradley$/]
This caters for an individual who is known by two normally unrelated first names. The two first names only match when the last name is Bradley.
Name.new("John", "Bradley").match("Sean", "Bradley") # => true Name.new("John", "Alfred").match("Sean", "Alfred") # => false
Mark Orr, rating officer for the Irish Chess Union (ICU).