~ubuntu-branches/ubuntu/lucid/graphviz/lucid-security

« back to all changes in this revision

Viewing changes to tcldgr/tcldgr.n

  • Committer: Bazaar Package Importer
  • Author(s): Stephen M Moraco
  • Date: 2002-02-05 18:52:12 UTC
  • Revision ID: james.westby@ubuntu.com-20020205185212-8i04c70te00rc40y
Tags: upstream-1.7.16
ImportĀ upstreamĀ versionĀ 1.7.16

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
.lf 1 tcldgr.n
 
2
'\"
 
3
'\" Copyright (c) 1997, 1998, 1999 Lucent Technologies, Inc.
 
4
'\"
 
5
.lf 1 man.macros
 
6
'\" The definitions below are for supplemental macros used in Tcl/Tk
 
7
'\" manual entries.
 
8
'\"
 
9
'\" .AP type name in/out ?indent?
 
10
'\"     Start paragraph describing an argument to a library procedure.
 
11
'\"     type is type of argument (int, etc.), in/out is either "in", "out",
 
12
'\"     or "in/out" to describe whether procedure reads or modifies arg,
 
13
'\"     and indent is equivalent to second arg of .IP (shouldn't ever be
 
14
'\"     needed;  use .AS below instead)
 
15
'\"
 
16
'\" .AS ?type? ?name?
 
17
'\"     Give maximum sizes of arguments for setting tab stops.  Type and
 
18
'\"     name are examples of largest possible arguments that will be passed
 
19
'\"     to .AP later.  If args are omitted, default tab stops are used.
 
20
'\"
 
21
'\" .BS
 
22
'\"     Start box enclosure.  From here until next .BE, everything will be
 
23
'\"     enclosed in one large box.
 
24
'\"
 
25
'\" .BE
 
26
'\"     End of box enclosure.
 
27
'\"
 
28
'\" .CS
 
29
'\"     Begin code excerpt.
 
30
'\"
 
31
'\" .CE
 
32
'\"     End code excerpt.
 
33
'\"
 
34
'\" .VS ?br?
 
35
'\"     Begin vertical sidebar, for use in marking newly-changed parts
 
36
'\"     of man pages.  If an argument is present, then a line break is
 
37
'\"     forced before starting the sidebar.
 
38
'\"
 
39
'\" .VE
 
40
'\"     End of vertical sidebar.
 
41
'\"
 
42
'\" .DS
 
43
'\"     Begin an indented unfilled display.
 
44
'\"
 
45
'\" .DE
 
46
'\"     End of indented unfilled display.
 
47
'\"
 
48
'\" .SO
 
49
'\"     Start of list of standard options for a Tk widget.  The
 
50
'\"     options follow on successive lines, in four columns separated
 
51
'\"     by tabs.
 
52
'\"
 
53
'\" .SE
 
54
'\"     End of list of standard options for a Tk widget.
 
55
'\"
 
56
'\" .OP cmdName dbName dbClass
 
57
'\"     Start of description of a specific option.  cmdName gives the
 
58
'\"     option's name as specified in the class command, dbName gives
 
59
'\"     the option's name in the option database, and dbClass gives
 
60
'\"     the option's class in the option database.
 
61
'\"
 
62
'\" .UL arg1 arg2
 
63
'\"     Print arg1 underlined, then print arg2 normally.
 
64
'\"
 
65
'\" SCCS: @(#) man.macros 1.8 96/02/15 20:02:24
 
66
'\"
 
67
'\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
 
68
.if t .wh -1.3i ^B
 
69
.nr ^l \n(.l
 
70
.ad b
 
71
'\"     # Start an argument description
 
72
.de AP
 
73
.ie !"\\$4"" .TP \\$4
 
74
.el \{\
 
75
.   ie !"\\$2"" .TP \\n()Cu
 
76
.   el          .TP 15
 
77
.\}
 
78
.ie !"\\$3"" \{\
 
79
.ta \\n()Au \\n()Bu
 
80
\&\\$1  \\fI\\$2\\fP    (\\$3)
 
81
.\".b
 
82
.\}
 
83
.el \{\
 
84
.br
 
85
.ie !"\\$2"" \{\
 
86
\&\\$1  \\fI\\$2\\fP
 
87
.\}
 
88
.el \{\
 
89
\&\\fI\\$1\\fP
 
90
.\}
 
91
.\}
 
92
..
 
93
'\"     # define tabbing values for .AP
 
94
.de AS
 
95
.nr )A 10n
 
96
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
 
97
.nr )B \\n()Au+15n
 
98
.\"
 
99
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 
100
.nr )C \\n()Bu+\\w'(in/out)'u+2n
 
101
..
 
102
.AS Tcl_Interp Tcl_CreateInterp in/out
 
103
'\"     # BS - start boxed text
 
104
'\"     # ^y = starting y location
 
105
'\"     # ^b = 1
 
106
.de BS
 
107
.br
 
108
.mk ^y
 
109
.nr ^b 1u
 
110
.if n .nf
 
