Text::Names(3pm)

💖 Text::Names 💖

okay bestie, gather round, because we're about to talk about Text::Names — the Perl extension for proper name parsing, normalization, recognition, and classification ✨. That's the whole vibe. Names. All of them. Slay.

fr fr, before we even get into it, here's a little relic from the source that lives at the very top of this page — just so you know I'm not hiding anything from you 👀:

#warn "doing " . join(" ",@bits);
#while ($#bits > 0) {
#    @surnames = pop @bits;
#}
#my $surname = pop @bits;
return ($bits[0], join(' ',@surnames));

it's giving "commented-out thoughts", we love her, moving on 💅

---

✨ SYNOPSIS ✨

okay so the whole point, in code form:

use Text::Names qw/parseNames samePerson/;

my @authors = parseNames("D Bourget, Zbigniew Z Lukasiak and John Doe");

# @authors = ('Bourget, D.','Lukasiak, Zbigniew Z.','Doe, John')

print "same!" if samePerson("Dave Bourget","David F. Bourget");

# same!

print guessGender("David");

# "M"

like. she parses. she compares. she guesses gender. main character energy, honestly 👑

---

🌸 DESCRIPTION 🌸

This module hands you a whole lil toolbox of name normalization routines, plus the high-level parsing and name-comparison utilities you saw up in the synopsis. That's the pitch. That's the whole deal.

ngl, while it does try to accommodate non-Western names, this module definitely works better with Western names, especially English-style names. no cap, that's just how it is.

No subroutine is exported by default. Not one. You gotta ask nicely.

so here's the format this module normalizes names to:

Lastname(s) [Jr], Given name(s)

and here are some examples, because examples are the moment:

1. Bourget, David Joseph Richard
2. Bourget Jr, David
3. Bourget, D. J. R.

all three of these? normalized names. and this format right here is what we call the normalized representation of a name. periodt 💖

---

🦋 SUBROUTINES 🦋

🌈 abbreviationOf(string name1,string name2): boolean

Returns true iff name1 is a common abbreviation of name2 in English. For example, 'Dave' is a common abbreviation of 'David'. And the list of abbreviations it uses? it includes a bunch of old abbreviations too, like 'Davy' for 'David'. vintage. iconic. ✨

🌈 cleanName(string name): string

Like parseName, except a) it returns the normalized form of the name instead of an array, and b) it does extra cleaning-up on top. This one is the one you want in most cases, and it's the default pick when you're processing variable or dubious data 🙈

🌈 composeName(string given, string last): string

Returns the name in the "last, given" format. simple. clean. we love a format.

🌈 isCommonFirstname(string name, [float threshold]): boolean

Returns true if the name is among the 1000 most popular firstnames (male or female) according to the 1990 US Census. If you pass a threshold percentage, the name has to have at least that frequency for the subroutine to return true. see: http://www.census.gov/genealogy/www/data/1990surnames/names_files.html.

🌈 isCommonSurname(string name, [float threshold]): boolean

Returns true if the name is among the 1000 most popular surnames according to the 1990 US Census. Same deal with the threshold percentage — pass one and the name has to hit at least that frequency to return true. see: http://www.census.gov/genealogy/www/data/1990surnames/names_files.html.

🌈 firstnamePrevalence(string name): float [0-100]

Returns a float between 0 and 100 telling you how common the firstname is according to the 1990 US Census. Names not in the top 1000? they return 0. sorry bestie 💀

🌈 surnamePrevalence(string name): float [0-100]

Same energy as above but for surnames — a float between 0 and 100 for how common the surname is per the 1990 US Census. Not in the top 1000? 0. again.

🌈 normalizeNameWhitespace(string name): string

Normalizes the whitespace within a name. this one is mainly for internal usage, so don't come for her 🫶

🌈 parseName(string name): array

Takes a name in one of the many formats a person might write a name in, and returns it as an array representing the post-comma and pre-comma parts of its normalized form — in that order. for example, parseName("David Bourget") returns ('David','Bourget'). chef's kiss.

