1Text::BibTeX::Bib(3) User Contributed Perl Documentation Text::BibTeX::Bib(3)
2
6 Text::BibTeX::Bib - defines the "Bib" database structure
7
9 $bibfile = Text::BibTeX::File $filename->new;
10 $bibfile->set_structure ('Bib',
11 # Default option values:
12 sortby => 'name',
13 namestyle => 'full'
14 nameorder => 'first',
15 atitle => 1,
16 labels => 'numeric');
17 # Alternate option values:
19 $bibfile->set_option (sortby => 'year');
20 $bibfile->set_option (namestyle => 'nopunct');
21 $bibfile->set_option (namestyle => 'nospace');
22 $bibfile->set_option (nameorder => 'last');
23 $bibfile->set_option (atitle => 0);
24 $bibfile->set_option (labels => 'alpha'); # not implemented yet!
25 # parse entry from $bibfile and automatically make it a BibEntry
27 $entry = Text::BibTeX::Entry->new($bibfile);
28 # or get an entry from somewhere else which is hard-coded to be
30 # a BibEntry
31 $entry = Text::BibTeX::BibEntry->new(...);
32 $sortkey = $entry->sort_key;
34 @blocks = $entry->format;
35
37 (NOTE! Do not believe everything you read in this document. The
38 classes described here are unfinished and only lightly tested. The
39 current implementation is a proof-of-principle, to convince myself (and
40 anyone who might be interested) that it really is possible to
41 reimplement BibTeX 0.99 in Perl using the core "Text::BibTeX" classes;
42 this principle is vaguely demonstrated by the current "Bib*" modules,
43 but not really proved. Many important features needed to reimplement
44 the standard styles of BibTeX 0.99 are missing, even though this
45 document may brashly assert otherwise. If you are interested in using
46 these classes, you should start by reading and grokking the code, and
47 contributing the missing bits and pieces that you need.)
48 "Text::BibTeX::Bib" implements the database structure for
50 bibliographies as defined by the standard styles of BibTeX 0.99. It
51 does this by providing two classes, "BibStructure" and "BibEntry" (the
52 leading "Text::BibTeX" is implied, and will be omitted for the rest of
53 this document). These two classes, being specific to bibliographic
54 data, are outside of the core "Text::BibTeX" class hierarchy, but are
55 distributed along with it as they provide a canonical example of a
56 specific database structure using classes derived from the core
57 hierarchy.
58 "BibStructure", which derives from the "Structure" class, deals with
60 the structure as a whole: it handles structure options and describes
61 all the types and fields that make up the database structure. If
62 you're interested in writing your own database structure modules, the
63 standard interface for both of these is described in
64 Text::BibTeX::Structure; if you're just interested in finding out the
65 exact database structure or the options supported by the "Bib"
66 structure, you've come to the right place. (However, you may have to
67 wade through a bit of excess verbiage due to this module's dual
68 purpose: first, to reimplement the standard styles of BibTeX 0.99, and
69 second, to provide an example for other programmers wishing to
70 implement new or derived database structure modules.)
71 "BibEntry" derives from the "StructuredEntry" class and provides
73 methods that operate on individual entries presumed to come from a
74 database conforming to the structure defined by the "BibStructure"
75 class. (Actually, to be completely accurate, "BibEntry" inherits from
76 two intermediate classes, "BibSort" and "BibFormat". These two classes
77 just exist to reduce the amount of code in the "Bib" module, and thanks
78 to the magic of inheritance, their existence is usually irrelevant.
79 But you might want to consult those two classes if you're interested in
80 the gory details of sorting and formatting entries from BibTeX
81 0.99-style bibliography databases.)
82
84 "BibStructure" handles several user-supplied "structure options" and
85 methods for dealing with them. The options currently supported by the
86 "Bib" database structure, and the values allowed for them, are:
87 "sortby"
89 How to sort entries. Valid values: "name" (sort on author names,
90 year, and title), "year" (sort on year, author names, and title).
91 Sorting on "author names" is a bit more complicated than just using
92 the "author" field; see Text::BibTeX::BibSort for details. Default
93 value: "name".
94 "namestyle"
96 How to print author (and editor) names: "full" for unabbreviated
97 first names, "abbrev" for first names abbreviated with periods,
98 "nopunct" for first names abbreviated with space but no periods,
99 and "nospace" to abbreviate without space or periods. Default
100 value: "full".
101 "nameorder"
103 The order in which to print names: "first" for "first von last jr"
104 order, and "last" for "von last jr first" order. Default value:
105 "first".
106 "atitle_lower"
108 A boolean option: if true, non-book titles will be changed to
109 "sentence capitalization:" words following colons and sentence-
110 ending punctuation will be capitalized, and everything else at
111 brace-depth zero will be changed to lowercase. Default value:
112 true.
113 "labels"
115 The type of bibliographic labels to generate: "numeric" or "alpha".
116 (Alphabetic labels are not yet implemented, so this option is
117 currently ignored.) Default value: "numeric".
118 Also, several "markup options" are supported. Markup options are
120 distinct because they don't change how text is extracted from the
121 database entries and subsequently mangled; rather, they supply bits of
122 markup that go around the database-derived text. Markup options are
123 always two-element lists: the first to "turn on" some feature of the
124 markup language, and the second to turn it off. For example, if your
125 target language is LaTeX2e and you want journal names emphasized, you
126 would supply a list reference "['\emph{','}']" for the "journal_mkup"
127 option. If you were instead generating HTML, you might supply
128 "['<emph>','</emph>']". To keep the structure module general with
129 respect to markup languages, all markup options are empty by default.
130 (Or, rather, they are all references to lists consisting of two empty
131 strings.)
132 "name_mkup"
134 Markup to add around the list of author names.
135 "atitle_mkup"
137 Markup to add around non-book (article) titles.
138 "btitle_mkup"
140 Markup to add around book titles.
141 "journal_mkup"
143 Markup to add around journal names.
144 Option methods
146 As required by the "Text::BibTeX::Structure" module,
147 "Text::BibTeX::Bib" provides two methods for handling options:
148 "known_option" and "default_option". (The other two option methods,
149 "set_options" and "get_options", are just inherited from
150 "Text::BibTeX::Structure".)
151 known_option (OPTION)
153 Returns true if OPTION is one of the options on the above list.
154 default_option (OPTION)
156 Returns the default value of OPTION, or "croak"s if OPTION is not a
157 supported option.
158
160 The other purpose of a structure class is to provide a method,
161 "describe_entry", that lists the allowed entry types and the known
162 fields for the structure. Programmers wishing to write their own
163 database structure module should consult Text::BibTeX::Structure for
164 the conventions and requirements of this method; the purpose of the
165 present document is to describe the "Bib" database structure.
166 The allowed entry types, and the fields recognized for them, are:
168 "article"
170 Required fields: "author", "title", "journal", "year". Optional
171 fields: "volume", "number", "pages", "month", "note".
172 "book"
174 Required fields: "title", "publisher", "year". Optional fields:
175 "series", "address", "edition", "month", "note". Constrained
176 fields: exactly one of "author", "editor"; at most one of "volume",
177 "number".
178 "booklet"
180 Required fields: "title". Optional fields: "author",
181 "howpublished", "address", "month", "year", "note".
182 "inbook"
184 Required fields: "publisher", "year". Optional fields: "series",
185 "type", "address", "edition", "month", "note". Constrained fields:
186 exactly one of "author", "editor"; at least one of "chapter",
187 "pages"; at most one of "volume", "number".
188 "incollection"
190 Required fields: "author", "title", "booktitle", "publisher",
191 "year". Optional fields: "editor", "series", "type", "chapter",
192 "pages", "address", "edition", "month", "note". Constrained
193 fields: at most one of "volume", "number".
194 "inproceedings"
196 "conference"
197 Required fields: "author", "title", "booktitle", "year". Optional
198 fields: "editor", "series", "pages", "address", "month",
199 "organization", "publisher", "note". Constrained fields: at most
200 one of "volume", "number".
201 "manual"
203 Required fields: "title". Optional fields: "author",
204 "organization", "address", "edition", "month", "year", "note".
205 "mastersthesis"
207 Required fields: "author", "title", "school", "year". Optional
208 fields: "type", "address", "month", "note".
209 "misc"
211 Required fields: none. Optional fields: "author", "title",
212 "howpublished", "month", "year", "note".
213 "phdthesis"
215 Required fields: "author", "title", "school", "year". Optional
216 fields: "type", "address", "month", "note".
217 "proceedings"
219 Required fields: "title", "year". Optional fields: "editor",
220 "series", "address", "month", "organization", "publisher", "note".
221 Constrained fields: at most one of "volume", "number".
222 "techreport"
224 Required fields: "author", "title", "institution", "year".
225 Optional fields: "type", "number", "address", "month", "note".
226 "unpublished"
228 Required fields: "author", "title", "note". Optional fields:
229 "month", "year".
230
232 The second class provided by the "Text::BibTeX::Bib" module is
233 "BibEntry" (again, a leading "Text::BibTeX" is implied). This being a
234 structured entry class, it derives from "StructuredEntry". The
235 conventions and requirements for such a class are documented in
236 Text::BibTeX::Structure for the benefit of programmers implementing
237 their own structure modules.
238 If you wish to write utilities making use of the "Bib" database
240 structure, then you should call one of the "officially supported"
241 methods provided by the "BibEntry" class. Currently, there are only
242 two of these: "sort_key" and "format". These are actually implemented
243 in the "BibSort" and "BibFormat" classes, respectively, which are base
244 classes of "BibEntry". Thus, see Text::BibTeX::BibSort and
245 Text::BibTeX::BibFormat for details on these two methods.
246
248 Text::BibTeX::Structure, Text::BibTeX::BibSort,
249 Text::BibTeX::BibFormat.
250
252 Greg Ward <gward@python.net>
253
255 Copyright (c) 1997-2000 by Gregory P. Ward. All rights reserved. This
256 file is part of the Text::BibTeX library. This library is free
257 software; you may redistribute it and/or modify it under the same terms
258 as Perl itself.
259perl v5.36.0 2023-01-29 Text::BibTeX::Bib(3)