.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Text::BibTeX 3pm" .TH Text::BibTeX 3pm "2019-07-17" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Text::BibTeX \- interface to read and parse BibTeX files .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Text::BibTeX; \& \& my $bibfile = Text::BibTeX::File\->new("foo.bib"); \& my $newfile = Text::BibTeX::File\->new(">newfoo.bib"); \& \& while ($entry = Text::BibTeX::Entry\->new($bibfile)) \& { \& next unless $entry\->parse_ok; \& \& . # hack on $entry contents, using various \& . # Text::BibTeX::Entry methods \& . \& \& $entry\->write ($newfile); \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Text::BibTeX\*(C'\fR module serves mainly as a high-level introduction to the \f(CW\*(C`Text::BibTeX\*(C'\fR library, for both code and documentation purposes. The code loads the two fundamental modules for processing BibTeX files (\f(CW\*(C`Text::BibTeX::File\*(C'\fR and \f(CW\*(C`Text::BibTeX::Entry\*(C'\fR), 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. .PP In addition, the \f(CW\*(C`Text::BibTeX\*(C'\fR 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 \&\f(CW\*(C`Text::BibTeX::Entry\*(C'\fR 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"\s-1MISCELLANEOUS FUNCTIONS\*(R"\s0. .PP Note that every module described here begins with the \f(CW\*(C`Text::BibTeX\*(C'\fR 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 manual pages in the library). .SH "MODULES AND CLASSES" .IX Header "MODULES AND CLASSES" The \f(CW\*(C`Text::BibTeX\*(C'\fR library includes a number of modules, many of which provide classes. Usually, the relationship is simple and obvious: a module provides a class of the same name\-\-\-for instance, the \&\f(CW\*(C`Text::BibTeX::Entry\*(C'\fR module provides the \f(CW\*(C`Text::BibTeX::Entry\*(C'\fR class. There are a few exceptions, though: most obviously, the \f(CW\*(C`Text::BibTeX\*(C'\fR module doesn't provide any classes itself, it merely loads two modules (\f(CW\*(C`Text::BibTeX::Entry\*(C'\fR and \f(CW\*(C`Text::BibTeX::File\*(C'\fR) that do. The other exceptions are mentioned in the descriptions below, and discussed in detail in the documentation for the respective modules. .PP The modules are presented roughly in order of increasing specialization: the first three are essential for any program that processes BibTeX data files, regardless of what kind of data they hold. The later modules are specialized for use with bibliographic databases, and serve both to emulate BibTeX 0.99's standard styles and to provide an example of how to define a database structure through such specialized modules. Each module is fully documented in its respective manual page. .ie n .IP """Text::BibTeX""" 4 .el .IP "\f(CWText::BibTeX\fR" 4 .IX Item "Text::BibTeX" Loads the two fundamental modules (\f(CW\*(C`Entry\*(C'\fR and \f(CW\*(C`File\*(C'\fR), and provides a number of miscellaneous functions that don't fit anywhere in the class hierarchy. .ie n .IP """Text::BibTeX::File""" 4 .el .IP "\f(CWText::BibTeX::File\fR" 4 .IX Item "Text::BibTeX::File" Provides an object-oriented interface to BibTeX database files. In addition to the obvious attributes of filename and filehandle, the \&\*(L"file\*(R" abstraction manages properties such as the database structure and options for it. .ie n .IP """Text::BibTeX::Entry""" 4 .el .IP "\f(CWText::BibTeX::Entry\fR" 4 .IX Item "Text::BibTeX::Entry" Provides an object-oriented interface to BibTeX entries, which can be parsed from \f(CW\*(C`File\*(C'\fR objects, arbitrary filehandles, or strings. Manages all the properties of a single entry: type, key, fields, and values. Also serves as the base class for the \fIstructured entry classes\fR (described in detail in Text::BibTeX::Structure). .ie n .IP """Text::BibTeX::Value""" 4 .el .IP "\f(CWText::BibTeX::Value\fR" 4 .IX Item "Text::BibTeX::Value" Provides an object-oriented interface to \fIvalues\fR and \fIsimple values\fR, high-level constructs that can be used to represent the strings associated with each field in an entry. Normally, field values are returned simply as Perl strings, with macros expanded and multiple strings \*(L"pasted\*(R" together. If desired, you can instruct \f(CW\*(C`Text::BibTeX\*(C'\fR to return \f(CW\*(C`Text::BibTeX::Value\*(C'\fR objects, which give you access to the original form of the data. .ie n .IP """Text::BibTeX::Structure""" 4 .el .IP "\f(CWText::BibTeX::Structure\fR" 4 .IX Item "Text::BibTeX::Structure" Provides the \f(CW\*(C`Structure\*(C'\fR and \f(CW\*(C`StructuredEntry\*(C'\fR classes, which serve primarily as base classes for the two kinds of classes that define database structures. Read this man page for a comprehensive description of the mechanism for implementing Perl classes analogous to BibTeX \&\*(L"style files\*(R". .ie n .IP """Text::BibTeX::Bib""" 4 .el .IP "\f(CWText::BibTeX::Bib\fR" 4 .IX Item "Text::BibTeX::Bib" Provides the \f(CW\*(C`BibStructure\*(C'\fR and \f(CW\*(C`BibEntry\*(C'\fR classes, which serve two purposes: they fulfill the same role as the standard style files of BibTeX 0.99, and they give an example of how to write new database structures. These ultimately derive from, respectively, the \&\f(CW\*(C`Structure\*(C'\fR and \f(CW\*(C`StructuredEntry\*(C'\fR classes provided by the \f(CW\*(C`Structure\*(C'\fR module. .ie n .IP """Text::BibTeX::BibSort""" 4 .el .IP "\f(CWText::BibTeX::BibSort\fR" 4 .IX Item "Text::BibTeX::BibSort" One of the \f(CW\*(C`BibEntry\*(C'\fR class's base classes: handles the generation of sort keys for sorting prior to output formatting. .ie n .IP """Text::BibTeX::BibFormat""" 4 .el .IP "\f(CWText::BibTeX::BibFormat\fR" 4 .IX Item "Text::BibTeX::BibFormat" One of the \f(CW\*(C`BibEntry\*(C'\fR class's base classes: handles the formatting of bibliographic data for output in a markup language such as LaTeX. .ie n .IP """Text::BibTeX::Name""" 4 .el .IP "\f(CWText::BibTeX::Name\fR" 4 .IX Item "Text::BibTeX::Name" A class used by the \f(CW\*(C`Bib\*(C'\fR structure and specific to bibliographic data as defined by BibTeX itself: parses individual author names into \&\*(L"first\*(R", \*(L"von\*(R", \*(L"last\*(R", and \*(L"jr\*(R" parts. .ie n .IP """Text::BibTeX::NameFormat""" 4 .el .IP "\f(CWText::BibTeX::NameFormat\fR" 4 .IX Item "Text::BibTeX::NameFormat" Also specific to bibliographic data: puts split-up names (as parsed by the \f(CW\*(C`Name\*(C'\fR class) back together in a custom way. .PP For a first time through the library, you'll probably want to confine your reading to Text::BibTeX::File and Text::BibTeX::Entry. The other modules will come in handy eventually, especially if you need to emulate BibTeX in a fairly fine grained way (e.g. parsing names, generating sort keys). But for the simple database hacks that are the bread and butter of the \f(CW\*(C`Text::BibTeX\*(C'\fR library, the \f(CW\*(C`File\*(C'\fR and \&\f(CW\*(C`Entry\*(C'\fR classes are the bulk of what you'll need. You may also find some of the material in this manual page useful, namely \*(L"\s-1CONSTANT VALUES\*(R"\s0 and \*(L"\s-1UTILITY FUNCTIONS\*(R"\s0. .SH "EXPORTS" .IX Header "EXPORTS" The \f(CW\*(C`Text::BibTeX\*(C'\fR module has a number of optional exports, most of them constant values described in \*(L"\s-1CONSTANT VALUES\*(R"\s0 below. The default exports are a subset of these constant values that are used particularly often, the \*(L"entry metatypes\*(R" (also accessible via the export tag \f(CW\*(C`metatypes\*(C'\fR). Thus, the following two lines are equivalent: .PP .Vb 2 \& use Text::BibTeX; \& use Text::BibTeX qw(:metatypes); .Ve .PP Some of the various subroutines provided by the module are also exportable. \f(CW\*(C`bibloop\*(C'\fR, \f(CW\*(C`split_list\*(C'\fR, \f(CW\*(C`purify_string\*(C'\fR, and \&\f(CW\*(C`change_case\*(C'\fR are all useful in everyday processing of BibTeX data, but don't really fit anywhere in the class hierarchy. They may be imported from \f(CW\*(C`Text::BibTeX\*(C'\fR using the \f(CW\*(C`subs\*(C'\fR export tag. \f(CW\*(C`check_class\*(C'\fR and \&\f(CW\*(C`display_list\*(C'\fR 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 \f(CW\*(C`Text::BibTeX\*(C'\fR and import the entry metatype constants and the common subroutines: .PP .Vb 1 \& use Text::BibTeX qw(:metatypes :subs); .Ve .PP 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\*(R", below) allow you to define, delete, and query the value of BibTeX macros (or \*(L"abbreviations\*(R"). They may be imported \fIen masse\fR using the \f(CW\*(C`macrosubs\*(C'\fR export tag: .PP .Vb 1 \& use Text::BibTeX qw(:macrosubs); .Ve .SH "CONSTANT VALUES" .IX Header "CONSTANT VALUES" The \f(CW\*(C`Text::BibTeX\*(C'\fR module makes a number of constant values available. These correspond to the values of various enumerated types in the underlying C library, \fBbtparse\fR, and their meanings are more fully explained in the \fBbtparse\fR documentation. .PP Each group of constants is optionally exportable using an export tag given in the descriptions below. .IP "Entry metatypes" 4 .IX Item "Entry metatypes" \&\f(CW\*(C`BTE_UNKNOWN\*(C'\fR, \f(CW\*(C`BTE_REGULAR\*(C'\fR, \f(CW\*(C`BTE_COMMENT\*(C'\fR, \f(CW\*(C`BTE_PREAMBLE\*(C'\fR, \&\f(CW\*(C`BTE_MACRODEF\*(C'\fR. The \f(CW\*(C`metatype\*(C'\fR method in the \f(CW\*(C`Entry\*(C'\fR class always returns one of these values. The latter three describe, respectively, \&\f(CW\*(C`comment\*(C'\fR, \f(CW\*(C`preamble\*(C'\fR, and \f(CW\*(C`string\*(C'\fR entries; \f(CW\*(C`BTE_REGULAR\*(C'\fR describes all other entry types. \f(CW\*(C`BTE_UNKNOWN\*(C'\fR should never be seen (it's mainly useful for C code that might have to detect half-baked data structures). See also btparse. Export tag: \f(CW\*(C`metatypes\*(C'\fR. .IP "\s-1AST\s0 node types" 4 .IX Item "AST node types" \&\f(CW\*(C`BTAST_STRING\*(C'\fR, \f(CW\*(C`BTAST_MACRO\*(C'\fR, \f(CW\*(C`BTAST_NUMBER\*(C'\fR. Used to distinguish the three kinds of simple values\-\-\-strings, macros, and numbers. The \&\f(CW\*(C`SimpleValue\*(C'\fR class' \f(CW\*(C`type\*(C'\fR method always returns one of these three values. See also Text::BibTeX::Value, btparse. Export tag: \&\f(CW\*(C`nodetypes\*(C'\fR. .IP "Name parts" 4 .IX Item "Name parts" \&\f(CW\*(C`BTN_FIRST\*(C'\fR, \f(CW\*(C`BTN_VON\*(C'\fR, \f(CW\*(C`BTN_LAST\*(C'\fR, \f(CW\*(C`BTN_JR\*(C'\fR, \f(CW\*(C`BTN_NONE\*(C'\fR. Used to specify the various parts of a name after it has been split up. These are mainly useful when using the \f(CW\*(C`NameFormat\*(C'\fR class. See also bt_split_names and bt_format_names. Export tag: \f(CW\*(C`nameparts\*(C'\fR. .IP "Join methods" 4 .IX Item "Join methods" \&\f(CW\*(C`BTJ_MAYTIE\*(C'\fR, \f(CW\*(C`BTJ_SPACE\*(C'\fR, \f(CW\*(C`BTJ_FORCETIE\*(C'\fR, \f(CW\*(C`BTJ_NOTHING\*(C'\fR. Used to tell the \f(CW\*(C`NameFormat\*(C'\fR class how to join adjacent tokens together; see Text::BibTeX::NameFormat and bt_format_names. Export tag: \&\f(CW\*(C`joinmethods\*(C'\fR. .SH "UTILITY FUNCTIONS" .IX Header "UTILITY FUNCTIONS" \&\f(CW\*(C`Text::BibTeX\*(C'\fR provides several functions that operate outside of the normal class hierarchy. Of these, only \f(CW\*(C`bibloop\*(C'\fR is likely to be of much use to you in writing everyday BibTeX-hacking programs; the other two (\f(CW\*(C`check_class\*(C'\fR and \f(CW\*(C`display_list\*(C'\fR) 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. .IP "bibloop (\s-1ACTION, FILES\s0 [, \s-1DEST\s0])" 4 .IX Item "bibloop (ACTION, FILES [, DEST])" Loops over all entries in a set of BibTeX files, performing some caller-supplied action on each entry. \s-1FILES\s0 should be a reference to the list of filenames to process, and \s-1ACTION\s0 a reference to a subroutine that will be called on each entry. \s-1DEST,\s0 if given, should be a \&\f(CW\*(C`Text::BibTeX::File\*(C'\fR object (opened for output) to which entries might be printed. .Sp The subroutine referenced by \s-1ACTION\s0 is called with exactly one argument: the \f(CW\*(C`Text::BibTeX::Entry\*(C'\fR 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 Text::BibTeX::Entry. The \s-1ACTION\s0 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 \&\fIall\fR successfully parsed entries are passed to the \s-1ACTION\s0 subroutine, even \f(CW\*(C`preamble\*(C'\fR, \f(CW\*(C`string\*(C'\fR, and \f(CW\*(C`comment\*(C'\fR entries. To skip these pseudo-entries and only process \*(L"regular\*(R" entries, then your action subroutine should look something like this: .Sp .Vb 5 \& sub action { \& my $entry = shift; \& return unless $entry\->metatype == BTE_REGULAR; \& # process $entry ... \& } .Ve .Sp If your action subroutine needs any more arguments, you can just create a closure (anonymous subroutine) as a wrapper, and pass it to \&\f(CW\*(C`bibloop\*(C'\fR: .Sp .Vb 4 \& sub action { \& my ($entry, $extra_stuff) = @_; \& # ... \& } \& \& my $extra = ...; \& Text::BibTeX::bibloop (sub { &action ($_[0], $extra) }, \e@files); .Ve .Sp If the \s-1ACTION\s0 subroutine returns a true value and \s-1DEST\s0 was given, then the processed entry will be written to \s-1DEST.\s0 .IP "check_class (\s-1PACKAGE, DESCRIPTION, SUPERCLASS, METHODS\s0)" 4 .IX Item "check_class (PACKAGE, DESCRIPTION, SUPERCLASS, METHODS)" Ensures that a \s-1PACKAGE\s0 implements a class meeting certain requirements. First, it inspects Perl's symbol tables to ensure that a package named \&\s-1PACKAGE\s0 actually exists. Then, it ensures that the class named by \&\s-1PACKAGE\s0 derives from \s-1SUPERCLASS\s0 (using the universal method \f(CW\*(C`isa\*(C'\fR). This derivation might be through multiple inheritance, or through several generations of a class hierarchy; the only requirement is that \&\s-1SUPERCLASS\s0 is somewhere in \s-1PACKAGE\s0's tree of base classes. Finally, it checks that \s-1PACKAGE\s0 provides each method listed in \s-1METHODS\s0 (a reference to a list of method names). This is done with the universal method \&\f(CW\*(C`can\*(C'\fR, so the methods might actually come from one of \s-1PACKAGE\s0's base classes. .Sp \&\s-1DESCRIPTION\s0 should be a brief string describing the class that was expected to be provided by \s-1PACKAGE.\s0 It is used for generating warning messages if any of the class requirements are not met. .Sp This is mainly used by the supervisory code in \&\f(CW\*(C`Text::BibTeX::Structure\*(C'\fR, to ensure that user-supplied structure modules meet the rules required of them. .IP "display_list (\s-1LIST, QUOTE\s0)" 4 .IX Item "display_list (LIST, QUOTE)" Converts a list of strings to the grammatical conventions of a human language (currently, only English rules are supported). \s-1LIST\s0 must be a reference to a list of strings. If this list is empty, the empty string is returned. If it has one element, then just that element is returned. If it has two elements, then they are joined with the string \&\f(CW" and "\fR and the resulting string is returned. Otherwise, the list has \fIN\fR elements for \fIN\fR >= 3; elements 1..\fIN\fR\-1 are joined with commas, and the final element is tacked on with an intervening \&\f(CW", and "\fR. .Sp If \s-1QUOTE\s0 is true, then each string is encased in single quotes before anything else is done. .Sp This is used elsewhere in the library for two very distinct purposes: for generating warning messages describing lists of fields that should be present or are conflicting in an entry, and for generating lists of author names in formatted bibliographies. .SH "MISCELLANEOUS FUNCTIONS" .IX Header "MISCELLANEOUS FUNCTIONS" In addition to loading the \f(CW\*(C`File\*(C'\fR and \f(CW\*(C`Entry\*(C'\fR modules, \f(CW\*(C`Text::BibTeX\*(C'\fR loads the \s-1XSUB\s0 code which bridges the Perl modules to the underlying C library, \fBbtparse\fR. This \s-1XSUB\s0 code provides a number of miscellaneous utility functions, most of which are put into other packages in the \&\f(CW\*(C`Text::BibTeX\*(C'\fR family for use by the corresponding classes. (For instance, the \s-1XSUB\s0 code loaded by \f(CW\*(C`Text::BibTeX\*(C'\fR provides a function \&\f(CW\*(C`Text::BibTeX::Entry::parse\*(C'\fR, which is actually documented as the \&\f(CW\*(C`parse\*(C'\fR method of the \f(CW\*(C`Text::BibTeX::Entry\*(C'\fR class\-\-\-see Text::BibTeX::Entry. However, for completeness this function\-\-\-and all the other functions that become available when you \f(CW\*(C`use Text::BibTeX\*(C'\fR\-\-\-are at least mentioned here. The only functions from this group that you're ever likely to use are described in \*(L"Generic string-processing functions\*(R". .SS "Startup/shutdown functions" .IX Subsection "Startup/shutdown functions" These just initialize and shutdown the underlying C library. Don't call either one of them; the \f(CW\*(C`Text::BibTeX\*(C'\fR startup/shutdown code takes care of it as appropriate. They're just mentioned here for completeness. .IP "initialize ()" 4 .IX Item "initialize ()" .PD 0 .IP "cleanup ()" 4 .IX Item "cleanup ()" .PD .SS "Generic string-processing functions" .IX Subsection "Generic string-processing functions" .IP "split_list (\s-1STRING, DELIM\s0 [, \s-1FILENAME\s0 [, \s-1LINE\s0 [, \s-1DESCRIPTION\s0 [, \s-1OPTS\s0]]]])" 4 .IX Item "split_list (STRING, DELIM [, FILENAME [, LINE [, DESCRIPTION [, OPTS]]]])" 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 \f(CW"and"\fR; here, you can supply any string. Instances of \s-1DELIM\s0 in \&\s-1STRING\s0 are considered delimiters if they are at brace-depth zero, surrounded by whitespace, and not at the beginning or end of \s-1STRING\s0; the comparison is case-insensitive. See bt_split_names for full details of how splitting is done (it's \fInot\fR the same as Perl's \f(CW\*(C`split\*(C'\fR function). \s-1OPTS\s0 is a hash ref of the same binmode and normalization arguments as with, e.g. Text::BibTeX::File\->\fBopen()\fR. split_list calls \fBisplit_list()\fR internally but handles \s-1UTF\-8\s0 conversion and normalization, if requested. .Sp Returns the list of strings resulting from splitting \s-1STRING\s0 on \s-1DELIM.\s0 .IP "isplit_list (\s-1STRING, DELIM\s0 [, \s-1FILENAME\s0 [, \s-1LINE\s0 [, \s-1DESCRIPTION\s0]]])" 4 .IX Item "isplit_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 \f(CW"and"\fR; here, you can supply any string. Instances of \s-1DELIM\s0 in \&\s-1STRING\s0 are considered delimiters if they are at brace-depth zero, surrounded by whitespace, and not at the beginning or end of \s-1STRING\s0; the comparison is case-insensitive. See bt_split_names for full details of how splitting is done (it's \fInot\fR the same as Perl's \f(CW\*(C`split\*(C'\fR function). This function returns bytes. Use Text::BibTeX::split_list to specify the same binmode and normalization arguments as with, e.g. Text::BibTeX::File\->\fBopen()\fR .Sp Returns the list of strings resulting from splitting \s-1STRING\s0 on \s-1DELIM.\s0 .IP "purify_string (\s-1STRING\s0 [, \s-1OPTIONS\s0])" 4 .IX Item "purify_string (STRING [, OPTIONS])" \&\*(L"Purifies\*(R" \s-1STRING\s0 in the BibTeX way (usually for generation of sort keys). See bt_misc for details; note that, unlike the C interface, \&\f(CW\*(C`purify_string\*(C'\fR does \fInot\fR modify \s-1STRING\s0 in-place. A purified copy of the input string is returned. .Sp \&\s-1OPTIONS\s0 is currently unused. .IP "change_case (\s-1TRANSFORM, STRING\s0 [, \s-1OPTIONS\s0])" 4 .IX Item "change_case (TRANSFORM, STRING [, OPTIONS])" Transforms the case of \s-1STRING\s0 according to \s-1TRANSFORM\s0 (a single character, one of \f(CW\*(Aqu\*(Aq\fR, \f(CW\*(Aql\*(Aq\fR, or \f(CW\*(Aqt\*(Aq\fR). See bt_misc for details; again, \f(CW\*(C`change_case\*(C'\fR differs from the C interface in that \&\s-1STRING\s0 is not modified in\-place\-\-\-the input string is copied, and the transformed copy is returned. .SS "Entry-parsing functions" .IX Subsection "Entry-parsing functions" Although these functions are provided by the \f(CW\*(C`Text::BibTeX\*(C'\fR module, they are actually in the \f(CW\*(C`Text::BibTeX::Entry\*(C'\fR package. That's because they are implemented in C, and thus loaded with the \s-1XSUB\s0 code that \&\f(CW\*(C`Text::BibTeX\*(C'\fR loads; however, they are actually methods in the \&\f(CW\*(C`Text::BibTeX::Entry\*(C'\fR class. Thus, they are documented as methods in Text::BibTeX::Entry. .IP "parse (\s-1ENTRY_STRUCT, FILENAME, FILEHANDLE\s0)" 4 .IX Item "parse (ENTRY_STRUCT, FILENAME, FILEHANDLE)" .PD 0 .IP "parse_s (\s-1ENTRY_STRUCT, TEXT\s0)" 4 .IX Item "parse_s (ENTRY_STRUCT, TEXT)" .PD .SS "Macro table functions" .IX Subsection "Macro table functions" These functions allow direct access to the macro table maintained by \&\fBbtparse\fR, the C library underlying \f(CW\*(C`Text::BibTeX\*(C'\fR. In the normal course of events, macro definitions always accumulate, and are only defined as a result of parsing a macro definition (\f(CW@string\fR) entry. \&\fBbtparse\fR 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 \f(CW\*(C`delete_all_macros\*(C'\fR. If you wish to pre-define certain macros, use \f(CW\*(C`add_macro_text\*(C'\fR. (But note that the \&\f(CW\*(C`Bib\*(C'\fR structure, as part of its mission to emulate BibTeX 0.99, defines the standard \*(L"month name\*(R" macros for you.) .PP See also bt_macros in the \fBbtparse\fR documentation for a description of the C interface to these functions. .IP "add_macro_text (\s-1MACRO, TEXT\s0 [, \s-1FILENAME\s0 [, \s-1LINE\s0]])" 4 .IX Item "add_macro_text (MACRO, TEXT [, FILENAME [, LINE]])" Defines a new macro, or redefines an old one. \s-1MACRO\s0 is the name of the macro, and \s-1TEXT\s0 is the text it should expand to. \s-1FILENAME\s0 and \s-1LINE\s0 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 \f(CW\*(C`add_macro_text()\*(C'\fR issues a warning saying so. .IP "delete_macro (\s-1MACRO\s0)" 4 .IX Item "delete_macro (MACRO)" Deletes a macro from the macro table. If \s-1MACRO\s0 isn't defined, takes no action. .IP "delete_all_macros ()" 4 .IX Item "delete_all_macros ()" Deletes all macros from the macro table, even the predefined month names. .IP "macro_length (\s-1MACRO\s0)" 4 .IX Item "macro_length (MACRO)" Returns the length of a macro's expansion text. If the macro is undefined, returns 0; no warning is issued. .IP "macro_text (\s-1MACRO\s0 [, \s-1FILENAME\s0 [, \s-1LINE\s0]])" 4 .IX Item "macro_text (MACRO [, FILENAME [, LINE]])" Returns the expansion text of a macro. If the macro is not defined, issues a warning and returns \f(CW\*(C`undef\*(C'\fR. \s-1FILENAME\s0 and \s-1LINE,\s0 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. .SS "Name-parsing functions" .IX Subsection "Name-parsing functions" These are both private functions for the use of the \f(CW\*(C`Name\*(C'\fR class, and therefore are put in the \f(CW\*(C`Text::BibTeX::Name\*(C'\fR package. You should use the interface provided by that class for parsing names in the BibTeX style. .IP "_split (\s-1NAME_STRUCT, NAME, FILENAME, LINE, NAME_NUM, KEEP_CSTRUCT\s0)" 4 .IX Item "_split (NAME_STRUCT, NAME, FILENAME, LINE, NAME_NUM, KEEP_CSTRUCT)" .PD 0 .IP "free (\s-1NAME_STRUCT\s0)" 4 .IX Item "free (NAME_STRUCT)" .PD .SS "Name-formatting functions" .IX Subsection "Name-formatting functions" These are private functions for the use of the \f(CW\*(C`NameFormat\*(C'\fR class, and therefore are put in the \f(CW\*(C`Text::BibTeX::NameFormat\*(C'\fR package. You should use the interface provided by that class for formatting names in the BibTeX style. .IP "create ([\s-1PARTS\s0 [, \s-1ABBREV_FIRST\s0]])" 4 .IX Item "create ([PARTS [, ABBREV_FIRST]])" .PD 0 .IP "free (\s-1FORMAT_STRUCT\s0)" 4 .IX Item "free (FORMAT_STRUCT)" .IP "_set_text (\s-1FORMAT_STRUCT, PART, PRE_PART, POST_PART, PRE_TOKEN, POST_TOKEN\s0)" 4 .IX Item "_set_text (FORMAT_STRUCT, PART, PRE_PART, POST_PART, PRE_TOKEN, POST_TOKEN)" .IP "_set_options (\s-1FORMAT_STRUCT, PART, ABBREV, JOIN_TOKENS, JOIN_PART\s0)" 4 .IX Item "_set_options (FORMAT_STRUCT, PART, ABBREV, JOIN_TOKENS, JOIN_PART)" .IP "format_name (\s-1NAME_STRUCT, FORMAT_STRUCT\s0)" 4 .IX Item "format_name (NAME_STRUCT, FORMAT_STRUCT)" .PD .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" \&\f(CW\*(C`Text::BibTeX\*(C'\fR inherits several limitations from its base C library, \&\fBbtparse\fR; see \*(L"\s-1BUGS AND LIMITATIONS\*(R"\s0 in btparse for details. In addition, \&\f(CW\*(C`Text::BibTeX\*(C'\fR will not work with a Perl binary built using the \f(CW\*(C`sfio\*(C'\fR library. This is because Perl's I/O abstraction layer does not extend to third-party C libraries that use stdio, and \fBbtparse\fR most certainly does use stdio. .SH "SEE ALSO" .IX Header "SEE ALSO" btool_faq, Text::BibTeX::File, Text::BibTeX::Entry, Text::BibTeX::Value .SH "AUTHOR" .IX Header "AUTHOR" Greg Ward .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 1997\-2000 by Gregory P. Ward. All rights reserved. This file is part of the Text::BibTeX library. This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.