1BT_MACROS(1) btparse BT_MACROS(1)
2
6 bt_macros - accessing and manipulating the btparse macro table
7
9 void bt_add_macro_value (AST * assignment,
10 btshort options);
11 void bt_add_macro_text (char * macro,
12 char * text,
13 char * filename,
14 int line);
15 void bt_delete_macro (char * macro);
17 void bt_delete_all_macros (void);
18 int bt_macro_length (char *macro);
20 char * bt_macro_text (char * macro,
21 char * filename,
22 int line);
23
25 btparse maintains a single table of all macros (abbreviations)
26 encountered while parsing BibTeX entries. It updates this table
27 whenever it encounters a "macro definition" (@string) entry, and refers
28 to it whenever a macro is used in an entry and needs to be expanded.
29 (Macros are not necessarily expanded on input, although this is the
30 default. See bt_postprocess.) Macro definitions are only cleared when
31 btparse's global cleanup function, "bt_cleanup()", is called. Thus,
32 unless you explicitly call "bt_delete_macro()" or
33 "bt_delete_all_macros()", macro definitions persist for as long as you
34 use the library---usually, the lifetime of your process.
35
37 You can use the following functions to add macros, delete them, and
38 query their values---thus interfering with btparse's normal operation
39 on the fly.
40 bt_add_macro_text ()
42 void bt_add_macro_text (char * macro,
43 char * text,
44 char * filename,
45 int line);
46 Defines a new macro, or redefines an old one. "macro" is the name
48 of the macro, and "text" is the text it should expand to.
49 "filename" and "line" are just used to generate any warnings about
50 the macro definition; if they don't apply, specify "NULL" for
51 "filename" and 0 for "line". The only such warning occurs when you
52 redefine an old macro: its value is overridden, and
53 "bt_add_macro_text()" issues a warning saying so.
54 For instance, when parsing this macro definition entry:
56 @string{fubar = "Fouled Up Beyond All Recognition"}
58 the library (in particular, the post-processing code called after
60 an entry is successfully parsed) will ultimately do this:
61 bt_add_macro_text ("fubar", "Fouled Up Beyond All Recognition",
63 filename, line);
64 This in turn will cause the macro "fubar" to be expanded
66 appropriately whenever the post-processing code sees it in any
67 future entries.
68 bt_add_macro_value ()
70 void bt_add_macro_value (AST * assignment,
71 btshort options);
72 This function is mainly for internal use by the library, but it's
74 available to you if you ever find yourself with a little bit of AST
75 representing a macro definition, and you want to set the macro
76 yourself (rather than letting the library's post-processing code
77 take care of it for you). "assignment" must be an AST node as
78 returned by "bt_next_field()". Unlike most other btparse functions
79 that take an "options" argument, "options" here tells how the value
80 in "assignment" was post-processed. This is needed because macro
81 values have to be processed in a special way to be valid in future
82 expansions; if this one wasn't processed like that,
83 "bt_add_macro_value()" will do it for you. If you don't know how
84 the value was post-processed, just supply 0 for "options"---that's
85 guaranteed to describe something different from "the right way" for
86 macros, so the post-processing will be done correctly.
87 The processing done to macro values is mainly to ensure that we can
89 get away with storing just a string in the macro table: macros
90 invoked by the macro are themselves expanded, and all sub-strings
91 are concatenated. For instance, if btparse parses these entries:
92 @string{and = " and "}
94 @string{jim_n_bob = "James Smith" # and # "Bob Jones"}
95 then the value stored for "jim_n_bob" should obviously be the
97 string "James Smith and Bob Jones". To ensure this, btparse has to
98 process the value of "and" differently from most BibTeX strings: in
99 particular, whitespace is not collapsed before the string is
100 stored. That way, the correct value, " and ", is interpolated into
101 the value of "jim_n_bob". Thus, all macro values have sub-macros
102 expanded and strings concatenated before they are stored, but
103 whitespace is not collapsed until the macro is used in a regular
104 entry.
105 This function calls "bt_add_macro_text()", so the same proviso
107 about redefining old macros applies---a warning will be issued, and
108 the old value lost.
109 bt_delete_macro ()
111 void bt_delete_macro (char * macro);
112 Deletes a macro from the macro table. If "macro" isn't defined,
114 takes no action.
115 bt_delete_all_macros ()
117 void bt_delete_all_macros (void);
118 Deletes all macros from the macro table.
120 bt_macro_length ()
122 int bt_macro_length (char *macro);
123 Returns the length of a macro's expansion text. If the macro is
125 undefined, returns 0; no warning is issued.
126 bt_macro_text ()
128 char * bt_macro_text (char * macro,
129 char * filename,
130 int line);
131 Returns the expansion text of a macro. If the macro is not
133 defined, issues a warning and returns "NULL". "filename" and
134 "line" are used for generating this warning; if they don't apply
135 (i.e. you're not expanding the macro as a result of finding it in
136 some file), supply "NULL" for "filename" and 0 for "line".
137
139 btparse
140
142 Greg Ward <gward@python.net>
143btparse, version 0.88 2022-07-22 BT_MACROS(1)