view release on metacpan or  search on metacpan

BibTeX.pm  view on Meta::CPAN

# ----------------------------------------------------------------------
# NAME       : BibTeX.pm
# DESCRIPTION: Code for the LaTeX::BibTeX module; loads up everything 
#              needed for parsing BibTeX files (both Perl and C code).
# CREATED    : February 1997, Greg Ward
# MODIFIED   : 
# VERSION    : $Id: BibTeX.pm,v 1.27 2000/03/23 02:08:40 greg Rel $
# COPYRIGHT  : Copyright (c) 1997-2000 by Gregory P. Ward.  All rights reserved.
#
#              This file is part of the LaTeX::BibTeX library.  This
#              library is free software; you may redistribute it and/or
#              modify it under the same terms as Perl itself.
# ----------------------------------------------------------------------

package LaTeX::BibTeX;

require 5.004;                          # needed for LaTeX::BibTeX::Entry

use strict;
use UNIVERSAL qw(isa can);              # for 'check_class' subroutine
use Carp;
use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $AUTOLOAD);

require Exporter;
require DynaLoader;
@ISA = qw(Exporter DynaLoader);
%EXPORT_TAGS = (nodetypes => [qw(BTAST_STRING BTAST_MACRO BTAST_NUMBER)],
                metatypes => [qw(BTE_UNKNOWN BTE_REGULAR BTE_COMMENT 
                                 BTE_PREAMBLE BTE_MACRODEF)],
                nameparts => [qw(BTN_FIRST BTN_VON BTN_LAST BTN_JR BTN_NONE)],
                joinmethods => [qw(BTJ_MAYTIE BTJ_SPACE 
                                   BTJ_FORCETIE BTJ_NOTHING)],
                subs      => [qw(bibloop split_list
                                 purify_string change_case)],
                macrosubs => [qw(add_macro_text
                                 delete_macro
                                 delete_all_macros
                                 macro_length
                                 macro_text)]);
@EXPORT_OK = (@{$EXPORT_TAGS{'subs'}},
              @{$EXPORT_TAGS{'macrosubs'}},
              @{$EXPORT_TAGS{'nodetypes'}},
              @{$EXPORT_TAGS{'nameparts'}},
              @{$EXPORT_TAGS{'joinmethods'}},
              'check_class', 'display_list');
@EXPORT = @{$EXPORT_TAGS{'metatypes'}};

=head1 NAME

LaTeX::BibTeX - interface to read and parse BibTeX files

=head1 SYNOPSIS

   use LaTeX::BibTeX;

   $bibfile = new LaTeX::BibTeX::File "foo.bib";
   $newfile = new LaTeX::BibTeX::File ">newfoo.bib";

   while ($entry = new LaTeX::BibTeX::Entry $bibfile)
   {
      next unless $entry->parse_ok;

         .             # hack on $entry contents, using various
         .             # LaTeX::BibTeX::Entry methods
         .

      $entry->write ($newfile);
   }

=head1 DESCRIPTION

The C<LaTeX::BibTeX> module serves mainly as a high-level introduction to
the C<LaTeX::BibTeX> library, for both code and documentation purposes.
The code loads the two fundamental modules for processing BibTeX files
(C<LaTeX::BibTeX::File> and C<LaTeX::BibTeX::Entry>), and this
documentation gives a broad overview of the whole library that isn't
available in the documentation for the individual modules that comprise
it.

In addition, the C<LaTeX::BibTeX> module provides a number of
miscellaneous functions that are useful in processing BibTeX data
(especially the kind that comes from bibliographies as defined by BibTeX
0.99, rather than generic database files).  These functions don't
generally fit in the object-oriented class hierarchy centred around the
C<LaTeX::BibTeX::Entry> class, mainly because they are specific to
bibliographic data and operate on generic strings (rather than being
tied to a particular BibTeX entry).  These are also documented here, in
L<"MISCELLANEOUS FUNCTIONS">.

