NAME

bt_input - input/parsing functions in btparse library

SYNOPSIS

typedef long (*bt_read_fn) (void *userdata, char *buf, size_t n);

bt_parser * bt_parser_new_reader (bt_read_fn read, void *userdata,
                                  const char *filename, unsigned flags);
bt_parser * bt_parser_new_string (const char *text, size_t len,
                                  const char *filename, int line,
                                  unsigned flags);
void        bt_parser_free (bt_parser *parser);
void        bt_parser_set_macros (bt_parser *parser, bt_macros *macros);
boolean     bt_parser_eof (bt_parser *parser);
boolean     bt_parser_read_error (bt_parser *parser);

AST * bt_parse_entry (bt_parser *parser, bt_errors *errs,
                      btshort options, boolean *status);

DESCRIPTION

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

All parsing state lives in a bt_parser object, so any number of inputs can be parsed at the same time, and from different threads (as long as each parser is only used by one thread at a time). Nothing is ever printed: errors and warnings are appended to a bt_errors list (see "ERROR HANDLING" in btparse).

bt_parser_new_reader ()

bt_parser * bt_parser_new_reader (bt_read_fn read, void *userdata,
                                  const char *filename, unsigned flags);

Creates a parser that reads its input by calling read(userdata, buf, n), which should put up to n bytes into buf and return the number of bytes read, 0 at end of input, or -1 on a read error. The parser reads ahead only as far as it needs to, so the input may be a pipe or a network stream. (The Perl interface uses this to read through PerlIO.)

filename is used in error messages, and may be NULL. flags may include BTP_UTF8 to have the input validated as UTF-8: invalid byte sequences are replaced with U+FFFD (with a warning), so that every string in the resulting AST is valid UTF-8. Without BTP_UTF8, bytes are passed through untouched. A UTF-8 byte order mark at the start of the input is always ignored.

bt_parser_new_string ()

bt_parser * bt_parser_new_string (const char *text, size_t len,
                                  const char *filename, int line,
                                  unsigned flags);

Creates a parser for the len bytes at text (which are copied). line is the line number of the start of the text, for error messages.

bt_parser_set_macros ()

void bt_parser_set_macros (bt_parser *parser, bt_macros *macros);

Sets the macro table used to expand macros and to store the definitions from @string entries (see bt_macros). The table is not owned by the parser.

bt_parse_entry ()

AST * bt_parse_entry (bt_parser *parser, bt_errors *errs,
                      btshort options, boolean *status);

Scans and parses the next BibTeX entry. options are the post-processing options applied to the entry (see bt_postprocess); @string definitions are stored in the parser's macro table unless BTO_NOSTORE is given. *status is set to TRUE if the entry parsed successfully or with only minor warnings, and FALSE if there were any serious lexical or syntactic errors. All errors are appended to errs (which may be NULL to discard them).

Returns the AST of the entry, or NULL at end of input. Free it with bt_free_ast(); it refers to the parser's copy of the filename, so it must not outlive the parser.

After a syntax error the parser recovers as BibTeX does: errors within a field skip to the next field, and anything worse skips to the next @ at top level. An entry is returned whenever one was started, even if it had errors, so you would usually call it like this:

while ((entry = bt_parse_entry (parser, &errs, 0, &ok)))
{
   if (ok)
   {
      /* ... process entry ... */
   }
   bt_free_ast (entry);
}

If the input contains no entries at all, the first call reports a syntax error ("expected '@'").

bt_parser_eof ()

True once all of the input has been consumed.

bt_parser_read_error ()

True if the read callback reported an error.

SEE ALSO

btparse, bt_postprocess, bt_traversal

AUTHOR

Greg Ward <gward@python.net>