1struct::graph(n)              Tcl Data Structures             struct::graph(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       struct::graph - Create and manipulate directed graph objects
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require struct::graph  ?2.3?
14
15       package require struct::list  ?1.5?
16
17       package require struct::set  ?2.2.3?
18
19       ::struct::graph ?graphName? ?=|:=|as|deserialize source?
20
21       graphName option ?arg arg ...?
22
23       graphName = sourcegraph
24
25       graphName --> destgraph
26
27       graphName append key value
28
29       graphName deserialize serialization
30
31       graphName destroy
32
33       graphName arc append arc key value
34
35       graphName arc attr key
36
37       graphName arc attr key -arcs list
38
39       graphName arc attr key -glob globpattern
40
41       graphName arc attr key -regexp repattern
42
43       graphName arc delete arc ?arc ...?
44
45       graphName arc exists arc
46
47       graphName arc flip arc
48
49       graphName arc get arc key
50
51       graphName arc getall arc ?pattern?
52
53       graphName arc getunweighted
54
55       graphName arc getweight arc
56
57       graphName arc keys arc ?pattern?
58
59       graphName arc keyexists arc key
60
61       graphName arc insert start end ?child?
62
63       graphName arc lappend arc key value
64
65       graphName arc rename arc newname
66
67       graphName arc set arc key ?value?
68
69       graphName arc setunweighted ?weight?
70
71       graphName arc setweight arc weight
72
73       graphName arc unsetweight arc
74
75       graphName arc hasweight arc
76
77       graphName arc source arc
78
79       graphName arc target arc
80
81       graphName arc move-source arc newsource
82
83       graphName arc move-target arc newtarget
84
85       graphName arc move arc newsource newtarget
86
87       graphName arc unset arc key
88
89       graphName arc weights
90
91       graphName   arcs   ?-key   key?   ?-value  value?  ?-filter  cmdprefix?
92       ?-in|-out|-adj|-inner|-embedding node node...?
93
94       graphName lappend key value
95
96       graphName node append node key value
97
98       graphName node attr key
99
100       graphName node attr key -nodes list
101
102       graphName node attr key -glob globpattern
103
104       graphName node attr key -regexp repattern
105
106       graphName node degree ?-in|-out? node
107
108       graphName node delete node ?node...?
109
110       graphName node exists node
111
112       graphName node get node key
113
114       graphName node getall node ?pattern?
115
116       graphName node keys node ?pattern?
117
118       graphName node keyexists node key
119
120       graphName node insert ?node...?
121
122       graphName node lappend node key value
123
124       graphName node opposite node arc
125
126       graphName node rename node newname
127
128       graphName node set node key ?value?
129
130       graphName node unset node key
131
132       graphName  nodes  ?-key  key?  ?-value   value?   ?-filter   cmdprefix?
133       ?-in|-out|-adj|-inner|-embedding node node...?
134
135       graphName get key
136
137       graphName getall ?pattern?
138
139       graphName keys ?pattern?
140
141       graphName keyexists key
142
143       graphName serialize ?node...?
144
145       graphName set key ?value?
146
147       graphName swap node1 node2
148
149       graphName unset key
150
151       graphName  walk node ?-order order? ?-type type? ?-dir direction? -com‐
152       mand cmd
153
154_________________________________________________________________
155

DESCRIPTION

157       A directed graph is a structure containing two collections of elements,
158       called  nodes and arcs respectively, together with a relation ("connec‐
159       tivity") that places a general structure upon the nodes and arcs.
160
161       Each arc is connected to two nodes, one of which is called  the  source
162       and  the other the target. This imposes a direction upon the arc, which
163       is said to go from the source to the target. It is allowed that  source
164       and  target  of an arc are the same node. Such an arc is called a loop.
165       Whenever a node is either the source or target of an arc both are  said
166       to be adjacent. This extends into a relation between nodes, i.e. if two
167       nodes are connected through at least one arc they are said to be  adja‐
168       cent too.
169
170       Each node can be the source and target for any number of arcs. The for‐
171       mer are called the outgoing arcs of the node, the latter  the  incoming
172       arcs  of  the  node. The number of arcs in either set is called the in-
173       degree resp. the out-degree of the node.
174
175       In addition to maintaining the node and arc relationships,  this  graph
176       implementation  allows  any number of named attributes to be associated
177       with the graph itself, and each node or arc.
178
179       Note: The major version of the package struct has been changed to  ver‐
180       sion  2.0, due to backward incompatible changes in the API of this mod‐
181       ule. Please read the section Changes for 2.0 for a  full  list  of  all
182       changes, incompatible and otherwise.
183
184       Note:  A  C-implementation  of the command can be had from the location
185       http://www.purl.org/NET/schlenker/tcl/cgraph.         See          also
186       http://wiki.tcl.tk/cgraph.   This implementation uses a bit less memory
187       than the tcl version provided here directly, and is faster. Its support
188       is limited to versions of the package before 2.0.
189
190       As  of  version  2.2 of this package a critcl based C implementation is
191       available from here as well. This implementation however  requires  Tcl
192       8.4 to run.
193
194       The main command of the package is:
195
196       ::struct::graph ?graphName? ?=|:=|as|deserialize source?
197              The command creates a new graph object with an associated global
198              Tcl command whose name is graphName.  This command may  be  used
199              to invoke various operations on the graph.  It has the following
200              general form:
201
202              graphName option ?arg arg ...?
203                     Option and the args determine the exact behavior  of  the
204                     command.
205
206       If  graphName  is  not specified a unique name will be generated by the
207       package itself. If a source is specified the new graph will be initial‐
208       ized  to  it.  For  the  operators =, :=, and as the source argument is
209       interpreted as the name of another graph  object,  and  the  assignment
210       operator = will be executed. For the operator deserialize the source is
211       a serialized graph object and deserialize will be executed.
212
213       In other words
214
215
216           ::struct::graph mygraph = b
217
218
219       is equivalent to
220
221
222           ::struct::graph mygraph
223           mygraph = b
224
225
226       and
227
228
229           ::struct::graph mygraph deserialize $b
230
231
232       is equivalent to
233
234
235           ::struct::graph mygraph
236           mygraph deserialize $b
237
238
239       The following commands are possible for graph objects:
240
241       graphName = sourcegraph
242              This is the assignment operator for graph objects. It copies the
243              graph  contained  in the graph object sourcegraph over the graph
244              data in graphName. The old contents of graphName are deleted  by
245              this operation.
246
247              This operation is in effect equivalent to
248
249
250                  graphName deserialize [sourcegraph serialize]
251
252
253              The  operation  assumes that the sourcegraph provides the method
254              serialize and that this method returns a valid graph  serializa‐
255              tion.
256
257       graphName --> destgraph
258              This  is  the  reverse assignment operator for graph objects. It
259              copies the graph contained in the graph  object  graphName  over
260              the  graph  data  in  the object destgraph.  The old contents of
261              destgraph are deleted by this operation.
262
263              This operation is in effect equivalent to
264
265
266                  destgraph deserialize [graphName serialize]
267
268
269              The operation assumes that the  destgraph  provides  the  method
270              deserialize and that this method takes a graph serialization.
271
272       graphName append key value
273              Appends  a  value to one of the keyed values associated with the
274              graph.  Returns the new value given to the attribute key.
275
276       graphName deserialize serialization
277              This is the complement to serialize. It replaces the graph  data
278              in  graphName  with  the  graph  described  by the serialization
279              value. The old contents of graphName are deleted by this  opera‐
280              tion.
281
282       graphName destroy
283              Destroys  the  graph, including its storage space and associated
284              command.
285
286       graphName arc append arc key value
287              Appends a value to one of the keyed values  associated  with  an
288              arc. Returns the new value given to the attribute key.
289
290       graphName arc attr key
291
292       graphName arc attr key -arcs list
293
294       graphName arc attr key -glob globpattern
295
296       graphName arc attr key -regexp repattern
297              This  method retrieves the value of the attribute named key, for
298              all arcs in the graph (matching the  restriction  specified  via
299              one of the possible options) and having the specified attribute.
300
301              The  result  is a dictionary mapping from arc names to the value
302              of attribute key at that arc.  Arcs  not  having  the  attribute
303              key,  or  not passing a specified restriction, are not listed in
304              the result.
305
306              The possible restrictions are:
307
308              -arcs  The value is a list of arcs. Only the arcs  mentioned  in
309                     this list are searched for the attribute.
310
311              -glob  The  value  is a glob pattern. Only the arcs in the graph
312                     whose names match  this  pattern  are  searched  for  the
313                     attribute.
314
315              -regexp
316                     The  value  is a regular expression. Only the arcs in the
317                     graph whose names match this pattern are searched for the
318                     attribute.
319
320
321       graphName arc delete arc ?arc ...?
322              Remove the specified arcs from the graph.
323
324       graphName arc exists arc
325              Return true if the specified arc exists in the graph.
326
327       graphName arc flip arc
328              Reverses  the  direction  of  the named arc, i.e. the source and
329              target nodes of the arc are exchanged with each other.
330
331       graphName arc get arc key
332              Returns the value associated with the key key for the arc.
333
334       graphName arc getall arc ?pattern?
335              Returns a dictionary (suitable for use with [array set]) for the
336              arc.   If  the  pattern  is  specified only the attributes whose
337              names match the pattern will be part of the returned dictionary.
338              The pattern is a glob pattern.
339
340       graphName arc getunweighted
341              Returns  a  list  containing  the names of all arcs in the graph
342              which have no weight associated with them.
343
344       graphName arc getweight arc
345              Returns the weight associated with the arc. Throws an  error  if
346              the arc has no weight associated with it.
347
348       graphName arc keys arc ?pattern?
349              Returns a list of keys for the arc.  If the pattern is specified
350              only the attributes whose names match the pattern will  be  part
351              of the returned list. The pattern is a glob pattern.
352
353       graphName arc keyexists arc key
354              Return true if the specified key exists for the arc.
355
356       graphName arc insert start end ?child?
357              Insert  an  arc named child into the graph beginning at the node
358              start and ending at the node end. If the name of the new arc  is
359              not specified the system will generate a unique name of the form
360              arcx.
361
362       graphName arc lappend arc key value
363              Appends a value (as a list) to one of the keyed  values  associ‐
364              ated  with  an arc. Returns the new value given to the attribute
365              key.
366
367       graphName arc rename arc newname
368              Renames the arc arc to newname. An error is thrown if either the
369              arc  does  not exist, or a arc with name newname does exist. The
370              result of the command is the new name of the arc.
371
372       graphName arc set arc key ?value?
373              Set or get one of the keyed values associated with an  arc.   An
374              arc  may have any number of keyed values associated with it.  If
375              value is not specified, this command returns the  current  value
376              assigned to the key; if value is specified, this command assigns
377              that value to the key, and returns that value.
378
379       graphName arc setunweighted ?weight?
380              Sets the weight of all arcs without a weight to weight.  Returns
381              the  empty  string as its result. If not present weight defaults
382              to 0.
383
384       graphName arc setweight arc weight
385              Sets the weight of the arc to weight. Returns weight.
386
387       graphName arc unsetweight arc
388              Removes the weight of the arc, if present. Does  nothing  other‐
389              wise. Returns the empty string.
390
391       graphName arc hasweight arc
392              Determines  if  the  arc  has  a weight associated with it.  The
393              result is a boolean value, True if  a  weight  is  defined,  and
394              False otherwise.
395
396       graphName arc source arc
397              Return the node the given arc begins at.
398
399       graphName arc target arc
400              Return the node the given arc ends at.
401
402       graphName arc move-source arc newsource
403              Changes  the source node of the arc to newsource. It can be said
404              that the arc rotates around its target node.
405
406       graphName arc move-target arc newtarget
407              Changes the target node of the arc to newtarget. It can be  said
408              that the arc rotates around its source node.
409
410       graphName arc move arc newsource newtarget
411              Changes  both  source  and target nodes of the arc to newsource,
412              and newtarget resp.
413
414       graphName arc unset arc key
415              Remove a keyed value from the arc arc. The method will do  noth‐
416              ing if the key does not exist.
417
418       graphName arc weights
419              Returns  a dictionary whose keys are the names of all arcs which
420              have a weight associated with them, and  the  values  are  these
421              weights.
422
423       graphName   arcs   ?-key   key?   ?-value  value?  ?-filter  cmdprefix?
424       ?-in|-out|-adj|-inner|-embedding node node...?
425              Returns a list of arcs in the graph. If no restriction is speci‐
426              fied  a  list  containing all arcs is returned. Restrictions can
427              limit the list of returned arcs based on the nodes that are con‐
428              nected  by the arc, on the keyed values associated with the arc,
429              or both. A general filter command  can  be  used  as  well.  The
430              restrictions that involve connected nodes take a variable number
431              of nodes as argument, specified after the name of  the  restric‐
432              tion itself.
433
434              The  restrictions  imposed by either -in, -out, -adj, -inner, or
435              -embedded are applied first. Specifying more than one of them is
436              illegal.
437
438              After  that  the  restrictions  set  via  -key  (and -value) are
439              applied. Specifying more than one -key (and -value) is  illegal.
440              Specifying -value alone, without -key is illegal as well.
441
442              Any  restriction set through -filter is applied last. Specifying
443              more than one -filter is illegal.
444
445              Coming back to the restrictions based on a  set  of  nodes,  the
446              command recognizes the following switches:
447
448              -in    Return  a  list  of  all  arcs whose target is one of the
449                     nodes in the set of nodes. I.e. it computes the union  of
450                     all incoming arcs of the nodes in the set.
451
452              -out   Return  a  list  of  all  arcs whose source is one of the
453                     nodes in the set of nodes. I.e. it computes the union  of
454                     all outgoing arcs of the nodes in the set.
455
456              -adj   Return a list of all arcs adjacent to at least one of the
457                     nodes in the set. This is the union of the nodes returned
458                     by -in and -out.
459
460              -inner Return  a  list  of all arcs which are adjacent to two of
461                     the nodes in the set. This is the set of arcs in the sub‐
462                     graph spawned by the specified nodes.
463
464              -embedding
465                     Return  a list of all arcs adjacent to exactly one of the
466                     nodes in the set. This is the set of arcs connecting  the
467                     subgraph  spawned  by  the specified nodes to the rest of
468                     the graph.
469
470              -key key
471                     Limit the list of arcs that are returned  to  those  arcs
472                     that have an associated key key.
473
474              -value value
475                     This  restriction  can  only  be used in combination with
476                     -key. It limits the list of arcs  that  are  returned  to
477                     those arcs whose associated key key has the value value.
478
479              -filter cmdrefix
480                     Limit  the  list  of arcs that are returned to those arcs
481                     that pass the test. The command in  cmdprefix  is  called
482                     with two arguments, the name of the graph object, and the
483                     name of the arc in question. It is executed in  the  con‐
484                     text  of  the  caller  and has to return a boolean value.
485                     Arcs for which the command returns false are removed from
486                     the result list before it is returned to the caller.
487
488       graphName lappend key value
489              Appends  a  value (as a list) to one of the keyed values associ‐
490              ated with  the  graph.  Returns  the  new  value  given  to  the
491              attribute key.
492
493       graphName node append node key value
494              Appends  a  value  to one of the keyed values associated with an
495              node. Returns the new value given to the attribute key.
496
497       graphName node attr key
498
499       graphName node attr key -nodes list
500
501       graphName node attr key -glob globpattern
502
503       graphName node attr key -regexp repattern
504              This method retrieves the value of the attribute named key,  for
505              all  nodes  in the graph (matching the restriction specified via
506              one of the possible options) and having the specified attribute.
507
508              The result is a dictionary mapping from node names to the  value
509              of  attribute  key at that node.  Nodes not having the attribute
510              key, or not passing a specified restriction, are not  listed  in
511              the result.
512
513              The possible restrictions are:
514
515              -nodes The value is a list of nodes. Only the nodes mentioned in
516                     this list are searched for the attribute.
517
518              -glob  The value is a glob pattern. Only the nodes in the  graph
519                     whose  names  match  this  pattern  are  searched for the
520                     attribute.
521
522              -regexp
523                     The value is a regular expression. Only the nodes in  the
524                     graph whose names match this pattern are searched for the
525                     attribute.
526
527
528       graphName node degree ?-in|-out? node
529              Return the number of arcs adjacent to the specified node. If one
530              of the restrictions -in or -out is given only the incoming resp.
531              outgoing arcs are counted.
532
533       graphName node delete node ?node...?
534              Remove the specified nodes from the graph.  All  of  the  nodes'
535              arcs will be removed as well to prevent unconnected arcs.
536
537       graphName node exists node
538              Return true if the specified node exists in the graph.
539
540       graphName node get node key
541              Return the value associated with the key key for the node.
542
543       graphName node getall node ?pattern?
544              Returns a dictionary (suitable for use with [array set]) for the
545              node.  If the pattern is specified  only  the  attributes  whose
546              names match the pattern will be part of the returned dictionary.
547              The pattern is a glob pattern.
548
549       graphName node keys node ?pattern?
550              Returns a list of keys for the node.  If the pattern  is  speci‐
551              fied  only  the attributes whose names match the pattern will be
552              part of the returned list. The pattern is a glob pattern.
553
554       graphName node keyexists node key
555              Return true if the specified key exists for the node.
556
557       graphName node insert ?node...?
558              Insert one or more nodes into the graph. The new nodes  have  no
559              arcs connected to them. If no node is specified one node will be
560              inserted, and the system will generate a unique name of the form
561              nodex for it.
562
563       graphName node lappend node key value
564              Appends  a  value (as a list) to one of the keyed values associ‐
565              ated with an node. Returns the new value given to the  attribute
566              key.
567
568       graphName node opposite node arc
569              Return the node at the other end of the specified arc, which has
570              to be adjacent to the given node.
571
572       graphName node rename node newname
573              Renames the node node to newname. An error is thrown  if  either
574              the node does not exist, or a node with name newname does exist.
575              The result of the command is the new name of the node.
576
577       graphName node set node key ?value?
578              Set or get one of the keyed values associated  with  a  node.  A
579              node may have any number of keyed values associated with it.  If
580              value is not specified, this command returns the  current  value
581              assigned to the key; if value is specified, this command assigns
582              that value to the key.
583
584       graphName node unset node key
585              Remove a keyed value from the node  node.  The  method  will  do
586              nothing if the key does not exist.
587
588       graphName   nodes   ?-key   key?  ?-value  value?  ?-filter  cmdprefix?
589       ?-in|-out|-adj|-inner|-embedding node node...?
590              Return a list of nodes in the graph. Restrictions can limit  the
591              list  of  returned nodes based on neighboring nodes, or based on
592              the keyed values associated with the node. The restrictions that
593              involve  neighboring  nodes  have  a  list of nodes as argument,
594              specified after the name of the restriction itself.
595
596              The possible restrictions are the same as for method  arcs.  The
597              exact meanings change slightly, as they operate on nodes instead
598              of arcs. The command recognizes:
599
600              -in    Return a list of all nodes with at least one outgoing arc
601                     ending  in  a  node  found in the specified set of nodes.
602                     Alternatively specified as the set of  source  nodes  for
603                     the -in arcs of the node set. The incoming neighbours.
604
605              -out   Return a list of all nodes with at least one incoming arc
606                     starting in a node found in the specified set  of  nodes.
607                     Alternatively  specified  as  the set of target nodes for
608                     the -out arcs of the node set. The outgoing neighbours.
609
610              -adj   This is the union of the nodes returned by -in and  -out.
611                     The neighbours.
612
613              -inner The  set of neighbours (see -adj above) which are also in
614                     the set of nodes. I.e. the intersection between  the  set
615                     of nodes and the neighbours per -adj.
616
617              -embedding
618                     The  set  of neighbours (see -adj above) which are not in
619                     the set of nodes. I.e. the difference between the  neigh‐
620                     bours as per -adj, and the set of nodes.
621
622              -key key
623                     Limit  the list of nodes that are returned to those nodes
624                     that have an associated key key.
625
626              -value value
627                     This restriction can only be  used  in  combination  with
628                     -key.  It  limits  the list of nodes that are returned to
629                     those nodes whose associated key key has the value value.
630
631              -filter cmdrefix
632                     Limit the list of nodes that are returned to those  nodes
633                     that  pass  the  test. The command in cmdprefix is called
634                     with two arguments, the name of the graph object, and the
635                     name  of the node in question. It is executed in the con‐
636                     text of the caller and has to  return  a  boolean  value.
637                     Nodes  for  which  the  command returns false are removed
638                     from the result list before it is returned to the caller.
639
640       graphName get key
641              Return the value associated with the key key for the graph.
642
643       graphName getall ?pattern?
644              Returns a dictionary (suitable for use with [array set]) for the
645              whole  graph.   If  the pattern is specified only the attributes
646              whose names match the pattern will be part of the returned  dic‐
647              tionary. The pattern is a glob pattern.
648
649       graphName keys ?pattern?
650              Returns  a  list of keys for the whole graph.  If the pattern is
651              specified only the attributes whose names match the pattern will
652              be part of the returned list. The pattern is a glob pattern.
653
654       graphName keyexists key
655              Return true if the specified key exists for the whole graph.
656
657       graphName serialize ?node...?
658              This method serializes the sub-graph spanned up by the nodes. In
659              other words it returns a tcl value  completely  describing  that
660              graph. If no nodes are specified the whole graph will be serial‐
661              ized.  This allows, for example, the transfer of  graph  objects
662              (or  parts  thereof)  over arbitrary channels, persistence, etc.
663              This method is also the basis for both the copy constructor  and
664              the assignment operator.
665
666              The  result of this method has to be semantically identical over
667              all implementations of the graph interface. This  is  what  will
668              enable  us  to copy graph data between different implementations
669              of the same interface.
670
671              The result is a list containing a multiple of three items,  plus
672              one!  In other words, '[llength $serial] % 3 == 1'. Valid values
673              include 1, 4, 7, ...
674
675              The last element of the list  is  a  dictionary  containing  the
676              attributes associated with the whole graph.  Regarding the other
677              elements; each triple consists of
678
679              [1]    The name of the node to be described,
680
681              [2]    A dictionary containing the  attributes  associated  with
682                     the node,
683
684              [3]    And a list describing all the arcs starting at that node.
685
686       The  elements  of  the arc list are lists containing three or four ele‐
687       ments each, i.e.
688
689              [1]    The name of the arc described by the element,
690
691              [2]    A reference to the destination node of the arc. This ref‐
692                     erence  is an integer number given the index of that node
693                     in the main serialization list. As  that  it  is  greater
694                     than  or equal to zero, less than the length of the seri‐
695                     alization, and a multiple of three.  Note:  For  internal
696                     consistency no arc name may be used twice, whether in the
697                     same node, or at some other node. This is a  global  con‐
698                     sistency requirement for the serialization.
699
700              [3]    And  a  dictionary  containing  the attributes associated
701                     with the arc.
702
703              [4]    The  weight  associated  with  the  arc.  This  value  is
704                     optional. Its non-presence means that the arc in question
705                     has no weight associated with it.
706
707                     Note: This information is new, compared to the serializa‐
708                     tion  of  graph 2.3 and earlier. By making it an optional
709                     element the new format is maximally compatible  with  the
710                     old.  This  means  that  any graph not using weights will
711                     generate a serialization which is still understood by the
712                     older  graph  package. A serialization will not be under‐
713                     stood any longer by the older packages if,  and  only  if
714                     the  graph  it  was generated from actually has arcs with
715                     weights.
716
717       For  all  attribute  dictionaries  they  keys  are  the  names  of  the
718       attributes, and the values are the values for each name.
719
720       Note: The order of the nodes in the serialization has no relevance, nor
721       has the order of the arcs per node.
722
723           # A possible serialization for the graph structure
724           #
725           #        d -----> %2
726           #       /         ^ \\
727           #      /         /   \\
728           #     /         b     \\
729           #    /         /       \\
730           #  %1 <- a - %0         e
731           #    ^         \\      /
732           #     \\        c     /
733           #      \\        \\  /
734           #       \\        v v
735           #        f ------ %3
736           # is
737           #
738           # %3 {} {{f 6 {}}} %0 {} {{a 6 {}} {b 9 {}} {c 0 {}}} %1 {} {{d 9 {}}} %2 {} {{e 0 {}}} {}
739           #
740           # This assumes that the graph has neither attribute data nor weighted arcs.
741
742
743
744       graphName set key ?value?
745              Set or get one of the keyed values associated with  a  graph.  A
746              graph may have any number of keyed values associated with it. If
747              value is not specified, this command returns the  current  value
748              assigned to the key; if value is specified, this command assigns
749              that value to the key.
750
751       graphName swap node1 node2
752              Swap the position of node1 and node2 in the graph.
753
754       graphName unset key
755              Remove a keyed value from the graph. The method will do  nothing
756              if the key does not exist.
757
758       graphName  walk node ?-order order? ?-type type? ?-dir direction? -com‐
759       mand cmd
760              Perform a breadth-first or depth-first walk of the graph  start‐
761              ing  at  the node node going in either the direction of outgoing
762              or opposite to the incoming arcs.
763
764              The type of walk, breadth-first or depth-first, is determined by
765              the  value  of  type; bfs indicates breadth-first, dfs indicates
766              depth-first.  Depth-first is the default.
767
768              The order of the walk, pre-order, post-order  or  both-order  is
769              determined  by the value of order; pre indicates pre-order, post
770              indicates post-order, both indicates  both-order.  Pre-order  is
771              the  default.  Pre-order  walking  means  that a node is visited
772              before any of its neighbors (as defined by  the  direction,  see
773              below).  Post-order walking means that a parent is visited after
774              any of its neighbors. Both-order walking means that  a  node  is
775              visited  before  and after any of its neighbors. The combination
776              of a breadth-first walk with post- or both-order is illegal.
777
778              The direction of the walk is determined by  the  value  of  dir;
779              backward  indicates the direction opposite to the incoming arcs,
780              forward indicates the direction of the outgoing arcs.
781
782              As the walk progresses, the command cmd  will  be  evaluated  at
783              each node, with the mode of the call (enter or leave) and values
784              graphName and the name of the current node appended. For a  pre-
785              order  walk,  all  nodes are entered, for a post-order all nodes
786              are left. In a both-order walk the first visit of a node  enters
787              it, the second visit leaves it.
788

CHANGES FOR 2.0

790       The following noteworthy changes have occurred:
791
792       [1]    The  API for accessing attributes and their values has been sim‐
793              plified.
794
795              All functionality regarding the  default  attribute  "data"  has
796              been removed. This default attribute does not exist anymore. All
797              accesses to attributes have to specify the name of the attribute
798              in  question.  This  backward  incompatible change allowed us to
799              simplify the signature of all methods handling attributes.
800
801              Especially the flag -key is not required anymore, even more, its
802              use  is now forbidden. Please read the documentation for the arc
803              and node methods  set,  get,  getall,  unset,  append,  lappend,
804              keyexists and keys for a description of the new API's.
805
806       [2]    The  methods  keys and getall now take an optional pattern argu‐
807              ment and will return only attribute data for keys matching  this
808              pattern.
809
810       [3]    Arcs and nodes can now be renamed. See the documentation for the
811              methods arc rename and node rename.
812
813       [4]    The structure has been extended with API's for the serialization
814              and deserialization of graph objects, and a number of operations
815              based on them (graph assignment, copy construction).
816
817              Please read the documentation for the methods serialize, deseri‐
818              alize,  =, and -->, and the documentation on the construction of
819              graph objects.
820
821              Beyond the copying of whole graph objects these new  API's  also
822              enable the transfer of graph objects over arbitrary channels and
823              for easy persistence.
824
825       [5]    A new method, attr, was added to both arc and node allowing  the
826              query  and retrieval of attribute data without regard to arc and
827              node relationships.
828
829       [6]    Both methods arcs and nodes have been extended with the  ability
830              to  select  arcs  and nodes based on an arbitrary filtering cri‐
831              terium.
832

BUGS, IDEAS, FEEDBACK

834       This document, and the package it describes, will  undoubtedly  contain
835       bugs  and other problems.  Please report such in the category struct ::
836       graph     of     the     Tcllib     SF     Trackers     [http://source
837       forge.net/tracker/?group_id=12883].   Please  also report any ideas for
838       enhancements you may have for either package and/or documentation.
839

KEYWORDS

841       adjacent, arc, cgraph, degree,  edge,  graph,  loop,  neighbour,  node,
842       serialization, subgraph, vertex
843
845       Copyright (c) 2002-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>
846
847
848
849
850struct                                2.3                     struct::graph(n)
Impressum