1BT_TRAVERSAL(1)                     btparse                    BT_TRAVERSAL(1)
2
3
4

NAME

6       bt_traversal - AST traversal/query functions in btparse library
7

SYNOPSIS

9          AST * bt_next_entry (AST * entry_list,
10                               AST * prev_entry)
11          AST * bt_next_field  (AST * entry, AST * prev, char ** name)
12          AST * bt_next_value  (AST * head,
13                                AST * prev,
14                                bt_nodetype_t * nodetype,
15                                char ** text)
16
17          bt_metatype_t bt_entry_metatype (AST * entry)
18          char * bt_entry_type (AST * entry)
19          char * bt_entry_key   (AST * entry)
20          char * bt_get_text   (AST * node)
21

DESCRIPTION

23       The functions described here are all used to traverse and query the
24       abstract-syntax trees (ASTs) returned by the input functions described
25       in bt_input.  The three "bt_next" functions ("bt_next_entry()",
26       "bt_next_field()", and "bt_next_value()") are used respectively to
27       traverse a list of entries, the list of fields within a particular
28       entry, and the list of simple values associated with a particular
29       field.  The other functions are just used to query various nodes in the
30       tree for the useful information contained in them.
31
32   Traversal functions
33       bt_next_entry()
34              AST * bt_next_entry (AST * entry_list,
35                                   AST * prev_entry)
36
37           Used to traverse the linked list of entries returned by
38           "bt_parse_file()" (see bt_input).  On the first call, you should
39           supply "NULL" for "prev_entry", and a pointer to the head of the
40           list will be returned.  On subsequent calls, pass the previous
41           return value as "prev_entry"; the function returns the next entry
42           in the list, or "NULL" if there are no more entries.  Also returns
43           "NULL" if either "entry_list" or "prev_entry" are improper.
44
45           For example (ignoring error handling and variable declarations):
46
47              entries = bt_parse_file (filename, options, &status);
48              entry = NULL;
49              while (entry = bt_next_entry (entries, entry))
50              {
51                 /* process entry */
52              }
53
54       bt_next_field()
55              AST * bt_next_field  (AST * entry, AST * prev, char ** name)
56
57           Used to traverse the list of fields in a regular or macro
58           definition entry.  (You should call "bt_entry_metatype()" to
59           determine if you have the right kind of entry before calling
60           "bt_next_field()".)  "entry" should be a pointer to the AST for a
61           single entry, as returned by "bt_parse_entry()",
62           "bt_parse_entry_s()", or "bt_next_entry()".  On the first call,
63           supply "NULL" for "prev"; "bt_next_field()" will return a pointer
64           to the first field in "entry", or "NULL" if "entry" has no fields
65           (for instance, if it's a comment or preamble entry).  On subsequent
66           calls, pass the previous return value as "prev"; "bt_next_field()"
67           will keep returning pointers to field sub-ASTs as long as it makes
68           sense.  These pointers can then be passed to "bt_next_value()" or
69           "bt_get_text()" to get the field's value.
70
71           For example, the loop body in the previous example could be:
72
73              field = NULL;
74              while (field = bt_next_field (entry, field, &field_name))
75              {
76                 /* process field */
77              }
78
79       bt_next_value()
80              AST * bt_next_value (AST * head,
81                                   AST * prev,
82                                   bt_nodetype_t * nodetype,
83                                   char ** text)
84
85           Traverses the list of simple values that make up the value of a
86           single field.  (Recall that a simple value is either a quoted
87           string, a macro invocation, or a number.  A compound value is a
88           list of these separated by '#' in the original input.  Depending on
89           the string post-processing options used when the data was parsed,
90           the "list of simple values" nature of the original data may be
91           preserved in the AST that you're traversing, in which case you'll
92           need a "bt_next_value()" loop.
93
94           "bt_next_value()" works much like "bt_next_entry()" and
95           "bt_next_field()": on the first call, you supply "NULL" for "prev",
96           and on subsequent calls you supply the previous return value.
97           Returns "NULL" when there are no more simple values to return.
98           Also sets *nodetype and *text to the corresponding information from
99           the simple value node.  *nodetype will be one of "BTAST_STRING",
100           "BTAST_MACRO", or "BTAST_NUMBER"; *text will point to the same
101           string as the AST node does (it is not copied for you), so don't
102           mess with it.
103
104           For example, the loop body in the "bt_next_field()" example could
105           be replaced with:
106
107              value = NULL;
108              while (value = bt_next_field (field, value, &nodetype, &text))
109              {
110                 switch (nodetype)
111                 {
112                    case BTAST_STRING:    /* process the string */
113                    case BTAST_MACRO:     /* process the macro */
114                    case BTAST_NUMBER:    /* process the number */
115                 }
116              }
117
118           See also "bt_get_text".
119
120   Query functions
121       bt_entry_metatype()
122              bt_metatype_t bt_entry_metatype (AST * entry)
123
124           Returns the metatype of an entry.  (Recall that the metatype is an
125           enumerated type whose values are derived from the specific type of
126           an entry; for instance, an @comment entry has type "comment" and
127           metatype "BTE_COMMENT".  The type-metatype relationship is
128           similarly obvious for "BTE_PREAMBLE"; "BTE_MACRODEF" corresponds to
129           @string entries; and "BTE_REGULAR" corresponds to any other type.)
130
131           Returns "BTE_UNKNOWN" if "entry" is invalid (i.e., "NULL" or not a
132           pointer to an entry AST).
133
134       bt_entry_type()
135              char * bt_entry_type (AST * entry)
136
137           Returns the type of an entry.  Recall that the type is the name
138           that appears after the '@' character in the original input.
139           Returns "NULL" if "entry" is invalid (i.e., "NULL" or not a pointer
140           to an entry AST).
141
142       bt_entry_key()
143              char * bt_entry_key (AST * entry)
144
145           Returns the citation key of a regular entry.  (The citation key is
146           the name that appears after the entry-open delimiter in a regular
147           entry.)  Returns "NULL" if "entry" is invalid (i.e., "NULL" or not
148           a pointer to the AST for a regular entry).
149
150       bt_get_text()
151              char * bt_get_text (AST * node)
152
153           Performs all string post-processing (macro expansion, concatenation
154           of simple values, and whitespace collapsing) of a compound value
155           and returns the string that results.  Can be called either on a
156           field for a regular or macro definition entry (as returned by
157           "bt_next_field()"), or on a comment or preamble entry.  Returns
158           "NULL" if called on an invalid AST node.
159

SEE ALSO

161       btparse, bt_input, bt_postprocess
162

AUTHOR

164       Greg Ward <gward@python.net>
165
166
167
168btparse, version 0.88             2022-07-22                   BT_TRAVERSAL(1)
Impressum