bt_traversal - AST traversal/query functions in btparse library

   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)

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 (CWbt_next_entry(), CWbt_next_field(), and CWbt_next_value()) are used respectively to traverse 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.

bt_next_entry()

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

Used to traverse the linked list of entries returned by CWbt_parse_file() (see bt_input). On the first call, you should supply CWNULL for CWprev_entry, and a pointer to the head of the list will be returned. On subsequent calls, pass the previous return value as CWprev_entry; the function returns the next entry in the list, or CWNULL if there are no more entries. Also returns CWNULL if either CWentry_list or CWprev_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 definition entry. (You should call CWbt_entry_metatype() to determine if you have the right kind of entry before calling CWbt_next_field().) CWentry should be a pointer to the AST for a single entry, as returned by CWbt_parse_entry(), CWbt_parse_entry_s(), or CWbt_next_entry(). On the first call, supply CWNULL for CWprev; CWbt_next_field() will return a pointer to the first field in CWentry, or CWNULL if CWentry has no fields (for instance, if it's a comment or preamble entry). On subsequent calls, pass the previous return value as CWprev; CWbt_next_field() will keep returning pointers to field sub-ASTs as long as it makes sense. These pointers can then be passed to CWbt_next_value() or CWbt_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 CW'#' 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 preserved in the AST that you're traversing, in which case you'll need a CWbt_next_value() loop. CWbt_next_value() works much like CWbt_next_entry() and CWbt_next_field(): on the first call, you supply CWNULL for CWprev, and on subsequent calls you supply the previous return value. Returns CWNULL when there are no more simple values to return. Also sets CW*nodetype and CW*text to the corresponding information from the simple value node. CW*nodetype will be one of CWBTAST_STRING, CWBTAST_MACRO, or CWBTAST_NUMBER; CW*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 CWbt_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.

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 CW@comment entry has type CW"comment" and metatype CWBTE_COMMENT. The type-metatype relationship is similarly obvious for CWBTE_PREAMBLE; CWBTE_MACRODEF corresponds to CW@string entries; and CWBTE_REGULAR corresponds to any other type.) Returns CWBTE_UNKNOWN if CWentry is invalid (i.e., CWNULL 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 CW'@' character in the original input. Returns CWNULL if CWentry is invalid (i.e., CWNULL 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 CWNULL if CWentry is invalid (i.e., CWNULL 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 CWbt_next_field()), or on a comment or preamble entry. Returns CWNULL if called on an invalid AST node.

btparse, bt_input, bt_postprocess

Greg Ward <gward@python.net>