NAME¶
Text::BibTeX::Structure - provides base classes for user structure modules
SYNOPSIS¶
# Define a 'Foo' structure for BibTeX databases: first, the
# structure class:
package Text::BibTeX::FooStructure;
@ISA = ('Text::BibTeX::Structure');
sub known_option
{
my ($self, $option) = @_;
...
}
sub default_option
{
my ($self, $option) = @_;
...
}
sub describe_entry
{
my $self = shift;
$self->set_fields ($type,
\@required_fields,
\@optional_fields,
[$constraint_1, $constraint_2, ...]);
...
}
# Now, the structured entry class
package Text::BibTeX::FooEntry;
@ISA = ('Text::BibTeX::StructuredEntry');
# define whatever methods you like
DESCRIPTION¶
The module "Text::BibTeX::Structure" provides two classes that form
the basis of the
btOOL "structure module" system. This system
is how database structures are defined and imposed on BibTeX files, and
provides an elegant synthesis of object-oriented techniques with BibTeX-style
database structures. Nothing described here is particularly deep or subtle;
anyone familiar with object-oriented programming should be able to follow it.
However, a fair bit of jargon in invented and tossed around, so pay attention.
A
database structure, in
btOOL parlance, is just a set of allowed
entry types and the rules for fields in each of those entry types. Currently,
there are three kinds of rules that apply to fields: some fields are
required, meaning they must be present in every entry for a given type;
some are
optional, meaning they may be present, and will be used if
they are; other fields are members of
constraint sets, which are
explained in "Field lists and constraint sets" below.
A
btOOL structure is implemented with two classes: the
structure
class and the
structured entry class. The former defines
everything that applies to the structure as a whole (allowed types and field
rules). The latter provides methods that operate on individual entries which
conform (or are supposed to conform) to the structure. The two classes
provided by the "Text::BibTeX::Structure" module are
"Text::BibTeX::Structure" and
"Text::BibTeX::StructuredEntry"; these serve as base classes for,
respectively, all structure classes and all structured entry classes. One
canonical structure is provided as an example with
btOOL: the
"Bib" structure, which (via the "BibStructure" and
"BibEntry" classes) provides the same functionality as the standard
style files of BibTeX 0.99. It is hoped that other programmers will write new
bibliography-related structures, possibly deriving from the "Bib"
structure, to emulate some of the functionality that is available through
third-party BibTeX style files.
The purpose of this manual page is to describe the whole "structure
module" system. It is mainly for programmers wishing to implement a new
database structure for data files with BibTeX syntax; if you are interested in
the particular rules for the BibTeX-emulating "Bib" structure, see
Text::BibTeX::Bib.
Please note that the "Text::BibTeX" prefix is dropped from most module
and class names in this manual page, except where necessary.
STRUCTURE CLASSES¶
Structure classes have two roles: to define the list of allowed types and field
rules, and to handle
structure options.
Field lists and constraint sets¶
Field lists and constraint sets define the database structure for a particular
entry type: that is, they specify the rules which an entry must follow to
conform to the structure (assuming that entry is of an allowed type). There
are three components to the field rules for each entry type: a list of
required fields, a list of optional fields, and
field constraints.
Required and optional fields should be obvious to anyone with BibTeX
experience: all required fields must be present, and any optional fields that
are present have some meaning to the structure. (One could conceive of a
"strict" interpretation, where any field not mentioned in the
official definition is disallowed; this would be contrary to the open spirit
of BibTeX databases, but could be useful in certain applications where a
stricter level of control is desired. Currently,
btOOL does not offer
such an option.)
Field constraints capture the "one or the other, but not both" type of
relationships present for some entry types in the BibTeX standard style files.
Most BibTeX documentation glosses over the distinction between mutually
constrained fields and required/optional fields. For instance, one of the
standard entry types is "book", and ""author" or
"editor"" is given in the list of required fields for that
type. The meaning of this is that an entry of type "book" must have
either the "author" or "editor" fields, but not
both. Likewise, the ""volume" or "number"" are
listed under the "optional fields" heading for "book"
entries; it would be more accurate to say that every "book" entry
may have one or the other, or neither, of "volume" or
"number"---but not both.
btOOL attempts to clarify this situation by creating a third category of
fields, those that are mutually constrained. For instance, neither
"author" nor "editor" appears in the list of required
fields for the "inbook" type according to
btOOL; rather, a
field constraint is created to express this relationship:
[1, 1, ['author', 'editor']]
That is, a field constraint is a reference to a three-element list. The last
element is a reference to the
constraint set, the list of fields to
which the constraint applies. (Calling this a set is a bit inaccurate, as
there are conditions in which the order of fields matters---see the
"check_field_constraints" method in "METHODS 2: BASE STRUCTURED
ENTRY CLASS".) The first two elements are the minimum and maximum number
of fields from the constraint set that must be present for an entry to conform
to the constraint. This constraint thus expresses that there must be exactly
one (>= 1 and <= 1) of the fields "author" and
"editor" in a "book" entry.
The "either one or neither, but not both" constraint that applies to
the "volume" and "number" fields for "book"
entries is expressed slightly differently:
[0, 1, ['volume', 'number']]
That is, either 0 or 1, but not the full 2, of "volume" and
"number" may be present.
It is important to note that checking and enforcing field constraints is based
purely on counting which fields from a set are actually present; this
mechanism can't capture "x must be present if y is" relationships.
The requirements imposed on the actual structure class are simple: it must
provide a method "describe_entry" which sets up a fancy data
structure describing the allowed entry types and all the field rules for those
types. The "Structure" class provides methods (inherited by a
particular structure class) to help particular structure classes create this
data structure in a consistent, controlled way. For instance, the
"describe_structure" method in the BibTeX 0.99-emulating
"BibStructure" class is quite simple:
sub describe_entry
{
my $self = shift;
# series of 13 calls to $self->set_fields (one for each standard
# entry type)
}
One of those calls to the "set_fields" method defines the rules for
"book" entries:
$self->set_fields ('book',
[qw(title publisher year)],
[qw(series address edition month note)],
[1, 1, [qw(author editor)]],
[0, 1, [qw(volume number)]]);
The first field list is the list of required fields, and the second is the list
of optional fields. Any number of field constraints may follow the list of
optional fields; in this case, there are two, one for each of the constraints
("author"/"editor" and
"volume"/"number") described above. At no point is a list
of allowed types explicitly supplied; rather, each call to
"set_fields" adds one more allowed type.
New structure modules that derive from existing ones will probably use the
"add_fields" method (and possibly "add_constraints") to
augment an existing entry type. Adding new types should be done with
"set_fields", though.
Structure options¶
The other responsibility of structure classes is to handle
structure
options. These are scalar values that let the user customize the
behaviour of both the structure class and the structured entry class. For
instance, one could have an option to enable "extended structure",
which might add on a bunch of new entry types and new fields. (In this case,
the "describe_entry" method would have to pay attention to this
option and modify its behaviour accordingly.) Or, one could have options to
control how the structured entry class sorts or formats entries (for
bibliography structures such as "Bib").
The easy way to handle structure options is to provide two methods,
"known_option" and "default_option". These return,
respectively, whether a given option is supported, and what its default value
is. (If your structure doesn't support any options, you can just inherit these
methods from the "Structure" class. The default
"known_option" returns false for all options, and its companion
"default_option" crashes with an "unknown option" error.)
Once "known_option" and "default_option" are provided, the
structure class can sit back and inherit the more visible
"set_options" and "get_options" methods from the
"Structure" class. These are the methods actually used to
modify/query options, and will be used by application programs to customize
the structure module's behaviour, and by the structure module itself to pay
attention to the user's wishes.
Options should generally have pure string values, so that the generic
set_options method doesn't have to parse user-supplied strings into some
complicated structure. However, "set_options" will take any scalar
value, so if the structure module clearly documents its requirements, the
application program could supply a structure that meets its needs. Keep in
mind that this requires cooperation between the application and the structure
module; the intermediary code in "Text::BibTeX::Structure" knows
nothing about the format or syntax of your structure's options, and whatever
scalar the application passes via "set_options" will be stored for
your module to retrieve via "get_options".
As an example, the "Bib" structure supports a number of
"markup" options that allow applications to control the markup
language used for formatting bibliographic entries. These options are
naturally paired, as formatting commands in markup languages generally have to
be turned on and off. The "Bib" structure thus expects references to
two-element lists for markup options; to specify LaTeX 2e-style emphasis for
book titles, an application such as "btformat" would set the
"btitle_mkup" option as follows:
$structure->set_options (btitle_mkup => ['\emph{', '}']);
Other options for other structures might have a more complicated structure, but
it's up to the structure class to document and enforce this.
STRUCTURED ENTRY CLASSES¶
A
structured entry class defines the behaviour of individual entries
under the regime of a particular database structure. This is the
raison
d'etre for any database structure: the structure class merely lays out the
rules for entries to conform to the structure, but the structured entry class
provides the methods that actually operate on individual entries. Because this
is completely open-ended, the requirements of a structured entry class are
much less rigid than for a structure class. In fact, all of the requirements
of a structured entry class can be met simply by inheriting from
"Text::BibTeX::StructuredEntry", the other class provided by the
"Text::BibTeX::Structure" module. (For the record, those
requirements are: a structured entry class must provide the entry
parse/query/manipulate methods of the "Entry" class, and it must
provide the "check", "coerce", and
"silently_coerce" methods of the "StructuredEntry" class.
Since "StructuredEntry" inherits from "Entry", both of
these requirements are met "for free" by structured entry classes
that inherit from "Text::BibTeX::StructuredEntry", so naturally this
is the recommended course of action!)
There are deliberately no other methods required of structured entry classes. A
particular application (eg. "btformat" for bibliography structures)
will require certain methods, but it's up to the application and the structure
module to work out the requirements through documentation.
CLASS INTERACTIONS¶
Imposing a database structure on your entries sets off a chain reaction of
interactions between various classes in the "Text::BibTeX" library
that should be transparent when all goes well. It could prove confusing if
things go wrong and you have to go wading through several levels of
application program, core "Text::BibTeX" classes, and some structure
module.
The justification for this complicated behaviour is that it allows you to write
programs that will use a particular structured module without knowing the name
of the structure when you write the program. Thus, the user can supply a
database structure, and ultimately the entry objects you manipulate will be
blessed into a class supplied by the structure module. A short example will
illustrate this.
Typically, a "Text::BibTeX"-based program is based around a kernel of
code like this:
$bibfile = new Text::BibTeX::File "foo.bib";
while ($entry = new Text::BibTeX::Entry $bibfile)
{
# process $entry
}
In this case, nothing fancy is happening behind the scenes: the $bibfile object
is blessed into the "Text::BibTeX::File" class, and $entry is
blessed into "Text::BibTeX::Entry". This is the conventional
behaviour of Perl classes, but it is not the only possible behaviour. Let us
now suppose that $bibfile is expected to conform to a database structure
specified by $structure (presumably a user-supplied value, and thus unknown at
compile-time):
$bibfile = new Text::BibTeX::File "foo.bib";
$bibfile->set_structure ($structure);
while ($entry = new Text::BibTeX::Entry $bibfile)
{
# process $entry
}
A lot happens behind the scenes with the call to $bibfile's
"set_structure" method. First, a new structure object is created
from $structure. The structure name implies the name of a Perl module---the
structure module---which is "require"'d by the "Structure"
constructor. (The main consequence of this is that any compile-time errors in
your structure module will not be revealed until a
"Text::BibTeX::File::set_structure" or
"Text::BibTeX::Structure::new" call attempts to load it.)
Recall that the first responsibility of a structure module is to define a
structure class. The "structure object" created by the
"set_structure" method call is actually an object of this class;
this is the first bit of trickery---the structure object (buried behind the
scenes) is blessed into a class whose name is not known until run-time.
Now, the behaviour of the "Text::BibTeX::Entry::new" constructor
changes subtly: rather than returning an object blessed into the
"Text::BibTeX::Entry" class as you might expect from the code, the
object is blessed into the structured entry class associated with $structure.
For example, if the value of $structure is "Foo", that means the user
has supplied a module implementing the "Foo" structure. (Ordinarily,
this module would be called "Text::BibTeX::Foo"---but you can
customize this.) Calling the "set_structure" method on $bibfile will
attempt to create a new structure object via the
"Text::BibTeX::Structure" constructor, which loads the structure
module "Text::BibTeX::Foo". Once this module is successfully loaded,
the new object is blessed into its structure class, which will presumably be
called "Text::BibTeX::FooStructure" (again, this is customizable).
The new object is supplied with the user's structure options via the
"set_options" method (usually inherited), and then it is asked to
describe the actual entry layout by calling its "describe_entry"
method. This, in turn, will usually call the inherited "set_fields"
method for each entry type in the database structure. When the
"Structure" constructor is finished, the new structure object is
stored in the "File" object (remember, we started all this by
calling "set_structure" on a "File" object) for future
reference.
Then, when a new "Entry" object is created and parsed from that
particular "File" object, some more trickery happens. Trivially, the
structure object stored in the "File" object is also stored in the
"Entry" object. (The idea is that entries could belong to a database
structure independently of any file, but usually they will just get the
structure that was assigned to their database file.) More importantly, the new
"Entry" object is re-blessed into the structured entry class
supplied by the structure module---presumably, in this case,
"Text::BibTeX::FooEntry" (also customizable).
Once all this sleight-of-hand is accomplished, the application may treat its
entry objects as objects of the structured entry class for the "Foo"
structure---they may call the check/coerce methods inherited from
"Text::BibTeX::StructuredEntry", and they may also call any methods
specific to entries for this particular database structure. What these methods
might be is up to the structure implementor to decide and document; thus,
applications may be specific to one particular database structure, or they may
work on all structures that supply certain methods. The choice is up to the
application developer, and the range of options open to him depends on which
methods structure implementors provide.
EXAMPLE¶
For example code, please refer to the source of the "Bib" module and
the "btcheck", "btsort", and "btformat"
applications supplied with "Text::BibTeX".
METHODS 1: BASE STRUCTURE CLASS¶
The first class provided by the "Text::BibTeX::Structure" module is
"Text::BibTeX::Structure". This class is intended to provide methods
that will be inherited by user-supplied structure classes; such classes should
not override any of the methods described here (except
"known_option" and "default_option") without very good
reason. Furthermore, overriding the "new" method would be useless,
because in general applications won't know the name of your structure
class---they can only call "Text::BibTeX::Structure::new" (usually
via "Text::BibTeX::File::set_structure").
Finally, there are three methods that structure classes should implement:
"known_option", "default_option", and
"describe_entry". The first two are described in "Structure
options" above, the latter in "Field lists and constraint
sets". Note that "describe_entry" depends heavily on the
"set_fields", "add_fields", and
"add_constraints" methods described here.
Constructor/simple query methods¶
- new (STRUCTURE, [OPTION => VALUE, ...])
- Constructs a new structure object---not a
"Text::BibTeX::Structure" object, but rather an object blessed
into the structure class associated with STRUCTURE. More precisely:
- •
- Loads (with "require") the module implementing
STRUCTURE. In the absence of other information, the module name is derived
by appending STRUCTURE to "Text::BibTeX::"---thus, the module
"Text::BibTeX::Bib" implements the "Bib" structure.
Use the pseudo-option "module" to override this module name. For
instance, if the structure "Foo" is implemented by the module
"Foo":
$structure = new Text::BibTeX::Structure
('Foo', module => 'Foo');
This method "die"s if there are any errors loading/compiling the
structure module.
- •
- Verifies that the structure module provides a structure
class and a structured entry class. The structure class is named by
appending "Structure" to the name of the module, and the
structured entry class by appending "Entry". Thus, in the
absence of a "module" option, these two classes (for the
"Bib" structure) would be named
"Text::BibTeX::BibStructure" and
"Text::BibTeX::BibEntry". Either or both of the default class
names may be overridden by having the structure module return a reference
to a hash (as opposed to the traditional 1 returned by modules). This hash
could then supply a "structure_class" element to name the
structure class, and an "entry_class" element to name the
structured entry class.
Apart from ensuring that the two classes actually exist, "new"
verifies that they inherit correctly (from
"Text::BibTeX::Structure" and
"Text::BibTeX::StructuredEntry" respectively), and that the
structure class provides the required "known_option",
"default_option", and "describe_entry" methods.
- •
- Creates the new structure object, and blesses it into the
structure class. Supplies it with options by passing all (OPTION, VALUE)
pairs to its "set_options" method. Calls its
"describe_entry" method, which should list the field
requirements for all entry types recognized by this structure.
"describe_entry" will most likely use some or all of the
"set_fields", "add_fields", and
"add_constraints" methods---described below---for this.
- name ()
- Returns the name of the structure described by the
object.
- entry_class ()
- Returns the name of the structured entry class associated
with this structure.
Field structure description methods¶
- add_constraints (TYPE, CONSTRAINT, ...)
- Adds one or more field constraints to the structure. A
field constraint is specified as a reference to a three-element list; the
last element is a reference to the list of fields affected, and the first
two elements are the minimum and maximum number of fields from the
constraint set allowed in an entry of type TYPE. See "Field lists and
constraint sets" for a full explanation of field constraints.
- add_fields (TYPE, REQUIRED [, OPTIONAL [, CONSTRAINT,
...]])
- Adds fields to the required/optional lists for entries of
type TYPE. Can also add field constraints, but you can just as easily use
"add_constraints" for that.
REQUIRED and OPTIONAL, if defined, should be references to lists of fields
to add to the respective field lists. The CONSTRAINTs, if given, are
exactly as described for "add_constraints" above.
- set_fields (TYPE, REQUIRED [, OPTIONAL [, CONSTRAINTS,
...]])
- Sets the lists of required/optional fields for entries of
type TYPE. Identical to "add_fields", except that the field
lists and list of constraints are set from scratch here, rather than being
added to.
Field structure query methods¶
- types ()
- Returns the list of entry types supported by the
structure.
- known_type (TYPE)
- Returns true if TYPE is a supported entry type.
- known_field (TYPE, FIELD)
- Returns true if FIELD is in the required list, optional
list, or one of the constraint sets for entries of type TYPE.
- required_fields (TYPE)
- Returns the list of required fields for entries of type
TYPE.
- optional_fields ()
- Returns the list of optional fields for entries of type
TYPE.
- field_constraints ()
- Returns the list of field constraints (in the format
supplied to "add_constraints") for entries of type TYPE.
Option methods¶
- known_option (OPTION)
- Returns false. This is mainly for the use of derived
structures that don't have any options, and thus don't need to provide
their own "known_option" method. Structures that actually offer
options should override this method; it should return true if OPTION is a
supported option.
- default_option (OPTION)
- Crashes with an "unknown option" message. Again,
this is mainly for use by derived structure classes that don't actually
offer any options. Structures that handle options should override this
method; every option handled by "known_option" should have a
default value (which might just be "undef") that is returned by
"default_option". Your "default_options" method should
crash on an unknown option, perhaps by calling
"SUPER::default_option" (in order to ensure consistent error
messages). For example:
sub default_option
{
my ($self, $option) = @_;
return $default_options{$option}
if exists $default_options{$option};
$self->SUPER::default_option ($option); # crash
}
The default value for an option is returned by "get_options" when
that options has not been explicitly set with
"set_options".
- set_options (OPTION => VALUE, ...)
- Sets one or more option values. (You can supply as many
"OPTION => VALUE" pairs as you like, just so long as there
are an even number of arguments.) Each OPTION must be handled by the
structure module (as indicated by the "known_option" method); if
not "set_options" will "croak". Each VALUE may be any
scalar value; it's up to the structure module to validate them.
- get_options (OPTION, ...)
- Returns the value(s) of one or more options. Any OPTION
that has not been set by "set_options" will return its default
value, fetched using the "default_value" method. If OPTION is
not supported by the structure module, then your program either already
crashed (when it tried to set it with "set_option"), or it will
crash here (thanks to calling "default_option").
METHODS 2: BASE STRUCTURED ENTRY CLASS¶
The other class provided by the "Structure" module is
"StructuredEntry", the base class for all structured entry classes.
This class inherits from "Entry", so all of its entry
query/manipulation methods are available. "StructuredEntry" adds
methods for checking that an entry conforms to the database structure defined
by a structure class.
It only makes sense for "StructuredEntry" to be used as a base class;
you would never create standalone "StructuredEntry" objects. The
superficial reason for this is that only particular structured-entry classes
have an actual structure class associated with them,
"StructuredEntry" on its own doesn't have any information about
allowed types, required fields, field constraints, and so on. For a deeper
understanding, consult "CLASS INTERACTIONS" above.
Since "StructuredEntry" derives from "Entry", it naturally
operates on BibTeX entries. Hence, the following descriptions refer to
"the entry"---this is just the object (entry) being operated on.
Note that these methods are presented in bottom-up order, meaning that the
methods you're most likely to actually use---"check",
"coerce", and "silently_coerce" are at the bottom. On a
first reading, you'll probably want to skip down to them for a quick summary.
- structure ()
- Returns the object that defines the structure the entry to
which is supposed to conform. This will be an instantiation of some
structure class, and exists mainly so the check/coerce methods can query
the structure about the types and fields it recognizes. If, for some
reason, you wanted to query an entry's structure about the validity of
type "foo", you might do this:
# assume $entry is an object of some structured entry class, i.e.
# it inherits from Text::BibTeX::StructuredEntry
$structure = $entry->structure;
$foo_known = $structure->known_type ('foo');
- check_type ([WARN])
- Returns true if the entry has a valid type according to its
structure. If WARN is true, then an invalid type results in a warning
being printed.
- check_required_fields ([WARN [, COERCE]])
- Checks that all required fields are present in the entry.
If WARN is true, then a warning is printed for every missing field. If
COERCE is true, then missing fields are set to the empty string.
This isn't generally used by other code; see the "check" and
"coerce" methods below.
- check_field_constraints ([WARN [, COERCE]])
- Checks that the entry conforms to all of the field
constraints imposed by its structure. Recall that a field constraint
consists of a list of fields, and a minimum and maximum number of those
fields that must be present in an entry. For each constraint,
"check_field_constraints" simply counts how many fields in the
constraint's field set are present. If this count falls below the minimum
or above the maximum for that constraint and WARN is true, a warning is
issued. In general, this warning is of the form "between x and y of
fields foo, bar, and baz must be present". The more common cases are
handled specially to generate more useful and human-friendly warning
messages.
If COERCE is true, then the entry is modified to force it into conformance
with all field constraints. How this is done depends on whether the
violation is a matter of not enough fields present in the entry, or of too
many fields present. In the former case, just enough fields are added (as
empty strings) to meet the requirements of the constraint; in the latter
case, fields are deleted. Which fields to add or delete is controlled by
the order of fields in the constraint's field list.
An example should clarify this. For instance, a field constraint specifying
that exactly one of "author" or "editor" must appear
in an entry would look like this:
[1, 1, ['author', 'editor']]
Suppose the following entry is parsed and expected to conform to this
structure:
@inbook{unknown:1997a,
title = "An Unattributed Book Chapter",
booktitle = "An Unedited Book",
publisher = "Foo, Bar \& Company",
year = 1997
}
If "check_field_constraints" is called on this method with COERCE
true (which is done by any of the "full_check",
"coerce", and "silently_coerce" methods), then the
"author" field is set to the empty string. (We go through the
list of fields in the constraint's field set in order -- since
"author" is the first missing field, we supply it; with that
done, the entry now conforms to the "author"/"editor"
constraint, so we're done.)
However, if the same structure was applied to this entry:
@inbook{smith:1997a,
author = "John Smith",
editor = "Fred Jones",
...
}
then the "editor" field would be deleted. In this case, we allow
the first field in the constraint's field list---"author". Since
only one field from the set may be present, all fields after the first one
are in violation, so they are deleted.
Again, this method isn't generally used by other code; rather, it is called
by "full_check" and its friends below.
- full_check ([WARN [, COERCE]])
- Returns true if an entry's type and fields are all valid.
That is, it calls "check_type",
"check_required_fields", and
"check_field_constraints"; if all of them return true, then so
does "full_check". WARN and COERCE are simply passed on to the
three "check_*" methods: the first controls the printing of
warnings, and the second decides whether we should modify the entry to
force it into conformance.
- check ()
- Checks that the entry conforms to the requirements of its
associated database structure: the type must be known, all required fields
must be present, and all field constraints must be met. See
"check_type", "check_required_fields", and
"check_field_constraints" for details.
Calling "check" is the same as calling "full_check" with
WARN true and COERCE false.
- coerce ()
- Same as "check", except entries are coerced into
conformance with the database structure---that is, it's just like
"full_check" with both WARN and COERCE true.
- silently_coerce ()
- Same as "coerce", except warnings aren't
printed---that is, it's just like "full_check" with WARN false
and COERCE true.
SEE ALSO¶
Text::BibTeX, Text::BibTeX::Entry, Text::BibTeX::File
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.