1Text::BibTeX::NameFormaUts(e3r)Contributed Perl DocumentTaetxito:n:BibTeX::NameFormat(3)
2
3
4

NAME

6       Text::BibTeX::NameFormat - format BibTeX-style author names
7

SYNOPSIS

9          use Text::BibTeX::NameFormat;
10
11          $format = Text::BibTeX::NameFormat->($parts, $abbrev_first);
12
13          $format->set_text ($part,
14                             $pre_part, $post_part,
15                             $pre_token, $post_token);
16
17          $format->set_options ($part, $abbrev, $join_tokens, $join_part
18
19          ## Uses the encoding/binmode and normalization form stored in $name
20          $formatted_name = $format->apply ($name);
21

DESCRIPTION

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
31       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
38       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

CONSTANTS

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
56          use Text::BibTeX qw(:nameparts :joinmethods);
57          use Text::BibTeX::Name;
58          use Text::BibTeX::NameFormat;
59
60       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

METHODS

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
88       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
96              $format->set_text ('first', undef, undef, undef, '');
97
98           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
103           See bt_format_names for full information on formatting names.
104
105       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
111           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
117              $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
122           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
126       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

EXAMPLES

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
142       The first step is covered in Text::BibTeX::Name; here's a brief
143       example:
144
145          $orig_name = 'Charles Louis Xavier Joseph de la Vall{\'e}e Poussin';
146          $name = Text::BibTeX::Name->new($orig_name);
147
148       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
152       Creating the name format is equally simple:
153
154          $format = Text::BibTeX::NameFormat->new('vljf', 1);
155
156       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
161       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
167          $formatted_name = $format->apply ($name);
168
169       while the second uses "Text::BibTeX::Name"'s "format" method:
170
171          $formatted_name = $name->format ($format);
172
173       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
176          de~la Vall{\'e}e~Poussin, C.~L. X.~J.
177
178       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

SEE ALSO

183       Text::BibTeX::Entry, Text::BibTeX::Name, bt_format_names.
184

AUTHOR

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.
193
194
195
196perl v5.32.0                      2020-07-28       Text::BibTeX::NameFormat(3)
Impressum