.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Text::BibTeX::File 3pm"
.TH Text::BibTeX::File 3pm "2019-07-17" "perl v5.28.1" "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 ([\s-1FILENAME\s0], [\s-1OPTS\s0])" 4
.IX Item "new ([FILENAME], [OPTS])"
Creates a new \f(CW\*(C`Text::BibTeX::File\*(C'\fR object.  If \s-1FILENAME\s0 is supplied, passes
it to the \f(CW\*(C`open\*(C'\fR method (along with \s-1OPTS\s0).  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 \s-1FILENAME\s0 isn't
supplied), \f(CW\*(C`new\*(C'\fR returns the new object reference.
.IP "open (\s-1FILENAME\s0 [\s-1OPTS\s0])" 4
.IX Item "open (FILENAME [OPTS])"
Opens the file specified by \s-1FILENAME. OPTS\s0 is an hashref that can have
the following values:
.RS 4
.IP "\s-1MODE\s0" 4
.IX Item "MODE"
mode as specified by IO::File
.IP "\s-1PERMS\s0" 4
.IX Item "PERMS"
permissions as specified by IO::File. Can only be used in conjunction
with \f(CW\*(C`MODE\*(C'\fR
.IP "\s-1BINMODE\s0" 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 \s-1UTF\-8.\s0 In this case, Text::BibTeX will return \s-1UTF\-8\s0 strings in
\&\s-1NFC\s0 mode. Note that at the moment files with \s-1BOM\s0 are not supported.
.Sp
Valid values are 'raw/bytes' or 'utf\-8'.
.IP "\s-1NORMALIZATION\s0" 4
.IX Item "NORMALIZATION"
By default, Text::BibTeX outputs \s-1UTF\-8\s0 in \s-1NFC\s0 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
('\s-1NFD\s0', '\s-1NFDK\s0' etc.)
.IP "\s-1RESET_MACROS\s0" 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 (\s-1STRUCTURE\s0 [, \s-1OPTION\s0 => \s-1VALUE, ...\s0])" 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 \*(L"\s-1CLASS
INTERACTIONS\*(R"\s0 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 ([\s-1PRESERVE\s0])" 4
.IX Item "preserve_values ([PRESERVE])"
Sets the \*(L"preserve values\*(R" flag, to control all future parsing of entries
from this file.  If \s-1PRESERVE\s0 isn't supplied, returns the current state of
the flag.  See Text::BibTeX::Value for details on parsing in \*(L"value
preservation\*(R" 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.