view release on metacpan or  search on metacpan

lib/Text/BibTeX/File.pm  view on Meta::CPAN

   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;

=head1 DESCRIPTION

C<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 C<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 I<database structure> and some I<structure options>.
These concepts are fully documented in L<Text::BibTeX::Structure>.

=head1 METHODS

=head2 Object creation, file operations

=over 4

=item new ([FILENAME], [OPTS]) 

Creates a new C<Text::BibTeX::File> object.  If FILENAME is supplied, passes
it to the C<open> method (along with OPTS).  If the C<open> fails, C<new>
fails and returns false; if the C<open> succeeds (or if FILENAME isn't
supplied), C<new> returns the new object reference.

=item open (FILENAME [OPTS])

Opens the file specified by FILENAME. OPTS is an hashref that can have
the following values:

=over 4

=item MODE

mode as specified by L<IO::File>

=item PERMS

permissions as specified by L<IO::File>. Can only be used in conjunction
with C<MODE>

=item 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'.

=item 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.)

=item 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).

=back 

=item close ()

Closes the filehandle associated with the object.  If there is no such
filehandle (i.e., C<open> was never called on the object), does nothing.

=item 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.

=back

=cut

sub new
{
   my $class = shift;

   $class = ref ($class) || $class;
   my $self = bless {}, $class;
   ($self->open (@_) || return undef) if @_; 
   $self;
}

sub open {
    my ($self) = shift;
    $self->{filename} = shift;

    $self->{binmode}       = 'bytes';
    $self->{normalization} = 'NFC';
    my @args = ( $self->{filename} );

    if ( ref $_[0] eq "HASH" ) {
        my $opts = {};
        $opts = shift;
        $opts->{ lc $_ } = $opts->{$_} for ( keys %$opts );
        $self->{binmode} = 'utf-8'
            if exists $opts->{binmode} && $opts->{binmode} =~ /utf-?8/i;