bt_input - input/parsing functions in btparse library

   void  bt_set_stringopts (bt_metatype_t metatype, ushort options);
   AST * bt_parse_entry_s (char *    entry_text,
                           char *    filename,
                           int       line,
                           ushort    options,
                           boolean * status);
   AST * bt_parse_entry   (FILE *    infile,
                           char *    filename,
                           ushort    options,
                           boolean * status);
   AST * bt_parse_file    (char *    filename, 
                           ushort    options, 
                           boolean * overall_status);

The functions described here are used to read and parse BibTeX data, converting it from raw text to abstract-syntax trees (ASTs).

bt_set_stringopts ()

   void bt_set_stringopts (bt_metatype_t metatype, ushort options);

Set the string-processing options for a particular entry metatype. This affects the entry post-processing done by CWbt_parse_entry_s(), CWbt_parse_entry(), and CWbt_parse_file(). If CWbt_set_stringopts() is never called, the four metatypes default to the following sets of string options:

   BTE_REGULAR    BTO_CONVERT | BTO_EXPAND | BTO_PASTE | BTO_COLLAPSE
   BTE_COMMENT    0
   BTE_PREAMBLE   0
   BTE_MACRODEF   BTO_CONVERT | BTO_EXPAND | BTO_PASTE

For example,

   bt_set_stringopts (BTE_COMMENT, BTO_COLLAPSE);

will cause the library to collapse whitespace in the value from all comment entries; the AST returned by one of the CWbt_parse_* functions will reflect this change.

bt_parse_entry ()

   AST * bt_parse_entry (FILE *    infile,
                         char *    filename,
                         ushort    options,
                         boolean * status);

Scans and parses the next BibTeX entry in CWinfile. You should supply CWfilename to help btparse generate accurate error messages; the library keeps track of CWinfile's current line number internally, so you don't need to pass that in. CWoptions should be a bitmap of non-string-processing options (currently, CWBTO_NOSTORE to disable storing macro expansions is the only such option). CW*status will be set to CWTRUE if the entry parsed successfully or with only minor warnings, and CWFALSE if there were any serious lexical or syntactic errors. If CWstatus is CWNULL, then the parse status will be unavailable to you. Both minor warnings and serious errors are reported on CWstderr. Returns a pointer to the abstract-syntax tree (AST) describing the entry just parsed, or CWNULL if no more entries were found in CWinfile (this will leave CWinfile at end-of-file). Do not attempt to second guess CWbt_parse_entry() by detecting end-of-file yourself; it must be allowed to determine this on its own so it can clean up some static data that is preserved between calls on the same file. CWbt_parse_entry() has two important restrictions that you should know about. First, you should let btparse manage all the input on the file; this is for reasons both superficial (so the library knows the current line number in order to generate accurate error messages) and fundamental (the library must be allowed to detect end-of-file in order to cleanup certain static variables and allow you to parse another file). Second, you cannot interleave the parsing of two different files; attempting to do so will result in a fatal error that will crash your program. This is a direct result of the static state maintained between calls of CWbt_parse_entry(). Because of two distinct failures possible for CWbt_parse_entry() (end-of-file, which is expected but means to stop processing the current file; and error-in-input, which is not expected but allows you to continue processing the same file), you should usually call it like this:

   while (entry = bt_parse_entry (file, filename, options, &ok))
   {
      if (ok)
      {
         /* ... process entry ... */
      }
   }

At the end of this loop, CWfeof (file) will be true.

bt_parse_entry_s ()

   AST * bt_parse_entry_s (char *    entry_text,
                           char *    filename,
                           int       line,
                           ushort    options,
                           boolean * status)

Scans and parses a single complete BibTeX entry contained in a string, CWentry_text. If you read this string from a file, you should help btparse generate accurate error messages by supplying the name of the file as CWfilename and the line number of the beginning of the entry as CWline; otherwise, set CWfilename to CWNULL and CWline to CW1. CWoptions and CWstatus are the same as for CWbt_parse_entry(). Returns a pointer to the abstract-syntax tree (AST) describing the entry just parsed, and CWNULL if no entries were found in CWentry_text or if CWentry_text was CWNULL. You should call CWbt_parse_entry_s() once more than the total number of entries you wish to parse; on the final call, set CWentry_text to CWNULL so the function knows there's no more text to parse. This final call allows it to clean up some structures allocated on the first call. Thus, CWbt_parse_entry_s() is usually used like this:

   char *  entry_text;
   ushort  options = 0;
   boolean ok;
   AST *   entry_ast;

   while (entry_text = get_more_text ())
   {
      entry_ast = bt_parse_entry_s (entry_text, NULL, 1, options, &ok);
      if (ok)
      {
         /* ... process entry ... */
      }
   }

   bt_parse_entry_s (NULL, NULL, 1, options, NULL);    /* cleanup */

assuming that CWget_more_text() returns a pointer to the text of an entry to parse, or CWNULL if there's no more text available.

bt_parse_file ()

   AST * bt_parse_file (char *    filename, 
                        ushort    options, 
                        boolean * status)

Scans and parses an entire BibTeX file. If CWfilename is CWNULL or CW"-", then CWstdin will be read; otherwise, attempts to open the named file. If this attempt fails, prints an error message to CWstderr and returns CWNULL. CWoptions and CWstatus are the same as for CWbt_parse_entry()---note that CW*status will be CWFALSE if there were any errors in the entire file; for finer granularity of error-checking, you should use CWbt_parse_entry(). Returns a pointer to a linked list of ASTs representing the entries in the file, or CWNULL if no entries were found in the file. This list can be traversed with CWbt_next_entry(), and the individual entries then traversed as usual (see bt_traversal).

btparse, bt_postprocess, bt_traversal

Greg Ward <gward@python.net>