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 bt_parse_entry_s(),
32           bt_parse_entry(), and bt_parse_file().  If bt_set_stringopts() is
33           never called, the four metatypes default to the following sets of
34           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 yourself;
71           it must be allowed to determine this on its own so it can clean up
72           some static data that is preserved between calls on the same file.
73
74           bt_parse_entry() has two important restrictions that you should
75           know about.  First, you should let btparse manage all the input on
76           the file; this is for reasons both superficial (so the library
77           knows the current line number in order to generate accurate error
78           messages) and fundamental (the library must be allowed to detect
79           end-of-file in order to cleanup certain static variables and allow
80           you to parse another file).  Second, you cannot interleave the
81           parsing of two different files; attempting to do so will result in
82           a fatal error that will crash your program.  This is a direct
83           result of the static state maintained between calls of
84           bt_parse_entry().
85
86           Because of two distinct "failures" possible for bt_parse_entry()
87           (end-of-file, which is expected but means to stop processing the
88           current file; and error-in-input, which is not expected but allows
89           you to continue processing the same file), you should usually call
90           it like this:
91
92              while (entry = bt_parse_entry (file, filename, options, &ok))
93              {
94                 if (ok)
95                 {
96                    /* ... process entry ... */
97                 }
98              }
99
100           At the end of this loop, "feof (file)" will be true.
101
102       bt_parse_entry_s ()
103              AST * bt_parse_entry_s (char *    entry_text,
104                                      char *    filename,
105                                      int       line,
106                                      btshort    options,
107                                      boolean * status)
108
109           Scans and parses a single complete BibTeX entry contained in a
110           string, "entry_text".  If you read this string from a file, you
111           should help btparse generate accurate error messages by supplying
112           the name of the file as "filename" and the line number of the
113           beginning of the entry as "line"; otherwise, set "filename" to
114           "NULL" and "line" to 1.  "options" and "status" are the same as for
115           bt_parse_entry().
116
117           Returns a pointer to the abstract-syntax tree (AST) describing the
118           entry just parsed, and "NULL" if no entries were found in
119           "entry_text" or if "entry_text" was "NULL".
120
121           You should call bt_parse_entry_s() once more than the total number
122           of entries you wish to parse; on the final call, set "entry_text"
123           to "NULL" so the function knows there's no more text to parse.
124           This final call allows it to clean up some structures allocated on
125           the first call.  Thus, bt_parse_entry_s() is usually used like
126           this:
127
128              char *  entry_text;
129              btshort  options = 0;
130              boolean ok;
131              AST *   entry_ast;
132
133              while (entry_text = get_more_text ())
134              {
135                 entry_ast = bt_parse_entry_s (entry_text, NULL, 1, options, &ok);
136                 if (ok)
137                 {
138                    /* ... process entry ... */
139                 }
140              }
141
142              bt_parse_entry_s (NULL, NULL, 1, options, NULL);    /* cleanup */
143
144           assuming that get_more_text() returns a pointer to the text of an
145           entry to parse, or "NULL" if there's no more text available.
146
147       bt_parse_file ()
148              AST * bt_parse_file (char *    filename,
149                                   btshort    options,
150                                   boolean * status)
151
152           Scans and parses an entire BibTeX file.  If "filename" is "NULL" or
153           "-", then "stdin" will be read; otherwise, attempts to open the
154           named file.  If this attempt fails, prints an error message to
155           "stderr" and returns "NULL".  "options" and "status" are the same
156           as for bt_parse_entry()---note that *status will be "FALSE" if
157           there were any errors in the entire file; for finer granularity of
158           error-checking, you should use bt_parse_entry().
159
160           Returns a pointer to a linked list of ASTs representing the entries
161           in the file, or "NULL" if no entries were found in the file.  This
162           list can be traversed with bt_next_entry(), and the individual
163           entries then traversed as usual (see bt_traversal).
164

SEE ALSO

166       btparse, bt_postprocess, bt_traversal
167

AUTHOR

169       Greg Ward <gward@python.net>
170
171
172
173btparse, version 0.89             2023-07-21                       BT_INPUT(1)
Impressum