File Coverage

blib/lib/Text/BibTeX.pm
Criterion Covered Total %
statement 76 91 83.5
branch 16 30 53.3
condition 12 17 70.5
subroutine 22 23 95.6
pod 4 9 44.4
total 130 170 76.4


line stmt bran cond sub pod time code
1             # ----------------------------------------------------------------------
2             # NAME : BibTeX.pm
3             # DESCRIPTION: Code for the Text::BibTeX module; loads up everything
4             # needed for parsing BibTeX files (both Perl and C code).
5             # CREATED : February 1997, Greg Ward
6             # MODIFIED :
7             # VERSION : $Id: BibTeX.pm 7274 2009-05-03 17:18:14Z ambs $
8             # COPYRIGHT : Copyright (c) 1997-2000 by Gregory P. Ward. All rights reserved.
9             #
10             # This file is part of the Text::BibTeX library. This
11             # library is free software; you may redistribute it and/or
12             # modify it under the same terms as Perl itself.
13             # ----------------------------------------------------------------------
14              
15             package Text::BibTeX;
16 13     13   1048531 use Text::BibTeX::Name;
  13         31  
  13         375  
17 13     13   5767 use Text::BibTeX::NameFormat;
  13         31  
  13         488  
18              
19 13     13   173 use 5.008001; # needed for Text::BibTeX::Entry
  13         53  
20              
21 13     13   70 use strict;
  13         27  
  13         234  
22 13     13   67 use Carp;
  13         21  
  13         994  
23 13     13   66 use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $AUTOLOAD);
  13         25  
  13         2583  
24              
25             require Exporter;
26             require DynaLoader;
27              
28             our $VERSION='0.87';
29              
30             @ISA = qw(Exporter DynaLoader);
31             %EXPORT_TAGS = (nodetypes => [qw(BTAST_STRING BTAST_MACRO BTAST_NUMBER)],
32             metatypes => [qw(BTE_UNKNOWN BTE_REGULAR BTE_COMMENT
33             BTE_PREAMBLE BTE_MACRODEF)],
34             nameparts => [qw(BTN_FIRST BTN_VON BTN_LAST BTN_JR BTN_NONE)],
35             joinmethods => [qw(BTJ_MAYTIE BTJ_SPACE
36             BTJ_FORCETIE BTJ_NOTHING)],
37             subs => [qw(bibloop split_list
38             purify_string change_case)],
39             macrosubs => [qw(add_macro_text
40             delete_macro
41             delete_all_macros
42             macro_length
43             macro_text)]);
44             @EXPORT_OK = (@{$EXPORT_TAGS{'subs'}},
45             @{$EXPORT_TAGS{'macrosubs'}},
46             @{$EXPORT_TAGS{'nodetypes'}},
47             @{$EXPORT_TAGS{'nameparts'}},
48             @{$EXPORT_TAGS{'joinmethods'}},
49             'check_class', 'display_list' );
50             @EXPORT = @{$EXPORT_TAGS{'metatypes'}};
51              
52 13     13   6692 use Encode 'encode', 'decode';
  13         112341  
  13         895  
53 13     13   6637 use Unicode::Normalize;
  13         24166  
  13         983  
