bt_traversal man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

bt_traversal(3)			    btparse		       bt_traversal(3)

NAME
       bt_traversal - AST traversal/query functions in btparse library

SYNOPSIS
	  AST * bt_next_entry (AST * entry_list,
			       AST * prev_entry)
	  AST * bt_next_field  (AST * entry, AST * prev, char ** name)
	  AST * bt_next_value  (AST * head,
				AST * prev,
				bt_nodetype_t * nodetype,
				char ** text)

	  bt_metatype_t bt_entry_metatype (AST * entry)
	  char * bt_entry_type (AST * entry)
	  char * bt_entry_key	(AST * entry)
	  char * bt_get_text   (AST * node)

DESCRIPTION
       The functions described here are all used to traverse and query the
       abstract-syntax trees (ASTs) returned by the input functions described
       in bt_input.  The three "bt_next" functions ("bt_next_entry()",
       "bt_next_field()", and "bt_next_value()") are used respectively to tra‐
       verse a list of entries, the list of fields within a particular entry,
       and the list of simple values associated with a particular field.  The
       other functions are just used to query various nodes in the tree for
       the useful information contained in them.

       Traversal functions

       bt_next_entry()
	      AST * bt_next_entry (AST * entry_list,
				   AST * prev_entry)

	   Used to traverse the linked list of entries returned by
	   "bt_parse_file()" (see bt_input).  On the first call, you should
	   supply "NULL" for "prev_entry", and a pointer to the head of the
	   list will be returned.  On subsequent calls, pass the previous
	   return value as "prev_entry"; the function returns the next entry
	   in the list, or "NULL" if there are no more entries.	 Also returns
	   "NULL" if either "entry_list" or "prev_entry" are improper.

	   For example (ignoring error handling and variable declarations):

	      entries = bt_parse_file (filename, options, &status);
	      entry = NULL;
	      while (entry = bt_next_entry (entries, entry))
	      {
		 /* process entry */
	      }

       bt_next_field()
	      AST * bt_next_field  (AST * entry, AST * prev, char ** name)

	   Used to traverse the list of fields in a regular or macro defini‐
	   tion entry.	(You should call "bt_entry_metatype()" to determine if
	   you have the right kind of entry before calling "bt_next_field()".)
	   "entry" should be a pointer to the AST for a single entry, as
	   returned by "bt_parse_entry()", "bt_parse_entry_s()", or
	   "bt_next_entry()".  On the first call, supply "NULL" for "prev";
	   "bt_next_field()" will return a pointer to the first field in
	   "entry", or "NULL" if "entry" has no fields (for instance, if it's
	   a comment or preamble entry).  On subsequent calls, pass the previ‐
	   ous return value as "prev"; "bt_next_field()" will keep returning
	   pointers to field sub-ASTs as long as it makes sense.  These point‐
	   ers can then be passed to "bt_next_value()" or "bt_get_text()" to
	   get the field's value.

	   For example, the loop body in the previous example could be:

	      field = NULL;
	      while (field = bt_next_field (entry, field, &field_name))
	      {
		 /* process field */
	      }

       bt_next_value()
	      AST * bt_next_value (AST * head,
				   AST * prev,
				   bt_nodetype_t * nodetype,
				   char ** text)

	   Traverses the list of simple values that make up the value of a
	   single field.  (Recall that a simple value is either a quoted
	   string, a macro invocation, or a number.  A compound value is a
	   list of these separated by '#' in the original input.  Depending on
	   the string post-processing options used when the data was parsed,
	   the "list of simple values" nature of the original data may be pre‐
	   served in the AST that you're traversing, in which case you'll need
	   a "bt_next_value()" loop.

	   "bt_next_value()" works much like "bt_next_entry()" and
	   "bt_next_field()": on the first call, you supply "NULL" for "prev",
	   and on subsequent calls you supply the previous return value.
	   Returns "NULL" when there are no more simple values to return.
	   Also sets *nodetype and *text to the corresponding information from
	   the simple value node.  *nodetype will be one of "BTAST_STRING",
	   "BTAST_MACRO", or "BTAST_NUMBER"; *text will point to the same
	   string as the AST node does (it is not copied for you), so don't
	   mess with it.

	   For example, the loop body in the "bt_next_field()" example could
	   be replaced with:

	      value = NULL;
	      while (value = bt_next_field (field, value, &nodetype, &text))
	      {
		 switch (nodetype)
		 {
		    case BTAST_STRING:	  /* process the string */
		    case BTAST_MACRO:	  /* process the macro */
		    case BTAST_NUMBER:	  /* process the number */
		 }
	      }

	   See also "bt_get_text".

       Query functions

       bt_entry_metatype()
	      bt_metatype_t bt_entry_metatype (AST * entry)

	   Returns the metatype of an entry.  (Recall that the metatype is an
	   enumerated type whose values are derived from the specific type of
	   an entry; for instance, an @comment entry has type "comment" and
	   metatype "BTE_COMMENT".  The type-metatype relationship is simi‐
	   larly obvious for "BTE_PREAMBLE"; "BTE_MACRODEF" corresponds to
	   @string entries; and "BTE_REGULAR" corresponds to any other type.)

	   Returns "BTE_UNKNOWN" if "entry" is invalid (i.e., "NULL" or not a
	   pointer to an entry AST).

       bt_entry_type()
	      char * bt_entry_type (AST * entry)

	   Returns the type of an entry.  Recall that the type is the name
	   that appears after the '@' character in the original input.
	   Returns "NULL" if "entry" is invalid (i.e., "NULL" or not a pointer
	   to an entry AST).

       bt_entry_key()
	      char * bt_entry_key (AST * entry)

	   Returns the citation key of a regular entry.	 (The citation key is
	   the name that appears after the entry-open delimiter in a regular
	   entry.)  Returns "NULL" if "entry" is invalid (i.e., "NULL" or not
	   a pointer to the AST for a regular entry).

       bt_get_text()
	      char * bt_get_text (AST * node)

	   Performs all string post-processing (macro expansion, concatenation
	   of simple values, and whitespace collapsing) of a compound value
	   and returns the string that results.	 Can be called either on a
	   field for a regular or macro definition entry (as returned by
	   "bt_next_field()"), or on a comment or preamble entry.  Returns
	   "NULL" if called on an invalid AST node.

SEE ALSO
       btparse, bt_input, bt_postprocess

AUTHOR
       Greg Ward <gward@python.net>

btparse, version 0.34		  2003-10-25		       bt_traversal(3)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net