File Coverage

blib/lib/Text/BibTeX/File.pm
Criterion Covered Total %
statement 52 55 94.5
branch 12 20 60.0
condition 5 11 45.4
subroutine 12 13 92.3
pod 7 7 100.0
total 88 106 83.0


line stmt bran cond sub pod time code
1             # ----------------------------------------------------------------------
2             # NAME : BibTeX/File.pm
3             # CLASSES : Text::BibTeX::File
4             # RELATIONS :
5             # DESCRIPTION: Provides an object-oriented interface to whole BibTeX
6             # files.
7             # CREATED : March 1997, Greg Ward
8             # MODIFIED :
9             # VERSION : $Id$
10             # COPYRIGHT : Copyright (c) 1997-2000 by Gregory P. Ward. All rights
11             # reserved.
12             #
13             # This file is part of the Text::BibTeX library. This
14             # library is free software; you may redistribute it and/or
15             # modify it under the same terms as Perl itself.
16             # ----------------------------------------------------------------------
17              
18             package Text::BibTeX::File;
19              
20 13     13   87 use strict;
  13         25  
  13         385  
21 13     13   62 use Carp;
  13         27  
  13         715  
22 13     13   6395 use IO::File;
  13         34868  
  13         1440  
23 13     13   6925 use Text::BibTeX::Entry;
  13         35  
  13         438  
24              
25 13     13   78 use vars qw'$VERSION';
  13         26  
  13         7424  
