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

FreeBSD Manual Pages

  
 
  

home | help
bt_input(3)			    btparse			   bt_input(3)

NAME
       bt_input	- input/parsing	functions in btparse library

SYNOPSIS
	  void	bt_set_stringopts (bt_metatype_t metatype, ushort options);
	  AST *	bt_parse_entry_s (char *    entry_text,
				  char *    filename,
				  int	    line,
				  ushort    options,
				  boolean * status);
	  AST *	bt_parse_entry	 (FILE *    infile,
				  char *    filename,
				  ushort    options,
				  boolean * status);
	  AST *	bt_parse_file	 (char *    filename,
				  ushort    options,
				  boolean * overall_status);

DESCRIPTION
       The functions described here are	used to	read and parse BibTeX data,
       converting it from raw text to abstract-syntax trees (ASTs).

       bt_set_stringopts ()
	      void bt_set_stringopts (bt_metatype_t metatype, ushort options);

	   Set the string-processing options for a particular entry metatype.
	   This	affects	the entry post-processing done by "bt_parse_en-
	   try_s()", "bt_parse_entry()", and "bt_parse_file()".	 If
	   "bt_set_stringopts()" is never called, the four metatypes default
	   to the following sets of string options:

	      BTE_REGULAR    BTO_CONVERT | BTO_EXPAND |	BTO_PASTE | BTO_COLLAPSE
	      BTE_COMMENT    0
	      BTE_PREAMBLE   0
	      BTE_MACRODEF   BTO_CONVERT | BTO_EXPAND |	BTO_PASTE

	   For example,

	      bt_set_stringopts	(BTE_COMMENT, BTO_COLLAPSE);

	   will	cause the library to collapse whitespace in the	value from all
	   comment entries; the	AST returned by	one of the "bt_parse_*"	func-
	   tions will reflect this change.

       bt_parse_entry ()
	      AST * bt_parse_entry (FILE *    infile,
				    char *    filename,
				    ushort    options,
				    boolean * status);

	   Scans and parses the	next BibTeX entry in "infile".	You should
	   supply "filename" to	help btparse generate accurate error messages;
	   the library keeps track of "infile"'s current line number inter-
	   nally, so you don't need to pass that in.  "options"	should be a
	   bitmap of non-string-processing options (currently, "BTO_NOSTORE"
	   to disable storing macro expansions is the only such	option).
	   *status will	be set to "TRUE" if the	entry parsed successfully or
	   with	only minor warnings, and "FALSE" if there were any serious
	   lexical or syntactic	errors.	 If "status" is	"NULL",	then the parse
	   status will be unavailable to you.  Both minor warnings and serious
	   errors are reported on "stderr".

	   Returns a pointer to	the abstract-syntax tree (AST) describing the
	   entry just parsed, or "NULL"	if no more entries were	found in "in-
	   file" (this will leave "infile" at end-of-file).  Do	not attempt to
	   second guess	"bt_parse_entry()" by detecting	end-of-file yourself;
	   it must be allowed to determine this	on its own so it can clean up
	   some	static data that is preserved between calls on the same	file.

	   "bt_parse_entry()" has two important	restrictions that you should
	   know	about.	First, you should let btparse manage all the input on
	   the file; this is for reasons both superficial (so the library
	   knows the current line number in order to generate accurate error
	   messages) and fundamental (the library must be allowed to detect
	   end-of-file in order	to cleanup certain static variables and	allow
	   you to parse	another	file).	Second,	you cannot interleave the
	   parsing of two different files; attempting to do so will result in
	   a fatal error that will crash your program.	This is	a direct re-
	   sult	of the static state maintained between calls of	"bt_parse_en-
	   try()".

	   Because of two distinct "failures" possible for "bt_parse_entry()"
	   (end-of-file, which is expected but means to	stop processing	the
	   current file; and error-in-input, which is not expected but allows
	   you to continue processing the same file), you should usually call
	   it like this:

	      while (entry = bt_parse_entry (file, filename, options, &ok))
	      {
		 if (ok)
		 {
		    /* ... process entry ... */
		 }
	      }

	   At the end of this loop, "feof (file)" will be true.

       bt_parse_entry_s	()
	      AST * bt_parse_entry_s (char *	entry_text,
				      char *	filename,
				      int	line,
				      ushort	options,
				      boolean *	status)

	   Scans and parses a single complete BibTeX entry contained in	a
	   string, "entry_text".  If you read this string from a file, you
	   should help btparse generate	accurate error messages	by supplying
	   the name of the file	as "filename" and the line number of the be-
	   ginning of the entry	as "line"; otherwise, set "filename" to	"NULL"
	   and "line" to 1.  "options" and "status" are	the same as for
	   "bt_parse_entry()".

	   Returns a pointer to	the abstract-syntax tree (AST) describing the
	   entry just parsed, and "NULL" if no entries were found in "en-
	   try_text" or	if "entry_text"	was "NULL".

	   You should call "bt_parse_entry_s()"	once more than the total num-
	   ber of entries you wish to parse; on	the final call,	set "en-
	   try_text" to	"NULL" so the function knows there's no	more text to
	   parse.  This	final call allows it to	clean up some structures allo-
	   cated on the	first call.  Thus, "bt_parse_entry_s()"	is usually
	   used	like this:

	      char *  entry_text;
	      ushort  options =	0;
	      boolean ok;
	      AST *   entry_ast;

	      while (entry_text	= get_more_text	())
	      {
		 entry_ast = bt_parse_entry_s (entry_text, NULL, 1, options, &ok);
		 if (ok)
		 {
		    /* ... process entry ... */
		 }
	      }

	      bt_parse_entry_s (NULL, NULL, 1, options,	NULL);	  /* cleanup */

	   assuming that "get_more_text()" returns a pointer to	the text of an
	   entry to parse, or "NULL" if	there's	no more	text available.

       bt_parse_file ()
	      AST * bt_parse_file (char	*    filename,
				   ushort    options,
				   boolean * status)

	   Scans and parses an entire BibTeX file.  If "filename" is "NULL" or
	   "-",	then "stdin" will be read; otherwise, attempts to open the
	   named file.	If this	attempt	fails, prints an error message to
	   "stderr" and	returns	"NULL".	 "options" and "status"	are the	same
	   as for "bt_parse_entry()"---note that *status will be "FALSE" if
	   there were any errors in the	entire file; for finer granularity of
	   error-checking, you should use "bt_parse_entry()".

	   Returns a pointer to	a linked list of ASTs representing the entries
	   in the file,	or "NULL" if no	entries	were found in the file.	 This
	   list	can be traversed with "bt_next_entry()", and the individual
	   entries then	traversed as usual (see	bt_traversal).

SEE ALSO
       btparse,	bt_postprocess,	bt_traversal

AUTHOR
       Greg Ward <gward@python.net>

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

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHOR

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

home | help