.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Text::BibTeX::File 3pm"
.TH Text::BibTeX::File 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Text::BibTeX::File \- interface to whole BibTeX files
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&   use Text::BibTeX::File;
\&
\&   $bib = Text::BibTeX::File\->new("foo.bib") or die "foo.bib: $!\en";
\&   # or:
\&   $bib =  Text::BibTeX::File\->new;
\&   $bib\->open("foo.bib", {binmode => \*(Aqutf\-8\*(Aq, normalization => \*(AqNFC\*(Aq}) || die "foo.bib: $!\en";
\&
\&   $bib\->set_structure ($structure_name,
\&                        $option1 => $value1, ...);
\&
\&   $at_eof = $bib\->eof;
\&
\&   $bib\->close;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Text::BibTeX::File\*(C'\fR 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 \f(CW\*(C`Text::BibTeX::Entry\*(C'\fR 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 \fIdatabase structure\fR and some \fIstructure options\fR.
These concepts are fully documented in Text::BibTeX::Structure.
.SH METHODS
.IX Header "METHODS"
.SS "Object creation, file operations"
.IX Subsection "Object creation, file operations"
.IP "new ([FILENAME], [OPTS])" 4
.IX Item "new ([FILENAME], [OPTS])"
Creates a new \f(CW\*(C`Text::BibTeX::File\*(C'\fR object.  If FILENAME is supplied, passes
it to the \f(CW\*(C`open\*(C'\fR method (along with OPTS).  If the \f(CW\*(C`open\*(C'\fR fails, \f(CW\*(C`new\*(C'\fR
fails and returns false; if the \f(CW\*(C`open\*(C'\fR succeeds (or if FILENAME isn't
supplied), \f(CW\*(C`new\*(C'\fR returns the new object reference.
.IP "open (FILENAME [OPTS])" 4
.IX Item "open (FILENAME [OPTS])"
Opens the file specified by FILENAME. OPTS is an hashref that can have
the following values:
.RS 4
.IP MODE 4
.IX Item "MODE"
mode as specified by IO::File
.IP PERMS 4
.IX Item "PERMS"
permissions as specified by IO::File. Can only be used in conjunction
with \f(CW\*(C`MODE\*(C'\fR
.IP BINMODE 4
.IX Item "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 return UTF\-8 strings in
NFC mode. Note that at the moment files with BOM are not supported.
.Sp
Valid values are 'raw/bytes' or 'utf\-8'.
.IP NORMALIZATION 4
.IX Item "NORMALIZATION"
By default, Text::BibTeX outputs UTF\-8 in NFC form. You can change this by passing
the name of a different form.
.Sp
Valid values are those forms supported by the Unicode::Normalize module
('NFD', 'NFDK' etc.)
.IP RESET_MACROS 4
.IX Item "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.
.Sp
This option can be used to force Text::BibTeX to clean up all macros definitions
(except for the month macros).
.RE
.RS 4
.RE
.IP "close ()" 4
.IX Item "close ()"
Closes the filehandle associated with the object.  If there is no such
filehandle (i.e., \f(CW\*(C`open\*(C'\fR was never called on the object), does nothing.
.IP "eof ()" 4
.IX Item "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.
.SS "Object properties"
.IX Subsection "Object properties"
.IP "set_structure (STRUCTURE [, OPTION => VALUE, ...])" 4
.IX Item "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 \fIstructure module\fR.  It also
gives you full access to the methods of the particular \fIstructured
entry class\fR 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 \f(CW\*(C`Text::BibTeX::File\*(C'\fR object.
.IP "structure ()" 4
.IX Item "structure ()"
Returns the name of the database structure associated with the object
(as set by \f(CW\*(C`set_structure\*(C'\fR).
.IP "preserve_values ([PRESERVE])" 4
.IX Item "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::BibTeX, Text::BibTeX::Entry, Text::BibTeX::Structure
.SH AUTHOR
.IX Header "AUTHOR"
Greg Ward <gward@python.net>
.SH COPYRIGHT
.IX Header "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.