NAME

Text::BibTeX::Entry - read and parse BibTeX files

SYNOPSIS

   # Assume $bib and $newbib are both objects of class 
   # Text::BibTeX::File, and that $newbib was opened 
   # for writing.

   $entry = new Text::BibTeX::Entry ($bib);
   die "Errors in entry\n" unless $entry->parse_ok;
   
   $type = $entry->type;

   $entry->set_type ($new_type);

   $key = $entry->key;

   $entry->set_key ($new_key);

   $num_fields = $entry->num_fields ();

   @fields = $entry->fields ();

   %values = $entry->values ();

   $has_title = $entry->exists ('title');

   $title = $entry->value ('title');

   $entry->set_value ('title', $new_title);

   $entry->put ($newbib);

DESCRIPTION

Text::BibTeX::Entry does all the real work of reading and parsing BibTeX files. (Well, actually it just provides an object-oriented Perl front-end to a C library that does all that. But that's not important right now.)

BibTeX entries can be read either from Text::BibTeX::File objects (using the get method), or directly from a filehandle (using the parse method). The former is preferable, since you don't have to worry about supplying the filename, and because I might add more functionality to that method in the future. Currently, though, the two are pretty much identical.

Once you have the entry, you can query it or change it in a variety of ways. The query methods are parse_ok, type, key, num_fields, fields, values, exists, and value. Methods for changing the entry are set_type, set_key, set_field and set_fields.

Finally, you can output BibTeX entries, again either to a filehandle or an open Text::BibTeX::File object. (This object must, of course, have been opened in write mode.) Output to a filehandle is done with the print method, and to a Text::BibTeX::File object via put. Again, the two are currently identical, but I may add interesting functionality to the nice object-oriented way of doing things. (In spite of that advice, I often write utilities that read from Text::BibTeX::File objects created from command-line arguments, and then just write to STDOUT, in the grand Unix filter fashion.)

METHODS

Entry creation/parsing methods

new ([SOURCE])

Creates a new Text::BibTeX::Entry object. If the SOURCE parameter is supplied, calls get on the new object with it. Returns the new object, unless SOURCE is supplied and get fails (e.g. due to end of file) -- then it returns a false value.

get (SOURCE)

Reads and parses an entry from SOURCE. SOURCE can be either a Text::BibTeX::File object (or descendant), in which case the next entry will be read from the file associated with that object. Otherwise, SOURCE should be a string containing an entire BibTeX entry, which will be parsed. (SOURCE could in fact contain multiple entries, but only the first one is seen, and the string is not modified to `pop' off this first entry.)

Returns the same as parse (or parse_s): false if no entry found (e.g., at end-of-file), true otherwise. To see if the parse itself failed (due to errors in the input), call the parse_ok method.

parse (FILENAME, FILEHANDLE)

Reads and parses the next entry from FILEHANDLE. (That is, it scans the input until an '@' sign is seen, and then slurps up to the next '@' sign. Everything between the two '@' signs [including the first one, but not the second one -- it's pushed back onto the input stream for the next entry] is parsed as a BibTeX entry, with the simultaneous construction of an abstract syntax tree [AST]. The AST is traversed to ferret out the most interesting information, and this is stuffed into a Perl hash, which coincidentally is the Text::BibTeX::Entry object you've been tossing around. But you don't need to know any of that -- I just figured if you've read this far, you might want to know something about the inner workings of this module.)

The success of the parse is stored internally so that you can later query it with the parse_ok method. Even in the presence of syntax errors, you'll usually get something resembling your input, but it's usually not wise to try to do anything with it. Just call parse_ok, and if it returns false then silently skip to the next entry. (The error messages printed out by the parser should be quite adequate for the user to figure out what's wrong. And no, there's currently no way for you to capture or redirect those error messages -- they're always printed to stderr by the underlying C code. That should change in future releases.)

If no '@' signs are seen on the input before reaching end-of-file, then we've exhausted all the entries in the file, and parse returns a false value. Otherwise, it returns a true value -- even if there were syntax errors. Hence, it's important to check parse_ok.

The FILENAME parameter is only used for generating error messages, but your users will certainly appreciate you setting it correctly!

parse_s (TEXT)

Parses a BibTeX entry (using the above rules) from the string TEXT. The string is not modified; repeatedly calling parse_s with the same string will give you the same results. Thus, there's no point in putting multiple entries in one string.

Entry query methods

parse_ok

Returns false if there were any serious errors encountered while parsing the entry. (A "serious" error is a lexical or syntax error; currently, warnings such as "undefined macro" result in an error message being printed to stderr for the user's edification, but no notice is available to the calling code.)

type

Returns the type of the entry. (The `type' is the word that follows the '@' sign; e.g. `article', `book', `inproceedings', etc. for the standard BibTeX styles.)

key

Returns the key of the entry. (The key is the token immediately following the opening `{' or `('.)

num_fields

Returns the number of fields in the entry. (Note that, currently, this is not equivalent to putting scalar in front of a call to fields. See below for the consequences of calling fields in a scalar context.)

fields

Returns the list of fields in the entry. (In a scalar context, returns a reference to the object's own list of fields. That way, you can change or reorder the field list with minimal interference from the class. I'm not entirely sure if this is a good idea, so don't rely on it existing in the future; feel free to play around with it and let me know if you get bitten in dangerous ways.)

values

Returns a hash mapping field name to field value for the entire entry. (In a scalar context, returns a reference to the object's own field value hash. The same caveats as for fields apply.)

exists (FIELD)

Returns true if a field named FIELD is present in the entry, false otherwise.

value (FIELD)

Returns the value of FIELD. If FIELD is not present in the entry, undef will be returned. However, you can't trust this as a test for presence or absence of a field; it is possible for a field to be present but undefined. Currently this can only happen due to certain syntax errors in the input, or if you pass an undefined value to set_field, or if you implicitly create a new field with set_fields.

Currently, the field value is what the input looks like after "maximal processing"--quote characters are removed, whitespace is collapsed (the same way that BibTeX itself does it), macros are expanded, and multiple tokens are pasted together. For example, if your input file has the following:

   @string{of = "of"}
   @string{foobars = "Foobars"}

   @article{foobar,
     title = {   The Mating Habits      } # of # " Adult   " # foobars
   }

then querying the value of the title field from the foobar entry would give the string "The Mating Habits of Adult Foobars". I have plans up my sleeve for giving access to the data at various stages of processing (the underlying C library is quite flexible in this regard; I just have to translate the flexibility to Perl), but haven't finalized anything yet. If you have ideas, feel free to email me! (I also have plans for documenting what exactly is done to strings in my BibTeX parser; that'll probably be distributed with the C library, btparse.)

names ([FIELD, [DELIM]]) *currently unimplemented*

Splits the value of FIELD (default: `author') on DELIM (default: `and'). This is a bit trickier than it sounds because we have to exclude delimiters encased in braces, which mandates scanning a character at a time and keeping track of brace-depth. (That's why this is currently unimplemented.)

Entry modification methods

set_type (TYPE)

Sets the entry's type.

set_key (KEY)

Sets the entry's key.

set_field (FIELD, VALUE)

Sets the value of field FIELD. (VALUE might be undef or unsupplied, in which FIELD will simply be set to undef -- this is where the difference between the exists method and testing the definedness of field values becomes clear.)

set_fields (FIELD1, ..., FIELDn)

Sets the entry's list of fields. If any of the field names supplied to set_fields are not currently present in the entry, they are created with the value undef and a warning is printed. Conversely, if any of the fields currently present in the entry are not named in the list of fields supplied to set_fields, they are deleted from the entry and another warning is printed.

Entry output methods

put (BIBFILE)

Prints a BibTeX entry on the filehandle associated with BIBFILE (which should be a Text::BibTeX::File object, opened for output). Currently the printout is not particularly human-friendly; a highly configurable pretty-printer will be developed eventually.

print (FILEHANDLE)

Prints a BibTeX entry on FILEHANDLE.

AUTHOR

Greg Ward <greg@bic.mni.mcgill.ca>

COPYRIGHT

Copyright (c) 1997 by Gregory P. Ward. All rights reserved. This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.