1BT_INPUT(1) btparse BT_INPUT(1)
2
6 bt_input - input/parsing functions in btparse library
7
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
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 bt_set_stringopts ()
28 void bt_set_stringopts (bt_metatype_t metatype, btshort options);
29 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 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 For example,
42 bt_set_stringopts (BTE_COMMENT, BTO_COLLAPSE);
44 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 bt_parse_entry ()
50 AST * bt_parse_entry (FILE * infile,
51 char * filename,
52 btshort options,
53 boolean * status);
54 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 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 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 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 while (entry = bt_parse_entry (file, filename, options, &ok))
93 {
94 if (ok)
95 {
96 /* ... process entry ... */
97 }
98 }
99 At the end of this loop, "feof (file)" will be true.
101 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 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 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 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 char * entry_text;
129 btshort options = 0;
130 boolean ok;
131 AST * entry_ast;
132 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 bt_parse_entry_s (NULL, NULL, 1, options, NULL); /* cleanup */
143 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 bt_parse_file ()
148 AST * bt_parse_file (char * filename,
149 btshort options,
150 boolean * status)
151 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 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
166 btparse, bt_postprocess, bt_traversal
167
169 Greg Ward <gward@python.net>
170btparse, version 0.89 2023-07-21 BT_INPUT(1)