Text::BibTeX::File (3)
Leading comments
Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) Standard preamble: ========================================================================
NAME
Text::BibTeX::File - interface to whole BibTeX filesSYNOPSIS
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 FILENAMEis supplied, passes it to the "open" method (along withOPTS). If the "open" fails, "new" fails and returns false; if the "open" succeeds (or ifFILENAMEisn't supplied), "new" returns the new object reference.
- open (FILENAME[OPTS])
-
Opens the file specified by FILENAME. OPTSis an hashref that can have the following values:
-
- MODE
- mode as specified by IO::File
- PERMS
- permissions as specified by IO::File. Can only be used in conjunction with "MODE"
- BINMODE
-
By default, Text::BibTeX uses bytes directly. Thus, you need to encode
strings accordingly with the encoding of the files you are reading. You can
also select UTF-8.In this case, Text::BibTeX will returnUTF-8strings inNFCmode. Note that at the moment files withBOMare not supported.
Valid values are 'raw/bytes' or 'utf-8'.
- NORMALIZATION
-
By default, Text::BibTeX outputs UTF-8inNFCform. You can change this by passing the name of a different form.
Valid values are those forms supported by the Unicode::Normalize module ('
NFD', 'NFDK' etc.) - RESET_MACROS
-
By default, Text::BibTeX accumulates macros. This means that when you open a second
file, macros defined by the first are still available. This may result on warnings
of macros being redefined.
This option can be used to force Text::BibTeX to clean up all macros definitions (except for the month macros).
-
- 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 PRESERVEisn't supplied, returns the current state of the flag. See Text::BibTeX::Value for details on parsing in ``value preservation'' mode.