1BT_INPUT(1)                         btparse                        BT_INPUT(1)
2
3
4

NAME

6       bt_input - input/parsing functions in btparse library
7

SYNOPSIS

9          void  bt_set_stringopts (bt_metatype_t metatype, btshort options);
10          AST * bt_parse_entry_s (char *    entry_text,
11                                  char *    filename,
12                                  int       line,
13                                  btshort    options,
14                                  boolean * status);
15          AST * bt_parse_entry   (FILE *    infile,
16                                  char *    filename,
17                                  btshort    options,
18                                  boolean * status);
19          AST * bt_parse_file    (char *    filename,
20                                  btshort    options,
21                                  boolean * overall_status);
22

DESCRIPTION

24       The functions described here are used to read and parse BibTeX data,
25       converting it from raw text to abstract-syntax trees (ASTs).
26
27       bt_set_stringopts ()
28              void bt_set_stringopts (bt_metatype_t metatype, btshort options);
29
30           Set the string-processing options for a particular entry metatype.
31           This affects the entry post-processing done by
32           "bt_parse_entry_s()", "bt_parse_entry()", and "bt_parse_file()".
33           If "bt_set_stringopts()" is never called, the four metatypes
34           default to the following sets of string options:
35
36              BTE_REGULAR    BTO_CONVERT | BTO_EXPAND | BTO_PASTE | BTO_COLLAPSE
37              BTE_COMMENT    0
38              BTE_PREAMBLE   0
39              BTE_MACRODEF   BTO_CONVERT | BTO_EXPAND | BTO_PASTE
40
41           For example,
42
43              bt_set_stringopts (BTE_COMMENT, BTO_COLLAPSE);
44
45           will cause the library to collapse whitespace in the value from all
46           comment entries; the AST returned by one of the "bt_parse_*"
47           functions will reflect this change.
48
49       bt_parse_entry ()
50              AST * bt_parse_entry (FILE *    infile,
51                                    char *    filename,
52                                    btshort    options,
53                                    boolean * status);
54
55           Scans and parses the next BibTeX entry in "infile".  You should
56           supply "filename" to help btparse generate accurate error messages;
57           the library keeps track of "infile"'s current line number
58           internally, so you don't need to pass that in.  "options" should be
59           a bitmap of non-string-processing options (currently, "BTO_NOSTORE"
60           to disable storing macro expansions is the only such option).
61           *status will be set to "TRUE" if the entry parsed successfully or
62           with only minor warnings, and "FALSE" if there were any serious
63           lexical or syntactic errors.  If "status" is "NULL", then the parse
64           status will be unavailable to you.  Both minor warnings and serious
65           errors are reported on "stderr".
66
67           Returns a pointer to the abstract-syntax tree (AST) describing the
68           entry just parsed, or "NULL" if no more entries were found in
69           "infile" (this will leave "infile" at end-of-file).  Do not attempt
70           to second guess "bt_parse_entry()" by detecting end-of-file
71           yourself; it must be allowed to determine this on its own so it can
72           clean up some static data that is preserved between calls on the
73           same file.
74
75           "bt_parse_entry()" has two important restrictions that you should
76           know about.  First, you should let btparse manage all the input on
77           the file; this is for reasons both superficial (so the library
78           knows the current line number in order to generate accurate error
79           messages) and fundamental (the library must be allowed to detect
80           end-of-file in order to cleanup certain static variables and allow
81           you to parse another file).  Second, you cannot interleave the
82           parsing of two different files; attempting to do so will result in
83           a fatal error that will crash your program.  This is a direct
84           result of the static state maintained between calls of
85           "bt_parse_entry()".
86
87           Because of two distinct "failures" possible for "bt_parse_entry()"
88           (end-of-file, which is expected but means to stop processing the
89           current file; and error-in-input, which is not expected but allows
90           you to continue processing the same file), you should usually call
91           it like this:
92
93              while (entry = bt_parse_entry (file, filename, options, &ok))
94              {
95                 if (ok)
96                 {
97                    /* ... process entry ... */
98                 }
99              }
100
101           At the end of this loop, "feof (file)" will be true.
102
103       bt_parse_entry_s ()
104              AST * bt_parse_entry_s (char *    entry_text,
105                                      char *    filename,
106                                      int       line,
107                                      btshort    options,
108                                      boolean * status)
109
110           Scans and parses a single complete BibTeX entry contained in a
111           string, "entry_text".  If you read this string from a file, you
112           should help btparse generate accurate error messages by supplying
113           the name of the file as "filename" and the line number of the
114           beginning of the entry as "line"; otherwise, set "filename" to
115           "NULL" and "line" to 1.  "options" and "status" are the same as for
116           "bt_parse_entry()".
117
118           Returns a pointer to the abstract-syntax tree (AST) describing the
119           entry just parsed, and "NULL" if no entries were found in
120           "entry_text" or if "entry_text" was "NULL".
121
122           You should call "bt_parse_entry_s()" once more than the total
123           number of entries you wish to parse; on the final call, set
124           "entry_text" to "NULL" so the function knows there's no more text
125           to parse.  This final call allows it to clean up some structures
126           allocated on the first call.  Thus, "bt_parse_entry_s()" is usually
127           used like this:
128
129              char *  entry_text;
130              btshort  options = 0;
131              boolean ok;
132              AST *   entry_ast;
133
134              while (entry_text = get_more_text ())
135              {
136                 entry_ast = bt_parse_entry_s (entry_text, NULL, 1, options, &ok);
137                 if (ok)
138                 {
139                    /* ... process entry ... */
140                 }
141              }
142
143              bt_parse_entry_s (NULL, NULL, 1, options, NULL);    /* cleanup */
144
145           assuming that "get_more_text()" returns a pointer to the text of an
146           entry to parse, or "NULL" if there's no more text available.
147
148       bt_parse_file ()
149              AST * bt_parse_file (char *    filename,
150                                   btshort    options,
151                                   boolean * status)
152
153           Scans and parses an entire BibTeX file.  If "filename" is "NULL" or
154           "-", then "stdin" will be read; otherwise, attempts to open the
155           named file.  If this attempt fails, prints an error message to
156           "stderr" and returns "NULL".  "options" and "status" are the same
157           as for "bt_parse_entry()"---note that *status will be "FALSE" if
158           there were any errors in the entire file; for finer granularity of
159           error-checking, you should use "bt_parse_entry()".
160
161           Returns a pointer to a linked list of ASTs representing the entries
162           in the file, or "NULL" if no entries were found in the file.  This
163           list can be traversed with "bt_next_entry()", and the individual
164           entries then traversed as usual (see bt_traversal).
165

SEE ALSO

167       btparse, bt_postprocess, bt_traversal
168

AUTHOR

170       Greg Ward <gward@python.net>
171
172
173
174btparse, version 0.85             2017-08-31                       BT_INPUT(1)
Impressum