111
.if n .ti 0
 
112
.if n \l'\\n(.lu\(ul'
 
113
.if n .fi
 
114
..
 
115
'\"     # BE - end boxed text (draw box now)
 
116
.de BE
 
117
.nf
 
118
.ti 0
 
119
.mk ^t
 
120
.ie n \l'\\n(^lu\(ul'
 
121
.el \{\
 
122
.\"     Draw four-sided box normally, but don't draw top of
 
123
.\"     box if the box started on an earlier page.
 
124
.ie !\\n(^b-1 \{\
 
125
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 
126
.\}
 
127
.el \}\
 
128
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 
129
.\}
 
130
.\}
 
131
.fi
 
132
.br
 
133
.nr ^b 0
 
134
..
 
135
'\"     # VS - start vertical sidebar
 
136
'\"     # ^Y = starting y location
 
137
'\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 
138
.de VS
 
139
.if !"\\$1"" .br
 
140
.mk ^Y
 
141
.ie n 'mc \s12\(br\s0
 
142
.el .nr ^v 1u
 
143
..
 
144
'\"     # VE - end of vertical sidebar
 
145
.de VE
 
146
.ie n 'mc
 
147
.el \{\
 
148
.ev 2
 
149
.nf
 
150
.ti 0
 
151
.mk ^t
 
152
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 
153
.sp -1
 
154
.fi
 
155
.ev
 
156
.\}
 
157
.nr ^v 0
 
158
..
 
159
'\"     # Special macro to handle page bottom:  finish off current
 
160
'\"     # box/sidebar if in box/sidebar mode, then invoked standard
 
161
'\"     # page bottom macro.
 
162
.de ^B
 
163
.ev 2
 
164
'ti 0
 
165
'nf
 
166
.mk ^t
 
