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 (FILENAME [OPTS])
           Opens the file specified by FILENAME. OPTS is 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 return UTF-8 strings in NFC mode. Note that
               at the moment files with BOM are not supported.

               Valid values are 'raw/bytes' or 'utf-8'.

           NORMALIZATION
               By default, Text::BibTeX outputs UTF-8 in NFC form. 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 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.