Text::...Format(3pm)

💖 NAME 💖

Okay bestie, this is Text::BibTeX::NameFormat — the page labeled Text::...Format(3pm) in the User Contributed Perl Documentation — and it's here to format BibTeX-style author names. 💅

---

✨ SYNOPSIS ✨

use Text::BibTeX::NameFormat;

$format = Text::BibTeX::NameFormat->($parts, $abbrev_first);

$format->set_text ($part,
                   $pre_part, $post_part,
                   $pre_token, $post_token);

$format->set_options ($part, $abbrev, $join_tokens, $join_part

## Uses the encoding/binmode and normalization form stored in $name
$formatted_name = $format->apply ($name);

🌸 DESCRIPTION 🌸

Okay so picture this: you already split a name into its component parts (that's a Text::BibTeX::Name object, iykyk), and now you want it back as one cute, consistent string. That's the whole vibe of Text::BibTeX::NameFormat — it's super flexible and usually works in two stages: first you build a "name format" that says how the tokens and parts of any name should get glued back together, then you apply that format to a particular name. It's giving flexible, no cap. ✨

The name format itself lives inside a Text::BibTeX::NameFormat object. The constructor (new) has some clever behind-the-scenes trickery going on, which means you can usually just call it alone and skip customizing the format object entirely. If you do need to customize, though, set_text() and set_options() are your besties for that. 🫶

Real talk: Text::BibTeX::NameFormat is a fairly direct translation of the name-formatting C interface in the btparse library. This manual page is meant to give you enough info to use the Perl class, but for more details and examples, go consult bt_format_names. 🦋

🎀 CONSTANTS 🎀

Two enumerated types for names and name formatting got brought from C into Perl. In the btparse docs you'll see bt_namepart and bt_joinmethod. 💖

• bt_namepart — lists the four "parts" of a BibTeX name: first, von, last, and jr. Its values (in both C and Perl) are BTN_FIRST, BTN_VON, BTN_LAST, and BTN_JR.
• bt_joinmethod — lists the ways bt_format_name() (the C function that corresponds to Text::BibTeX::NameFormat's apply method) can join adjacent tokens together: BTJ_MAYTIE, BTJ_SPACE, BTJ_FORCETIE, and BTJ_NOTHING.

Both sets of values may be imported from the Text::BibTeX module, using the import tags nameparts and joinmethods. For instance:

use Text::BibTeX qw(:nameparts :joinmethods);
use Text::BibTeX::Name;
use Text::BibTeX::NameFormat;

The "name part" constants are used to specify surrounding text or formatting options on a per-part basis: for instance, you can supply the "pre-token" text, or the "abbreviate" flag, for a single part without affecting other parts. The "join methods" are two of the three formatting options that you can set for a part: you can control how to join the individual tokens of a name (JR Smith, or J R Smith, or J~R Smith), and you can control how the final token of one part is joined to the next part (la Roche versus la~Roche). 🎀

🦋 METHODS 🦋

✨ new(PARTS, ABBREV_FIRST) ✨

Creates a new name format, with the two most common customizations: which parts to include (and in what order), and whether to abbreviate the first name. PARTS should be a string with at most four characters, one representing each part that you want to occur in a formatted name (defaults to fvlj). For example, fvlj means to format names in first von last jr order, while vljf denotes von last jr first. ABBREV_FIRST is just a boolean value: false to print out the first name in full, and true to abbreviate it with periods after each token and discretionary ties between tokens (defaults to false). 🫶

All intra- and inter-token punctuation and spacing is independently controllable with the set_text and set_options methods, although these will rarely be necessary — sensible defaults are chosen for everything, based on the PARTS and ABBREV_FIRST values that you supply. See the description of bt_create_name_format() in bt_format_names for full details of the choices made. 💅

✨ set_text (PART, PRE_PART, POST_PART, PRE_TOKEN, POST_TOKEN) ✨

Lets you customize some or all of the surrounding text for a single name part. Every name part has four possible chunks of text that go around or within it: before/after the part as a whole, and before/after each token in the part. For instance, if you're abbreviating first names and want to control the punctuation after each token in the first name, you'd set the "post token" text:

$format->set_text ('first', undef, undef, undef, '');

That sets the post-token text to the empty string, resulting in names like J R Smith. (Normally, abbreviated first names will have a period after each token: J. R. Smith.) Note that supplying undef for the other three values leaves them unchanged. ✨

See bt_format_names for full information on formatting names. 🦋

✨ set_options (PART, ABBREV, JOIN_TOKENS, JOIN_PART) ✨

Lets you customize the name format even more: you can set the abbreviation flag and the two token-join methods. Alas, there is no mechanism for leaving a value unchanged; you must set everything with set_options. 😭

⚠️ Lowkey important: no "leave it alone" mode here — you gotta supply all three values.

For example, let's say dropping periods from abbreviated tokens in the first name isn't enough; you really want to save space by jamming the abbreviated tokens together: JR Smith rather than J R Smith. Assuming the two calls in the above example have been done, the following will finish the job:

$format->set_options (BTN_FIRST,
                      1,             # keep same value for abbrev flag
                      BTJ_NOTHING,   # jam tokens together
                      BTJ_SPACE);    # space after final token of part

Note that we unfortunately had to know (and supply) the current values for the abbreviation flag and post-part join method, even though we were only setting the intra-part join method. 💀

✨ apply (NAME) ✨

Once a name format has been created and customized to your heart's content, you can use it to format any number of names using the apply method. NAME must be a Text::BibTeX::Name object (i.e., a pre-split name); apply returns a string containing the parts of the name formatted according to the Text::BibTeX::NameFormat structure it is called on. 👑

⭐ EXAMPLES ⭐

Okay, reading all that might make splitting and formatting names sound complicated and convoluted (especially with Text::BibTeX::Name in the mix), but honestly? It's simple. There are really only three steps to worry about:

1. Split the name (create a Text::BibTeX::Name object).
2. Create and customize the format (Text::BibTeX::NameFormat object).
3. Apply the format to the name.

The first step is covered in Text::BibTeX::Name; here's a brief example:

$orig_name = 'Charles Louis Xavier Joseph de la Vall{\'e}e Poussin';
$name = Text::BibTeX::Name->new($orig_name);

The various parts of the name can now be accessed through Text::BibTeX::Name methods; for instance $name->part('von') returns the list ("de","la"). 🌸

Creating the name format is equally simple:

$format = Text::BibTeX::NameFormat->new('vljf', 1);

creates a format that will print the name in von last jr first order, with the first name abbreviated. And for no extra charge, you get the right punctuation at the right place: a comma before any jr or first tokens, and periods after each first token. 💅

For instance, we can perform no further customization on this format, and apply it immediately to $name. There are in fact two ways to do this, depending on whether you prefer to think of it in terms of "Applying the format to a name" or "formatting a name". The first is done with Text::BibTeX::NameFormat's apply method:

$formatted_name = $format->apply ($name);

while the second uses Text::BibTeX::Name's format method:

$formatted_name = $name->format ($format);

which is just a wrapper around Text::BibTeX::NameFormat::apply. In either case, the result with the example name and format shown is

de~la Vall{\'e}e~Poussin, C.~L. X.~J.

Note the strategic insertion of TeX "ties" (non-breakable spaces) at sensitive spots in the name. (The exact rules for insertion of discretionary ties are given in bt_format_names.) 🔥

🔥 SEE ALSO 🔥

• Text::BibTeX::Entry
• Text::BibTeX::Name
• bt_format_names

👑 AUTHOR 👑

Greg Ward <gward@python.net>

💜 COPYRIGHT 💜

Copyright (c) 1997-2000 by Gregory P. Ward. All rights reserved. This file is part of the Text::BibTeX library. This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself. 🫶

💖 That's the whole page, bestie! It's from perl v5.42.0, dated 2025-01-31, and the page label is Text::...Format(3pm). Now go format those names and slay! 💅✨