Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Text::BibTeX::NameFormUser)Contributed Perl DocumenText::BibTeX::NameFormat(3)

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.

       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 (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 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	= 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 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.

perl v5.24.1			  2017-07-02	   Text::BibTeX::NameFormat(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTANTS | METHODS | EXAMPLES | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Text::BibTeX::NameFormat&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help