Provided by: tcllib_1.17-dfsg-1_all bug

NAME

       bibtex - Parse bibtex files

SYNOPSIS

       package require Tcl  8.4

       package require bibtex  ?0.6?

       ::bibtex::parse ?options? ?text?

       ::bibtex::parse text

       ::bibtex::parse ?-command cmd? -channel chan

       ::bibtex::parse     ?-recordcommand       recordcmd?     ?-preamblecommand    preamblecmd?
       ?-stringcommand   stringcmd? ?-commentcommand  commentcmd? ?-progresscommand  progresscmd?
       ?-casesensitivestrings bool? (text | -channel chan)

       ::bibtex::wait token

       ::bibtex::destroy token

       ::bibtex::addStrings token stringdict

_________________________________________________________________________________________________

DESCRIPTION

       This package provides commands for the parsing of bibliographies in BibTeX format.

       ::bibtex::parse ?options? ?text?
              This  is  the  general form of the command for parsing a bibliography. Depending on
              the options used to invoke it it will either return a token for the parser, or  the
              parsed  entries of the input bibliography. Instead of performing an immediate parse
              returning a predefined format the command can also  enter  an  event-based  parsing
              style  where  all  relevant  entries  in  the  input  are reported through callback
              commands, in the style of SAX.

       ::bibtex::parse text
              In this form the command will assume that the specified text is a  bibliography  in
              BibTeX  format,  parse it, and then return a list containing one element per record
              found in the bibliography. Note that comments, string definitions, preambles,  etc.
              will  not  show  up  in  the result.  Each element will be a list containing record
              type, bibliography key and record data, in this order. The record data  will  be  a
              dictionary, its keys the keys of the record, with the associated values.

       ::bibtex::parse ?-command cmd? -channel chan
              In this form the command will reads the bibliography from the specified Tcl channel
              chan and then returns the same data structure as described above.

              If however the option -command is specified the result will be  a  handle  for  the
              parser instead and all processing will be incremental and happen in the background.
              When the input has been exhausted the callback cmd will be invoked with the  result
              of the parse. The exact definition for the callback is

              cmd token parseresult
                     The  parse  result  will have the structure explained above, for the simpler
                     forms of the parser.

       Note that the parser will not close the channel after it has exhausted it. This  is  still
       the responsibility of the user of the parser.

       ::bibtex::parse     ?-recordcommand       recordcmd?     ?-preamblecommand    preamblecmd?
       ?-stringcommand   stringcmd? ?-commentcommand  commentcmd? ?-progresscommand  progresscmd?
       ?-casesensitivestrings bool? (text | -channel chan)
              This  is  the  most  low-level  form  for the parser. The returned result will be a
              handle for the parser. During processing it will invoke the  invoke  the  specified
              callback commands for each type of data found in the bibliography.

              The  processing  will be incremental and happen in the background if, and only if a
              Tcl channel chan is specified. For a text the processing  will  happen  immediately
              and all callbacks will be invoked before the command itself returns.

              The  callbacks,  i.e.  *cmd,  are  all  command  prefixes  and will be invoked with
              additional arguments appended to them. The meaning of the arguments depends on  the
              callback  and  is  explained  below.  The first argument will however always be the
              handle of the parser invoking the callback.

              -casesensitivestrings
                     This option takes a boolean value. When set string macro processing  becomes
                     case-sensitive. The default is case-insensitive string macro processing.

              recordcmd token type key recorddict
                     This  callback  is invoked whenever the parser detects a bibliography record
                     in the input. Its arguments are the record type, the  bibliography  key  for
                     the  record,  and a dictionary containing the keys and values describing the
                     record. Any string macros known to the parser have already been expanded.

              preamblecmd token preambletext
                     This callback is invoked whenever the parser detects an @preamble  block  in
                     the  input.  The  only additional argument is the text found in the preamble
                     block. By default such entries are ignored.

              stringcmd token stringdict
                     This callback is invoked whenever the parser detects an @string-based  macro
                     definition  in  the input. The argument is a dictionary with the macro names
                     as keys and their replacement strings as values. By default such definitions
                     are added to the parser state for use in future bibliography records.

              commentcmd token commenttext
                     This callback is invoked whenever the parser detects a comment in the input.
                     The only additional argument is the comment text. By  default  such  entries
                     are ignored.

              progresscmd token percent
                     This  callback  is  invoked  during  processing  to  tell the user about the
                     progress which has been  made.  Its  argument  is  the  percentage  of  data
                     processed,  as integer number between 0 and 100.  In the case of incremental
                     processing the perecentage will always be -1 as the total number of  entries
                     is not known beforehand.

       ::bibtex::wait token
              This  command  waits  for  the parser represented by the token to complete and then
              returns. The returned result is the empty string.

       ::bibtex::destroy token
              This command cleans up all internal state associated with the parser represented by
              the handle token, effectively destroying it. This command can be called from within
              the parser callbacks to terminate processing.

       ::bibtex::addStrings token stringdict
              This command adds the macro definitions stored in the dictionary stringdict to  the
              parser represented by the handle token.

              The  dictionary  keys are the macro names and the values their replacement strings.
              This command has the correct signature for use as a -stringcommand callback  in  an
              invokation of the command ::bibtex::parse.

BUGS, IDEAS, FEEDBACK

       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.   Please  report  such  in  the  category  bibtex   of   the   Tcllib   Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

KEYWORDS

       bibliography, bibtex, parsing, text processing

CATEGORY

       Text processing

COPYRIGHT

       Copyright (c) 2005 for documentation, Andreas Kupries <andreas_kupries@users.sourceforge.net>