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