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
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 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
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 "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 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 while (entry = bt_parse_entry (file, filename, options, &ok))
94 {
95 if (ok)
96 {
97 /* ... process entry ... */
98 }
99 }
100 At the end of this loop, "feof (file)" will be true.
102 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 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 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 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 char * entry_text;
130 btshort options = 0;
131 boolean ok;
132 AST * entry_ast;
133 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 bt_parse_entry_s (NULL, NULL, 1, options, NULL); /* cleanup */
144 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 bt_parse_file ()
149 AST * bt_parse_file (char * filename,
150 btshort options,
151 boolean * status)
152 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 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
167 btparse, bt_postprocess, bt_traversal
168
170 Greg Ward <gward@python.net>
171btparse, version 0.85 2017-08-31 BT_INPUT(1)