1Text::BibTeX::File(3) User Contributed Perl DocumentationText::BibTeX::File(3)
2
3
4

NAME

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

SYNOPSIS

9          use Text::BibTeX::File;
10
11          $bib = Text::BibTeX::File->new("foo.bib") or die "foo.bib: $!\n";
12          # or:
13          $bib =  Text::BibTeX::File->new;
14          $bib->open("foo.bib", {binmode => 'utf-8', normalization => 'NFC'}) || die "foo.bib: $!\n";
15
16          $bib->set_structure ($structure_name,
17                               $option1 => $value1, ...);
18
19          $at_eof = $bib->eof;
20
21          $bib->close;
22

DESCRIPTION

24       "Text::BibTeX::File" provides an object-oriented interface to BibTeX
25       files.  Its most obvious purpose is to keep track of a filename and
26       filehandle together for use by the "Text::BibTeX::Entry" module (which
27       is much more interesting).  In addition, it allows you to specify
28       certain options which are applicable to a whole database (file), rather
29       than having to specify them for each entry in the file.  Currently, you
30       can specify the database structure and some structure options.  These
31       concepts are fully documented in Text::BibTeX::Structure.
32

METHODS

34   Object creation, file operations
35       new ([FILENAME], [OPTS])
36           Creates a new "Text::BibTeX::File" object.  If FILENAME is
37           supplied, passes it to the "open" method (along with OPTS).  If the
38           "open" fails, "new" fails and returns false; if the "open" succeeds
39           (or if FILENAME isn't supplied), "new" returns the new object
40           reference.
41
42       open (FILENAME [OPTS])
43           Opens the file specified by FILENAME. OPTS is an hashref that can
44           have the following values:
45
46           MODE
47               mode as specified by IO::File
48
49           PERMS
50               permissions as specified by IO::File. Can only be used in
51               conjunction with "MODE"
52
53           BINMODE
54               By default, Text::BibTeX uses bytes directly. Thus, you need to
55               encode strings accordingly with the encoding of the files you
56               are reading. You can also select UTF-8. In this case,
57               Text::BibTeX will return UTF-8 strings in NFC mode. Note that
58               at the moment files with BOM are not supported.
59
60               Valid values are 'raw/bytes' or 'utf-8'.
61
62           NORMALIZATION
63               By default, Text::BibTeX outputs UTF-8 in NFC form. You can
64               change this by passing the name of a different form.
65
66               Valid values are those forms supported by the
67               Unicode::Normalize module ('NFD', 'NFDK' etc.)
68
69           RESET_MACROS
70               By default, Text::BibTeX accumulates macros. This means that
71               when you open a second file, macros defined by the first are
72               still available. This may result on warnings of macros being
73               redefined.
74
75               This option can be used to force Text::BibTeX to clean up all
76               macros definitions (except for the month macros).
77
78       close ()
79           Closes the filehandle associated with the object.  If there is no
80           such filehandle (i.e., "open" was never called on the object), does
81           nothing.
82
83       eof ()
84           Returns the end-of-file state of the filehandle associated with the
85           object: a true value means we are at the end of the file.
86
87   Object properties
88       set_structure (STRUCTURE [, OPTION => VALUE, ...])
89           Sets the database structure for a BibTeX file.  At the simplest
90           level, this means that entries from the file are expected to
91           conform to certain field requirements as specified by the structure
92           module.  It also gives you full access to the methods of the
93           particular structured entry class for this structure, allowing you
94           to perform operations specific to this kind of database.  See
95           "CLASS INTERACTIONS" in Text::BibTeX::Structure for all the
96           consequences of setting the database structure for a
97           "Text::BibTeX::File" object.
98
99       structure ()
100           Returns the name of the database structure associated with the
101           object (as set by "set_structure").
102
103       preserve_values ([PRESERVE])
104           Sets the "preserve values" flag, to control all future parsing of
105           entries from this file.  If PRESERVE isn't supplied, returns the
106           current state of the flag.  See Text::BibTeX::Value for details on
107           parsing in "value preservation" mode.
108

SEE ALSO

110       Text::BibTeX, Text::BibTeX::Entry, Text::BibTeX::Structure
111

AUTHOR

113       Greg Ward <gward@python.net>
114

116       Copyright (c) 1997-2000 by Gregory P. Ward.  All rights reserved.  This
117       file is part of the Text::BibTeX library.  This library is free
118       software; you may redistribute it and/or modify it under the same terms
119       as Perl itself.
120
121
122
123perl v5.34.0                      2022-01-21             Text::BibTeX::File(3)
Impressum