Text::...eX::Bib(3pm)

🦋 Text::BibTeX::Bib(3pm) — user-contributed Perl documentation

✨ NAME ✨

Text::BibTeX::Bib — defines the "Bib" database structure. Short, sweet, iconic.

📚 SYNOPSIS 📚

Okay bestie, here's the whole vibe of how you touch this thing:

$bibfile = Text::BibTeX::File $filename->new;
$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 = Text::BibTeX::Entry->new($bibfile);

# or get an entry from somewhere else which is hard-coded to be
# a BibEntry
$entry = Text::BibTeX::BibEntry->new(...);

$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 croaks 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

Okay so this whole glorious thing was made by Greg Ward — yes, the Greg Ward — and if you ever need to slide into his inbox about it, the addy is gward@python.net. Bestie wrote the manual, wrote the code, wrote the vibes. Iconic behavior, honestly. 👑

---

📜 COPYRIGHT

So here's the legal bit, and ngl you should actually read it because it's short and it's slaying:

Copyright (c) 1997-2000 by Gregory P. Ward. All rights reserved.

This file is part of the Text::BibTeX library. And the way this library is set up? It's free software — like, genuinely free, not "free if you're normal about it" free. You may redistribute it and/or modify it under the same terms as Perl itself. That's it. That's the whole deal. 🫶

Fr fr, "same terms as Perl itself" is doing a lot of heavy lifting there — if you wanna remix, redistribute, or generally mess with it, go check Perl's own license terms, because that's the vibe you're agreeing to. No cap. ✨

---

And that's the page, babes! 🎀 This edition came to you from perl v5.42.0, dated 2025-01-31 — so yeah, it's recent, it's fresh, it's giving main character documentation. Go forth and format your bibliographies like the icon you are. 💅🌸🦋