--- name: "bt_macros" section: "3" platform: "linux" package: "libbtparse-dev" version: "0.91-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/bt_macros/3" --- # bt\_macros(3) accessing and manipulating the btparse macro table ## NAME bt\_macros - accessing and manipulating the btparse macro table ## SYNOPSIS ``` void bt_add_macro_value (AST * assignment, btshort options); void bt_add_macro_text (char * macro, char * text, char * filename, int line); void bt_delete_macro (char * macro); void bt_delete_all_macros (void); int bt_macro_length (char *macro); char * bt_macro_text (char * macro, char * filename, int line); ``` ## DESCRIPTION **btparse** maintains a single table of all macros (abbreviations) encountered while parsing BibTeX entries. It updates this table whenever it encounters a "macro definition" (`@string`) entry, and refers to it whenever a macro is used in an entry and needs to be expanded. (Macros are not necessarily expanded on input, although this is the default. See bt\_postprocess.) Macro definitions are only cleared when **btparse**'s global cleanup function, `bt_cleanup()`, is called. Thus, unless you explicitly call `bt_delete_macro()` or `bt_delete_all_macros()`, macro definitions persist for as long as you use the library---usually, the lifetime of your process. ## FUNCTIONS You can use the following functions to add macros, delete them, and query their values---thus interfering with **btparse**'s normal operation on the fly. - bt\_add\_macro\_text () ``` void bt_add_macro_text (char * macro, char * text, char * filename, int line); ``` Defines a new macro, or redefines an old one. `"macro"` is the name of the macro, and `"text"` is the text it should expand to. `"filename"` and `"line"` are just used to generate any warnings about the macro definition; if they don't apply, specify `"NULL"` for `"filename"` and `0` for `"line"`. The only such warning occurs when you redefine an old macro: its value is overridden, and `bt_add_macro_text()` issues a warning saying so. For instance, when parsing this macro definition entry: ``` @string{fubar = "Fouled Up Beyond All Recognition"} ``` the library (in particular, the post-processing code called after an entry is successfully parsed) will ultimately do this: ``` bt_add_macro_text ("fubar", "Fouled Up Beyond All Recognition", filename, line); ``` This in turn will cause the macro `"fubar"` to be expanded appropriately whenever the post-processing code sees it in any future entries. - bt\_add\_macro\_value () ``` void bt_add_macro_value (AST * assignment, btshort options); ``` This function is mainly for internal use by the library, but it's available to you if you ever find yourself with a little bit of AST representing a macro definition, and you want to set the macro yourself (rather than letting the library's post-processing code take care of it for you). `"assignment"` must be an AST node as returned by `bt_next_field()`. Unlike most other **btparse** functions that take an `"options"` argument, `"options"` here tells how the value in `"assignment"` was post-processed. This is needed because macro values have to be processed in a special way to be valid in future expansions; if this one wasn't processed like that, `bt_add_macro_value()` will do it for you. If you don't know how the value was post-processed, just supply `0` for `"options"`---that's guaranteed to describe something different from "the right way" for macros, so the post-processing will be done correctly. The processing done to macro values is mainly to ensure that we can get away with storing just a string in the macro table: macros invoked by the macro are themselves expanded, and all sub-strings are concatenated. For instance, if **btparse** parses these entries: ``` @string{and = " and "} @string{jim_n_bob = "James Smith" # and # "Bob Jones"} ``` then the value stored for `"jim_n_bob"` should obviously be the string `"James Smith and Bob Jones"`. To ensure this, **btparse** has to process the value of `"and"` differently from most BibTeX strings: in particular, whitespace is *not* collapsed before the string is stored. That way, the correct value, `" and "`, is interpolated into the value of `"jim_n_bob"`. Thus, all macro values have sub-macros expanded and strings concatenated before they are stored, but whitespace is not collapsed until the macro is used in a regular entry. This function calls `bt_add_macro_text()`, so the same proviso about redefining old macros applies---a warning will be issued, and the old value lost. - bt\_delete\_macro () ``` void bt_delete_macro (char * macro); ``` Deletes a macro from the macro table. If `"macro"` isn't defined, takes no action. - bt\_delete\_all\_macros () ``` void bt_delete_all_macros (void); ``` Deletes all macros from the macro table. - bt\_macro\_length () ``` int bt_macro_length (char *macro); ``` Returns the length of a macro's expansion text. If the macro is undefined, returns 0; no warning is issued. - bt\_macro\_text () ``` char * bt_macro_text (char * macro, char * filename, int line); ``` Returns the expansion text of a macro. If the macro is not defined, issues a warning and returns `"NULL"`. `"filename"` and `"line"` are used for generating this warning; if they don't apply (i.e. you're not expanding the macro as a result of finding it in some file), supply `"NULL"` for `"filename"` and `0` for `"line"`. ## SEE ALSO btparse ## AUTHOR Greg Ward \