1bibtex(n) bibtex bibtex(n)
2______________________________________________________________________________
6
8 bibtex - Parse bibtex files
9
11 package require Tcl 8.4
12 package require bibtex ?0.6?
14 ::bibtex::parse ?options? ?text?
16 ::bibtex::parse text
18 ::bibtex::parse ?-command cmd? -channel chan
20 ::bibtex::parse ?-recordcommand recordcmd? ?-preamblecommand pream‐
22 blecmd? ?-stringcommand stringcmd? ?-commentcommand commentcmd?
23 ?-progresscommand progresscmd? ?-casesensitivestrings bool? (text |
24 -channel chan)
25 ::bibtex::wait token
27 ::bibtex::destroy token
29 ::bibtex::addStrings token stringdict
31______________________________________________________________________________
33
35 This package provides commands for the parsing of bibliographies in
36 BibTeX format.
37 ::bibtex::parse ?options? ?text?
39 This is the general form of the command for parsing a bibliogra‐
40 phy. Depending on the options used to invoke it it will either
41 return a token for the parser, or the parsed entries of the in‐
42 put bibliography. Instead of performing an immediate parse re‐
43 turning a predefined format the command can also enter an event-
44 based parsing style where all relevant entries in the input are
45 reported through callback commands, in the style of SAX.
46 ::bibtex::parse text
48 In this form the command will assume that the specified text is
49 a bibliography in BibTeX format, parse it, and then return a
50 list containing one element per record found in the bibliogra‐
51 phy. Note that comments, string definitions, preambles, etc.
52 will not show up in the result. Each element will be a list
53 containing record type, bibliography key and record data, in
54 this order. The record data will be a dictionary, its keys the
55 keys of the record, with the associated values.
56 ::bibtex::parse ?-command cmd? -channel chan
58 In this form the command will reads the bibliography from the
59 specified Tcl channel chan and then returns the same data struc‐
60 ture as described above.
61 If however the option -command is specified the result will be a
63 handle for the parser instead and all processing will be incre‐
64 mental and happen in the background. When the input has been ex‐
65 hausted the callback cmd will be invoked with the result of the
66 parse. The exact definition for the callback is
67 cmd token parseresult
70 The parse result will have the structure explained above,
71 for the simpler forms of the parser.
72 Note that the parser will not close the channel after it has exhausted
74 it. This is still the responsibility of the user of the parser.
75 ::bibtex::parse ?-recordcommand recordcmd? ?-preamblecommand pream‐
77 blecmd? ?-stringcommand stringcmd? ?-commentcommand commentcmd?
78 ?-progresscommand progresscmd? ?-casesensitivestrings bool? (text |
79 -channel chan)
80 This is the most low-level form for the parser. The returned re‐
81 sult will be a handle for the parser. During processing it will
82 invoke the invoke the specified callback commands for each type
83 of data found in the bibliography.
84 The processing will be incremental and happen in the background
86 if, and only if a Tcl channel chan is specified. For a text the
87 processing will happen immediately and all callbacks will be in‐
88 voked before the command itself returns.
89 The callbacks, i.e. *cmd, are all command prefixes and will be
91 invoked with additional arguments appended to them. The meaning
92 of the arguments depends on the callback and is explained below.
93 The first argument will however always be the handle of the
94 parser invoking the callback.
95 -casesensitivestrings
97 This option takes a boolean value. When set string macro
98 processing becomes case-sensitive. The default is case-
99 insensitive string macro processing.
100 recordcmd token type key recorddict
102 This callback is invoked whenever the parser detects a
103 bibliography record in the input. Its arguments are the
104 record type, the bibliography key for the record, and a
105 dictionary containing the keys and values describing the
106 record. Any string macros known to the parser have al‐
107 ready been expanded.
108 preamblecmd token preambletext
110 This callback is invoked whenever the parser detects an
111 @preamble block in the input. The only additional argu‐
112 ment is the text found in the preamble block. By default
113 such entries are ignored.
114 stringcmd token stringdict
116 This callback is invoked whenever the parser detects an
117 @string-based macro definition in the input. The argument
118 is a dictionary with the macro names as keys and their
119 replacement strings as values. By default such defini‐
120 tions are added to the parser state for use in future
121 bibliography records.
122 commentcmd token commenttext
124 This callback is invoked whenever the parser detects a
125 comment in the input. The only additional argument is the
126 comment text. By default such entries are ignored.
127 progresscmd token percent
129 This callback is invoked during processing to tell the
130 user about the progress which has been made. Its argument
131 is the percentage of data processed, as integer number
132 between 0 and 100. In the case of incremental processing
133 the perecentage will always be -1 as the total number of
134 entries is not known beforehand.
135 ::bibtex::wait token
138 This command waits for the parser represented by the token to
139 complete and then returns. The returned result is the empty
140 string.
141 ::bibtex::destroy token
143 This command cleans up all internal state associated with the
144 parser represented by the handle token, effectively destroying
145 it. This command can be called from within the parser callbacks
146 to terminate processing.
147 ::bibtex::addStrings token stringdict
149 This command adds the macro definitions stored in the dictionary
150 stringdict to the parser represented by the handle token.
151 The dictionary keys are the macro names and the values their re‐
153 placement strings. This command has the correct signature for
154 use as a -stringcommand callback in an invokation of the command
155 ::bibtex::parse.
156
158 This document, and the package it describes, will undoubtedly contain
159 bugs and other problems. Please report such in the category bibtex of
160 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
161 also report any ideas for enhancements you may have for either package
162 and/or documentation.
163 When proposing code changes, please provide unified diffs, i.e the out‐
165 put of diff -u.
166 Note further that attachments are strongly preferred over inlined
168 patches. Attachments can be made by going to the Edit form of the
169 ticket immediately after its creation, and then using the left-most
170 button in the secondary navigation bar.
171
173 bibliography, bibtex, parsing, text processing
174
176 Text processing
177
179 Copyright (c) 2005 for documentation, Andreas Kupries <andreas_kupries@users.sourceforge.net>
180tcllib 0.6 bibtex(n)