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 <gward@python.net>

btparse, version 0.88                              2022-02-06                         btparse::doc::bt_macros(3)