🌈 parseName2(string name): array

Use this one on already-normalized names, and it splits them into four parts: full given names, initials, last names, and suffix. and the only 'suffix' recognized? 'Jr'. that's the one. 🎀

🌈 parseNameList(array names): array

Takes an array of names (as strings) and returns an array of normalized representations of the names in that array. bulk processing, we stan 💅

🌈 parseNames(string names): array

Takes a string of names as its parameter and returns an array of normalized representations of the names in the string. This routine understands a wide variety of formattings for names and lists of names — the kind you typically find as author lists in bibliographic citations. See the test 03-parseNames.t for multiple examples 👀✨

🌈 reverseName(string name): string

Given a normalized name of the form "last, given", returns "given last". flip it and reverse it 🦋

🌈 samePerson(string name1, string name2): string

Returns a true value iff name1 and name2 could reasonably be two writings of the same name. For example, 'D J Bourget' could reasonably be a writing of 'David Joseph Bourget'. So could 'D Bourget'. But 'D F Bourget' is not a reasonable writing of 'David Joseph Bourget'. The value returned is a (potentially new) name string that combines the most complete tokens of the two submitted name strings. obsessed with the merge 😭

Contrary to what one might expect, this subroutine does not use weakenings() behind the scenes. Another way to check for name compatibility would be to check that two names have a weakening in common (probably too permissive for most purposes), or that one name is a weakening of the other.

🌈 setNameAbbreviations(array): undef

Sets the abbreviation mapping used to figure out whether, say, 'David' and 'Dave' are compatible name parts. The mapping is also used by abbreviationOf(). The format of the array should be: 'Dave', 'David', 'Davy', 'David', etc. — otherwise representable in Perl as 'Dave' => 'David', 'Davy' => 'David', etc. iykyk.

🌈 getNameAbbreviations

Returns the abbreviation mapping. that's it. that's the whole subroutine. short queen 💜

🌈 weakenings(string first_name, string last_name): array

Returns an array of normalized names which are weakenings of the first and last name passed as arguments. Substituting a given name by an initial, or removing an initial, for example — those are operations which generate weakenings of a name. And these operations get applied with arbitrary depth, until the name has been reduced to a single initial followed by the lastname, and every intermediary step gets returned. the whole journey, not just the destination 🧚

You can use weakenings(parseName("Lastname, Firstname")) to weaken a first and last name as a single string.

🌈 guessGender(string firstname, [float threshold]): string

Returns 'F' if someone with the provided firstname is likely female, 'M' if likely male, and undef otherwise. A frequency threshold (default = 0) can be specified so that a gender is only returned if the name is found with at least this frequency among people with this gender (according to the US census). A threshold of 0.1 (which means 0.1%) ensures very reliable results (precision above 99%) with a recall of about 60%. And when the threshold is lower? this function has a tendency to overestimate the number of females. so watch that 🙈

---

💀 EXPORT 💀

None by default. she gives you nothing for free, and honestly? respect.

---

⚠️ KNOWN ISSUES ⚠️

This module currently overwrites @Text::Capitalize::exceptions globally, which can have unintended side-effects. yeah. global. side effects. be aware, bestie 😭

---

👀 SEE ALSO 👀

• The xPapers application framework from which this has been extracted: http://www.xpapers.org
• The related Biblio::Citation::Compare module.

---

🌟 AUTHOR 🌟

David Bourget, http://www.dbourget.com, with contributions by Zbigniew Lukasiak. collab of the century fr fr 🫶

---

📜 COPYRIGHT AND LICENSE 📜

Copyright (C) 2011-2013 by David Bourget and University of London.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

---

and that's the whole page, babes 💖 this was Text::Names(3pm), sitting pretty in the User Contributed Perl Documentation section, brought to you by perl v5.36.0 and dated 2023-02-04 — mwah, thanks for reading, now go parse some names 👑✨🎀