54              
55              
56             sub _process_result {
57 13     13   102 no strict 'refs';
  13         27  
  13         14781  
58 448     448   1034 my ( $self, $result, $encoding, $norm ) = @_;
59              
60 448   100     1227 $norm ||= "NFC"; # best to force it here.
61 448         567 my $normsub = \&{"$norm"}; # symbolic ref
  448         1316  
62 448 100       873 if ( $encoding eq "utf-8" ) {
63 17 50       41 if ( utf8::is_utf8($result) ) {
64 0         0 return $normsub->($result);
65             }
66             else {
67 17         44 return $normsub->( decode( $encoding, $result ) );
68             }
69             }
70 431         1587 else { return $result; }
71              
72             }
73              
74             sub _process_argument {
75 377     377   788 my ( $self, $value, $encoding ) = @_;
76              
77 377 100 100     957 if ( $encoding eq "utf-8" && utf8::is_utf8($value)) {
78 10         38 return encode( $encoding, $value );
79             }
80             else {
81 367         1618 return $value;
82             }
83             }
84              
85             sub split_list {
86 32     32 1 23925 my ( $field, $delim, $filename, $line, $desc, $opts ) = @_;
87 32   100     155 $opts ||= {};
88 32   100     117 $opts->{binmode} ||= 'bytes';
89 32   100     102 $opts->{normalization} ||= 'NFC';
90             return
91 32         285 map { Text::BibTeX->_process_result( $_, $opts->{binmode}, $opts->{normalization} ) }
  93         317  
92             Text::BibTeX::isplit_list( $field, $delim, $filename, $line, $desc );
93              
94             }
95              
96             =encoding UTF-8
97              
98             =head1 NAME
99              
100             Text::BibTeX - interface to read and parse BibTeX files
101              
102             =head1 SYNOPSIS
103              
104             use Text::BibTeX;
105              
106             my $bibfile = Text::BibTeX::File->new("foo.bib");
107             my $newfile = Text::BibTeX::File->new(">newfoo.bib");
108              
109             while ($entry = Text::BibTeX::Entry->new($bibfile))
110             {
111             next unless $entry->parse_ok;
112              
113             . # hack on $entry contents, using various
114             . # Text::BibTeX::Entry methods
115             .
116              
117             $entry->write ($newfile);
118             }
119              
120             =head1 DESCRIPTION
121              
122             The C module serves mainly as a high-level introduction to
123             the C library, for both code and documentation purposes.
124             The code loads the two fundamental modules for processing BibTeX files
125             (C and C), and this
126             documentation gives a broad overview of the whole library that isn't
127             available in the documentation for the individual modules that comprise
128             it.
129              
130             In addition, the C module provides a number of
131             miscellaneous functions that are useful in processing BibTeX data
132             (especially the kind that comes from bibliographies as defined by BibTeX
133             0.99, rather than generic database files). These functions don't
134             generally fit in the object-oriented class hierarchy centred around the
135             C class, mainly because they are specific to
136             bibliographic data and operate on generic strings (rather than being
137             tied to a particular BibTeX entry). These are also documented here, in
138             L<"MISCELLANEOUS FUNCTIONS">.
139              
140             Note that every module described here begins with the C
141             prefix. For brevity, I have dropped this prefix from most class and
142             module names in the rest of this manual page (and in most of the other
143             manual pages in the library).
144              
145             =head1 MODULES AND CLASSES
146              
147             The C library includes a number of modules, many of which
148             provide classes. Usually, the relationship is simple and obvious: a
149             module provides a class of the same name---for instance, the
150             C module provides the C class.
151             There are a few exceptions, though: most obviously, the C
152             module doesn't provide any classes itself, it merely loads two modules
153             (C and C) that do. The other
154             exceptions are mentioned in the descriptions below, and discussed in
155             detail in the documentation for the respective modules.
156              
157             The modules are presented roughly in order of increasing specialization:
158             the first three are essential for any program that processes BibTeX data
159             files, regardless of what kind of data they hold. The later modules are
160             specialized for use with bibliographic databases, and serve both to
161             emulate BibTeX 0.99's standard styles and to provide an example of how
162             to define a database structure through such specialized modules. Each
163             module is fully documented in its respective manual page.
164              
165             =over 4
166              
167             =item C
168              
169             Loads the two fundamental modules (C and C), and provides a
170             number of miscellaneous functions that don't fit anywhere in the class
171             hierarchy.
172              
173             =item C
174              
175             Provides an object-oriented interface to BibTeX database files. In
176             addition to the obvious attributes of filename and filehandle, the
177             "file" abstraction manages properties such as the database structure and
178             options for it.
179              
180             =item C
181              
182             Provides an object-oriented interface to BibTeX entries, which can be
183             parsed from C objects, arbitrary filehandles, or strings. Manages
184             all the properties of a single entry: type, key, fields, and values.
185             Also serves as the base class for the I
186             (described in detail in L).
187              
188             =item C
189              
190             Provides an object-oriented interface to I and I,
191             high-level constructs that can be used to represent the strings
192             associated with each field in an entry. Normally, field values are
193             returned simply as Perl strings, with macros expanded and multiple
194             strings "pasted" together. If desired, you can instruct C
195             to return C objects, which give you access to the
196             original form of the data.
197              
198             =item C
199              
200             Provides the C and C classes, which serve
201             primarily as base classes for the two kinds of classes that define
202             database structures. Read this man page for a comprehensive description
203             of the mechanism for implementing Perl classes analogous to BibTeX
204             "style files".
205              
206             =item C
207              
208             Provides the C and C classes, which serve two
209             purposes: they fulfill the same role as the standard style files of
210             BibTeX 0.99, and they give an example of how to write new database
211             structures. These ultimately derive from, respectively, the
212             C and C classes provided by the C
213             module.
214              
215             =item C
216              
217             One of the C class's base classes: handles the generation of
218             sort keys for sorting prior to output formatting.
219              
220             =item C
221              
222             One of the C class's base classes: handles the formatting of
223             bibliographic data for output in a markup language such as LaTeX.
224              
225             =item C
226              
227             A class used by the C structure and specific to bibliographic data
228             as defined by BibTeX itself: parses individual author names into
229             "first", "von", "last", and "jr" parts.
230              
231             =item C
232              
233             Also specific to bibliographic data: puts split-up names (as parsed by
234             the C class) back together in a custom way.
235              
236             =back
237              
238             For a first time through the library, you'll probably want to confine
239             your reading to L and L. The
240             other modules will come in handy eventually, especially if you need to
241             emulate BibTeX in a fairly fine grained way (e.g. parsing names,
242             generating sort keys). But for the simple database hacks that are the
243             bread and butter of the C library, the C and
244             C classes are the bulk of what you'll need. You may also find
245             some of the material in this manual page useful, namely L<"CONSTANT
246             VALUES"> and L<"UTILITY FUNCTIONS">.
247              
248             =cut
249              
250             sub AUTOLOAD
251             {
252             # This AUTOLOAD is used to 'autoload' constants from the constant()
253             # XS function.
254              
255             # print "AUTOLOAD: \$AUTOLOAD=$AUTOLOAD\n";
256              
257 13     13   36 my ($constname, $ok, $val);
258 13         77 ($constname = $AUTOLOAD) =~ s/.*:://;
259 13 50       51 carp ("Recursive AUTOLOAD--probable compilation error"), return
260             if $constname eq 'constant';
261 13 50       73 $val = constant ($constname)
262             if $constname =~ /^BT/;
263 13 50       37 croak ("Unknown Text::BibTeX function: \"$constname\"")
264             unless (defined $val);
265            
266             # print " constant ($constname) returned \"$val\"\n";
267              
268 13     14 0 556 eval "sub $AUTOLOAD { $val }";
  14     4 0 93  
  4     10 0 32  
  10     3 0 128  
  3     4 0 12  
  4         70  
269 13         178 $val;
270             }
271              
272             # Load the two fundamental classes in the Text::BibTeX hierarchy
273             require Text::BibTeX::File;
274             require Text::BibTeX::Entry;
275              
276             # Load the XSUB code that's needed to parse BibTeX entries and
277             # the strings in them
278             bootstrap Text::BibTeX;
279              
280             # For the curious: I don't put the call to &initialize into a BEGIN block,
281             # because then it would come before the bootstrap above, and &initialize is
282             # XS code -- bad! (The manifestation of this error is rather interesting:
283             # Perl calls my AUTOLOAD routine, which then tries to call `constant', but
284             # that's also an as-yet-unloaded XS routine, so it falls back to AUTOLOAD,
285             # which tries to call `constant' again, ad infinitum. The moral of the
286             # story: beware of what you put in BEGIN blocks in XS-dependent modules!)
287              
288             initialize(); # these are both XS functions
289 13     13   61987 END { &cleanup; }
290              
291             # This can't go in a BEGIN because of the .XS bootstrapping mechanism
292             _define_months();
293              
294             sub _define_months {
295 24     24   280 for my $month (qw.january february march april may june
296             july august september october november december.) {
297 156         669 add_macro_text(substr($month, 0, 3), ucfirst($month));
298             }
299             }
300              
301              
302             =head1 EXPORTS
303              
304             The C module has a number of optional exports, most of
305             them constant values described in L<"CONSTANT VALUES"> below. The
306             default exports are a subset of these constant values that are used
307             particularly often, the "entry metatypes" (also accessible via the
308             export tag C). Thus, the following two lines are equivalent:
309              
310             use Text::BibTeX;
311             use Text::BibTeX qw(:metatypes);
312              
313             Some of the various subroutines provided by the module are also
314             exportable. C, C, C, and
315             C are all useful in everyday processing of BibTeX data, but
316             don't really fit anywhere in the class hierarchy. They may be imported
317             from C using the C export tag. C and
318             C are also exportable, but only by name; they are not
319             included in any export tag. (These two mainly exist for use by other
320             modules in the library.) For instance, to use C and
321             import the entry metatype constants and the common subroutines:
322              
323             use Text::BibTeX qw(:metatypes :subs);
324              
325             Another group of subroutines exists for direct manipulation of the macro
326             table maintained by the underlying C library. These functions (see
327             L<"Macro table functions">, below) allow you to define, delete, and
328             query the value of BibTeX macros (or "abbreviations"). They may be
329             imported I using the C export tag:
330              
331             use Text::BibTeX qw(:macrosubs);
332              
333             =head1 CONSTANT VALUES
334              
335             The C module makes a number of constant values available.
336             These correspond to the values of various enumerated types in the
337             underlying C library, B, and their meanings are more fully
338             explained in the B documentation.
339              
340             Each group of constants is optionally exportable using an export tag
341             given in the descriptions below.
342              
343             =over 4
344              
345             =item Entry metatypes
346              
347             C, C, C, C,
348             C. The C method in the C class always
349             returns one of these values. The latter three describe, respectively,
350             C, C, and C entries; C describes
351             all other entry types. C should never be seen (it's mainly
352             useful for C code that might have to detect half-baked data structures).
353             See also L. Export tag: C.
354              
355             =item AST node types
356              
357             C, C, C. Used to distinguish
358             the three kinds of simple values---strings, macros, and numbers. The
359             C class' C method always returns one of these three
360             values. See also L, L. Export tag:
361             C.
362              
363             =item Name parts
364              
365             C, C, C, C, C. Used to
366             specify the various parts of a name after it has been split up. These
367             are mainly useful when using the C class. See also
368             L and L. Export tag: C.
369              
370             =item Join methods
371              
372             C, C, C, C. Used to
373             tell the C class how to join adjacent tokens together; see
374             L and L. Export tag:
375             C.
376              
377             =back
378              
379             =head1 UTILITY FUNCTIONS
380              
381             C provides several functions that operate outside of the
382             normal class hierarchy. Of these, only C is likely to be of
383             much use to you in writing everyday BibTeX-hacking programs; the other
384             two (C and C) are mainly provided for the use
385             of other modules in the library. They are documented here mainly for
386             completeness, but also because they might conceivably be useful in other
387             circumstances.
388              
389             =over 4
390              
391             =item bibloop (ACTION, FILES [, DEST])
392              
393             Loops over all entries in a set of BibTeX files, performing some
394             caller-supplied action on each entry. FILES should be a reference to
395             the list of filenames to process, and ACTION a reference to a subroutine
396             that will be called on each entry. DEST, if given, should be a
397             C object (opened for output) to which entries might
398             be printed.
399              
400             The subroutine referenced by ACTION is called with exactly one argument:
401             the C object representing the entry currently being
402             processed. Information about both the entry itself and the file where
403             it originated is available through this object; see
404             L. The ACTION subroutine is only called if the
405             entry was successfully parsed; any syntax errors will result in a
406             warning message being printed, and that entry being skipped. Note that
407             I successfully parsed entries are passed to the ACTION subroutine,
408             even C, C, and C entries. To skip these
409             pseudo-entries and only process "regular" entries, then your action
410             subroutine should look something like this:
411              
412             sub action {
413             my $entry = shift;
414             return unless $entry->metatype == BTE_REGULAR;
415             # process $entry ...
416             }
417              
418             If your action subroutine needs any more arguments, you can just create
419             a closure (anonymous subroutine) as a wrapper, and pass it to
420             C:
421              
422             sub action {
423             my ($entry, $extra_stuff) = @_;
424             # ...
425             }
426              
427             my $extra = ...;
428             Text::BibTeX::bibloop (sub { &action ($_[0], $extra) }, \@files);
429              
430             If the ACTION subroutine returns a true value and DEST was given, then
431             the processed entry will be written to DEST.
432              
433             =cut
434              
435             # ----------------------------------------------------------------------
436             # NAME : bibloop
437             # INPUT : $action
438             # $files
439             # $dest
440             # OUTPUT :
441             # RETURNS :
442             # DESCRIPTION: Loops over all entries in a set of files, calling
443             # &$action on each one.
444             # CREATED : summer 1996 (in original Bibtex.pm module)
445             # MODIFIED : May 1997 (added to Text::BibTeX with revisions)
446             # Feb 1998 (simplified and documented)
447             # ----------------------------------------------------------------------
448             sub bibloop (&$;$)
449             {
450 0     0 1 0 my ($action, $files, $dest) = @_;
451              
452 0         0 my $file;
453 0         0 while ($file = shift @$files)
454             {
455 0         0 my $bib = Text::BibTeX::File->new($file);
456            
457 0         0 while (! $bib->eof())
458             {
459 0         0 my $entry = Text::BibTeX::Entry->new($bib);
460 0 0       0 next unless $entry->parse_ok;
461              
462 0         0 my $result = &$action ($entry);
463 0 0 0     0 $entry->write ($dest, 1)
464             if ($result && $dest)
465             }
466             }
467             }
468              
469             =item check_class (PACKAGE, DESCRIPTION, SUPERCLASS, METHODS)
470              
471             Ensures that a PACKAGE implements a class meeting certain requirements.
472             First, it inspects Perl's symbol tables to ensure that a package named
473             PACKAGE actually exists. Then, it ensures that the class named by
474             PACKAGE derives from SUPERCLASS (using the universal method C).
475             This derivation might be through multiple inheritance, or through
476             several generations of a class hierarchy; the only requirement is that
477             SUPERCLASS is somewhere in PACKAGE's tree of base classes. Finally, it
478             checks that PACKAGE provides each method listed in METHODS (a reference
479             to a list of method names). This is done with the universal method
480             C, so the methods might actually come from one of PACKAGE's base
481             classes.
482              
483             DESCRIPTION should be a brief string describing the class that was
484             expected to be provided by PACKAGE. It is used for generating warning
485             messages if any of the class requirements are not met.
486              
487             This is mainly used by the supervisory code in
488             C, to ensure that user-supplied structure
489             modules meet the rules required of them.
490              
491             =cut
492              
493             # ----------------------------------------------------------------------
494             # NAME : check_class
495             # INPUT : $package - the name of a package that is expected to exist
496             # $description
497             # - string describing what the package is
498             # $superclass
499             # - a package name from which $package is expected
500             # to inherit
501             # $methods - ref to list of method names expected to be
502             # available via $package (possibly through
503             # inheritance)
504             # OUTPUT :
505             # RETURNS :
506             # DESCRIPTION: Makes sure that a package named by $package exists
507             # (by following the chain of symbol tables starting
508             # at %::) Dies if not.
509             # CALLERS : Text::BibTeX::Structure::new
510             # CREATED : 1997/09/09, GPW
511             # MODIFIED :
512             # ----------------------------------------------------------------------
513             sub check_class
514             {
515 2     2 1 7 my ($package, $description, $superclass, $methods) = @_;
516 2         16 my (@components, $component, $prev_symtab);
517              
518 2         8 @components = split ('::', $package);
519 2         4 $prev_symtab = \%::;
520 2         5 while (@components)
521             {
522 6         12 $component = (shift @components) . '::';
523 6 50       25 unless (defined ($prev_symtab = $prev_symtab->{$component}))
524             {
525 0         0 die "Text::BibTeX::Structure: $description " .
526             "\"$package\" apparently not supplied\n";
527             }
528             }
529              
530 2 50 33     33 if ($superclass && ! $package->isa($superclass))
531             {
532 0         0 die "Text::BibTeX::Structure: $description \"$package\" " .
533             "improperly defined: ! isa ($superclass)\n";
534             }
535              
536 2         5 my $method;
537 2         6 for $method (@$methods)
538             {
539 3 50       18 unless ($package->can($method))
540             {
541 0         0 die "Text::BibTeX::Structure: $description \"$package\" " .
542             "improperly defined: no method \"$method\"\n";
543             }
544             }
545             } # &check_class
546              
547              
548             =item display_list (LIST, QUOTE)
549              
550             Converts a list of strings to the grammatical conventions of a human
551             language (currently, only English rules are supported). LIST must be a
552             reference to a list of strings. If this list is empty, the empty string
553             is returned. If it has one element, then just that element is
554             returned. If it has two elements, then they are joined with the string
555             C<" and "> and the resulting string is returned. Otherwise, the list
556             has I elements for I E= 3; elements 1..I-1 are joined with
557             commas, and the final element is tacked on with an intervening
558             C<", and ">.
559              
560             If QUOTE is true, then each string is encased in single quotes before
561             anything else is done.
562              
563             This is used elsewhere in the library for two very distinct purposes:
564             for generating warning messages describing lists of fields that should
565             be present or are conflicting in an entry, and for generating lists of
566             author names in formatted bibliographies.
567              
568             =cut
569              
570             # ----------------------------------------------------------------------
571             # NAME : display_list
572             # INPUT : $list - reference to list of strings to join
573             # $quote - if true, they will be single-quoted before join
574             # OUTPUT :
575             # RETURNS : elements of @$list, joined together into a single string
576             # with commas and 'and' as appropriate
577             # DESCRIPTION: Formats a list of strings for display as English text.
578             # CALLERS : Text::BibTeX::Structure::check_interacting_fields
579             # CALLS :
580             # CREATED : 1997/09/23, GPW
581             # MODIFIED :
582             # ----------------------------------------------------------------------
583             sub display_list
584             {
585 9     9 1 20 my ($list, $quote) = @_;
586 9         26 my @list;
587              
588 9 50       22 return '' if @$list == 0;
589 9 50       26 @list = $quote ? map { "'$_'" } @$list : @$list;
  0         0  
590 9 100       25 return $list[0] if @list == 1;
591 7 50       39 return $list[0] . ' and ' . $list[1] if @list == 2;
592 0         0 return join (', ', @list[0 .. ($#list-1)]) . ', and ' . $list[-1];
593             }
594              
595              
596             =back
597              
598             =head1 MISCELLANEOUS FUNCTIONS
599              
600             In addition to loading the C and C modules, C
601             loads the XSUB code which bridges the Perl modules to the underlying C
602             library, B. This XSUB code provides a number of miscellaneous
603             utility functions, most of which are put into other packages in the
604             C family for use by the corresponding classes. (For
605             instance, the XSUB code loaded by C provides a function
606             C, which is actually documented as the
607             C method of the C class---see
608             L. However, for completeness this function---and
609             all the other functions that become available when you C
610             Text::BibTeX>---are at least mentioned here. The only functions from
611             this group that you're ever likely to use are described in L<"Generic
612             string-processing functions">.
613              
614             =head2 Startup/shutdown functions
615              
616             These just initialize and shutdown the underlying C library. Don't call
617             either one of them; the C startup/shutdown code takes care
618             of it as appropriate. They're just mentioned here for completeness.
619              
620             =over 4
621              
622             =item initialize ()
623              
624             =item cleanup ()
625              
626             =back
627              
628             =head2 Generic string-processing functions
629              
630             =over 4
631              
632             =item split_list (STRING, DELIM [, FILENAME [, LINE [, DESCRIPTION [, OPTS]]]])
633              
634             Splits a string on a fixed delimiter according to the BibTeX rules for
635             splitting up lists of names. With BibTeX, the delimiter is hard-coded
636             as C<"and">; here, you can supply any string. Instances of DELIM in
637             STRING are considered delimiters if they are at brace-depth zero,
638             surrounded by whitespace, and not at the beginning or end of STRING; the
639             comparison is case-insensitive. See L for full details
640             of how splitting is done (it's I the same as Perl's C
641             function). OPTS is a hash ref of the same binmode and normalization
642             arguments as with, e.g. Text::BibTeX::File->open(). split_list calls isplit_list()
643             internally but handles UTF-8 conversion and normalization, if requested.
644              
645             Returns the list of strings resulting from splitting STRING on DELIM.
646              
647             =item isplit_list (STRING, DELIM [, FILENAME [, LINE [, DESCRIPTION]]])
648              
649             Splits a string on a fixed delimiter according to the BibTeX rules for
650             splitting up lists of names. With BibTeX, the delimiter is hard-coded
651             as C<"and">; here, you can supply any string. Instances of DELIM in
652             STRING are considered delimiters if they are at brace-depth zero,
653             surrounded by whitespace, and not at the beginning or end of STRING; the
654             comparison is case-insensitive. See L for full details
655             of how splitting is done (it's I the same as Perl's C
656             function). This function returns bytes. Use Text::BibTeX::split_list to specify
657             the same binmode and normalization arguments as with, e.g. Text::BibTeX::File->open()
658              
659             Returns the list of strings resulting from splitting STRING on DELIM.
660              
661             =item purify_string (STRING [, OPTIONS])
662              
663             "Purifies" STRING in the BibTeX way (usually for generation of sort
664             keys). See L for details; note that, unlike the C interface,
665             C does I modify STRING in-place. A purified copy of
666             the input string is returned.
667              
668             OPTIONS is currently unused.
669              
670             =item change_case (TRANSFORM, STRING [, OPTIONS])
671              
672             Transforms the case of STRING according to TRANSFORM (a single
673             character, one of C<'u'>, C<'l'>, or C<'t'>). See L for
674             details; again, C differs from the C interface in that
675             STRING is not modified in-place---the input string is copied, and the
676             transformed copy is returned.
677              
678             =back
679              
680             =head2 Entry-parsing functions
681              
682             Although these functions are provided by the C module,
683             they are actually in the C package. That's because
684             they are implemented in C, and thus loaded with the XSUB code that
685             C loads; however, they are actually methods in the
686             C class. Thus, they are documented as methods in
687             L.
688              
689             =over 4
690              
691             =item parse (ENTRY_STRUCT, FILENAME, FILEHANDLE)
692              
693             =item parse_s (ENTRY_STRUCT, TEXT)
694              
695             =back
696              
697             =head2 Macro table functions
698              
699             These functions allow direct access to the macro table maintained by
700             B, the C library underlying C. In the normal
701             course of events, macro definitions always accumulate, and are only
702             defined as a result of parsing a macro definition (C<@string>) entry.
703             B never deletes old macro definitions for you, and doesn't have
704             any built-in default macros. If, for example, you wish to start fresh
705             with new macros for every file, use C. If you wish
706             to pre-define certain macros, use C. (But note that the
707             C structure, as part of its mission to emulate BibTeX 0.99, defines
708             the standard "month name" macros for you.)
709              
710             See also L in the B documentation for a description
711             of the C interface to these functions.
712              
713             =over 4
714              
715             =item add_macro_text (MACRO, TEXT [, FILENAME [, LINE]])
716              
717             Defines a new macro, or redefines an old one. MACRO is the name of the
718             macro, and TEXT is the text it should expand to. FILENAME and LINE are
719             just used to generate any warnings about the macro definition. The only
720             such warning occurs when you redefine an old macro: its value is
721             overridden, and C issues a warning saying so.
722              
723             =item delete_macro (MACRO)
724              
725             Deletes a macro from the macro table. If MACRO isn't defined,
726             takes no action.
727              
728             =item delete_all_macros ()
729              
730             Deletes all macros from the macro table, even the predefined month
731             names.
732              
733             =item macro_length (MACRO)
734              
735             Returns the length of a macro's expansion text. If the macro is
736             undefined, returns 0; no warning is issued.
737              
738             =item macro_text (MACRO [, FILENAME [, LINE]])
739              
740             Returns the expansion text of a macro. If the macro is not defined,
741             issues a warning and returns C. FILENAME and LINE, if supplied,
742             are used for generating this warning; they should be supplied if you're
743             looking up the macro as a result of finding it in a file.
744              
745             =back
746              
747             =head2 Name-parsing functions
748              
749             These are both private functions for the use of the C class, and
750             therefore are put in the C package. You should use
751             the interface provided by that class for parsing names in the BibTeX
752             style.
753              
754             =over 4
755              
756             =item _split (NAME_STRUCT, NAME, FILENAME, LINE, NAME_NUM, KEEP_CSTRUCT)
757              
758             =item free (NAME_STRUCT)
759              
760             =back
761              
762             =head2 Name-formatting functions
763              
764             These are private functions for the use of the C class, and
765             therefore are put in the C package. You
766             should use the interface provided by that class for formatting names in
767             the BibTeX style.
768              
769             =over 4
770              
771             =item create ([PARTS [, ABBREV_FIRST]])
772              
773             =item free (FORMAT_STRUCT)
774              
775             =item _set_text (FORMAT_STRUCT, PART, PRE_PART, POST_PART, PRE_TOKEN, POST_TOKEN)
776              
777             =item _set_options (FORMAT_STRUCT, PART, ABBREV, JOIN_TOKENS, JOIN_PART)
778              
779             =item format_name (NAME_STRUCT, FORMAT_STRUCT)
780              
781             =back
782              
783             =head1 BUGS AND LIMITATIONS
784              
785             C inherits several limitations from its base C library,
786             B; see L for details. In addition,
787             C will not work with a Perl binary built using the C
788             library. This is because Perl's I/O abstraction layer does not extend to
789             third-party C libraries that use stdio, and B most certainly does
790             use stdio.
791              
792             =head1 SEE ALSO
793              
794             L, L, L,
795             L
796              
797             =head1 AUTHOR
798              
799             Greg Ward
800              
801             =head1 COPYRIGHT
802              
803             Copyright (c) 1997-2000 by Gregory P. Ward. All rights reserved. This file
804             is part of the Text::BibTeX library. This library is free software; you
805             may redistribute it and/or modify it under the same terms as Perl itself.
806              
807             =cut
808              
809             1;