---
name: "Text::BibTeX::File"
section: "3pm"
platform: "linux"
package: "perl-text-bibtex"
version: "0.91-3"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Text::BibTeX::File"
---

# Text::BibTeX::File(3pm)

interface to whole BibTeX files

## 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.