view release on metacpan or  search on metacpan

BibTeX/NameFormat.pm  view on Meta::CPAN

#              This file is part of the LaTeX::BibTeX library.  This
#              library is free software; you may redistribute it and/or
#              modify it under the same terms as Perl itself.
# ----------------------------------------------------------------------

package LaTeX::BibTeX::NameFormat;

require 5.004;

use strict;
use Carp;

=head1 NAME

LaTeX::BibTeX::NameFormat - format BibTeX-style author names

=head1 SYNOPSIS

   $format = new LaTeX::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);

=head1 DESCRIPTION

After splitting a name into its components parts (represented as a
C<LaTeX::BibTeX::Name> object), you often want to put it back together
again as a single string formatted in a consistent way.
C<LaTeX::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 C<LaTeX::BibTeX::NameFormat>
object.  The constructor (C<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 C<set_text()> and C<set_options()>
methods provide that capability.

Note that C<LaTeX::BibTeX::NameFormat> is a fairly direct translation of
the name-formatting C interface in the B<btparse> library.  This manual
page is meant to provide enough information to use the Perl class, but
for more details and examples, consult L<bt_format_names>.

=head1 CONSTANTS

Two enumerated types for dealing with names and name formatting have
been brought from C into Perl.  In the B<btparse> documentation, you'll
see references to C<bt_namepart> and C<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 C<BTN_FIRST>, C<BTN_VON>, C<BTN_LAST>, and
C<BTN_JR>.  The latter lists the ways in which C<bt_format_name()> (the
C function that corresponds to C<LaTeX::BibTeX::NameFormat>'s C<apply>
method) can join adjacent tokens together: C<BTJ_MAYTIE>, C<BTJ_SPACE>,
C<BTJ_FORCETIE>, and C<BTJ_NOTHING>.  Both sets of values may be
imported from the C<LaTeX::BibTeX> module, using the import tags
C<nameparts> and C<joinmethods>.  For instance:

   use LaTeX::BibTeX qw(:nameparts :joinmethods);
   use LaTeX::BibTeX::Name;
   use LaTeX::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 (C<"JR Smith">, or C<"J R Smith">,
or C<"J~R Smith">, and you can control how the final token of one part
is joined to the next part (C<"la Roche"> versus C<"la~Roche">).

=head1 METHODS

=over 4

=item 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, C<"fvlj"> means to format names in "first von last jr"
order, while C<"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 C<set_text> and C<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 C<bt_create_name_format()> in
L<bt_format_names> for full details of the choices made.

=cut

sub new
{
   my ($class, $parts, $abbrev_first) = @_;

   $class = ref ($class) || $class;
   my $self = bless {}, $class;
   $self->{_cstruct} = create ($parts, $abbrev_first);
   $self;
}


sub DESTROY
{
   my $self = shift;
   free ($self->{'_cstruct'}) 
      if defined $self->{'_cstruct'};
}


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