Lingua::EN::NameParse - routines for manipulating a persons name
use Lingua::EN::NameParse qw(clean case_surname); my %args = ( salutation => 'Dear', sal_default => 'Friend', auto_clean => 1, force_case => 1, lc_prefix => 1, initials => 3 ); my $name = new Lingua::EN::NameParse(%args); $error = $name->parse("MR AC DE SILVA"); %my_name = $name->components; $surname = $my_name{surname_1}; $correct_casing = $name->case_all; %name = $name->case_components; $correct_casing = &case_surname("DE SILVA-MACNAY" [,$lc_prefix]); $good_name = &clean("Bad Na9me"); $name->salutation; %my_properties = $name->properties; $number_surnames = $my_properties{number}; $bad_input = $my_properties{non_matching};
Perl, version 5.001 or higher and Parse::RecDescent
This module takes as input a person or persons name in free format text such as,
Mr AB & M/s CD MacNay-Smith MR J.L. D'ANGELO Estate Of The Late Lieutenant Colonel AB Van Der Heiden
and attempts to parse it. If successful, the name is broken down into components and useful functions can be performed such as :
converting upper or lower case values to name case (Mr AB MacNay ) creating a personalised greeting or salutation (Dear Mr MacNay ) extracting the names individual components (Mr,AB,MacNay ) determining the type of format the name is in (Mr_A_Smith )
If the name cannot be parsed you have the option of cleaning the name of bad characters, or extracting any portion that was parsed and the portion that failed.
This module can be used for analysing and improving the quality of lists of names.
The following terms are used by NameParse to define the components that can make up a name.
Precursor - Estate of (The Late) ... Title - Mr, Mrs, Ms., Sir, Dr, Major, Reverend ... Conjunction - word to separate names or initials, such as "And" Initials - 1-3 letters, each with an optional space and/or dot Surname - De Silva, Van Der Heiden, MacNay-Smith, O'Reilly ...
Refer to the component grammar defined within the code for a complete list of combinations.
'Name casing' refers to the correct use of upper and lower case letters in peoples names, such as Mr AB McNay.
To describe the formats supported by NameParse, a short hand representation of the name is used. The following formats are currently supported :
Mr_A_Smith_&_Ms_B_Jones Mr_&_Ms_A_&_B_Smith Mr_A_&_Ms_B_Smith Mr_&_Ms_A_Smith Mr_A_&_B_Smith Mr_John_A_Smith Mr_John_Smith Mr_A_Smith John_A_Smith John_Smith A_Smith
Precursors are only applied to the 'Mr_John_A_Smith','Mr_John_Smith', 'Mr_A_Smith', 'Mr_John_Smith', 'John_Smith' and 'A_Smith' formats
The new method creates an instance of a name object and sets up the grammar used to parse names. This must be called before any of the following methods are invoked. Note that the object only needs to be created once, and can be reused with new input data.
new
Various setup options may be defined in a hash that is passed as an optional argument to the new method.
my %args = ( salutation => 'Dear', sal_default => 'Friend', auto_clean => 1, force_case => 1, lc_prefix => 1, initials => 3 ); my $name = new Lingua::EN::NameParse(%args);
The option defines the salutation word, such as "Dear" or "Greetings". It must be defined if you are planning to use the salutation method.
salutation
This option defines the defaulting word to substitute for the title and surname(s), when parsing fails to identify them. It is also used when a precursor occurs. Examples are "Friend" or "Member".It must be defined if you are planning to use the salutation method. If an '&' or 'and' occurs in the unmatched section then it is assumed that we are dealing with more than one person, and an 's' is appended to the defaulting word.
This option will force the case_all method to name case the entire input string, including any unmatched sections that failed parsing. For example, in "MR A JONES & ASSOCIATES", "& ASSOCIATES" will also be name cased. The casing rules for unmatched sections are the same as for surnames. This is usually the best option, although any initials in the unmatched section will not be correctly cased. This option is useful when you know you data has invalid names, but you cannot filter out or reject them.
case_all
When this option is set to a positive value, any call to the parse method that fails will attempt to 'clean' the name and then reparse it. See the clean method for details. This is useful for dirty data with embedded unprintable or non alphabetic characters.
parse
clean
When this option is set to a positive value, it will force the case_all and case_component methods to lower case the first letter of each word that occurs in the prefix portion of a surname. For example, Mr AB de Silva, or Ms AS von der Heiden.
case_component
Allows the user to control the number of letters that can occur in the initials. Valid settings are 1,2 or 3. If no value is supplied a default of 2 is used.
$error = $name->parse("MR AC DE SILVA");
The parse method takes a single parameter of a text string containing a name. It attempts to parse the name and break it down into the components described above. If the name was parsed successfully, a 0 is returned, otherwise a 1. This step is a pre-requisite for the following functions.
$correct_casing = $name->case_all;
The case_all method converts the first letter of each component to capitals and the remainder to lower case, with the following exceptions-
initials remain capitalised surnames such as MacNay-Smith, O'Brien and Van Der Heiden are observed
A complete definition of the capitalising rules can be found by studying the component grammar defined within the code.
The method returns the entire cased name as text.
%my_name = $name->components; $cased_surname = $my_name{surname_1};
The case_components method does the same thing as the case_all method, but returns the name cased components in a hash. The following keys are used for each component-
case_components
precursor title_1 title_2 given_name_1 initials_1 initials_2 conjunction_1 conjunction_2 surname_1 surname_2
Entries only occur in the hash for each component that the currently parsed name has, meaning there are no keys with undefined values.
%name = $name->components; $surname = $my_name{surname_1};
The components method does the same thing as the case_components method, but each component is returned as it appears in the input string, with no case conversion.
components
$correct_casing = &case_surname("DE SILVA-MACNAY" [,$lc_prefix]);
case_surname is a stand alone function that does not require a name object. The input is a text string and the output is a string converted to the correct casing for surnames. An optional argument controls the casing rules for prefix portions of a surname, as described above in the lc_prefix section.
case_surname
lc_prefix
This function is useful when you know you are only dealing with names that do not have initials like "Mr John Jones". It is much faster than the case_all method, but does not understand context, and cannot detect errors on strings that are not personal names.
The salutation method converts a name into a personal greeting, such as "Dear Mr & Mrs O'Brien".
If an error is detected during parsing, such as with the name "AB Smith & Associates", the title (if it occurs) and the surname(s) are replaced with a default word like "Friend" or "Member". If the input string contains a conjunction, an 's' is added to the default.
If the name contains a precursor, a default salutation is also produced.
$good_name = &clean("Bad Na9me");
clean is a stand alone function that does not require a name object. The input is a text string and the output is the string with:
all repeating spaces removed all characters not in the set (A-Z a-z - ' , . &) removed
The properties method return several properties of then name as a hash.
properties
The type of format a name is in, as one of the following strings:
Mr_A_Smith_&_Ms_B_Jones Mr_&_Ms_A_&_B_Smith Mr_A_&_Ms_B_Smith Mr_&_Ms_A_Smith Mr_A_&_B_Smith Mr_John_A_Smith Mr_John_Smith Mr_A_Smith John_A_Smith John_Smith A_Smith unknown
Returns the number of surnames found in the input strings. Unknown name types have a number of 0.
Returns any unmatched section that was found.
The huge number of character combinations that can form a valid names makes it is impossible to correctly identify them all. Firstly, there are many ambiguities, which have no right answer.
Macbeth or MacBeth, are both valid spellings Is ED WOOD E.D. Wood or Edward Wood Is 'Mr Rapid Print' a name or a company
One approach is to have large lookup files of names and words, statistical rules and fuzzy logic to attempt to derive context. This approach gives high levels of accuracy but uses a lot of your computers time and resources.
NameParse takes the approach of using a limited set of rules, based on the formats that are commonly used by business to represent peoples names. This gives us fairly high accuracy, with acceptable speed and program size.
NameParse will accept names from many countries, like Van Der Heiden, De La Mare and Le Fontain. Having said that, it is still biased toward English, because the precursors, titles and conjunctions are based on English usage.
Names with two or more words, but no separating hyphen are not recognized. This is a real quandary as Indian, Chinese and other names can have several components. If these are allowed for, any component after the surname will also be picked up. For example in "Mr AB Jones Trading As Jones Pty Ltd" will return a surname of "Jones Trading".
Because of the large combination of possible names defined in the grammar, the program is not very fast, except for the more limited case_surname subroutine. See the "Future Directions" section for possible speed ups.
"The Wordsworth Dictionary of Abbreviations & Acronyms" (1997)
Australian Standard AS4212-1994 "Geographic Information Systems - Data Dictionary for transfer of street addressing information"
Allow for a user defined file of local spellings, like duPont, MacHado etc Add filtering of very long names Add diagnostic messages explaining why parsing failed Add transforming methods to do things like remove dots from initials Add suffixes like Senior, Jnr, IV, "The Third' Add awards like OBE, PhD, BSc ... Try to derive gender (Mr... is male, Ms, Mrs... is female)
Let the user select what level of complexity of grammar they need for their data. For example, if you know most of your names are in a "John Smith" format, you can avoid the ambiguity between two letter given names and initials. Using a limited grammar subset will also be much faster.
Define grammar for other languages. Hopefully, all that would be needed is to specify a new module with its own grammar, and inherit all the existing methods. I don't have the knowledge of the naming conventions for non-english languages.
Add regression tests for all combinations of each component
0.01 25 Apr 1999: First Release
0.02 01 May 1999: Added test script, converted source to Unix format
0.03 02 May 1999: Altered output of test script to work with Test::Harness Modified &clean to remove single leading or trailing space
0.04 16 May 1999: Added test script for rule ordering Added more titles, improved documentation
0.10 04 Jul 1999: Allowed for lower casing of surname prefixes
0.30 21 Aug 1999: Allowed for user defined length of initials Added the Mr_John_Smith name type Added the John_Smith name type Surnames with the D' prefix now correctly capitalised
If a parsed name had no components, the components method returned an odd numbered hash and case_componets returned 1. Both these methods now return undef in this situation.
0.40 14 Sep 1999: Added the Mr_John_A_Smith and John_A_Smith name types Allowed for hyphenated given names
Copyright (c) 1999 Kim Ryan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html).
NameParse was written by Kim Ryan <kimaryan@ozemail.com.au> in 1999. Thanks to all the people who provided ideas and suggestions, including -
QM Industries <http://www.qmi.com.au> Damian Conway <damian@cs.monash.edu.au> author of Parse::RecDescent <mark.summerfield@chest.ac.uk>, author of Text::NameCase, Ron Savage <rpsavage@ozemail.com.au> <alastair@calliope.demon.co.uk>
To install Lingua::EN::NameParse, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Lingua::EN::NameParse
CPAN shell
perl -MCPAN -e shell install Lingua::EN::NameParse
For more information on module installation, please visit the detailed CPAN module installation guide.