NAME

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

SYNOPSIS

          use Text::BibTeX;     # this loads Text::BibTeX::File

          $bib = new Text::BibTeX::File "foo.bib" or die "foo.bib: $!\n";
          # or:
          $bib = new Text::BibTeX::File;
          $bib->open ("foo.bib") || 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 [,MODE [,PERMS]]])
           Creates  a  new "Text::BibTeX::File" object.  If FILENAME is supplied, passes it to the "open" method
           (along with MODE and PERMS if they are supplied).  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 [,MODE [,PERMS]])
           Opens the file specified by  FILENAME,  possibly  using  MODE  and  PERMS.   See  IO::File  for  full
           semantics; this "open" is just a front end for "IO::File::open".

       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.

perl v5.22.1                                       2015-12-18                            Text::BibTeX::File(3pm)