Note that every module described here begins with the C<LaTeX::BibTeX>
prefix.  For brevity, I have dropped this prefix from most class and
module names in the rest of this manual page (and in most of the other

BibTeX.pm  view on Meta::CPAN

Some of the various subroutines provided by the module are also
exportable.  C<bibloop>, C<split_list>, C<purify_string>, and
C<change_case> are all useful in everyday processing of BibTeX data, but
don't really fit anywhere in the class hierarchy.  They may be imported
from C<LaTeX::BibTeX> using the C<subs> export tag.  C<check_class> and
C<display_list> are also exportable, but only by name; they are not
included in any export tag.  (These two mainly exist for use by other
modules in the library.)  For instance, to use C<LaTeX::BibTeX> and
import the entry metatype constants and the common subroutines:

   use LaTeX::BibTeX qw(:metatypes :subs);

Another group of subroutines exists for direct manipulation of the macro
table maintained by the underlying C library.  These functions (see
L<"Macro table functions">, below) allow you to define, delete, and
query the value of BibTeX macros (or "abbreviations").  They may be
imported I<en masse> using the C<macrosubs> export tag:

   use LaTeX::BibTeX qw(:macrosubs);

=head1 CONSTANT VALUES

The C<LaTeX::BibTeX> module makes a number of constant values available.
These correspond to the values of various enumerated types in the
underlying C library, B<btparse>, and their meanings are more fully
explained in the B<btparse> documentation.  

Each group of constants is optionally exportable using an export tag
given in the descriptions below.

=over 4

=item Entry metatypes

C<BTE_UNKNOWN>, C<BTE_REGULAR>, C<BTE_COMMENT>, C<BTE_PREAMBLE>,
C<BTE_MACRODEF>.  The C<metatype> method in the C<Entry> class always
returns one of these values.  The latter three describe, respectively,
C<comment>, C<preamble>, and C<string> entries; C<BTE_REGULAR> describes
all other entry types.  C<BTE_UNKNOWN> should never be seen (it's mainly
useful for C code that might have to detect half-baked data structures).
See also L<btparse>.  Export tag: C<metatypes>.

=item AST node types

C<BTAST_STRING>, C<BTAST_MACRO>, C<BTAST_NUMBER>.  Used to distinguish
the three kinds of simple values---strings, macros, and numbers.  The
C<SimpleValue> class' C<type> method always returns one of these three
values.  See also L<LaTeX::BibTeX::Value>, L<btparse>.  Export tag:
C<nodetypes>.

=item Name parts

C<BTN_FIRST>, C<BTN_VON>, C<BTN_LAST>, C<BTN_JR>, C<BTN_NONE>.  Used to
specify the various parts of a name after it has been split up.  These
are mainly useful when using the C<NameFormat> class.  See also
L<bt_split_names> and L<bt_format_names>.  Export tag: C<nameparts>.

=item Join methods

C<BTJ_MAYTIE>, C<BTJ_SPACE>, C<BTJ_FORCETIE>, C<BTJ_NOTHING>.  Used to
tell the C<NameFormat> class how to join adjacent tokens together; see
L<LaTeX::BibTeX::NameFormat> and L<bt_format_names>.  Export tag:
C<joinmethods>.

=back

=head1 UTILITY FUNCTIONS

C<LaTeX::BibTeX> provides several functions that operate outside of the
normal class hierarchy.  Of these, only C<bibloop> is likely to be of
much use to you in writing everyday BibTeX-hacking programs; the other
two (C<check_class> and C<display_list>) are mainly provided for the use
of other modules in the library.  They are documented here mainly for
completeness, but also because they might conceivably be useful in other
circumstances.

=over 4

=item bibloop (ACTION, FILES [, DEST])

Loops over all entries in a set of BibTeX files, performing some
caller-supplied action on each entry.  FILES should be a reference to
the list of filenames to process, and ACTION a reference to a subroutine
that will be called on each entry.  DEST, if given, should be a
C<LaTeX::BibTeX::File> object (opened for output) to which entries might
be printed.

The subroutine referenced by ACTION is called with exactly one argument:
the C<LaTeX::BibTeX::Entry> object representing the entry currently being
processed.  Information about both the entry itself and the file where
it originated is available through this object; see
L<LaTeX::BibTeX::Entry>.  The ACTION subroutine is only called if the
entry was successfully parsed; any syntax errors will result in a
warning message being printed, and that entry being skipped.  Note that
I<all> successfully parsed entries are passed to the ACTION subroutine,
even C<preamble>, C<string>, and C<comment> entries.  To skip these
pseudo-entries and only process "regular" entries, then your action
subroutine should look something like this:

   sub action {
      my $entry = shift;
      return unless $entry->metatype == BTE_REGULAR;
      # process $entry ...
   }

If your action subroutine needs any more arguments, you can just create
a closure (anonymous subroutine) as a wrapper, and pass it to
C<bibloop>:

   sub action {
      my ($entry, $extra_stuff) = @_;
      # ...
   }

   my $extra = ...;
   LaTeX::BibTeX::bibloop (sub { &action ($_[0], $extra) }, \@files);

If the ACTION subroutine returns a true value and DEST was given, then
the processed entry will be written to DEST.