Precursors and suffixes may be applied to single names that include a surname

METHODS

new

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 should be reused with new input data. Calling new repeatedly will significantly slow your program down.

Various setup options may be defined in a hash that is passed as an optional argument to the new method. Note that all the arguments are optional. You need to define the combination of arguments that are appropriate for your usage.

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.

auto_clean

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.

lc_prefix

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.

initials

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.

allow_reversed

When this option is set to a positive value, names in reverse order will be processed. The only valid format is the surname followed by a comma and the rest of the name, which can be in any of the combinations allowed by non reversed names. Some examples are:

Smith, Mr AB Jones, Jim De Silva, Professor A.B.

The program changes the order of the name back to the non reversed format, and then performs the normal parsing. Note that if the name can be parsed, the fact that it's order was originally reversed, is not recorded as a property of the name object.

joint_names

When this option is set to a positive value, joint names are accounted for:

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.

case_all_reversed

$correct_casing = $name->case_all_reversed;

The case_all_reversed method applies the same type of casing as case_all. However, the name is returned as surname followed by a comma and the rest of the name, which can be any of the combinations allowed for a name, except the title. Some examples are: "Smith, John", "De Silva, A.B." This is useful for sorting names alphabetically by surname.

If a component has no matching data for a given name, it's values will be set to the empty string.

If the name could not be parsed, this method returns null. If you assign the return value to a hash, you should check the error status returned by the parse method first. Ohterwise, you will get an odd number of values addigned to the hash.

components

%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.

case_surname

$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. An optional input argument controls the casing rules for prefix portions of a surname, as described above in the lc_prefix section.

The output is a string converted to the correct casing for surnames. See surname_prefs.txt for user defined exceptions

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.

surname_prefs.txt

Some surnames can have more than one form of valid capitalisation, such as MacQuarie or Macquarie. Where the user wants to specify one form as the default, a text file called surname_prefs.txt should be created and placed in the same location as the NameParse module. The text file should contain one surname per line, in the capitalised form you want, such as

salutation

The salutation method converts a name into a personal greeting, such as "Dear Mr & Mrs O'Brien" or "Dear Sue and John"

Optional parameters may be specided in a hash as follows:

salutation:
The greeting word such as 'Dear' or 'Greetings'. If not spefied than 'Dear' is used
sal_default:
The default word used when a personalised salution cannot be generated. If not
specified, than 'Friend' is used.
sal_type:
Can be either 'given_name' such as 'Dear Sue' or 'title_plus_name' such as 'Dear Ms Smith'
If not specified, than 'given_name' is used.

If an error is detected during parsing, such as with the name "AB Smith & Associates", then the value of sal_default is used instead of a given name, or a title and surname. If the input string contains a conjunction, an 's' is added to the value of sal_default.

If the name contains a precursor, a default salutation is produced.

clean

$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

properties

The properties method returns all the properties of the name, non_matching, number and type, as a hash.

report

Create a formatted text report to standard output listing - the input string, - the name and value of each defined component - any non matching component

LIMITATIONS

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
Does John Bradfield Smith have a middle name of Bradfield, or a surname of Bradfield-Smith?

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.

As the parser has a very limited understanding of context, the "John_Adam_Smith" name type is most likely to cause problems, as it contains no known tokens like a title. A string such as "National Australia Bank" would be accepted as a valid name, first name National etc. Supplying a list of common pronouns as exceptions could solve this problem.

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.

SEE ALSO

TO DO

BUGS

The dot in a suffix of Jnr. or Snr. will be consumed as unmatched text, and not be retained with the suffix.

Names with accented characters (acute, circumfelx etc) will not be parsed correctly. A work around is to replace the character class [a-z] with \w in the appropriate rules in the grammar tree, but this could lower the accuracy of names based purely on ASCII text.

CREDITS

Thanks to all the people who provided ideas and suggestions, including -

AUTHOR

COPYRIGHT AND LICENSE

Copyright (c) 2013 Kim Ryan. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

case_all_reversed

Apply correct capitalisation to a person's entire name and reverse the order so that surname is first, followed by the other components, such as: Smith, Mr John A Useful for creating a list of names that can be sorted by surname.

If name type is unknown , returns null

If the name type has a joint name, such as 'Mr_A_Smith_Ms_B_Jones', return null, as it is ambiguous which surname to place at the start of the string

Else, returns a string of all cased components in correct reversed order

Module Install Instructions

To install Lingua::EN::NameParse, simply copy and paste either of the commands in to your terminal

As a valued partner and proud supporter of MetaCPAN, StickerYou is
happy to offer a 10% discount on all Custom Stickers,
Business Labels, Roll Labels,
Vinyl Lettering or Custom Decals. StickerYou.com
is your one-stop shop to make your business stick.
Use code METACPAN10 at checkout to apply your discount.