167
.if \\n(^b \{\
 
168
.\"     Draw three-sided box if this is the box's first page,
 
169
.\"     draw two sides but no top otherwise.
 
170
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 
171
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 
172
.\}
 
173
.if \\n(^v \{\
 
174
.nr ^x \\n(^tu+1v-\\n(^Yu
 
175
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 
176
.\}
 
177
.bp
 
178
'fi
 
179
.ev
 
180
.if \\n(^b \{\
 
181
.mk ^y
 
182
.nr ^b 2
 
183
.\}
 
184
.if \\n(^v \{\
 
185
.mk ^Y
 
186
.\}
 
187
..
 
188
'\"     # DS - begin display
 
189
.de DS
 
190
.RS
 
191
.nf
 
192
.sp
 
193
..
 
194
'\"     # DE - end display
 
195
.de DE
 
196
.fi
 
197
.RE
 
198
.sp
 
199
..
 
200
'\"     # SO - start of list of standard options
 
201
.de SO
 
202
.SH "STANDARD OPTIONS"
 
203
.LP
 
204
.nf
 
205
.ta 4c 8c 12c
 
206
.ft B
 
207
..
 
208
'\"     # SE - end of list of standard options
 
209
.de SE
 
210
.fi
 
211
.ft R
 
212
.LP
 
213
See the \\fBoptions\\fR manual entry for details on the standard options.
 
214
..
 
215
'\"     # OP - start of full description for a single option
 
216
.de OP
 
217
.LP
 
218
.nf
 
219
.ta 4c
 
220
Command-Line Name:      \\fB\\$1\\fR
 
221
Database Name:  \\fB\\$2\\fR
 
222
Database Class: \\fB\\$3\\fR
 
223
.fi
 
224
.IP
 
225
..
 
226
'\"     # CS - begin code excerpt
 
227
.de CS
 
228
.RS
 
229
.nf
 
230
.ta .25i .5i .75i 1i
 
231
..
 
232
'\"     # CE - end code excerpt
 
233
.de CE
 
234
.fi
 
235
.RE
 
236
..
 
237
.de UL
 
238
\\$1\l'|0\(ul'\\$2
 
239
..
 
240
.lf 5 tcldgr.n
 
241
.TH TCLDGR 1 "Tcl Extension"
 
242
.BS
 
243
'\" Note:  do not modify the .SH NAME line immediately below!
 
244
.SH NAME
 
245
Tcldgr \- dynamic graph manipulation in tcl
 
246
.SH SYNOPSIS
 
247
 
 
248
#!/bin/sh
 
249
.br
 
250
# next line is a comment in tcl \\
 
251
.br
 
252
exec tclsh "$0" ${1+"$@"}
 
253
.br
 
254
package require Tcldgr
 
255
.BE
 
256
 
 
257
.SH USAGE
 
258
 
 
259
Requires the dynamic loading facilities of tcl7.6 or later.
 
260
Does \fInot\fR require tk.
 
261
 
 
262
.SH INTRODUCTION
 
263
 
 
264
.B Tcldgr
 
265
is a member of the 
 
266
.B Tcldg
 
267
family of extensions, another being
 
268
.B Tcldgl
 
269
(layouts).
 
270
.B Tcldgr
 
271
provides an interface to the graph manipulation facilities of 
 
272
.B libgraph(3).
 
273
 
 
274
This extension is an evolution from its
 
275
.B tcldot
 
276
heritage.
 
277
The major differences are the "bindings" to graph for incremental graph
 
278
events, and the removal to the companion package 
 
279
.B Tcldgl
 
280
of all layout features.
 
281
 
 
282
All tcl commands used in this family of extensions use the prefix "dg".
 
283
 
 
284
.SH COMMAND SUMMARY
 
285
 
 
286
.B Tcldgr
 
287
extends the
 
288
.I Tcl
 
289
(Tool Command Language).
 
290
Tcl provides control flow (e.g., if, for, break),
 
291
expression evaluation and several other features such as recursion,
 
292
procedure definition, etc.
 
293
Commands used in this man page but not defined (e.g.,
 
294
.BR set ,
 
295
.BR if ,
 
296
.BR exec )
 
297
are Tcl commands (see
 
298
.B Tcl(n)
 
299
for more details).
 
300
 
 
301
.B Tcldgr
 
302
initially adds only five commands to the 
 
303
.B tcl
 
304
interpreter, namely:
 
305
.B dgnew,
 
306
.B dgread,
 
307
.B dgstring,
 
308
.B dg,
 
309
and
 
310
.B dgreset.
 
311
The command: \fBdgreset\fR is intended for use only in regression tests
 
312
and is not documented further in these man pages.
 
313
 
 
314
Many
 
315
.B Tcldgr
 
316
commands return a handle of a graph, node, or edge.
 
317
Handles take forms like: "dgG0" "dgN5" "dgE20".  The prefix of handles
 
318
is always "dg", the "G", "N", or "E", indicate the type of object 
 
319
(Graph, Node, Edge), and the number is a unique ID across all dg 
 
320
objects used in a single interpreter session.  
 
321
IDs are reused if objects are deleted.
 
322
 
 
323
There are two script styles supported by \fBTcldgr\fR,
 
324
the style is selected by the first command used to create a
 
325
graph in an interpreter.
 
326
 
 
327
The first style is selected if
 
328
\fBdgnew\fR, \fBdgread\fR, or \fBdgstring\fR are used.
 
329
In this style the handles of created objects are themselves registered as 
 
330
tcl commands to permit direct operations on the objects. In this case the
 
331
\fBdg\fR command is deleted from the interpreter to prevent mixing
 
332
styles in the script.
 
333
The additional commands are all of the form:
 
334
.nf
 
335
        <handle> <method> <parameters>
 
336
.fi
 
337
 
 
338
In the second style, the only tcl command used is \fBdg\fR and
 
339
handles are not registered as commands.  This style may be used if the
 
340
user is concerned about pollution of the tcl command namespace.
 
341
There isn't likely to be much difference in efficiency.
 
342
Once \fBdg\fR is used the first time the commands \fBdgnew\fR, 
 
343
\fBdgread\fR, and \fBdgstring\fR are deleted to prevent mixing of styles.
 
344
The dg commands are:
 
345
.nf
 
346
        dg new <same parameters as dgnew>
 
347
        dg read <same parameters as dgread>
 
348
        dg string <same parameters as dgstring>
 
349
        dg <handle> <method> <parameters>
 
350
.fi
 
351
 
 
352
The remainder of this man page uses the first style
 
353
and the \fBdg ...\fR style is not further discussed.
 
354
 
 
355
The commands and methods are described in detail below, but in summary:
 
356
.HP
 
357
Tcl commands are:
 
358
.br
 
359
dgnew, dgread, dgstring, dg, dgreset.
 
360
.HP
 
361
Graph methods are:
 
362
.br
 
363
addedge, addnode, addsubgraph, batch, bind, concatfile,
 
364
countedges, countnodes, findedge, graphof,
 
365
listattributes, listedgeattributes, listnodeattributes,
 
366
listedges, listnodes, listsubgraphs, nextedge, nextnode,
 
367
parentgraph, queryattributes,
 
368
queryedgeattributes, querynodeattributes, set,
 
369
setattributes, setedgeattributes, setnodeattributes,
 
370
showname, showtype, write.
 
371
.HP
 
372
Node methods are:
 
373
.br
 
374
addedge, countedges, countinedges, countoutedges, delete,
 
375
findedge, graphof, listattributes, listedges, listinedges,
 
376
listoutedges, nextedge, nextinedge, nextoutedge,
 
377
queryattributes, set, setattributes, showname.
 
378
.HP
 
379
Edge methods are: 
 
380
.br
 
381
delete, graphof, headof, listattributes, listnodes, listheadnodes,
 
382
listtailnodes, queryattributes, set, setattributes, showname, tailof.
 
383
 
 
384
.P
 
385
Also, if a graph, node or edge has an attributeName that begins
 
386
with '_' then the attributeName is accepted as a method somewhat like a
 
387
method in an OO language.
 
388
When the _attributeName is invoked then the attributeValue is interpreted
 
389
as a script after
 
390
first substituting and %g, %n, %e, or %a in the script with 
 
391
.I graphHandle, nodeHandle, edgeHandle,
 
392
and
 
393
.I arglist
 
394
from the command.   For example:
 
395
.nf
 
396
 
 
397
         set g [dgnew graph]
 
398
         set n [$g addnode]
 
399
         $n set _mymethod {puts "msg from %n: %a"}
 
400
         $n _mymethod hello world
 
401
 
 
402
.fi
 
403
when evaluated will print out:
 
404
.nf
 
405
 
 
406
         msg from dgN1: hello world
 
407
.fi
 
408
 
 
409
Common methods can be provided to all nodes, or edges, in a graph
 
410
by use of:
 
411
.nf
 
412
 
 
413
        $g setnodeattribute _method {script...}
 
414
        $g setedgeattribute _method {script...}
 
415
.fi
 
416
 
 
417
.SH GRAPH COMMANDS
 
418
 
 
419
.TP
 
420
\fBdgnew\fR \fIgraphType ?graphName? ?attributeName attributeValue? ?...?\fR
 
421
 
 
422
creates a new empty graph and returns its 
 
423
.I graphHandle.
 
424
 
 
425
.I graphType
 
426
can be any of:
 
427
"graph," "digraph," "strictgraph," or "strictdigraph."
 
428
(In digraphs edges have a direction from tail to head. "Strict" graphs
 
429
or digraphs collapse multiple edges between the same pair of
 
430
nodes into a single edge, and disallow self-edges.)
 
431
 
 
432
Following the mandatory 
 
433
.I graphType
 
434
parameter the 
 
435
.B dgnew
 
436
command will accept an optional name for the graph and an
 
437
arbitrary number of attribute name/value pairs.
 
438
In Tcldgr (unlike tcldot) there are no predifined attributes,
 
439
so the script programmer can freely use attributes for the
 
440
application.
 
441
e.g.
 
442
.nf
 
443
 
 
444
        set g [dgnew digraph G author "John Ellson"]
 
445
.fi
 
446
.TP
 
447
\fBdgread\fR \fIfileHandle\fR
 
448
 
 
449
reads in a dot-language description of a graph from a previously opened
 
450
file identified by the 
 
451
.I fileHandle.
 
452
The command returns the
 
453
.I graphHandle
 
454
of the newly read graph.  e.g.
 
455
.nf
 
456
        
 
457
        set f [open test.dot r]
 
458
        set g [dgread $f]
 
459
.fi
 
460
.TP
 
461
\fBdgstring\fR \fIstring\fR
 
462
 
 
463
accepts a dot-language string description of a graph.
 
464
The command returns the
 
465
.I graphHandle
 
466
of the newly read graph.  e.g.
 
467
.nf
 
468
        
 
469
        set s "digraph G {a->b}"
 
470
        set g [dgstring $s]
 
471
.fi
 
472
.TP
 
473
\fIgraphHandle\fR \fBaddnode\fR \fI?nodeName? ?attributeName attributeValue? ?...?\fR
 
474
 
 
475
creates a new node in the graph whose handle is
 
476
.I graphHandle
 
477
and returns its
 
478
.I nodeHandle.
 
479
The handle of a node is a string like: "dgN0" where the integer value is
 
480
different for each node.
 
481
An optional name may be provided for the node, followed by
 
482
an arbitrary number of attribute name/value pairs.
 
483
e.g.
 
484
.nf
 
485
        
 
486
        set n [$g addnode "N" label "Top\\nNode" ]
 
487
 
 
488
.fi
 
489
Execution of \fBaddnode\fR will have the side effect of also executing
 
490
any scripts that have been attached to the \fIinsert_node\fR event by the
 
491
bind method on the graph.
 
492
 
 
493
A possible cause of confusion in 
 
494
.B Tcldgr
 
495
is the distinction between handles, names, labels, and variables.
 
496
The distinction is primarily in who owns them.
 
497
Handles are owned by Tcldgr and are guaranteed to be unique within
 
498
one interpreter session.  Typically handles are assigned to variables,
 
499
like "n" above, for manipulation within a tcl script.
 
500
Variables are owned by the programmer.
 
501
Names are owned by the application that is using the
 
502
graph, typically names are important when reading in a graph from
 
503
an external program or file.  Labels are the text that is displayed with
 
504
the node
 
505
(or edge) when the graph is displayed, labels are meaningful to the
 
506
reader of the graph.  Only the handles and variables are essential to 
 
507
.B Tcldgr's
 
508
ability to manipulate abstract graphs.  If a name is not specified then
 
509
it defaults to a "%<num>" form where <num> is the numeric part of the handle.
 
510
Unlike 
 
511
.B tcldot,
 
512
labels are no longer specifically provided for, but it is probably a
 
513
good idea to continue to use the attributName "label" so that dot
 
514
files can be interpreted by the older tools..
 
515
 
 
516
.PD 0
 
517
.TP
 
518
\fIgraphHandle\fR \fBaddedge\fR \fItailNode headNode ?edgeName? ?attributeName attributeValue? ?...?\fR
 
519
.TP
 
520
\fInodeHandle\fR \fBaddedge\fR \fIheadNode ?edgeName? ?attributeName attributeValue? ?...?\fR
 
521
.PD
 
522
 
 
523
creates a new edge and returns its
 
524
.I edgeHandle.
 
525
The 
 
526
.I tailNode 
 
527
and
 
528
.I headNode
 
529
can be specified either by their
 
530
.I nodeHandle
 
531
or by their 
 
532
.I nodeName
 
533
e.g.
 
534
.nf
 
535
 
 
536
        set n [$g addnode]
 
537
        set m [$g addnode M]
 
538
        set p [$g addnode]
 
539
        $g addedge $n M myedge label "NM"
 
540
        $p addedge M label "PM"
 
541
        $p addedge $n
 
542
 
 
543
.fi
 
544
The \fItailNode\fR and \fIheadNode\fR parameters are recognized as handles
 
545
in preference to names, so it is best
 
546
to avoid names like "dgN6" for nodes.  If there is potential
 
547
for conflict then use
 
548
.B findnode
 
549
which gives preference to names over handles instead. 
 
550
e.g.
 
551
.nf
 
552
 
 
553
        $g addnode "dgN6"
 
554
        $g addnode "dgN99"
 
555
        $g addedge [$g findnode "dgN6"] [$g findnode "dgN99"]
 
556
 
 
557
.fi
 
558
An optional name may be provided for the edge, followed by
 
559
an arbitrary number of attribute name/value pairs.
 
560
 
 
561
Execution of \fBaddedge\fR will have the side effect of also executing
 
562
any scripts that have been attached to the \fIinsert_edge\fR event by the
 
563
bind method on the graph.
 
564
 
 
565
.TP
 
566
\fIgraphHandle\fR \fBaddsubgraph\fR \fI?graphName? ?attributeName attributeValue? ?...?\fR
 
567
 
 
568
creates a new subgraph in the graph and returns its
 
569
.I graphHandle.
 
570
If the
 
571
.I graphName
 
572
is omitted then the name of the subgraph defaults to it's 
 
573
.I graphHandle.
 
574
There can be an arbitrary number of attribute name/value pairs
 
575
for the subgraph.
 
576
e.g.
 
577
.nf
 
578
        
 
579
        set sg [$g addsubgraph]
 
580
.fi
 
581
 
 
582
Execution of \fBaddsubgraph\fR will have the side effect of also executing
 
583
any scripts that have been attached to the \fIinsert_graph\fR event by the
 
584
bind method on the graph.
 
585
 
 
586
.TP
 
587
\fIgraphHandle\fR \fBbatch\fR \fIboolean\fI
 
588
 
 
589
When set, batches up all events in a buffer until cleared.
 
590
Initially batch is cleared so that events immediately
 
591
invoke any scripts that have been attached with "bind".
 
592
 
 
593
Some operations on the graph may result in multiple events, and so it is
 
594
useful to be able to bracket the set of events generated by a single
 
595
input action.  To support this,  all events (even singletons)
 
596
reported by a graph are surrounded by "batch 1" ... "batch 0" events.
 
597
These batch events can themselves be bound (see next section).
 
598
If the batch command is used then the interval of the batched
 
599
is enlarged to the interval of the commanded batching,
 
600
thus allowing the user to define larger atomic transactions.
 
601
 
 
602
.TP
 
603
\fIgraphHandle\fR \fBbind\fR \fIgraphEvent ?+??script?\fI
 
604
 
 
605
attaches a script to be executed whenever a specified event occurs.
 
606
.I graphEvent
 
607
can be any one of:
 
608
 
 
609
.DS
 
610
.ta 3c
 
611
\fBbatch\fR     %g %a
 
612
\fBinsert_graph\fR      %g
 
613
\fBinsert_node\fR       %g %n
 
614
\fBinsert_edge\fR       %g %t %e %h
 
615
\fBmodify_graph\fR      %g %n %e %A %a
 
616
\fBmodify_node\fR       %g %n %A %a
 
617
\fBmodify_edge\fR       %g %e %A %a
 
618
\fBdelete_graph\fR      %g
 
619
\fBdelete_node\fR       %g %n
 
620
\fBdelete_edge\fR       %g %e
 
621
.DE
 
622
 
 
623
Where the substitutions are:
 
624
 
 
625
.DS
 
626
.ta 1c
 
627
%g      the graph handle
 
628
%n      the node handle (or tail node handle)
 
629
        or "node" when \fBmodify_graph\fR reports node attribute creation
 
630
%t      tail node handle (%t is an alias for %n)
 
631
%e      the edge handle 
 
632
        or "edge" when \fBmodify_graph\fR reports edge attribute creation
 
633
%h      head node handle (%h is an alias for %A)
 
634
%A      the attribute name (or head node handle)
 
635
%a      the attribute value ("0" or "1" for batch bindings)
 
636
.DE
 
637
 
 
638
If the \fIscript\fR parameter starts with a "+" then the binding is
 
639
appended to any existing binding on the event, otherwise the binding
 
640
replaces any existing binding.  Bindings can be deleted by use of a
 
641
zero length script string.
 
642
 
 
643
.B Debugging hint:
 
644
To set up bindings to all possible events and parameters from a graph
 
645
you can use:
 
646
.nf
 
647
 
 
648
        foreach b [$g bind] {$g bind $b "+puts \\"%g $b %n %e %A %a\\""}
 
649
.fi
 
650
 
 
651
.PD 0
 
652
.TP
 
653
\fIgraphHandle\fR \fBcountnodes\fR
 
654
.TP
 
655
\fIgraphHandle\fR \fBcountedges\fR
 
656
.PD
 
657
 
 
658
Returns the number of nodes, or edges, in the graph.
 
659
 
 
660
.PD 0
 
661
.TP
 
662
\fInodeHandle\fR \fBcountedges\fR
 
663
.TP
 
664
\fInodeHandle\fR \fBcountinedges\fR
 
665
.TP
 
666
\fInodeHandle\fR \fBcountoutedges\fR
 
667
.PD
 
668
 
 
669
Returns the number of edges at a node.
 
670
 
 
671
.PD 0
 
672
.TP
 
673
\fIgraphHandle\fR \fBconcatfile\fR \fIfileHandle\fR
 
674
.TP
 
675
\fIgraphHandle\fR \fBconcatstring\fR \fIdot_language_string\fR
 
676
.PD
 
677
 
 
678
Reads in a \fIdot\fR file from an open \fIfileHandle\fR,
 
679
or from a string, and concatenates the graph to any existing graph
 
680
in \fIgraphHandle\fR.
 
681
 
 
682
(This mechanism was introduced so that event bindings could be 
 
683
established on an empty graph before the file was read in, so that the
 
684
callbacks occur for the contents of the file.  It is not clear
 
685
that concatenating a graph to a non-empty graph produces intuitively
 
686
predictable results.)
 
687
 
 
688
.PD 0
 
689
.TP 
 
690
\fIgraphHandle\fR \fBdelete\fR
 
691
.TP
 
692
\fInodeHandle\fR \fBdelete\fR
 
693
.TP
 
694
\fIedgeHandle\fR \fBdelete\fR
 
695
.PD
 
696
 
 
697
Delete all data structures associated with the graph, node, edge
 
698
from the internal storage of the interpreter.  Deletion of a node also
 
699
results in the deletion of all subtending edges on that node.
 
700
Deletion of a graph also results in the deletion of all nodes edges and
 
701
subgraphs within that graph.
 
702
 
 
703
Execution of graph, node or edge \fBdelete\fR will have the side effect
 
704
of also executing any scripts that have been attached to the
 
705
\fIdelete_graph\fR, \fIdelete_node\fR, \fIdelete_edge\fR events by the
 
706
bind method on the graph.
 
707
 
 
708
.PD 0
 
709
.TP
 
710
\fIgraphHandle\fR \fBfindnode\fR \fInodeName\fR
 
711
.TP
 
712
\fIgraphHandle\fR \fBfindedge\fR \fItailnodeName headNodeName\fR
 
713
.TP
 
714
\fInodeHandle\fR \fBfindedge\fR \fInodeName\fR
 
715
.PD
 
716
 
 
717
Each return the handle of the item if found, or an error if none are found.  
 
718
For non-strict graphs when there are multiple edges between two nodes
 
719
.B findedge
 
720
will return an arbitrary edge from the set.
 
721
\fIName\fR parameters to the \fBfind\fR method can be either names
 
722
or handles, but priority is given to a name interpretation.
 
723
 
 
724
.PD 0
 
725
.TP
 
726
\fIgraphHandle\fR \fBgraphof\fR
 
727
.TP
 
728
\fInodeHandle\fR \fBgraphof\fR
 
729
.TP
 
730
\fIedgeHandle\fR \fBgraphof\fR
 
731
.PD
 
732
 
 
733
Returns the handle of the root graph which contains the graph,
 
734
subgraph, node, or edge.
 
735
 
 
736
.TP
 
737
\fIedgeHandle\fR \fBheadof\fR
 
738
 
 
739
(Synonym for \fBlistheadnodes\fR.)
 
740
 
 
741
.PD 0
 
742
.TP
 
743
\fIgraphHandle\fR \fBlistattributes\fR ?attributeNamePattern?
 
744
.TP
 
745
\fInodeHandle\fR \fBlistattributes\fR ?attributeNamePattern?
 
746
.TP
 
747
\fIedgeHandle\fR \fBlistattributes\fR ?attributeNamePattern?
 
748
.PD
 
749
 
 
750
Return a list of attribute names (attribute values are provided by
 
751
\fBqueryattribute\fR).  If an attributeNamePattern is specified then 
 
752
only those attributeNames that match the pattern are returned.
 
753
The pattern can contain "*?[]" as in Tcl's string match command.
 
754
 
 
755
.PD 0
 
756
.TP
 
757
\fIgraphHandle\fR \fBlistnodes\fR ?attributeName attributeValuePattern? ?...?
 
758
.TP
 
759
\fIgraphHandle\fR \fBlistedges\fR ?attributeName attributeValuePattern? ?...?
 
760
.TP
 
761
\fIgraphHandle\fR \fBlistsubgraphs\fR ?attributeName attributeValuePattern? ?...?
 
762
.TP
 
763
\fInodeHandle\fR \fBlistedges\fR ?attributeName attributeValuePattern? ?...?
 
764
.TP
 
765
\fInodeHandle\fR \fBlistinedges\fR ?attributeName attributeValuePattern? ?...?
 
766
.TP
 
767
\fInodeHandle\fR \fBlistoutedges\fR ?attributeName attributeValuePattern? ?...?
 
768
.TP
 
769
\fIedgeHandle\fR \fBlistnodes\fR ?attributeName attributeValuePattern? ?...?
 
770
.TP
 
771
\fIedgeHandle\fR \fBlistheadnodes\fR ?attributeName attributeValuePattern? ?...?
 
772
.TP
 
773
\fIedgeHandle\fR \fBlisttailnodes\fR ?attributeName attributeValuePattern? ?...?
 
774
.PD
 
775
 
 
776
Each return a list of handles of nodes, edges, or subgraphs, as appropriate.
 
777
If an attributeName and attributeValuePattern pairs are specified then
 
778
only those objects whose attributeValue match all of them are returned.
 
779
The pattern matching supports "*?[]" as in Tcl's string match command.
 
780
 
 
781
.PD 0
 
782
.TP
 
783
\fIgraphHandle\fR \fBnextedge\fR \fI?edgeHandle?\fR ?attributeName attributeValuePattern? ?...?
 
784
.TP
 
785
\fIgraphHandle\fR \fBnextnode\fR \fI?nodeHandle?\fR ?attributeName attributeValuePattern? ?...?
 
786
.TP
 
787
\fInodeHandle\fR \fBnextedge\fR \fI?edgeHandle?\fR ?attributeName attributeValuePattern? ?...?
 
788
.TP
 
789
\fInodeHandle\fR \fBnextinedge\fR \fI?edgeHandle?\fR ?attributeName attributeValuePattern? ?...?
 
790
.TP
 
791
\fInodeHandle\fR \fBnextoutedge\fR \fI?edgeHandle?\fR ?attributeName attributeValuePattern? ?...?
 
792
.PD
 
793
 
 
794
Provide an iteration through nodes or edges.  Returns the handle of the "next" node or edge that
 
795
follows the one identified in first parameter that matches the
 
796
attribute/value patterns.  If the first parameter
 
797
is omitted then it returns the first node or edge that matches the
 
798
attribute/value patterns.
 
799
The pattern matching supports "*?[]" as in Tcl's string match command.
 
800
 
 
801
.TP
 
802
\fIgraphHandle\fR \fBparentgraph\fR
 
803
 
 
804
If the graph is a subgraph the this method returns the handle
 
805
of its parent graph.  If the graph is the root graph then this method
 
806
returns a null string.  (See also: \fBgraphof\fR)
 
807
 
 
808
.PD 0
 
809
.TP
 
810
\fIgraphHandle\fR \fBqueryattributes\fR \fIattributeName ?...?\fR
 
811
.TP
 
812
\fInodeHandle\fR \fBqueryattributes\fR \fIattributeName ?...?\fR
 
813
.TP
 
814
\fIedgeHandle\fR \fBqueryattributes\fR \fIattributeName ?...?\fR
 
815
.PD
 
816
 
 
817
Return a list of attribute values, one value for each of the
 
818
attribute names provided with the method.  (See also the \fBset\fR
 
819
method which can be used to query a single attribute without
 
820
returning the value in a list.)
 
821
 
 
822
.PD 0
 
823
.TP
 
824
\fIgraphHandle\fR \fBshowname\fR
 
825
.TP
 
826
\fInodeHandle\fR \fBshowname\fR
 
827
.TP
 
828
\fIedgeHandle\fR \fBshowname\fR
 
829
.PD
 
830
 
 
831
Each return the name of the graph, node, or edge.
 
832
Edge names are of the form:
 
833
"a->b" where "a" and "b" are the names of the nodes and the connector
 
834
"->" indicates the tail-to-head direction of the edge. In undirected
 
835
graphs the connector "--" is used.
 
836
 
 
837
.PD 0
 
838
.TP
 
839
\fIgraphHandle\fR \fBset\fR \fIattributeName ?attributeValue?\fR
 
840
.TP
 
841
\fInodeHandle\fR \fBset\fR \fIattributeName ?attributeValue?\fR
 
842
.TP
 
843
\fIedgeHandle\fR \fBset\fR \fIattributeName ?attributeValue?\fR
 
844
.PD
 
845
 
 
846
Set, or query, (in the style of Tcl's set) one attribute name/value
 
847
pair for a specific graph, node, or edge instance.
 
848
 
 
849
Attributes whose 
 
850
.I attributeName
 
851
starts with the character '_' can be used to extend the method set of
 
852
graphs, nodes or edges by evaluating the 
 
853
.fIattributeValue
 
854
as a script after first substituting %g %n %e %a with
 
855
graphHandle, nodeHandle, edgeHandle and arglist.
 
856
 
 
857
Execution of \fBset\fR with a new value, i.e. a string value different from the
 
858
current value, will have the side effect
 
859
of also executing any scripts that have been attached to the
 
860
\fImodify_graph\fR, \fImodify_node\fR, or \fImodify_edge\fR events by the
 
861
bind method on the graph.  Note that this is different from
 
862
\fBsetattributes\fR which will execute scripts when a new value is
 
863
written regardless of whether its string value has changed.
 
864
 
 
865
.PD 0
 
866
.TP
 
867
\fIgraphHandle\fR \fBsetnodeattributes\fR \fIattributeName attributeValue ?...?\fR
 
868
.TP
 
869
\fIgraphHandle\fR \fBsetedgeattributes\fR \fIattributeName attributeValue ?...?\fR
 
870
.PD
 
871
 
 
872
Set one or more default attribute name/values that are to apply to
 
873
all subsequent nodes, or edges unless overridden.
 
874
 
 
875
Attributes whose 
 
876
.I attributeName
 
877
starts with the charater '_' can be used to extend the method set of
 
878
nodes or edges by evaluating the 
 
879
.fIattributeValue
 
880
as a script after first substituting %g %n %e %a with
 
881
graphHandle, nodeHandle, edgeHandle and arglist.
 
882
 
 
883
Execution of \fBsetnodeattributes\fR, or \fBsetedgeattributes\fR,
 
884
will have the side effect
 
885
of also executing any scripts that have been attached to the
 
886
\fImodify_node\fR, or \fImodify_edge\fR events by the
 
887
bind method on the graph.
 
888
 
 
889
.PD 0
 
890
.TP
 
891
\fIgraphHandle\fR \fBsetattributes\fR \fIattributeName attributeValue ?...?\fR
 
892
.TP
 
893
\fInodeHandle\fR \fBsetattributes\fR \fIattributeName attributeValue ?...?\fR
 
894
.TP
 
895
\fIedgeHandle\fR \fBsetattributes\fR \fIattributeName attributeValue ?...?\fR
 
896
.PD
 
897
 
 
898
Set one or more attribute name/value pairs for a specific graph, node,
 
899
or edge instance.
 
900
 
 
901
Attributes whose 
 
902
.I attributeName
 
903
starts with the charater '_' can be used to extend the method set of
 
904
graphs, nodes or edges by evaluating the 
 
905
.fIattributeValue
 
906
as a script after first substituting %g %n %e %a with
 
907
graphHandle, nodeHandle, edgeHandle and arglist.
 
908
 
 
909
Execution of \fBsetattributes\fR,
 
910
will have the side effect
 
911
of also executing any scripts that have been attached to the
 
912
\fImodify_graph\fR, \fImodify_node\fR, or \fImodify_edge\fR events by the
 
913
bind method on the graph.
 
914
 
 
915
(The only real advantage of \fBsetattributes\fR over \fBset\fR is
 
916
that it allows multiple attributes to be set in a single atomic
 
917
action. The other difference is that the bindings will be executed even
 
918
if the string value of the attribute is the same as before.)
 
919
 
 
920
.TP
 
921
\fIedgeHandle\fR \fBtailof\fR
 
922
 
 
923
(Synonym for \fBlisttailnodes\fR.)
 
924
 
 
925
.TP
 
926
\fIgraphHandle\fR \fBwrite\fR \fI?fileHandle?\fR
 
927
 
 
928
Write a graph in the dot_language to the open file represented by
 
929
.I fileHandle
 
930
or, if
 
931
.I fileHandle
 
932
is omitted, then return the dot-language result as a string.
 
933
 
 
934
 
 
935
.SH BUGS
 
936
 
 
937
This man page is impossible to comprehend in a single reading.
 
938
 
 
939
It would be useful to be able to delete individual parts of
 
940
a binding that was built from "+" appended parts.
 
941
 
 
942
It probably should be modified to use Tcl_Obj in tcl8.0 and later.
 
943
 
 
944
.SH AUTHOR
 
945
 
 
946
John Ellson, Lucent Technologies, Holmdel, NJ. (ellson@lucent.com)
 
947
 
 
948
.SH ACKNOWLEDGEMENTS
 
949
 
 
950
John Ousterhout, of course, for 
 
951
.B tcl
 
952
and
 
953
.B tk.
 
954
Steven North and Eleftherios Koutsofios for
 
955
.B dot, libgraph
 
956
and
 
957
.B libincr.
 
958
Karl Lehenbauer and Mark Diekhans of NeoSoft
 
959
for the dghandles.c code which was derived from tclXhandles.c.
 
960
 
 
961
.SH KEYWORDS
 
962
 
 
963
Tcldgr, graph, tcl, tk, dot, tcldot, graphviz.