NAME

Text::BibTeX::File - interface to whole BibTeX files

SYNOPSIS

use Text::BibTeX::File;

$bib = Text::BibTeX::File->new("foo.bib") or die "foo.bib: $!\n";
# or:
$bib =  Text::BibTeX::File->new;
$bib->open("foo.bib", {binmode => 'utf-8', normalization => 'NFC'}) || die "foo.bib: $!\n";

$bib->set_structure ($structure_name,
                     $option1 => $value1, ...);

$at_eof = $bib->eof;

$bib->close;

DESCRIPTION

Text::BibTeX::File provides an object-oriented interface to BibTeX files. Its most obvious purpose is to keep track of a filename and filehandle together for use by the Text::BibTeX::Entry module (which is much more interesting). In addition, it allows you to specify certain options which are applicable to a whole database (file), rather than having to specify them for each entry in the file. Currently, you can specify the database structure and some structure options. These concepts are fully documented in Text::BibTeX::Structure.

METHODS

Object creation, file operations

new ([FILENAME], [OPTS])

Creates a new Text::BibTeX::File object. If FILENAME is supplied, passes it to the open method (along with OPTS). If the open fails, new fails and returns false; if the open succeeds (or if FILENAME isn't supplied), new returns the new object reference.

open (SOURCE [, OPTS])

Opens SOURCE for reading. SOURCE is usually a filename, but may also be a reference to a scalar (to read from a string in memory) or an already open filehandle (any Perl filehandle works, including tied handles and handles with I/O layers). OPTS is a hashref that can have the following values (case-insensitive):

MODE

mode as specified by IO::File

PERMS

permissions as specified by IO::File. Can only be used in conjunction with MODE

BINMODE

'utf-8' (the default) or 'bytes' (also 'raw').

In 'utf-8' mode the input is decoded as UTF-8 and all strings returned (entry types, keys, field names, values, names...) are Perl character strings, normalised as given by NORMALIZATION. Bytes that are not valid UTF-8 are replaced by U+FFFD with a warning; use ENCODING to read files in other encodings. A leading byte order mark is ignored.

In 'bytes' mode the input is not decoded at all and strings are returned as byte strings, exactly as they appear in the file.

ENCODING

The encoding of the file, if it isn't UTF-8 (eg. 'latin1'): an :encoding(...) layer is pushed onto the filehandle. If you pass in a filehandle that already has an encoding layer, you don't need this.

NORMALIZATION

The Unicode normalization form for strings returned in 'utf-8' mode: 'NFC' (the default), 'NFD', 'NFKC', 'NFKD', or 'none'.

RESET_MACROS

By default, macros (@string definitions) accumulate in one global table, as in BibTeX itself: when you open a second file, macros defined by the first are still available. This option clears all macro definitions (except for the month macros) before the file is read.

PRIVATE_MACROS

Give this file its own macro table: @string definitions in it are not seen by any other file, and it does not see those made by other files. It still sees the global macros (the month names, and any defined with "add_macro_text" in Text::BibTeX).

FILENAME

When SOURCE is a filehandle, the name to use in error messages.

close ()

Closes the filehandle associated with the object. If there is no such filehandle (i.e., open was never called on the object), does nothing.

eof ()

Returns the end-of-file state of the filehandle associated with the object: a true value means we are at the end of the file.

Object properties

set_structure (STRUCTURE [, OPTION => VALUE, ...])

Sets the database structure for a BibTeX file. At the simplest level, this means that entries from the file are expected to conform to certain field requirements as specified by the structure module. It also gives you full access to the methods of the particular structured entry class for this structure, allowing you to perform operations specific to this kind of database. See "CLASS INTERACTIONS" in Text::BibTeX::Structure for all the consequences of setting the database structure for a Text::BibTeX::File object.

structure ()

Returns the name of the database structure associated with the object (as set by set_structure).

preserve_values ([PRESERVE])

Sets the "preserve values" flag, to control all future parsing of entries from this file. If PRESERVE isn't supplied, returns the current state of the flag. See Text::BibTeX::Value for details on parsing in "value preservation" mode.

SEE ALSO

Text::BibTeX, Text::BibTeX::Entry, Text::BibTeX::Structure

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.