/ 
Text-BibTeX-1.00
/ Text::BibTeX::NameFormat

NAME

Text::BibTeX::NameFormat - 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

After splitting a name into its components parts (represented as a Text::BibTeX::Name object), you often want to put it back together again as a single string formatted in a consistent way. Text::BibTeX::NameFormat provides a very flexible way to do this, generally in two stages: first, you create a "name format" which describes how to put the tokens and parts of any name back together, and then you apply the format to a particular name.

The "name format" is encapsulated in a Text::BibTeX::NameFormat object. The constructor (new) includes some clever behind-the-scenes trickery that means you can usually get away with calling it alone, and not need to do any customization of the format object. If you do need to customize the format, though, the set_text() and set_options() methods provide that capability.

CONSTANTS

Two sets of constants are used with name formats. The "name part" constants name the four "parts" of a BibTeX name: BTN_FIRST, BTN_VON, BTN_LAST, and BTN_JR. The "join method" constants are the ways in which adjacent tokens can be joined together: BTJ_MAYTIE, BTJ_SPACE, BTJ_FORCETIE, and BTJ_NOTHING (see "FORMATTING RULES"). 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").

FORMATTING RULES

A name format controls the following:

  • which name parts are printed, and in what order (e.g. "first von last jr", or "von last jr first")

  • the text that precedes and follows each part (e.g. if the first name follows the last name, you probably want a comma before the `first' part: "Smith, John" rather than "Smith John")

  • the text that precedes and follows each token (e.g. if the first name is abbreviated, you may want a period after each token: "J. R. Smith" rather than "J R Smith")

  • whether the tokens of each part are abbreviated

  • the method used to join the tokens of each part together

  • the method used to join each part to the following part

There are two join methods for each part: one between the tokens within the part, and one between the part and the next part. The first allows you, for example, to change "J R Smith" (first name abbreviated with no post-token text but tokens joined by a space) to "JR Smith" (the same, but first-name tokens jammed together). The second is mainly used to ensure that `von' and `last' parts may be joined with a tie: "de~Roche" rather than "de Roche".

The join methods are:

BTJ_MAYTIE

Insert a "discretionary tie" between tokens: either a space or a "tie" is inserted, depending on context. (A tie, otherwise known as an unbreakable space, is always "~", as in TeX.)

BTJ_SPACE

Always insert a space between tokens.

BTJ_FORCETIE

Always insert a tie ("~") between tokens.

BTJ_NOTHING

Insert nothing between tokens---just jam them together.

With BTJ_MAYTIE, the choice between a space and a tie follows BibTeX. Within a part, a tie is used after the first token if it is less than three characters long, and before the last token. Between parts, a tie is used only if the preceding part consists of a single token less than three characters long. In all other cases, a space is used.

Defaults

new sets up the whole format, based on the PARTS and ABBREV_FIRST arguments, so that customization is rarely needed:

  • The token join method is BTJ_MAYTIE for all parts.

  • The part join method is BTJ_SPACE for the `first', `last', and `jr' parts. If the `von' part immediately precedes the `last' part (which will almost always be the case), BTJ_MAYTIE is used to join `von' to `last'; otherwise `von' also gets BTJ_SPACE.

  • The `von', `last', and `jr' parts are not abbreviated; the `first' part is abbreviated if ABBREV_FIRST is true.

  • All the surrounding text starts out empty. If ABBREV_FIRST is true, the post-token text for the first name is ".", which changes "J R Smith" to "J. R. Smith".

    If `jr' immediately follows `last' (almost always the case), the pre-part text for `jr' is ", " and the part join method for `last' is BTJ_NOTHING, so you get "John Smith, Jr". Because the ", " is associated with the `jr' part, it is not printed when there is no `jr' part.

    Likewise, if `first' immediately follows `jr' or `last' (as in "last name first" formats), the pre-part text for `first' is ", " and the part join method of the preceding part is BTJ_NOTHING.

So if you only need "fvlj" and "vljf" part orders, only want to abbreviate the first name, and want periods after abbreviated tokens, ties in the "right" places and commas in the conventional places, you don't need to customize anything. For something out of the ordinary---for instance, abbreviated tokens jammed together with no punctuation, or abbreviated last names---use set_text and set_options.

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 "Defaults" for full details of the choices made.

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

Allows you to 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 are abbreviating first names and wish to control the punctuation after each token in the first name, you would set the "post token" text:

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

would set 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 "FORMATTING RULES" for full information on formatting names.

set_options (PART, ABBREV, JOIN_TOKENS, JOIN_PART)

Allows further customization of a name format: 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.

For example, let's say that just 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

Although the process of splitting and formatting names may sound complicated and convoluted from reading the above (along with Text::BibTeX::Name), it's actually quite simple. There are really only three steps to worry about: split the name (create a Text::BibTeX::Name object), create and customize the format (Text::BibTeX::NameFormat object), and 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 "FORMATTING RULES".)

SEE ALSO

Text::BibTeX::Entry, Text::BibTeX::Name.

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.