new

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.

   my %args =
   (
      auto_clean     => 1,
      lc_prefix      => 1,
      initials       => 3,
      allow_reversed => 1
   );


   my $name = Lingua::EN::NameParse->new(%args);

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 "components" 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:

Mr_A_Smith_&Ms_B_Jones Mr_&Ms_A_&B_Smith Mr_A_&Ms_B_Smith Mr_&Ms_A_Smith Mr_A_&B_Smith

Note that if this option is not specified, than by default joint names are ignored. Disabling joint names speeds up the processing a lot.

extended_titles

When this option is set to a positive value, all combinations of titles, such as Colonel, Mother Superior are used. If this value is not set, only the following titles are accounted for:

    Mr
    Ms
    M/s
    Mrs
    Miss
    Dr
    Sir
    Dame
    

Note that if this option is not specified, than by default extended titles are ignored. Disabling extended titles speeds up the parsing.

parse

    $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

Returns an error flag. If the name was parsed successfully, it's value is 0, otherwise a 1. This step is a prerequisite for the following methods.

case_all

    $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
   surname spelling such as MacNay-Smith, O'Brien and Van Der Heiden are preserved
   - see C<surname_prefs.txt> for user defined exceptions

A complete definition of the capitalising rules can be found by studying the case_surname function.

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.

The method returns the entire reverse order cased name as text.

components

   %my_name = $name->components;
   $cased_surname = $my_name{surname_1};

The "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:

   precursor
   title_1
   title_2
   given_name_1
   given_name_2
   initials_1
   initials_2
   middle_name
   conjunction_1
   conjunction_2
   surname_1
   surname_2
   suffix

If a component has no matching data for a given name, it will not appear in the hash

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 assigned to the hash.

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

   Macquarie
   MacHado

NameParse will still operate if the file does not exist

salutation

    $salutation = $name->salutation(salutation => 'Dear',sal_default => 'Friend',sal_type => 'given_name'));

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

type

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_Adam_Smith
    Mr_John_A_Smith
    Mr_John_Smith
    Mr_A_Smith
    John_Adam_Smith
    John_A_Smith
    J_Adam_Smith
    John_Smith
    A_Smith
    John
    unknown
    

non_matching

Returns any unmatched section that was found.

report