1Text::BibTeX::NameFormaUts(e3r)Contributed Perl DocumentTaetxito:n:BibTeX::NameFormat(3)
2
6 Text::BibTeX::NameFormat - format BibTeX-style author names
7
9 use Text::BibTeX::NameFormat;
10 $format = Text::BibTeX::NameFormat->($parts, $abbrev_first);
12 $format->set_text ($part,
14 $pre_part, $post_part,
15 $pre_token, $post_token);
16 $format->set_options ($part, $abbrev, $join_tokens, $join_part
18 ## Uses the encoding/binmode and normalization form stored in $name
20 $formatted_name = $format->apply ($name);
21
23 After splitting a name into its components parts (represented as a
24 "Text::BibTeX::Name" object), you often want to put it back together
25 again as a single string formatted in a consistent way.
26 "Text::BibTeX::NameFormat" provides a very flexible way to do this,
27 generally in two stages: first, you create a "name format" which
28 describes how to put the tokens and parts of any name back together,
29 and then you apply the format to a particular name.
30 The "name format" is encapsulated in a "Text::BibTeX::NameFormat"
32 object. The constructor ("new") includes some clever behind-the-scenes
33 trickery that means you can usually get away with calling it alone, and
34 not need to do any customization of the format object. If you do need
35 to customize the format, though, the "set_text()" and "set_options()"
36 methods provide that capability.
37 Note that "Text::BibTeX::NameFormat" is a fairly direct translation of
39 the name-formatting C interface in the btparse library. This manual
40 page is meant to provide enough information to use the Perl class, but
41 for more details and examples, consult bt_format_names.
42
44 Two enumerated types for dealing with names and name formatting have
45 been brought from C into Perl. In the btparse documentation, you'll
46 see references to "bt_namepart" and "bt_joinmethod". The former lists
47 the four "parts" of a BibTeX name: first, von, last, and jr; its values
48 (in both C and Perl) are "BTN_FIRST", "BTN_VON", "BTN_LAST", and
49 "BTN_JR". The latter lists the ways in which "bt_format_name()" (the C
50 function that corresponds to "Text::BibTeX::NameFormat"'s "apply"
51 method) can join adjacent tokens together: "BTJ_MAYTIE", "BTJ_SPACE",
52 "BTJ_FORCETIE", and "BTJ_NOTHING". Both sets of values may be imported
53 from the "Text::BibTeX" module, using the import tags "nameparts" and
54 "joinmethods". For instance:
55 use Text::BibTeX qw(:nameparts :joinmethods);
57 use Text::BibTeX::Name;
58 use Text::BibTeX::NameFormat;
59 The "name part" constants are used to specify surrounding text or
61 formatting options on a per-part basis: for instance, you can supply
62 the "pre-token" text, or the "abbreviate" flag, for a single part
63 without affecting other parts. The "join methods" are two of the three
64 formatting options that you can set for a part: you can control how to
65 join the individual tokens of a name ("JR Smith", or "J R Smith", or
66 "J~R Smith", and you can control how the final token of one part is
67 joined to the next part ("la Roche" versus "la~Roche").
68
70 new(PARTS, ABBREV_FIRST)
71 Creates a new name format, with the two most common customizations:
72 which parts to include (and in what order), and whether to
73 abbreviate the first name. PARTS should be a string with at most
74 four characters, one representing each part that you want to occur
75 in a formatted name (defaults to "fvlj"). For example, "fvlj"
76 means to format names in "first von last jr" order, while "vljf"
77 denotes "von last jr first." ABBREV_FIRST is just a boolean value:
78 false to print out the first name in full, and true to abbreviate
79 it with periods after each token and discretionary ties between
80 tokens (defaults to false). All intra- and inter-token punctuation
81 and spacing is independently controllable with the "set_text" and
82 "set_options" methods, although these will rarely be
83 necessary---sensible defaults are chosen for everything, based on
84 the PARTS and ABBREV_FIRST values that you supply. See the
85 description of "bt_create_name_format()" in bt_format_names for
86 full details of the choices made.
87 set_text (PART, PRE_PART, POST_PART, PRE_TOKEN, POST_TOKEN)
89 Allows you to customize some or all of the surrounding text for a
90 single name part. Every name part has four possible chunks of text
91 that go around or within it: before/after the part as a whole, and
92 before/after each token in the part. For instance, if you are
93 abbreviating first names and wish to control the punctuation after
94 each token in the first name, you would set the "post token" text:
95 $format->set_text ('first', undef, undef, undef, '');
97 would set the post-token text to the empty string, resulting in
99 names like "J R Smith". (Normally, abbreviated first names will
100 have a period after each token: "J. R. Smith".) Note that
101 supplying "undef" for the other three values leaves them unchanged.
102 See bt_format_names for full information on formatting names.
104 set_options (PART, ABBREV, JOIN_TOKENS, JOIN_PART)
106 Allows further customization of a name format: you can set the
107 abbreviation flag and the two token-join methods. Alas, there is
108 no mechanism for leaving a value unchanged; you must set everything
109 with "set_options".
110 For example, let's say that just dropping periods from abbreviated
112 tokens in the first name isn't enough; you really want to save
113 space by jamming the abbreviated tokens together: "JR Smith" rather
114 than "J R Smith" Assuming the two calls in the above example have
115 been done, the following will finish the job:
116 $format->set_options (BTN_FIRST,
118 1, # keep same value for abbrev flag
119 BTJ_NOTHING, # jam tokens together
120 BTJ_SPACE); # space after final token of part
121 Note that we unfortunately had to know (and supply) the current
123 values for the abbreviation flag and post-part join method, even
124 though we were only setting the intra-part join method.
125 apply (NAME)
127 Once a name format has been created and customized to your heart's
128 content, you can use it to format any number of names using the
129 "apply" method. NAME must be a "Text::BibTeX::Name" object (i.e.,
130 a pre-split name); "apply" returns a string containing the parts of
131 the name formatted according to the "Text::BibTeX::NameFormat"
132 structure it is called on.
133
135 Although the process of splitting and formatting names may sound
136 complicated and convoluted from reading the above (along with
137 Text::BibTeX::Name), it's actually quite simple. There are really only
138 three steps to worry about: split the name (create a
139 "Text::BibTeX::Name" object), create and customize the format
140 ("Text::BibTeX::NameFormat" object), and apply the format to the name.
141 The first step is covered in Text::BibTeX::Name; here's a brief
143 example:
144 $orig_name = 'Charles Louis Xavier Joseph de la Vall{\'e}e Poussin';
146 $name = Text::BibTeX::Name->new($orig_name);
147 The various parts of the name can now be accessed through
149 "Text::BibTeX::Name" methods; for instance "$name->part('von')" returns
150 the list "("de","la")".
151 Creating the name format is equally simple:
153 $format = Text::BibTeX::NameFormat->new('vljf', 1);
155 creates a format that will print the name in "von last jr first" order,
157 with the first name abbreviated. And for no extra charge, you get the
158 right punctuation at the right place: a comma before any `jr' or
159 `first' tokens, and periods after each `first' token.
160 For instance, we can perform no further customization on this format,
162 and apply it immediately to $name. There are in fact two ways to do
163 this, depending on whether you prefer to think of it in terms of
164 "Applying the format to a name" or "formatting a name". The first is
165 done with "Text::BibTeX::NameFormat"'s "apply" method:
166 $formatted_name = $format->apply ($name);
168 while the second uses "Text::BibTeX::Name"'s "format" method:
170 $formatted_name = $name->format ($format);
172 which is just a wrapper around "Text::BibTeX::NameFormat::apply". In
174 either case, the result with the example name and format shown is
175 de~la Vall{\'e}e~Poussin, C.~L. X.~J.
177 Note the strategic insertion of TeX "ties" (non-breakable spaces) at
179 sensitive spots in the name. (The exact rules for insertion of
180 discretionary ties are given in bt_format_names.)
181
183 Text::BibTeX::Entry, Text::BibTeX::Name, bt_format_names.
184
186 Greg Ward <gward@python.net>
187
189 Copyright (c) 1997-2000 by Gregory P. Ward. All rights reserved. This
190 file is part of the Text::BibTeX library. This library is free
191 software; you may redistribute it and/or modify it under the same terms
192 as Perl itself.
193perl v5.30.1 2020-01-30 Text::BibTeX::NameFormat(3)