Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
bt_macros(3)			    btparse			  bt_macros(3)

       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) encoun-
       tered while parsing BibTeX entries.  It updates this table whenever it
       encounters a "macro definition" (@string) entry,	and refers to it when-
       ever 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.  "file-
	   name" and "line" are	just used to generate any warnings about the
	   macro definition; if	they don't apply, specify "NULL" for "file-
	   name" and 0 for "line".  The	only such warning occurs when you re-
	   define 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 appropri-
	   ately whenever the post-processing code sees	it in any future en-

       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 re-
	   turned 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 in-
	   voked 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 de-
	   fined, 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".


       Greg Ward <>

btparse, version 0.34		  2003-10-25			  bt_macros(3)


Want to link to this manual page? Use this URL:

home | help