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