26             $VERSION = 0.87;
27              
28             =head1 NAME
29              
30             Text::BibTeX::File - interface to whole BibTeX files
31              
32             =head1 SYNOPSIS
33              
34             use Text::BibTeX::File;
35              
36             $bib = Text::BibTeX::File->new("foo.bib") or die "foo.bib: $!\n";
37             # or:
38             $bib = Text::BibTeX::File->new;
39             $bib->open("foo.bib", {binmode => 'utf-8', normalization => 'NFC'}) || die "foo.bib: $!\n";
40              
41             $bib->set_structure ($structure_name,
42             $option1 => $value1, ...);
43              
44             $at_eof = $bib->eof;
45              
46             $bib->close;
47              
48             =head1 DESCRIPTION
49              
50             C provides an object-oriented interface to BibTeX
51             files. Its most obvious purpose is to keep track of a filename and
52             filehandle together for use by the C module (which
53             is much more interesting). In addition, it allows you to specify
54             certain options which are applicable to a whole database (file), rather
55             than having to specify them for each entry in the file. Currently, you
56             can specify the I and some I.
57             These concepts are fully documented in L.
58              
59             =head1 METHODS
60              
61             =head2 Object creation, file operations
62              
63             =over 4
64              
65             =item new ([FILENAME], [OPTS])
66              
67             Creates a new C object. If FILENAME is supplied, passes
68             it to the C method (along with OPTS). If the C fails, C
69             fails and returns false; if the C succeeds (or if FILENAME isn't
70             supplied), C returns the new object reference.
71              
72             =item open (FILENAME [OPTS])
73              
74             Opens the file specified by FILENAME. OPTS is an hashref that can have
75             the following values:
76              
77             =over 4
78              
79             =item MODE
80              
81             mode as specified by L
82              
83             =item PERMS
84              
85             permissions as specified by L. Can only be used in conjunction
86             with C
87              
88             =item BINMODE
89              
90             By default, Text::BibTeX uses bytes directly. Thus, you need to encode
91             strings accordingly with the encoding of the files you are reading. You can
92             also select UTF-8. In this case, Text::BibTeX will return UTF-8 strings in
93             NFC mode. Note that at the moment files with BOM are not supported.
94              
95             Valid values are 'raw/bytes' or 'utf-8'.
96              
97             =item NORMALIZATION
98              
99             By default, Text::BibTeX outputs UTF-8 in NFC form. You can change this by passing
100             the name of a different form.
101              
102             Valid values are those forms supported by the Unicode::Normalize module
103             ('NFD', 'NFDK' etc.)
104              
105             =item RESET_MACROS
106              
107             By default, Text::BibTeX accumulates macros. This means that when you open a second
108             file, macros defined by the first are still available. This may result on warnings
109             of macros being redefined.
110              
111             This option can be used to force Text::BibTeX to clean up all macros definitions
112             (except for the month macros).
113              
114             =back
115              
116             =item close ()
117              
118             Closes the filehandle associated with the object. If there is no such
119             filehandle (i.e., C was never called on the object), does nothing.
120              
121             =item eof ()
122              
123             Returns the end-of-file state of the filehandle associated with the
124             object: a true value means we are at the end of the file.
125              
126             =back
127              
128             =cut
129              
130             sub new
131             {
132 8     8 1 5583 my $class = shift;
133              
134 8   33     53 $class = ref ($class) || $class;
135 8         22 my $self = bless {}, $class;
136 8 50 50     41 ($self->open (@_) || return undef) if @_;
137 8         473 $self;
138             }
139              
140             sub open {
141 8     8 1 19 my ($self) = shift;
142 8         42 $self->{filename} = shift;
143              
144 8         21 $self->{binmode} = 'bytes';
145 8         18 $self->{normalization} = 'NFC';
146 8         21 my @args = ( $self->{filename} );
147              
148 8 100       29 if ( ref $_[0] eq "HASH" ) {
149 5         12 my $opts = {};
150 5         9 $opts = shift;
151 5         29 $opts->{ lc $_ } = $opts->{$_} for ( keys %$opts );
152             $self->{binmode} = 'utf-8'
153 5 100 66     82 if exists $opts->{binmode} && $opts->{binmode} =~ /utf-?8/i;
154 5 50       15 $self->{normalization} = $opts->{normalization} if exists $opts->{normalization};
155              
156 5 0 33     13 if (exists $opts->{reset_macros} && $opts->{reset_macros}) {
157 0         0 Text::BibTeX::delete_all_macros();
158 0         0 Text::BibTeX::_define_months();
159             }
160              
161 5 100       16 if ( exists $opts->{mode} ) {
162 1         2 push @args, $opts->{mode};
163 1 50       4 push @args, $opts->{perms} if exists $opts->{perms};
164             }
165             }
166             else {
167 3         9 push @args, @_;
168             }
169              
170 8         48 $self->{handle} = IO::File->new;
171 8         368 $self->{handle}->open(@args); # filename, maybe mode, maybe perms
172             }
173              
174              
175             sub close
176             {
177 10     10 1 26 my $self = shift;
178 10 50       39 if ( $self->{handle} ) {
179 10         55 Text::BibTeX::Entry->new ($self->{filename}, undef); # resets parser
180 10         61 $self->{handle}->close;
181             }
182             }
183              
184             sub eof
185             {
186 0     0 1 0 eof (shift->{handle});
187             }
188            
189             sub DESTROY
190             {
191 8     8   4635 my $self = shift;
192 8         29 $self->close;
193             }
194              
195             =head2 Object properties
196              
197             =over 4
198              
199             =item set_structure (STRUCTURE [, OPTION =E VALUE, ...])
200              
201             Sets the database structure for a BibTeX file. At the simplest level,
202             this means that entries from the file are expected to conform to certain
203             field requirements as specified by the I. It also
204             gives you full access to the methods of the particular I
205             entry class> for this structure, allowing you to perform operations
206             specific to this kind of database. See L
207             INTERACTIONS"> for all the consequences of setting the database
208             structure for a C object.
209              
210             =item structure ()
211              
212             Returns the name of the database structure associated with the object
213             (as set by C).
214              
215             =cut
216              
217             sub set_structure
218             {
219 1     1 1 8 my ($self, $structure, @options) = @_;
220              
221 1         8 require Text::BibTeX::Structure;
222 1 50       5 croak "Text::BibTeX::File::set_structure: options list must have even " .
223             "number of elements"
224             unless @options % 2 == 0;
225 1         9 $self->{structure} = Text::BibTeX::Structure->new($structure, @options);
226             }
227              
228 85     85 1 265 sub structure { shift->{structure} }
229              
230              
231             =item preserve_values ([PRESERVE])
232              
233             Sets the "preserve values" flag, to control all future parsing of entries
234             from this file. If PRESERVE isn't supplied, returns the current state of
235             the flag. See L for details on parsing in "value
236             preservation" mode.
237              
238             =back
239              
240             =cut
241              
242             sub preserve_values
243             {
244 88     88 1 172 my $self = shift;
245              
246 88 50       177 $self->{'preserve_values'} = shift if @_;
247 88         184 $self->{'preserve_values'};
248             }
249              
250              
251             1;
252              
253             =head1 SEE ALSO
254              
255             L, L, L
256              
257             =head1 AUTHOR
258              
259             Greg Ward
260              
261             =head1 COPYRIGHT
262              
263             Copyright (c) 1997-2000 by Gregory P. Ward. All rights reserved. This file
264             is part of the Text::BibTeX library. This library is free software; you
265             may redistribute it and/or modify it under the same terms as Perl itself.