1[comment {-*- tcl -*- doctools manpage}] 2[vset VERSION 0.6] 3[manpage_begin bibtex n [vset VERSION]] 4[keywords bibliography] 5[keywords bibtex] 6[keywords parsing] 7[keywords {text processing}] 8[copyright {2005 for documentation, Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 9[moddesc {bibtex}] 10[titledesc {Parse bibtex files}] 11[category {Text processing}] 12[require Tcl 8.4] 13[require bibtex [opt [vset VERSION]]] 14[description] 15[para] 16 17This package provides commands for the parsing of bibliographies in 18BibTeX format. 19 20[list_begin definitions] 21 22[call [cmd ::bibtex::parse] [opt [arg options]] [opt [arg text]]] 23 24This is the general form of the command for parsing a 25bibliography. Depending on the options used to invoke it it will 26either return a token for the parser, or the parsed entries of the 27input bibliography. Instead of performing an immediate parse returning 28a predefined format the command can also enter an event-based parsing 29style where all relevant entries in the input are reported through 30callback commands, in the style of SAX. 31 32[call [cmd ::bibtex::parse] [arg text]] 33 34In this form the command will assume that the specified [arg text] is 35a bibliography in BibTeX format, parse it, and then return a list 36containing one element per record found in the bibliography. Note that 37comments, string definitions, preambles, etc. will not show up in the 38result. Each element will be a list containing record type, 39bibliography key and record data, in this order. The record data will 40be a dictionary, its keys the keys of the record, with the associated 41values. 42 43[call [cmd ::bibtex::parse] \ 44 [opt "[option -command] [arg cmd]"] \ 45 [option -channel] [arg chan]] 46 47In this form the command will reads the bibliography from the 48specified Tcl channel [arg chan] and then returns the same data 49structure as described above. 50 51[para] 52 53If however the option [option -command] is specified the result will be a 54handle for the parser instead and all processing will be incremental 55and happen in the background. When the input has been exhausted the 56callback [arg cmd] will be invoked with the result of the parse. The 57exact definition for the callback is 58 59[para] 60 61[list_begin definitions] 62[def "[cmd cmd] [arg token] [arg parseresult]"] 63 64The parse result will have the structure explained above, for the 65simpler forms of the parser. 66 67[list_end] 68[para] 69 70[emph Note] that the parser will [emph not] close the channel after it 71has exhausted it. This is still the responsibility of the user of the 72parser. 73 74[call [cmd ::bibtex::parse] \ 75 [opt "[option -recordcommand] [arg recordcmd]"] \ 76 [opt "[option -preamblecommand] [arg preamblecmd]"] \ 77 [opt "[option -stringcommand] [arg stringcmd]"] \ 78 [opt "[option -commentcommand] [arg commentcmd]"] \ 79 [opt "[option -progresscommand] [arg progresscmd]"] \ 80 [opt "[option -casesensitivestrings] [arg bool]"] \ 81 "([arg text] | [option -channel] [arg chan])"] 82 83This is the most low-level form for the parser. The returned result 84will be a handle for the parser. During processing it will invoke the 85invoke the specified callback commands for each type of data found in 86the bibliography. 87 88[para] 89 90The processing will be incremental and happen in the background if, 91and only if a Tcl channel [arg chan] is specified. For a [arg text] 92the processing will happen immediately and all callbacks will be 93invoked before the command itself returns. 94 95[para] 96 97The callbacks, i.e. [arg *cmd], are all command prefixes and will be 98invoked with additional arguments appended to them. The meaning of the 99arguments depends on the callback and is explained below. The first 100argument will however always be the handle of the parser invoking the 101callback. 102 103[list_begin definitions] 104 105[def "[option -casesensitivestrings]"] 106 107This option takes a boolean value. When set string macro processing 108becomes case-sensitive. The default is case-insensitive string macro 109processing. 110 111[def "[cmd recordcmd] [arg token] [arg type] [arg key] [arg recorddict]"] 112 113This callback is invoked whenever the parser detects a bibliography 114record in the input. Its arguments are the record type, the 115bibliography key for the record, and a dictionary containing the keys 116and values describing the record. Any string macros known to the 117parser have already been expanded. 118 119[def "[cmd preamblecmd] [arg token] [arg preambletext]"] 120 121This callback is invoked whenever the parser detects an @preamble 122block in the input. The only additional argument is the text found in 123the preamble block. By default such entries are ignored. 124 125[def "[cmd stringcmd] [arg token] [arg stringdict]"] 126 127This callback is invoked whenever the parser detects an @string-based 128macro definition in the input. The argument is a dictionary with the 129macro names as keys and their replacement strings as values. By 130default such definitions are added to the parser state for use in 131future bibliography records. 132 133[def "[cmd commentcmd] [arg token] [arg commenttext]"] 134 135This callback is invoked whenever the parser detects a comment in the 136input. The only additional argument is the comment text. By default 137such entries are ignored. 138 139[def "[cmd progresscmd] [arg token] [arg percent]"] 140 141This callback is invoked during processing to tell the user about the 142progress which has been made. Its argument is the percentage of data 143processed, as integer number between [const 0] and [const 100]. 144 145In the case of incremental processing the perecentage will always be 146[const -1] as the total number of entries is not known beforehand. 147 148[list_end] 149[para] 150 151[call [cmd ::bibtex::wait] [arg token]] 152 153This command waits for the parser represented by the [arg token] to 154complete and then returns. The returned result is the empty string. 155 156[call [cmd ::bibtex::destroy] [arg token]] 157 158This command cleans up all internal state associated with the parser 159represented by the handle [arg token], effectively destroying it. This 160command can be called from within the parser callbacks to terminate 161processing. 162 163[call [cmd ::bibtex::addStrings] [arg token] [arg stringdict]] 164 165This command adds the macro definitions stored in the 166dictionary [arg stringdict] to the parser represented 167by the handle [arg token]. 168 169[para] 170 171The dictionary keys are the macro names and the values their 172replacement strings. This command has the correct signature for use as 173a [option -stringcommand] callback in an invokation of the command 174[cmd ::bibtex::parse]. 175 176[list_end] 177 178[vset CATEGORY bibtex] 179[include ../common-text/feedback.inc] 180[manpage_end] 181