NAME¶
Text::BibTeX::Bib - defines the "Bib" database structure
SYNOPSIS¶
$bibfile = new Text::BibTeX::File $filename;
$bibfile->set_structure ('Bib',
# Default option values:
sortby => 'name',
namestyle => 'full'
nameorder => 'first',
atitle => 1,
labels => 'numeric');
# Alternate option values:
$bibfile->set_option (sortby => 'year');
$bibfile->set_option (namestyle => 'nopunct');
$bibfile->set_option (namestyle => 'nospace');
$bibfile->set_option (nameorder => 'last');
$bibfile->set_option (atitle => 0);
$bibfile->set_option (labels => 'alpha'); # not implemented yet!
# parse entry from $bibfile and automatically make it a BibEntry
$entry = new Text::BibTeX::Entry $bibfile;
# or get an entry from somewhere else which is hard-coded to be
# a BibEntry
$entry = new Text::BibTeX::BibEntry ...;
$sortkey = $entry->sort_key;
@blocks = $entry->format;
DESCRIPTION¶
(
NOTE! Do not believe everything you read in this document. The classes
described here are unfinished and only lightly tested. The current
implementation is a proof-of-principle, to convince myself (and anyone who
might be interested) that it really is possible to reimplement BibTeX 0.99 in
Perl using the core "Text::BibTeX" classes; this principle is
vaguely demonstrated by the current "Bib*" modules, but not really
proved. Many important features needed to reimplement the standard styles of
BibTeX 0.99 are missing, even though this document may brashly assert
otherwise. If you are interested in using these classes, you should start by
reading and grokking the code, and contributing the missing bits and pieces
that you need.)
"Text::BibTeX::Bib" implements the database structure for
bibliographies as defined by the standard styles of BibTeX 0.99. It does this
by providing two classes, "BibStructure" and "BibEntry"
(the leading "Text::BibTeX" is implied, and will be omitted for the
rest of this document). These two classes, being specific to bibliographic
data, are outside of the core "Text::BibTeX" class hierarchy, but
are distributed along with it as they provide a canonical example of a
specific database structure using classes derived from the core hierarchy.
"BibStructure", which derives from the "Structure" class,
deals with the structure as a whole: it handles structure options and
describes all the types and fields that make up the database structure. If
you're interested in writing your own database structure modules, the standard
interface for both of these is described in Text::BibTeX::Structure; if you're
just interested in finding out the exact database structure or the options
supported by the "Bib" structure, you've come to the right place.
(However, you may have to wade through a bit of excess verbiage due to this
module's dual purpose: first, to reimplement the standard styles of BibTeX
0.99, and second, to provide an example for other programmers wishing to
implement new or derived database structure modules.)
"BibEntry" derives from the "StructuredEntry" class and
provides methods that operate on individual entries presumed to come from a
database conforming to the structure defined by the "BibStructure"
class. (Actually, to be completely accurate, "BibEntry" inherits
from two intermediate classes, "BibSort" and "BibFormat".
These two classes just exist to reduce the amount of code in the
"Bib" module, and thanks to the magic of inheritance, their
existence is usually irrelevant. But you might want to consult those two
classes if you're interested in the gory details of sorting and formatting
entries from BibTeX 0.99-style bibliography databases.)
STRUCTURE OPTIONS¶
"BibStructure" handles several user-supplied "structure
options" and methods for dealing with them. The options currently
supported by the "Bib" database structure, and the values allowed
for them, are:
- "sortby"
- How to sort entries. Valid values: "name" (sort
on author names, year, and title), "year" (sort on year, author
names, and title). Sorting on "author names" is a bit more
complicated than just using the "author" field; see
Text::BibTeX::BibSort for details. Default value: "name".
- "namestyle"
- How to print author (and editor) names: "full"
for unabbreviated first names, "abbrev" for first names
abbreviated with periods, "nopunct" for first names abbreviated
with space but no periods, and "nospace" to abbreviate without
space or periods. Default value: "full".
- "nameorder"
- The order in which to print names: "first" for
"first von last jr" order, and "last" for "von
last jr first" order. Default value: "first".
- "atitle_lower"
- A boolean option: if true, non-book titles will be changed
to "sentence capitalization:" words following colons and
sentence-ending punctuation will be capitalized, and everything else at
brace-depth zero will be changed to lowercase. Default value: true.
- "labels"
- The type of bibliographic labels to generate:
"numeric" or "alpha". (Alphabetic labels are not yet
implemented, so this option is currently ignored.) Default value:
"numeric".
Also, several "markup options" are supported. Markup options are
distinct because they don't change how text is extracted from the database
entries and subsequently mangled; rather, they supply bits of markup that go
around the database-derived text. Markup options are always two-element lists:
the first to "turn on" some feature of the markup language, and the
second to turn it off. For example, if your target language is LaTeX2e and you
want journal names emphasized, you would supply a list reference
"['\emph{','}']" for the "journal_mkup" option. If you
were instead generating HTML, you might supply
"['<emph>','</emph>']". To keep the structure module
general with respect to markup languages, all markup options are empty by
default. (Or, rather, they are all references to lists consisting of two empty
strings.)
- "name_mkup"
- Markup to add around the list of author names.
- "atitle_mkup"
- Markup to add around non-book (article) titles.
- "btitle_mkup"
- Markup to add around book titles.
- "journal_mkup"
- Markup to add around journal names.
Option methods¶
As required by the "Text::BibTeX::Structure" module,
"Text::BibTeX::Bib" provides two methods for handling options:
"known_option" and "default_option". (The other two option
methods, "set_options" and "get_options", are just
inherited from "Text::BibTeX::Structure".)
- known_option (OPTION)
- Returns true if OPTION is one of the options on the above
list.
- default_option (OPTION)
- Returns the default value of OPTION, or "croak"s
if OPTION is not a supported option.
DATABASE STRUCTURE¶
The other purpose of a structure class is to provide a method,
"describe_entry", that lists the allowed entry types and the known
fields for the structure. Programmers wishing to write their own database
structure module should consult Text::BibTeX::Structure for the conventions
and requirements of this method; the purpose of the present document is to
describe the "Bib" database structure.
The allowed entry types, and the fields recognized for them, are:
- "article"
- Required fields: "author", "title",
"journal", "year". Optional fields:
"volume", "number", "pages",
"month", "note".
- "book"
- Required fields: "title", "publisher",
"year". Optional fields: "series",
"address", "edition", "month",
"note". Constrained fields: exactly one of "author",
"editor"; at most one of "volume",
"number".
- "booklet"
- Required fields: "title". Optional fields:
"author", "howpublished", "address",
"month", "year", "note".
- "inbook"
- Required fields: "publisher", "year".
Optional fields: "series", "type",
"address", "edition", "month",
"note". Constrained fields: exactly one of "author",
"editor"; at least one of "chapter",
"pages"; at most one of "volume",
"number".
- "incollection"
- Required fields: "author", "title",
"booktitle", "publisher", "year". Optional
fields: "editor", "series", "type",
"chapter", "pages", "address",
"edition", "month", "note". Constrained
fields: at most one of "volume", "number".
- "inproceedings"
- "conference"
- Required fields: "author", "title",
"booktitle", "year". Optional fields:
"editor", "series", "pages",
"address", "month", "organization",
"publisher", "note". Constrained fields: at most one
of "volume", "number".
- "manual"
- Required fields: "title". Optional fields:
"author", "organization", "address",
"edition", "month", "year",
"note".
- "mastersthesis"
- Required fields: "author", "title",
"school", "year". Optional fields: "type",
"address", "month", "note".
- "misc"
- Required fields: none. Optional fields: "author",
"title", "howpublished", "month",
"year", "note".
- "phdthesis"
- Required fields: "author", "title",
"school", "year". Optional fields: "type",
"address", "month", "note".
- "proceedings"
- Required fields: "title", "year".
Optional fields: "editor", "series",
"address", "month", "organization",
"publisher", "note". Constrained fields: at most one
of "volume", "number".
- "techreport"
- Required fields: "author", "title",
"institution", "year". Optional fields:
"type", "number", "address",
"month", "note".
- "unpublished"
- Required fields: "author", "title",
"note". Optional fields: "month",
"year".
STRUCTURED ENTRY CLASS¶
The second class provided by the "Text::BibTeX::Bib" module is
"BibEntry" (again, a leading "Text::BibTeX" is implied).
This being a structured entry class, it derives from
"StructuredEntry". The conventions and requirements for such a class
are documented in Text::BibTeX::Structure for the benefit of programmers
implementing their own structure modules.
If you wish to write utilities making use of the "Bib" database
structure, then you should call one of the "officially supported"
methods provided by the "BibEntry" class. Currently, there are only
two of these: "sort_key" and "format". These are actually
implemented in the "BibSort" and "BibFormat" classes,
respectively, which are base classes of "BibEntry". Thus, see
Text::BibTeX::BibSort and Text::BibTeX::BibFormat for details on these two
methods.
SEE ALSO¶
Text::BibTeX::Structure, Text::BibTeX::BibSort, Text::BibTeX::BibFormat.
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.