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

FreeBSD Manual Pages

  
 
  

home | help
BT_MACROS(1)			    btparse			  BT_MACROS(1)

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.80		  2017-03-25			  BT_MACROS(1)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=bt_macros&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help