1[comment {-*- tcl -*- doctools manpage}]
2[manpage_begin page_util_flow n 1.0]
3[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
4[moddesc   {Parser generator tools}]
5[titledesc {page dataflow/treewalker utility}]
6[category  {Page Parser Generator}]
7[require page::util::flow [opt 0.1]]
8[require snit]
9[keywords page dataflow {tree walking} {graph walking}]
10[keywords {parser generator} {text processing}]
11[description]
12[para]
13
14This package provides a single utility command for easy dataflow based
15manipulation of arbitrary data structures, especially abstract syntax
16trees.
17
18[section API]
19
20[list_begin definitions]
21[call [cmd ::page::util::flow] [arg start] [arg flowvar] [arg nodevar] [arg script]]
22
23This command contains the core logic to drive the walking of an
24arbitrary data structure which can partitioned into separate
25parts. Examples of such structures are trees and graphs.
26
27[para]
28
29The command makes no assumptions at all about the API of the structure
30to be walked, except that that its parts, here called [term nodes],
31are identified by strings. These strings are taken as is, from the
32arguments, and the body, and handed back to the body, without
33modification.
34
35[para]
36
37Access to the actual data structure, and all decisions regarding which
38nodes to visit in what order are delegated to the body of the loop,
39i.e. the [arg script].
40
41[para]
42
43The body is invoked first for the nodes in the start-set specified via
44[arg start]), and from then on for the nodes the body has requested to
45be visited. The command stops when the set of nodes to visit becomes
46empty. Note that a node can be visited more than once. The body has
47complete control about this.
48
49[para]
50
51The body is invoked in the context of the caller. The variable named
52by [arg nodevar] will be set to the current node, and the variable
53named by [arg flowvar] will be set to the command of the flow object
54through which the body can request the nodes to visit next. The API
55provided by this object is described in the next section,
56[sectref {FLOW API}].
57
58[para]
59
60Note that the command makes no promises regarding the order in which
61nodes are visited, excpt that the nodes requested to be visited by the
62current iteration will be visited afterward, in some order.
63
64[list_end]
65
66[section {FLOW API}]
67
68This section describes the API provided by the flow object made
69accessible to the body script of [cmd ::page::util::flow].
70
71[list_begin definitions]
72
73[call [arg flow] [method visit] [arg node]]
74
75Invoking this method requests that the node [arg n] is visited after
76the current iteration.
77
78[call [arg flow] [method visitl] [arg nodelist]]
79
80Invoking this method requests that all the nodes found in the list
81[arg nodelist] are visited after the current iteration.
82
83[call [arg flow] [method visita] [arg node]...]
84
85This is the variadic arguments form of the method [method visitl], see
86above.
87
88[list_end]
89
90[section {BUGS, IDEAS, FEEDBACK}]
91
92This document, will undoubtedly contain bugs and other problems.
93
94Please report such in the category [emph page] of the
95[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}].
96
97Please also report any ideas for enhancements you may have.
98
99[manpage_end]
100