=head1 NAME

Lingua::EN::NameParse - routines for manipulating a persons name

=head1 SYNOPSIS

   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};


=head1 DESCRIPTION

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 like :

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

=head1 REQUIRES

Perl, version 5.001 or higher and Parse::RecDescent


=head1 HOW TO INSTALL

    perl Makefile.PL
    make
    make test
    make install


=head1 BUGS


=head1 CHANGES

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 remvove 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 
                  
=head1 AUTHOR

NameParse was written by Kim Ryan <kimaryan@ozemail.com.au>.

=head1 COPYRIGHT

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

=cut