NAME¶
Text::BibTeX::NameFormat - format BibTeX-style author names
SYNOPSIS¶
$format = new 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
$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.
Note that "Text::BibTeX::NameFormat" is a fairly direct translation of
the name-formatting C interface in the
btparse library. This manual
page is meant to provide enough information to use the Perl class, but for
more details and examples, consult bt_format_names.
CONSTANTS¶
Two enumerated types for dealing with names and name formatting have been
brought from C into Perl. In the
btparse documentation, you'll see
references to "bt_namepart" and "bt_joinmethod". The
former 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". The latter
lists the ways in which "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. 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. 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)
- 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 bt_format_names 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 = new Text::BibTeX::Name $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 = new Text::BibTeX::NameFormat ('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.