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>