btool_faq(3)

btool_faq 💖

okay bestie, welcome to btool_faq from the btparse manual, section 3. this is the FAQ page. it's giving "the answers you needed were scattered across five different man pages and nobody told you" energy. 🫶

---

✨ NAME ✨

btool_faq — the Frequently-Asked Questions about btparse and Text::BibTeX. literally what it says on the tin. 💅

---

✨ DESCRIPTION ✨

so here's the vibe: this document exists because people keep asking me the same questions over and over, and they're easy to answer — but not if you're just reading the docs like a normal person. 😭 for various reasons, the answers tend to be thinly distributed across several man pages, which makes it genuinely hard to figure out what's going on. so annoying.

so this man page is here to tie together various strands of thought and give you quick, focused, "How do I do X?" answers, instead of the lengthy descriptions of the capabilities and conventions of the btOOL libraries. no cap. 🎀

---

🌸 PERL LIBRARY 🌸

this section is for the Text::BibTeX girlies — that's the Perl component of btOOL, and these are the questions you've actually asked. 💜

🌈 Why aren't the BibTeX month macros defined?

okay so this one comes up SO much. the answer is: because they're bibliography-specific, and Text::BibTeX by default doesn't impose any assumptions about a particular type of database or data-processing domain on your entries. it's respecting your autonomy. 👑

the problem shows up when you parse entries from a file — say foo.bib — that quite sensibly uses the month macros (jan, feb, etc.) that the BibTeX standard style files hand you:

$bibfile = Text::BibTeX::File->new('foo.bib')    # open file
   or die "foo.bib: $!\n";
$entry = Text::BibTeX::Entry->new($bibfile);     # parse first entry

run this and you might get an "undefined macro" warning for every single entry parsed from foo.bib. 💀 and honestly, apart from the superficial annoyance of all those warning messages, the undefined macros get expanded as empty strings — meaning you lose any information about them. not good. not the vibe.

you could always kludge it and forcibly define the month macros yourself. prior to release 0.30, this had to be done by parsing a set of fake entries, but now Text::BibTeX provides a direct interface to the underlying macro table. so you could just do this before parsing any entries:

use Text::BibTeX qw(:macrosubs);
# ...
my %month = (jan => 'January', feb => 'February', ... );
add_macro_text ($macro, $value)
   while (($macro, $value) = each %month);

but there's a better way, and it's more in keeping with how things are done under BibTeX (where default macros are defined in the style file): use Text::BibTeX's object-oriented analogue to style files, called structure modules. 🦋

Text::BibTeX provides a structure module, Text::BibTeX::Bib, that (partially) emulates the standard style files of BibTeX 0.99 — including the definition of month macros. structure modules are specified on a per-file basis by using the set_structure method on a Text::BibTeX::File object. it's quite simple to tell Text::BibTeX that entries from $bibfile are expected to conform to the Bib structure (which is implemented by the Text::BibTeX::Bib module, but you don't really need to know that):

$bibfile = Text::BibTeX::File->new('foo.bib')
   or die "foo.bib: $!\n";
$bibfile->set_structure ('Bib');

you probably shouldn't hardcode the name of a particular structure in your programs, though, as there will eventually be a multitude of structure modules to choose from — just as there are a multitude of BibTeX style files to choose from. my preferred approach is to make the structure a command-line option which defaults to Bib, since that's the only structure actually implemented as of this writing. 💅

🌈 How do I append to a BibTeX file?

just open it in append mode and write entries to it as usual. simple as. ✨

remember, a Text::BibTeX::File object is mainly a wrapper around an IO::File object, and the Text::BibTeX::File::open method (and thus new as well) is just a front-end to IO::File::open. IO::File::open, in turn, is a front-end either to Perl's builtin open (if called with one argument) or sysopen (two or three arguments).

to save you the trouble of going off and reading all those man pages, here's the trick: if you pass just a filename to Text::BibTeX::File's new method, then it's treated just like a filename passed to Perl's builtin open:

my $append_file = Text::BibTeX::File->new(">>$filename")
   or die "couldn't open $filename for appending: $!\n";

this opens $filename for appending. 🎀

and if, later on, you have an entry from another file (say $entry), then you can append it to $append_file by just writing it as usual:

$entry->write ($append_file);

see append_entries in the examples/ subdirectory of the Text::BibTeX distribution for a complete example. iykyk 🫶

---

🌸 C LIBRARY 🌸

this section covers the frequently-asked questions about btparse — that's the C component of btOOL, bestie. 🔥

🌈 Is there a Python binding for btparse yet?

not that i know of. 😭 i haven't written one. if you do so, please let me know about it. bestie behavior only. 💖

---

✨ SEE ALSO ✨

• btparse
• Text::BibTeX

---

✨ 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. 📜

---

okay that's the whole page, bestie, you made it to the end 🎉 this was btparse, version 0.91, dated 2025-01-31, and honestly? iconic. go forth and parse your bibliographies. slay 💅✨🌸