view release on metacpan or  search on metacpan

BibTeX.pm  view on Meta::CPAN

   my ($constname, $ok, $val);
   ($constname = $AUTOLOAD) =~ s/.*:://;
   carp ("Recursive AUTOLOAD--probable compilation error"), return
      if $constname eq 'constant';
   $val = constant ($constname)
      if $constname =~ /^BT/;
   croak ("Unknown LaTeX::BibTeX function: \"$constname\"")
      unless (defined $val);
   
#   print "          constant ($constname) returned \"$val\"\n";

   eval "sub $AUTOLOAD { $val }";
   $val;
}

# Load the two fundamental classes in the LaTeX::BibTeX hierarchy
require LaTeX::BibTeX::File;
require LaTeX::BibTeX::Entry;

# Load the XSUB code that's needed to parse BibTeX entries and 
# the strings in them
bootstrap LaTeX::BibTeX;

# For the curious: I don't put the call to &initialize into a BEGIN block,
# because then it would come before the bootstrap above, and &initialize is
# XS code -- bad!  (The manifestation of this error is rather interesting:
# Perl calls my AUTOLOAD routine, which then tries to call `constant', but
# that's also an as-yet-unloaded XS routine, so it falls back to AUTOLOAD,
# which tries to call `constant' again, ad infinitum.  The moral of the
# story: beware of what you put in BEGIN blocks in XS-dependent modules!)

&initialize;                            # these are both XS functions
END { &cleanup; }


=head1 EXPORTS

The C<LaTeX::BibTeX> module has a number of optional exports, most of
them constant values described in L<"CONSTANT VALUES"> below.  The
default exports are a subset of these constant values that are used
particularly often, the "entry metatypes" (also accessible via the
export tag C<metatypes>).  Thus, the following two lines are equivalent:

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

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.

BibTeX.pm  view on Meta::CPAN

=item initialize ()

=item cleanup ()

=back

=head2 Generic string-processing functions

=over 4

=item split_list (STRING, DELIM [, FILENAME [, LINE [, DESCRIPTION]]])

Splits a string on a fixed delimiter according to the BibTeX rules for
splitting up lists of names.  With BibTeX, the delimiter is hard-coded
as C<"and">; here, you can supply any string.  Instances of DELIM in
STRING are considered delimiters if they are at brace-depth zero,
surrounded by whitespace, and not at the beginning or end of STRING; the
comparison is case-insensitive.  See L<bt_split_names> for full details
of how splitting is done (it's I<not> the same as Perl's C<split>
function).

Returns the list of strings resulting from splitting STRING on DELIM.

=item purify_string (STRING [, OPTIONS])

"Purifies" STRING in the BibTeX way (usually for generation of sort
keys).  See L<bt_misc> for details; note that, unlike the C interface,
C<purify_string> does I<not> modify STRING in-place.  A purified copy of
the input string is returned.

OPTIONS is currently unused.

=item change_case (TRANFORM, STRING [, OPTIONS])

Transforms the case of STRING according to TRANSFORM (a single
character, one of C<'u'>, C<'l'>, or C<'t'>).  See L<bt_misc> for
details; again, C<change_case> differs from the C interface in that
STRING is not modified in-place---the input string is copied, and the
transformed copy is returned.

=back

=head2 Entry-parsing functions

Although these functions are provided by the C<LaTeX::BibTeX> module,
they are actually in the C<LaTeX::BibTeX::Entry> package.  That's because
they are implemented in C, and thus loaded with the XSUB code that
C<LaTeX::BibTeX> loads; however, they are actually methods in the
C<LaTeX::BibTeX::Entry> class.  Thus, they are documented as methods in
L<LaTeX::BibTeX::Entry>.

=over 4

=item parse (ENTRY_STRUCT, FILENAME, FILEHANDLE)

=item parse_s (ENTRY_STRUCT, TEXT)

=back

=head2 Macro table functions

These functions allow direct access to the macro table maintained by
B<btparse>, the C library underlying C<LaTeX::BibTeX>.  In the normal
course of events, macro definitions always accumulate, and are only
defined as a result of parsing a macro definition (C<@string>) entry.
B<btparse> never deletes old macro definitions for you, and doesn't have
any built-in default macros.  If, for example, you wish to start fresh
with new macros for every file, use C<delete_all_macros>.  If you wish
to pre-define certain macros, use C<add_macro_text>.  (But note that the
C<Bib> structure, as part of its mission to emulate BibTeX 0.99, defines
the standard "month name" macros for you.)

See also L<bt_macros> in the B<btparse> documentation for a description
of the C interface to these functions.

=over 4

=item add_macro_text (MACRO, TEXT [, FILENAME [, LINE]])

Defines a new macro, or redefines an old one.  MACRO is the name of the
macro, and TEXT is the text it should expand to.  FILENAME and LINE are
just used to generate any warnings about the macro definition.  The only
such warning occurs when you redefine an old macro: its value is
overridden, and C<add_macro_text()> issues a warning saying so.

=item delete_macro (MACRO)

Deletes a macro from the macro table.  If MACRO isn't defined,
takes no action.

=item delete_all_macros ()

Deletes all macros from the macro table.

=item macro_length (MACRO)

Returns the length of a macro's expansion text.  If the macro is
undefined, returns 0; no warning is issued.

=item macro_text (MACRO [, FILENAME [, LINE]])    

Returns the expansion text of a macro.  If the macro is not defined,
issues a warning and returns C<undef>.  FILENAME and LINE, if supplied,
are used for generating this warning; they should be supplied if you're
looking up the macro as a result of finding it in a file.

=back

=head2 Name-parsing functions

These are both private functions for the use of the C<Name> class, and
therefore are put in the C<LaTeX::BibTeX::Name> package.  You should use
the interface provided by that class for parsing names in the BibTeX
style.

=over 4

=item _split (NAME_STRUCT, NAME, FILENAME, LINE, NAME_NUM, KEEP_CSTRUCT)

=item free (NAME_STRUCT)