1bibtex(n)                           bibtex                           bibtex(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       bibtex - Parse bibtex files
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require bibtex  ?0.7?
14
15       ::bibtex::parse ?options? ?text?
16
17       ::bibtex::parse text
18
19       ::bibtex::parse ?-command cmd? -channel chan
20
21       ::bibtex::parse  ?-recordcommand    recordcmd? ?-preamblecommand pream‐
22       blecmd?  ?-stringcommand    stringcmd?  ?-commentcommand    commentcmd?
23       ?-progresscommand  progresscmd?  ?-casesensitivestrings  bool?  (text |
24       -channel chan)
25
26       ::bibtex::wait token
27
28       ::bibtex::destroy token
29
30       ::bibtex::addStrings token stringdict
31
32______________________________________________________________________________
33

DESCRIPTION

35       This package provides commands for the  parsing  of  bibliographies  in
36       BibTeX format.
37
38       ::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
47       ::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
57       ::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
62              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
68
69              cmd token parseresult
70                     The parse result will have the structure explained above,
71                     for the simpler forms of the parser.
72
73       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
76       ::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
85              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
90              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
96              -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
101              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
109              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
115              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
123              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
128              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
136
137       ::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
142       ::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
148       ::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
152              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

BUGS, IDEAS, FEEDBACK

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
164       When proposing code changes, please provide unified diffs, i.e the out‐
165       put of diff -u.
166
167       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

KEYWORDS

173       bibliography, bibtex, parsing, text processing
174

CATEGORY

176       Text processing
177
179       Copyright (c) 2005 for documentation, Andreas Kupries <andreas_kupries@users.sourceforge.net>
180
181
182
183
184tcllib                                0.7                            bibtex(n)
Impressum