btool_faq - Frequently-Asked Questions about btparse and Text::BibTeX
This document attempts to address questions that I have been asked several times, and are easy to answer -- but not by perusing the documentation. For various reasons, the answers tend to be thinly distributed across several man pages, making it difficult to figure out what's going on. Hence, this man page will attempt to tie together various strands of thought, providing quick, focused, "How do I do X?" answers as opposed to lengthy descriptions of the capabilities and conventions of the btOOL libraries.
This section covers questions that users of Text::BibTeX
, the Perl component of btOOL, have asked.
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. The problem arises when you parse entries from a file, say foo.bib that quite sensibly use the month macros (jan
, feb
, etc.) provided by the BibTeX standard style files:
$bibfile = Text::BibTeX::File->new('foo.bib') # open file
or die "foo.bib: $!\n";
$entry = Text::BibTeX::Entry->new($bibfile); # parse first entry
Using this code, you might get an "undefined macro" warning for every entry parsed from foo.bib. Apart from the superficial annoyance of all those warning messages, the undefined macros are expanded as empty strings, meaning you lose any information about them---not good.
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. 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 that'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).
Just open it in append mode, and write entries to it as usual. 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";
opens $filename
for appending. 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.
This section covers frequently-asked questions about btparse, the C component of btOOL.
Not that I know of. I haven't written one. If you do so, please let me know about it.
Greg Ward <gward@python.net>
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.