Man Linux: Main Page and Category List


       bt_macros - accessing and manipulating the btparse macro table


          void bt_add_macro_value (AST *  assignment,
                                   ushort 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);


       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.


       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
            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,
                                       ushort 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  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

           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  for "line".




       Greg Ward <>