1. Manuals
  2. Tumbleweed
  3. tcllib
  4. bibtex(n)

Scroll to navigation

bibtex(n) bibtex bibtex(n) 





NAME


bibtex - Parse bibtex files






SYNOPSIS


package require Tcl 8.4


package require bibtex ?0.7?


::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

    

  







  

  
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.

  







  

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

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.


When proposing code changes, please provide unified diffs,
    i.e the output of diff -u.


Note further that attachments are strongly preferred over
    inlined patches. Attachments can be made by going to the Edit form of
    the ticket immediately after its creation, and then using the left-most
    button in the secondary navigation bar.






KEYWORDS


bibliography, bibtex, parsing, text processing






CATEGORY


Text processing






COPYRIGHT


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








  

    0.7
    tcllib