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.6?
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
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
48       ::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
58       ::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
63              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
69
70              cmd token parseresult
71                     The parse result will have the structure explained above,
72                     for the simpler forms of the parser.
73
74       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
77       ::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
86              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
91              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
97              -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
102              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
110              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
116              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
124              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
129              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
137
138       ::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
143       ::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
149       ::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
153              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

BUGS, IDEAS, FEEDBACK

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

KEYWORDS

174       bibliography, bibtex, parsing, text processing
175

CATEGORY

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