btparse::doc::bt_macros(3)

💖 bt_macros — the macro table glow-up 💖

okay so bestie, you know how btparse keeps a whole lil collection of macros (a.k.a. abbreviations) it bumps into while it's parsing BibTeX entries? yeah. that's this. this is the page for btparse::doc::bt_macros(3), and it's lowkey the backstage pass to that whole 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 🦋

so here's the tea, bestie: btparse maintains a single table of all the macros (abbreviations) it encounters while parsing BibTeX entries. it updates that table every single time it runs into a "macro definition" entry — you know, the @string ones — and it refers back to the table whenever a macro gets used in an entry and needs to be expanded. 🫶

ngl, macros aren't necessarily expanded on input, even though that's the default. go peek at bt_postprocess if you wanna know more. 👀

and here's the part you need to remember: macro definitions are only cleared when btparse's global cleanup function, bt_cleanup(), gets called. so unless you explicitly call bt_delete_macro() or bt_delete_all_macros(), those macro definitions persist for as long as you use the library — which is usually, like, the entire lifetime of your process. 💀 they're not going anywhere. they're the main characters. they live here now.

---

✨ FUNCTIONS ✨

you can use the following functions to add macros, delete them, and query their values — which means yes, you can absolutely interfere with btparse's normal operation on the fly. iconique behavior, honestly. 💅

🎀 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 there to generate any warnings about the macro definition — so if they don't apply, pass NULL for filename and 0 for line.

the only warning that can happen here is when you redefine an old macro: its value gets 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);

and that in turn will cause the macro fubar to be expanded appropriately whenever the post-processing code sees it in any future entries. slay. 🌟

🧚 bt_add_macro_value ()

void bt_add_macro_value (AST *  assignment,
                         btshort options);

this one is mainly for internal use by the library, but it's available to you if you ever find yourself holding a little bit of AST that represents a macro definition and you want to set the macro yourself instead of letting the library's post-processing code handle it for you. 💁

assignment must be an AST node as returned by bt_next_field(). and okay, unlike most other btparse functions that take an options argument, options here tells how the value in assignment was post-processed. why does that matter? because macro values have to be processed in a special way to be valid in future expansions, and 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. no cap. ✅

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 make that happen, 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. so basically: all macro values have sub-macros expanded and strings concatenated before they're stored, but whitespace isn't collapsed until the macro is used in a regular entry. periodt. 💖

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, it takes no action. very chill of it.

🌈 bt_delete_all_macros ()

void bt_delete_all_macros (void);

deletes all macros from the macro table. every last one. bye besties. 👋

⭐ 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 — and no warning is issued. it's not mad, it's just not gonna make it a whole thing.

🍓 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, it issues a warning and returns NULL. filename and line are used for generating that warning; if they don't apply (i.e. you're not expanding the macro because you found it in some file), supply NULL for filename and 0 for line. 🫶

---

👀 SEE ALSO 👀

btparse

---

👑 AUTHOR 👑

Greg Ward <gward@python.net>

---

and that's the whole page, bestie — btparse, version 0.91, dated 2025-01-31, brought to you by btparse::doc::bt_macros(3). go forth and macro responsibly. 💅✨🦋