Mercurial > hg > camir-aes2014

annotate toolboxes/graph_visualisation/share/man/man1/gvpr.1 @ 0:e9a9cd732c1e tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
first hg version after svn
author wolffd
date Tue, 10 Feb 2015 15:05:51 +0000
parents
children
rev   line source
wolffd@0 1 .de TQ
wolffd@0 2 . br
wolffd@0 3 . ns
wolffd@0 4 . TP \\$1
wolffd@0 5 ..
wolffd@0 6 .TH GVPR 1 "24 April 2008"
wolffd@0 7 .SH NAME
wolffd@0 8 gvpr \- graph pattern scanning and processing language
wolffd@0 9 .br
wolffd@0 10 ( previously known as
wolffd@0 11 .B gpr
wolffd@0 12 )
wolffd@0 13 .SH SYNOPSIS
wolffd@0 14 .B gvpr
wolffd@0 15 [\fB\-icqV?\fP]
wolffd@0 16 [
wolffd@0 17 .BI \-o
wolffd@0 18 .I outfile
wolffd@0 19 ]
wolffd@0 20 [
wolffd@0 21 .BI \-a
wolffd@0 22 .I args
wolffd@0 23 ]
wolffd@0 24 [
wolffd@0 25 .I 'prog'
wolffd@0 26 |
wolffd@0 27 .BI \-f
wolffd@0 28 .I progfile
wolffd@0 29 ]
wolffd@0 30 [
wolffd@0 31 .I files
wolffd@0 32 ]
wolffd@0 33 .SH DESCRIPTION
wolffd@0 34 .B gvpr
wolffd@0 35 is a graph stream editor inspired by \fBawk\fP.
wolffd@0 36 It copies input graphs to its
wolffd@0 37 output, possibly transforming their structure and attributes,
wolffd@0 38 creating new graphs, or printing arbitrary information.
wolffd@0 39 The graph model is that provided by
wolffd@0 40 .IR libcgraph (3).
wolffd@0 41 In particular, \fBgvpr\fP reads and writes graphs using the
wolffd@0 42 dot language.
wolffd@0 43 .PP
wolffd@0 44 Basically,
wolffd@0 45 .B gvpr
wolffd@0 46 traverses each input graph, denoted by \fB$G\fP, visiting each node and edge,
wolffd@0 47 matching it with the predicate\(hyaction rules supplied in the input program.
wolffd@0 48 The rules are evaluated in order.
wolffd@0 49 For each predicate evaluating to true, the corresponding
wolffd@0 50 action is performed.
wolffd@0 51 During the traversal, the current node or edge being visited
wolffd@0 52 is denoted by \fB$\fP.
wolffd@0 53 .PP
wolffd@0 54 For each input graph, there is a target subgraph, denoted by
wolffd@0 55 \fB$T\fP, initially empty and used to accumulate
wolffd@0 56 chosen entities, and an output graph, \fB$O\fP, used for final processing
wolffd@0 57 and then written to output.
wolffd@0 58 By default, the output graph is the target graph.
wolffd@0 59 The output graph can be set in the program or, in a limited sense,
wolffd@0 60 on the command line.
wolffd@0 61 .SH OPTIONS
wolffd@0 62 The following options are supported:
wolffd@0 63 .TP
wolffd@0 64 .BI \-a " args"
wolffd@0 65 The string \fIargs\fP is split into whitespace\(hyseparated tokens,
wolffd@0 66 with the individual tokens
wolffd@0 67 available as strings in the \fBgvpr\fP program
wolffd@0 68 as \fBARGV[\fI0\fP],...,ARGV[ARGC\-1]\fR.
wolffd@0 69 Whitespace characters within single or double quoted substrings, or
wolffd@0 70 preceded by a backslash, are ignored as separators.
wolffd@0 71 In general, a backslash character turns off any special meaning of the
wolffd@0 72 following character.
wolffd@0 73 Note that the tokens derived from multiple \fB\-a\fP flags are concatenated.
wolffd@0 74 .TP
wolffd@0 75 .B \-c
wolffd@0 76 Use the source graph as the output graph.
wolffd@0 77 .TP
wolffd@0 78 .B \-i
wolffd@0 79 Derive the node\(hyinduced subgraph extension of the output graph in the context
wolffd@0 80 of its root graph.
wolffd@0 81 .TP
wolffd@0 82 .BI \-o " outfile"
wolffd@0 83 Causes the output stream to be written to the specified file; by default,
wolffd@0 84 output is written to \fBstdout\fP.
wolffd@0 85 .TP
wolffd@0 86 .BI \-f " progfile"
wolffd@0 87 Use the contents of the specified file as the program to execute
wolffd@0 88 on the input. If \fIprogfile\fP contains a slash character, the name is taken
wolffd@0 89 as the pathname of the file. Otherwise, \fBgvpr\fP will use the
wolffd@0 90 directories specified in the environment variable \fBGPRPATH\fP to look
wolffd@0 91 for the file. If
wolffd@0 92 .B \-f
wolffd@0 93 is not given,
wolffd@0 94 .B gvpr
wolffd@0 95 will use the first non\(hyoption argument as the program.
wolffd@0 96 .TP
wolffd@0 97 .B \-q
wolffd@0 98 Turns off warning messages.
wolffd@0 99 .TP
wolffd@0 100 .B \-V
wolffd@0 101 Causes the program to print version information and exit.
wolffd@0 102 .TP
wolffd@0 103 .B \-?
wolffd@0 104 Causes the program to print usage information and exit.
wolffd@0 105 .SH OPERANDS
wolffd@0 106 The following operand is supported:
wolffd@0 107 .TP 8
wolffd@0 108 .I files
wolffd@0 109 Names of files containing 1 or more graphs in the dot language.
wolffd@0 110 If no
wolffd@0 111 .B \-f
wolffd@0 112 option is given, the first name is removed from the list and used
wolffd@0 113 as the input program. If the list of files is empty, \fBstdin\fP will be used.
wolffd@0 114 .SH PROGRAMS
wolffd@0 115 A
wolffd@0 116 .B gvpr
wolffd@0 117 program consists of a list of predicate\(hyaction clauses, having one
wolffd@0 118 of the forms:
wolffd@0 119 .IP
wolffd@0 120 .BI "BEGIN { " action " }"
wolffd@0 121 .IP
wolffd@0 122 .BI "BEG_G { " action " }"
wolffd@0 123 .IP
wolffd@0 124 .BI "N [ " predicate " ] { " action " }
wolffd@0 125 .IP
wolffd@0 126 .BI "E [ " predicate " ] { " action " }
wolffd@0 127 .IP
wolffd@0 128 .BI "END_G { " action " }"
wolffd@0 129 .IP
wolffd@0 130 .BI "END { " action " }"
wolffd@0 131 .PP
wolffd@0 132 A program can contain at most one of each of the \fBBEGIN\fP, \fBBEG_G\fP,
wolffd@0 133 \fBEND_G\fP and \fBEND\fP clauses.
wolffd@0 134 There can be any number of \fBN\fP and \fBE\fP statements,
wolffd@0 135 the first applied to nodes, the second to edges.
wolffd@0 136 The top\(hylevel semantics of a \fBgvpr\fP program are:
wolffd@0 137 .PP
wolffd@0 138 .ta \w'\f(CWdelete array[expression]'u
wolffd@0 139 .RS
wolffd@0 140 .nf
wolffd@0 141 Evaluate the \fBBEGIN\fP clause, if any.
wolffd@0 142 For each input graph \fIG\fP {
wolffd@0 143 Set \fIG\fP as the current graph and current object.
wolffd@0 144 Evaluate the \fBBEG_G\fP clause, if any.
wolffd@0 145 For each node and edge in \fIG\fP {
wolffd@0 146 Set the node or edge as the current object.
wolffd@0 147 Evaluate the \fBN\fP or \fBE\fP clauses, as appropriate.
wolffd@0 148 }
wolffd@0 149 Set \fIG\fP as the current object.
wolffd@0 150 Evaluate the \fBEND_G\fP clause, if any.
wolffd@0 151 }
wolffd@0 152 Evaluate the \fBEND\fP clause, if any.
wolffd@0 153 .fi
wolffd@0 154 .RE
wolffd@0 155 .DT
wolffd@0 156 .PP
wolffd@0 157 The actions of the \fBBEGIN\fP, \fBBEG_G\fP, \fBEND_G\fP and \fBEND\fP clauses
wolffd@0 158 are performed when the clauses are evaluated.
wolffd@0 159 For \fBN\fP or \fBE\fP clauses,
wolffd@0 160 either the predicate or action may be omitted.
wolffd@0 161 If there is no predicate with an action, the action is
wolffd@0 162 performed on every node or edge, as appropriate.
wolffd@0 163 If there is no action and the predicate evaluates to true,
wolffd@0 164 the associated node or edge is added to the target graph.
wolffd@0 165 .PP
wolffd@0 166 Predicates and actions are sequences of statements in the C dialect
wolffd@0 167 supported by the
wolffd@0 168 .IR libexpr (3)
wolffd@0 169 library.
wolffd@0 170 The only difference between predicates and actions is that the former
wolffd@0 171 must have a type that may interpreted as either true or false.
wolffd@0 172 Here the usual C convention is followed, in which a non\(hyzero value is
wolffd@0 173 considered true. This would include non\(hyempty strings and non\(hyempty
wolffd@0 174 references to nodes, edges, etc. However, if a string can be
wolffd@0 175 converted to an integer, this value is used.
wolffd@0 176 .PP
wolffd@0 177 In addition to the usual C base types
wolffd@0 178 (\fBvoid\fP, \fBint\fP, \fBchar\fP, \fBfloat\fP, \fBlong\fP,
wolffd@0 179 \fBunsigned\fP and \fBdouble\fP),
wolffd@0 180 \fBgvpr\fP \fRprovides \fBstring\fP as a synonym for \fBchar*\fP, and
wolffd@0 181 the graph\(hybased types \fBnode_t\fP,
wolffd@0 182 \fBedge_t\fP, \fBgraph_t\fP and \fBobj_t\fP.
wolffd@0 183 The \fBobj_t\fP type can be viewed as a supertype of the other 3 concrete types;
wolffd@0 184 the correct base type is maintained dynamically.
wolffd@0 185 Besides these base types, the only other supported type expressions
wolffd@0 186 are (associative) arrays.
wolffd@0 187 .PP
wolffd@0 188 Constants follow C syntax, but strings may be quoted with either
wolffd@0 189 \fB"..."\fP or \fB'...'\fP. In certain contexts, string values are
wolffd@0 190 interpreted as patterns for the purpose of regular expression matching.
wolffd@0 191 Patterns use
wolffd@0 192 .IR ksh (1)
wolffd@0 193 file match pattern syntax.
wolffd@0 194 \fBgvpr\fP accepts C++ comments as well as cpp\(hytype comments.
wolffd@0 195 For the latter, if a line begins with a '#' character, the rest of
wolffd@0 196 the line is ignored.
wolffd@0 197 .PP
wolffd@0 198 A statement can be a declaration of a function, a variable
wolffd@0 199 or an array, or an executable statement. For declarations, there
wolffd@0 200 is a single scope. Array declarations have the form:
wolffd@0 201 .PP
wolffd@0 202 .ta \w'\f(CWdelete array[expression]'u
wolffd@0 203 .RS
wolffd@0 204 .nf
wolffd@0 205 \fI type array \fB[\fP type0 \fB]\fR
wolffd@0 206 .fi
wolffd@0 207 .RE
wolffd@0 208 .DT
wolffd@0 209 .PP
wolffd@0 210 where \fI type0 \fP is optional. If it is supplied, the parser will
wolffd@0 211 enforce that all array subscripts have the specified type. If it is
wolffd@0 212 not supplied, objects of all types can be used as subscripts.
wolffd@0 213 As in C, variables and arrays must
wolffd@0 214 be declared. In particular, an undeclared variable will be interpreted
wolffd@0 215 as the name of an attribute of a node, edge or graph, depending on the
wolffd@0 216 context.
wolffd@0 217 .PP
wolffd@0 218 Executable statements can be one of the following:
wolffd@0 219 .ta \w'\f(CWdelete array[expression]'u
wolffd@0 220 .RS
wolffd@0 221 .nf
wolffd@0 222 \fB{\fR [\fI statement ... \fR] \fB}\fR
wolffd@0 223 \fIexpression\fP \fR// commonly\fP\fI var \fB=\fP expression\fR
wolffd@0 224 \fBif(\fI expression \fP)\fI statement \fR[ \fBelse\fI statement \fR]
wolffd@0 225 \fBfor(\fI expression \fP;\fI expression \fP;\fI expression \fP)\fI statement\fP
wolffd@0 226 \fBfor(\fI array \fP[\fI var \fP])\fI statement\fP
wolffd@0 227 \fBwhile(\fI expression \fP)\fI statement\fP
wolffd@0 228 \fBswitch(\fI expression \fP)\fI case statements\fP
wolffd@0 229 \fBbreak [\fI expression \fP]
wolffd@0 230 \fBcontinue [\fI expression \fP]
wolffd@0 231 \fBreturn [\fI expression \fP]\fR
wolffd@0 232 .fi
wolffd@0 233 .RE
wolffd@0 234 .ST
wolffd@0 235 Items in brackets are optional.
wolffd@0 236 .PP
wolffd@0 237 In the second form of the \fBfor\fP statement, the variable \fIvar\fP
wolffd@0 238 is set to each value used as an index in the specified array and then
wolffd@0 239 the associated \fIstatement\fP is evaluated. Function definitions can
wolffd@0 240 only appear in the \fBBEGIN\fP clause.
wolffd@0 241 .PP
wolffd@0 242 Expressions include the usual C expressions.
wolffd@0 243 String comparisons using \fB==\fP and \fB!=\fP
wolffd@0 244 treat the right hand operand as a pattern.
wolffd@0 245 \fBgvpr\fP will attempt to use an expression as a string or numeric value
wolffd@0 246 as appropriate.
wolffd@0 247 .PP
wolffd@0 248 Expressions of graphical type (i.e., \fBgraph_t, node_t,
wolffd@0 249 edge_t, obj_t\fP) may be followed by a field reference in the
wolffd@0 250 form of \fB.\fP\fIname\fP. The resulting value is the value
wolffd@0 251 of the attribute named \fIname\fP of the given object.
wolffd@0 252 In addition, in certain contexts an undeclared, unmodified
wolffd@0 253 identifier is taken to be an
wolffd@0 254 attribute name. Specifically, such identifiers denote attributes
wolffd@0 255 of the current node or edge, respectively, in \fBN\fP
wolffd@0 256 and \fBE\fP clauses, and the current graph in \fBBEG_G\fP and \fBEND_G\fP
wolffd@0 257 clauses.
wolffd@0 258 .PP
wolffd@0 259 As usual in the
wolffd@0 260 .IR libcgraph (3)
wolffd@0 261 model, attributes are string\(hyvalued.
wolffd@0 262 In addition,
wolffd@0 263 .B gvpr
wolffd@0 264 supports certain pseudo\(hyattributes of graph objects, not necessarily
wolffd@0 265 string\(hyvalued. These reflect intrinsic properties of the graph objects
wolffd@0 266 and cannot be set by the user.
wolffd@0 267 .TP
wolffd@0 268 \fBhead\fR : \fBnode_t\fR
wolffd@0 269 the head of an edge.
wolffd@0 270 .TP
wolffd@0 271 \fBtail\fR : \fBnode_t\fR
wolffd@0 272 the tail of an edge.
wolffd@0 273 .TP
wolffd@0 274 \fBname\fR : \fBstring\fR
wolffd@0 275 the name of an edge, node or graph. The name of an edge has the
wolffd@0 276 form "\fI<tail\(hyname><edge\(hyop><head\(hyname>\fB[\fI<key>\fB]\fR",
wolffd@0 277 where \fI<edge\(hyop>\fP is "\fB\->\fP" or "\fB\-\-\fP" depending on
wolffd@0 278 whether the graph is directed or not. The bracket part \fB[\fI<key>\fB]\fR
wolffd@0 279 only appears if the edge has a non\(hytrivial key.
wolffd@0 280 .TP
wolffd@0 281 \fBindegree\fR : \fBint\fR
wolffd@0 282 the indegree of a node.
wolffd@0 283 .TP
wolffd@0 284 \fBoutdegree\fR : \fBint\fR
wolffd@0 285 the outdegree of a node.
wolffd@0 286 .TP
wolffd@0 287 \fBdegree\fR : \fBint\fR
wolffd@0 288 the degree of a node.
wolffd@0 289 .TP
wolffd@0 290 \fBroot\fR : \fBgraph_t\fR
wolffd@0 291 the root graph of an object. The root of a root graph
wolffd@0 292 is itself.
wolffd@0 293 .TP
wolffd@0 294 \fBparent\fR : \fBgraph_t\fR
wolffd@0 295 the parent graph of a subgraph. The parent of a root graph
wolffd@0 296 is \fBNULL\fP
wolffd@0 297 .TP
wolffd@0 298 \fBn_edges\fR : \fBint\fR
wolffd@0 299 the number of edges in the graph
wolffd@0 300 .TP
wolffd@0 301 \fBn_nodes\fR : \fBint\fR
wolffd@0 302 the number of nodes in the graph
wolffd@0 303 .TP
wolffd@0 304 \fBdirected\fR : \fBint\fR
wolffd@0 305 true (non\(hyzero) if the graph is directed
wolffd@0 306 .TP
wolffd@0 307 \fBstrict\fR : \fBint\fR
wolffd@0 308 true (non\(hyzero) if the graph is strict
wolffd@0 309 .SH "BUILT\(hyIN FUNCTIONS"
wolffd@0 310 .PP
wolffd@0 311 The following functions are built into \fBgvpr\fP. Those functions
wolffd@0 312 returning references to graph objects return \fBNULL\fP in case of failure.
wolffd@0 313 .SS "Graphs and subgraph"
wolffd@0 314 .TP
wolffd@0 315 \fBgraph\fP(\fIs\fP : \fBstring\fP, \fIt\fP : \fBstring\fP) : \fBgraph_t\fP
wolffd@0 316 creates a graph whose name is \fIs\fP and whose type is
wolffd@0 317 specified by the string \fIt\fP. Ignoring case, the characters
wolffd@0 318 \fBU, D, S, N\fR have the interpretation undirected, directed,
wolffd@0 319 strict, and non\(hystrict, respectively. If \fIt\fP is empty,
wolffd@0 320 a directed, non\(hystrict graph is generated.
wolffd@0 321 .TP
wolffd@0 322 \fBsubg\fP(\fIg\fP : \fBgraph_t\fP, \fIs\fP : \fBstring\fP) : \fBgraph_t\fP
wolffd@0 323 creates a subgraph in graph \fIg\fP with name \fIs\fP. If the subgraph
wolffd@0 324 already exists, it is returned.
wolffd@0 325 .TP
wolffd@0 326 \fBisSubg\fP(\fIg\fP : \fBgraph_t\fP, \fIs\fP : \fBstring\fP) : \fBgraph_t\fP
wolffd@0 327 returns the subgraph in graph \fIg\fP with name \fIs\fP, if it exists,
wolffd@0 328 or \fBNULL\fP otherwise.
wolffd@0 329 .TP
wolffd@0 330 \fBfstsubg\fP(\fIg\fP : \fBgraph_t\fP) : \fBgraph_t\fP
wolffd@0 331 returns the first subgraph in graph \fIg\fP, or \fBNULL\fP if none exists.
wolffd@0 332 .TP
wolffd@0 333 \fBnxtsubg\fP(\fIsg\fP : \fBgraph_t\fP) : \fBgraph_t\fP
wolffd@0 334 returns the next subgraph after \fIsg\fP, or \fBNULL\fP.
wolffd@0 335 .TP
wolffd@0 336 \fBisDirect\fP(\fIg\fP : \fBgraph_t\fP) : \fBint\fP
wolffd@0 337 returns true if and only if \fIg\fP is directed.
wolffd@0 338 .TP
wolffd@0 339 \fBisStrict\fP(\fIg\fP : \fBgraph_t\fP) : \fBint\fP
wolffd@0 340 returns true if and only if \fIg\fP is strict.
wolffd@0 341 .TP
wolffd@0 342 \fBnNodes\fP(\fIg\fP : \fBgraph_t\fP) : \fBint\fP
wolffd@0 343 returns the number of nodes in \fIg\fP.
wolffd@0 344 .TP
wolffd@0 345 \fBnEdges\fP(\fIg\fP : \fBgraph_t\fP) : \fBint\fP
wolffd@0 346 returns the number of edges in \fIg\fP.
wolffd@0 347 .SS "Nodes"
wolffd@0 348 .TP
wolffd@0 349 \fBnode\fP(\fIsg\fP : \fBgraph_t\fP, \fIs\fP : \fBstring\fP) : \fBnode_t\fP
wolffd@0 350 creates a node in graph \fIg\fP of name \fIs\fP. If such a node
wolffd@0 351 already exists, it is returned.
wolffd@0 352 .TP
wolffd@0 353 \fBsubnode\fP(\fIsg\fP : \fBgraph_t\fP, \fIn\fP : \fBnode_t\fP) : \fBnode_t\fP
wolffd@0 354 inserts the node \fIn\fP into the subgraph \fIg\fP. Returns the node.
wolffd@0 355 .TP
wolffd@0 356 \fBfstnode\fP(\fIg\fP : \fBgraph_t\fP) : \fBnode_t\fP
wolffd@0 357 returns the first node in graph \fIg\fP, or \fBNULL\fP if none exists.
wolffd@0 358 .TP
wolffd@0 359 \fBnxtnode\fP(\fIn\fP : \fBnode_t\fP) : \fBnode_t\fP
wolffd@0 360 returns the next node after \fIn\fP in the root graph, or \fBNULL\fP.
wolffd@0 361 .TP
wolffd@0 362 \fBnxtnode_sg\fP(\fIsg\fP : \fBgraph_t\fP, \fIn\fP : \fBnode_t\fP) : \fBnode_t\fP
wolffd@0 363 returns the next node after \fIn\fP in \fIsg\fP, or \fBNULL\fP.
wolffd@0 364 .TP
wolffd@0 365 \fBisNode\fP(\fIsg\fP : \fBgraph_t\fP, \fIs\fP : \fBstring\fP) : \fBnode_t\fP
wolffd@0 366 looks for a node in (sub)graph \fIsg\fP of name \fIs\fP. If such a node
wolffd@0 367 exists, it is returned. Otherwise, \fBNULL\fP is returned.
wolffd@0 368 .TP
wolffd@0 369 \fBisSubnode\fP(\fIsg\fP : \fBgraph_t\fP, \fIn\fP : \fBnode_t\fP) : \fBint\fP
wolffd@0 370 returns non-zero if node \fIn\fP is in (sub)graph \fIsg\fP, or zero
wolffd@0 371 otherwise.
wolffd@0 372 .TP
wolffd@0 373 \fBindegreeOf\fP(\fIsg\fP : \fBgraph_t\fP, \fIn\fP : \fBnode_t\fP) : \fBint\fP
wolffd@0 374 returns the indegree of node \fIn\fP in (sub)graph \fIsg\fP.
wolffd@0 375 .TP
wolffd@0 376 \fBoutdegreeOf\fP(\fIsg\fP : \fBgraph_t\fP, \fIn\fP : \fBnode_t\fP) : \fBint\fP
wolffd@0 377 returns the outdegree of node \fIn\fP in (sub)graph \fIsg\fP.
wolffd@0 378 .TP
wolffd@0 379 \fBdegreeOf\fP(\fIsg\fP : \fBgraph_t\fP, \fIn\fP : \fBnode_t\fP) : \fBint\fP
wolffd@0 380 returns the degree of node \fIn\fP in (sub)graph \fIsg\fP.
wolffd@0 381 .SS "Edges"
wolffd@0 382 .TP
wolffd@0 383 \fBedge\fP(\fIt\fP : \fBnode_t\fP, \fIh\fP : \fBnode_t\fP, \fIs\fP : \fBstring\fP) : \fBedge_t\fP
wolffd@0 384 creates an edge with tail node \fIt\fP, head node \fIh\fP and
wolffd@0 385 name \fIs\fP in the root graph. If the graph is undirected, the
wolffd@0 386 distinction between head and tail nodes is unimportant.
wolffd@0 387 If such an edge already exists, it is returned.
wolffd@0 388 .TP
wolffd@0 389 \fBedge_sg\fP(\fIsg\fP : \fBgraph_t\fP, \fIt\fP : \fBnode_t\fP, \fIh\fP : \fBnode_t\fP, \fIs\fP : \fBstring\fP) : \fBedge_t\fP
wolffd@0 390 creates an edge with tail node \fIt\fP, head node \fIh\fP and name \fIs\fP
wolffd@0 391 in (sub)graph \fIsg\fP (and all parent graphs). If the graph is undirected, the distinction between
wolffd@0 392 head and tail nodes is unimportant.
wolffd@0 393 If such an edge already exists, it is returned.
wolffd@0 394 .TP
wolffd@0 395 \fBsubedge\fP(\fIg\fP : \fBgraph_t\fP, \fIe\fP : \fBedge_t\fP) : \fBedge_t\fP
wolffd@0 396 inserts the edge \fIe\fP into the subgraph \fIg\fP. Returns the edge.
wolffd@0 397 .TP
wolffd@0 398 \fBisEdge\fP(\fIt\fP : \fBnode_t\fP, \fIh\fP : \fBnode_t\fP, \fIs\fP : \fBstring\fP) : \fBedge_t\fP
wolffd@0 399 looks for an edge with tail node \fIt\fP, head node \fIh\fP and
wolffd@0 400 name \fIs\fP. If the graph is undirected, the distinction between
wolffd@0 401 head and tail nodes is unimportant.
wolffd@0 402 If such an edge exists, it is returned. Otherwise, \fBNULL\fP is returned.
wolffd@0 403 .TP
wolffd@0 404 \fBisEdge_sg\fP(\fIsg\fP : \fBgraph_t\fP, \fIt\fP : \fBnode_t\fP, \fIh\fP : \fBnode_t\fP, \fIs\fP : \fBstring\fP) : \fBedge_t\fP
wolffd@0 405 looks for an edge with tail node \fIt\fP, head node \fIh\fP and
wolffd@0 406 name \fIs\fP in (sub)graph \fIsg\fP. If the graph is undirected, the distinction between
wolffd@0 407 head and tail nodes is unimportant.
wolffd@0 408 If such an edge exists, it is returned. Otherwise, \fBNULL\fP is returned.
wolffd@0 409 .TP
wolffd@0 410 \fBisSubedge\fP(\fIg\fP : \fBgraph_t\fP, \fIe\fP : \fBedge_t\fP) : \fBint\fP
wolffd@0 411 returns non-zero if edge \fIe\fP is in (sub)graph \fIsg\fP, or zero
wolffd@0 412 otherwise.
wolffd@0 413 .TP
wolffd@0 414 \fBfstout\fP(\fIn\fP : \fBnode_t\fP) : \fBedge_t\fP
wolffd@0 415 returns the first outedge of node \fIn\fP in the root graph.
wolffd@0 416 .TP
wolffd@0 417 \fBfstout_sg\fP(\fIsg\fP : \fBgraph_t\fP, \fIn\fP : \fBnode_t\fP) : \fBedge_t\fP
wolffd@0 418 returns the first outedge of node \fIn\fP in (sub)graph \fIsg\fP.
wolffd@0 419 .TP
wolffd@0 420 \fBnxtout\fP(\fIe\fP : \fBedge_t\fP) : \fBedge_t\fP
wolffd@0 421 returns the next outedge after \fIe\fP in the root graph.
wolffd@0 422 .TP
wolffd@0 423 \fBnxtout_sg\fP(\fIsg\fP : \fBgraph_t\fP, \fIe\fP : \fBedge_t\fP) : \fBedge_t\fP
wolffd@0 424 returns the next outedge after \fIe\fP in graph \fIsg\fP.
wolffd@0 425 .TP
wolffd@0 426 \fBfstin\fP(\fIn\fP : \fBnode_t\fP) : \fBedge_t\fP
wolffd@0 427 returns the first inedge of node \fIn\fP in the root graph.
wolffd@0 428 .TP
wolffd@0 429 \fBfstin_sg\fP(\fIsg\fP : \fBgraph_t\fP, \fIn\fP : \fBnode_t\fP) : \fBedge_t\fP
wolffd@0 430 returns the first inedge of node \fIn\fP in graph \fIsg\fP.
wolffd@0 431 .TP
wolffd@0 432 \fBnxtin\fP(\fIe\fP : \fBedge_t\fP) : \fBedge_t\fP
wolffd@0 433 returns the next inedge after \fIe\fP in the root graph.
wolffd@0 434 .TP
wolffd@0 435 \fBnxtin_sg\fP(\fIsg\fP : \fBgraph_t\fP, \fIe\fP : \fBedge_t\fP) : \fBedge_t\fP
wolffd@0 436 returns the next inedge after \fIe\fP in graph \fIsg\fP.
wolffd@0 437 .TP
wolffd@0 438 \fBfstedge\fP(\fIn\fP : \fBnode_t\fP) : \fBedge_t\fP
wolffd@0 439 returns the first edge of node \fIn\fP in the root graph.
wolffd@0 440 .TP
wolffd@0 441 \fBfstedge_sg\fP(\fIsg\fP : \fBgraph_t\fP, \fIn\fP : \fBnode_t\fP) : \fBedge_t\fP
wolffd@0 442 returns the first edge of node \fIn\fP in graph \fIsg\fP.
wolffd@0 443 .TP
wolffd@0 444 \fBnxtedge\fP(\fIe\fP : \fBedge_t\fP, \fBnode_t\fP) : \fBedge_t\fP
wolffd@0 445 returns the next edge after \fIe\fP in the root graph.
wolffd@0 446 .TP
wolffd@0 447 \fBnxtedge_sg\fP(\fIsg\fP : \fBgraph_t\fP, \fIe\fP : \fBedge_t\fP, \fBnode_t\fP) : \fBedge_t\fP
wolffd@0 448 returns the next edge after \fIe\fP in the graph \fIsg\fP.
wolffd@0 449 .SS "Graph I/O"
wolffd@0 450 .TP
wolffd@0 451 \fBwrite\fP(\fIg\fP : \fBgraph_t\fP) : \fBvoid\fP
wolffd@0 452 prints \fIg\fP in dot format onto the output stream.
wolffd@0 453 .TP
wolffd@0 454 \fBwriteG\fP(\fIg\fP : \fBgraph_t\fP, \fIfname\fP : \fBstring\fP) : \fBvoid\fP
wolffd@0 455 prints \fIg\fP in dot format into the file \fIfname\fP.
wolffd@0 456 .TP
wolffd@0 457 \fBfwriteG\fP(\fIg\fP : \fBgraph_t\fP, \fIfd\fP : \fBint\fP) : \fBvoid\fP
wolffd@0 458 prints \fIg\fP in dot format onto the open stream denoted
wolffd@0 459 by the integer \fIfd\fP.
wolffd@0 460 .TP
wolffd@0 461 \fBreadG\fP(\fIfname\fP : \fBstring\fP) : \fBgraph_t\fP
wolffd@0 462 returns a graph read from the file \fIfname\fP. The graph should be
wolffd@0 463 in dot format. If no graph can be read, \fBNULL\fP is returned.
wolffd@0 464 .TP
wolffd@0 465 \fBfreadG\fP(\fIfd\fP : \fBint\fP) : \fBgraph_t\fP
wolffd@0 466 returns the next graph read from the open stream \fIfd\fP.
wolffd@0 467 Returns \fBNULL\fP at end of file.
wolffd@0 468 .SS "Graph miscellany"
wolffd@0 469 .TP
wolffd@0 470 \fBdelete\fP(\fIg\fP : \fBgraph_t\fP, \fIx\fP : \fBobj_t\fP) : \fBvoid\fP
wolffd@0 471 deletes object \fIx\fP from graph \fIg\fP.
wolffd@0 472 If \fIg\fP is \fBNULL\fP, the function uses the root graph of \fIx\fP.
wolffd@0 473 If \fIx\fP is a graph or subgraph, it is closed unless \fIx\fP is locked.
wolffd@0 474 .TP
wolffd@0 475 \fBisIn\fP(\fIg\fP : \fBgraph_t\fP, \fIx\fP : \fBobj_t\fP) : \fBint\fP
wolffd@0 476 returns true if \fIx\fP is in subgraph \fIg\fP.
wolffd@0 477 .TP
wolffd@0 478 \fBclone\fP(\fIg\fP : \fBgraph_t\fP, \fIx\fP : \fBobj_t\fP) : \fBobj_t\fP
wolffd@0 479 creates a clone of object \fIx\fP in graph \fIg\fP.
wolffd@0 480 In particular, the new object has the same name/value attributes
wolffd@0 481 and structure as the original object.
wolffd@0 482 If an object with the same key as \fIx\fP already exists, its attributes
wolffd@0 483 are overlaid by those of \fIx\fP and the object is returned.
wolffd@0 484 If an edge is cloned, both endpoints are implicitly cloned.
wolffd@0 485 If a graph is cloned, all nodes, edges and subgraphs are implicitly
wolffd@0 486 cloned.
wolffd@0 487 If \fIx\fP is a graph, \fIg\fP may be \fBNULL\fP, in which case the cloned
wolffd@0 488 object will be a new root graph.
wolffd@0 489 .TP
wolffd@0 490 \fBcopy\fP(\fIg\fP : \fBgraph_t\fP, \fIx\fP : \fBobj_t\fP) : \fBobj_t\fP
wolffd@0 491 creates a copy of object \fIx\fP in graph \fIg\fP,
wolffd@0 492 where the new object has the same name/value attributes
wolffd@0 493 as the original object.
wolffd@0 494 If an object with the same key as \fIx\fP already exists, its attributes
wolffd@0 495 are overlaid by those of \fIx\fP and the object is returned.
wolffd@0 496 Note that this is a shallow copy. If \fIx\fP is a graph, none of its nodes,
wolffd@0 497 edges or subgraphs are copied into the new graph. If \fIx\fP is an edge,
wolffd@0 498 the endpoints are created if necessary, but they are not cloned.
wolffd@0 499 If \fIx\fP is a graph, \fIg\fP may be \fBNULL\fP, in which case the cloned
wolffd@0 500 object will be a new root graph.
wolffd@0 501 .TP
wolffd@0 502 \fBcopyA\fP(\fIsrc\fP : \fBobj_t\fP, \fItgt\fP : \fBobj_t\fP) : \fBint\fP
wolffd@0 503 copies the attributes of object \fIsrc\fP to object \fItgt\fP, overwriting
wolffd@0 504 any attribute values \fItgt\fP may initially have.
wolffd@0 505 .TP
wolffd@0 506 \fBinduce\fP(\fIg\fP : \fBgraph_t\fP) : \fBvoid\fP
wolffd@0 507 extends \fIg\fP to its node\(hyinduced subgraph extension in its root graph.
wolffd@0 508 .TP
wolffd@0 509 \fBhasAttr\fP(\fIsrc\fP : \fBobj_t\fP, \fIname\fP : \fBstring\fP) : \fBint\fP
wolffd@0 510 returns non-zero if object \fIsrc\fP has an attribute whose name is
wolffd@0 511 \fIname\fP. It returns 0 otherwise.
wolffd@0 512 .TP
wolffd@0 513 \fBisAttr\fP(\fIg\fP : \fBgraph_t\fP, \fIkind\fP : \fBstring\fP, \fIname\fP : \fBstring\fP) : \fBint\fP
wolffd@0 514 returns non-zero if an attribute \fIname\fP has been defined in \fIg\fP
wolffd@0 515 for objects of the given \fIkind\fP. For nodes, edges, and graphs, \fIkind\fP
wolffd@0 516 should be "N", "E", and "G", respectively.
wolffd@0 517 It returns 0 otherwise.
wolffd@0 518 .TP
wolffd@0 519 \fBaget\fP(\fIsrc\fP : \fBobj_t\fP, \fIname\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 520 returns the value of attribute \fIname\fP in object \fIsrc\fP. This is
wolffd@0 521 useful for those cases when \fIname\fP conflicts with one of the keywords
wolffd@0 522 such as "head" or "root".
wolffd@0 523 If the attribute has not been declared in the graph, the function will
wolffd@0 524 initialize it with a default value of "". To avoid this, one should use
wolffd@0 525 the \fBhasAttr\fP or \fBisAttr\fP function to check that the attribute exists.
wolffd@0 526 .TP
wolffd@0 527 \fBaset\fP(\fIsrc\fP : \fBobj_t\fP, \fIname\fP : \fBstring\fP, \fIvalue\fP : \fBstring\fP) : \fBint\fP
wolffd@0 528 sets the value of attribute \fIname\fP in object \fIsrc\fP to \fIvalue\fP.
wolffd@0 529 Returns 0 on success, non\(hyzero on failure. See \fBaget\fP above.
wolffd@0 530 .TP
wolffd@0 531 \fBgetDflt\fP(\fIg\fP : \fBgraph_t\fP, \fIkind\fP : \fBstring\fP, \fIname\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 532 returns the default value of attribute \fIname\fP in objects in \fIg\fP of
wolffd@0 533 the given \fIkind\fP. For nodes, edges, and graphs, \fIkind\fP
wolffd@0 534 should be "N", "E", and "G", respectively.
wolffd@0 535 If the attribute has not been declared in the graph, the function will
wolffd@0 536 initialize it with a default value of "". To avoid this, one should use
wolffd@0 537 the \fBisAttr\fP function to check that the attribute exists.
wolffd@0 538 .TP
wolffd@0 539 \fBsetDflt\fP(\fIg\fP : \fBgraph_t\fP, \fIkind\fP : \fBstring\fP, \fIname\fP : \fBstring\fP, \fIvalue\fP : \fBstring\fP) : \fBint\fP
wolffd@0 540 sets the default value of attribute \fIname\fP to \fIvalue\fP in
wolffd@0 541 objects in \fIg\fP of
wolffd@0 542 the given \fIkind\fP. For nodes, edges, and graphs, \fIkind\fP
wolffd@0 543 should be "N", "E", and "G", respectively.
wolffd@0 544 Returns 0 on success, non\(hyzero on failure. See \fBgetDflt\fP above.
wolffd@0 545 .TP
wolffd@0 546 \fBfstAttr\fP(\fIg\fP : \fBgraph_t\fP, \fIkind\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 547 returns the name of the first attribute of objects in \fIg\fP of
wolffd@0 548 the given \fIkind\fP. For nodes, edges, and graphs, \fIkind\fP
wolffd@0 549 should be "N", "E", and "G", respectively.
wolffd@0 550 If there are no attributes, the string "" is returned.
wolffd@0 551 .TP
wolffd@0 552 \fBnxtAttr\fP(\fIg\fP : \fBgraph_t\fP, \fIkind\fP : \fBstring\fP, \fIname\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 553 returns the name of the next attribute of objects in \fIg\fP of
wolffd@0 554 the given \fIkind\fP after the attribute \fIname\fP.
wolffd@0 555 The argument \fIname\fP must be the name of an existing attribute; it will
wolffd@0 556 typically be the return value of an previous call to \fBfstAttr\fP or
wolffd@0 557 \fBnxtAttr\fP.
wolffd@0 558 For nodes, edges, and graphs, \fIkind\fP
wolffd@0 559 should be "N", "E", and "G", respectively.
wolffd@0 560 If there are no attributes left, the string "" is returned.
wolffd@0 561 .TP
wolffd@0 562 \fBcompOf\fP(\fIg\fP : \fBgraph_t\fP, \fIn\fP : \fBnode_t\fP) : \fBgraph_t\fP
wolffd@0 563 returns the connected component of the graph \fIg\fP containing node \fIn\fP,
wolffd@0 564 as a subgraph of \fIg\fP. The subgraph only contains the nodes. One can
wolffd@0 565 use \fIinduce\fP to add the edges. The function fails and returns \fBNULL\fP
wolffd@0 566 if \fIn\fP is not in \fIg\fP. Connectivity is based on the underlying
wolffd@0 567 undirected graph of \fIg\fP.
wolffd@0 568 .TP
wolffd@0 569 \fBkindOf\fP(\fIobj\fP : \fBobj_t\fP) : \fBstring\fP
wolffd@0 570 returns an indication of what kind of graph object is the argument.
wolffd@0 571 For nodes, edges, and graphs, it returns
wolffd@0 572 should be "N", "E", and "G", respectively.
wolffd@0 573 .TP
wolffd@0 574 \fBlock\fP(\fIg\fP : \fBgraph_t\fP, \fIv\fP : \fBint\fP) : \fBint\fP
wolffd@0 575 implements graph locking on root graphs. If the integer \fIv\fP is positive, the
wolffd@0 576 graph is set so that future calls to \fBdelete\fP have no immediate effect.
wolffd@0 577 If \fIv\fP is zero, the graph is unlocked. If there has been a call
wolffd@0 578 to delete the graph while it was locked, the graph is closed.
wolffd@0 579 If \fIv\fP is negative, nothing is done.
wolffd@0 580 In all cases, the previous lock value is returned.
wolffd@0 581 .SS "Strings"
wolffd@0 582 .TP
wolffd@0 583 \fBsprintf\fP(\fIfmt\fP : \fBstring\fP, \fI...\fP) : \fBstring\fP
wolffd@0 584 returns the string resulting from formatting
wolffd@0 585 the values of the expressions occurring after \fIfmt\fP
wolffd@0 586 according to the
wolffd@0 587 .IR printf (3)
wolffd@0 588 format
wolffd@0 589 .I fmt
wolffd@0 590 .TP
wolffd@0 591 \fBgsub\fP(\fIstr\fP : \fBstring\fP, \fIpat\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 592 .TP
wolffd@0 593 \fBgsub\fP(\fIstr\fP : \fBstring\fP, \fIpat\fP : \fBstring\fP, \fIrepl\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 594 returns \fIstr\fP with all substrings matching \fIpat\fP
wolffd@0 595 deleted or replaced by \fIrepl\fP, respectively.
wolffd@0 596 .TP
wolffd@0 597 \fBsub\fP(\fIstr\fP : \fBstring\fP, \fIpat\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 598 .TP
wolffd@0 599 \fBsub\fP(\fIstr\fP : \fBstring\fP, \fIpat\fP : \fBstring\fP, \fIrepl\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 600 returns \fIstr\fP with the leftmost substring matching \fIpat\fP
wolffd@0 601 deleted or replaced by \fIrepl\fP, respectively. The
wolffd@0 602 characters '^' and '$'
wolffd@0 603 may be used at the beginning and end, respectively,
wolffd@0 604 of \fIpat\fP to anchor the pattern to the beginning or end of \fIstr\fP.
wolffd@0 605 .TP
wolffd@0 606 \fBsubstr\fP(\fIstr\fP : \fBstring\fP, \fIidx\fP : \fBint\fP) : \fBstring\fP
wolffd@0 607 .TP
wolffd@0 608 \fBsubstr\fP(\fIstr\fP : \fBstring\fP, \fIidx\fP : \fBint\fP, \fIlen\fP : \fBint\fP) : \fBstring\fP
wolffd@0 609 returns the substring of \fIstr\fP starting at position \fIidx\fP to
wolffd@0 610 the end of the string or of length \fIlen\fP, respectively.
wolffd@0 611 Indexing starts at 0. If \fIidx\fP is negative or \fIidx\fP is greater than
wolffd@0 612 the length of \fIstr\fP, a fatal error occurs. Similarly, in the second
wolffd@0 613 case, if \fIlen\fP is negative or \fIidx\fP + \fIlen\fP is greater than the
wolffd@0 614 length of \fIstr\fP, a fatal error occurs.
wolffd@0 615 .TP
wolffd@0 616 \fBlength\fP(\fIs\fP : \fBstring\fP) : \fBint\fP
wolffd@0 617 returns the length of the string \fIs\fP.
wolffd@0 618 .TP
wolffd@0 619 \fBindex\fP(\fIs\fP : \fBstring\fP, \fIt\fP : \fBstring\fP) : \fBint\fP
wolffd@0 620 .TP
wolffd@0 621 \fBrindex\fP(\fIs\fP : \fBstring\fP, \fIt\fP : \fBstring\fP) : \fBint\fP
wolffd@0 622 returns the index of the character in string \fIs\fP where the leftmost
wolffd@0 623 (rightmost) copy of string \fIt\fP can be found, or \-1 if \fIt\fP is not a
wolffd@0 624 substring of \fIs\fP.
wolffd@0 625 .TP
wolffd@0 626 \fBmatch\fP(\fIs\fP : \fBstring\fP, \fIp\fP : \fBstring\fP) : \fBint\fP
wolffd@0 627 returns the index of the character in string \fIs\fP where the leftmost
wolffd@0 628 match of pattern \fIp\fP can be found, or \-1 if no substring of \fIs\fP
wolffd@0 629 matches \fIp\fP.
wolffd@0 630 .TP
wolffd@0 631 \fBcanon\fP(\fIs\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 632 returns a version of \fIs\fP appropriate to be used as an identifier
wolffd@0 633 in a dot file.
wolffd@0 634 .TP
wolffd@0 635 \fBxOf\fP(\fIs\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 636 returns the string "\fIx\fP" if \fIs\fP has the form "\fIx\fP,\fIy\fP",
wolffd@0 637 where both \fIx\fP and \fIy\fP are numeric.
wolffd@0 638 .TP
wolffd@0 639 \fByOf\fP(\fIs\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 640 returns the string "\fIy\fP" if \fIs\fP has the form "\fIx\fP,\fIy\fP",
wolffd@0 641 where both \fIx\fP and \fIy\fP are numeric.
wolffd@0 642 .TP
wolffd@0 643 \fBllOf\fP(\fIs\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 644 returns the string "\fIllx\fP,\fIlly\fP" if \fIs\fP has the form
wolffd@0 645 "\fIllx\fP,\fIlly\fP,\fIurx\fP,\fIury\fP",
wolffd@0 646 where all of \fIllx\fP, \fIlly\fP, \fIurx\fP, and \fIury\fP are numeric.
wolffd@0 647 .TP
wolffd@0 648 .BI urOf( s )
wolffd@0 649 \fBurOf\fP(\fIs\fP : \fBstring\fP) : \fBstring\fP
wolffd@0 650 returns the string "\fIurx\fP,\fIury\fP" if \fIs\fP has the form
wolffd@0 651 "\fIllx\fP,\fIlly\fP,\fIurx\fP,\fIury\fP",
wolffd@0 652 where all of \fIllx\fP, \fIlly\fP, \fIurx\fP, and \fIury\fP are numeric.
wolffd@0 653 .TP
wolffd@0 654 \fBsscanf\fP(\fIs\fP : \fBstring\fP, \fIfmt\fP : \fBstring\fP, \fI...\fP) : \fBint\fP
wolffd@0 655 scans the string \fIs\fP, extracting values
wolffd@0 656 according to the
wolffd@0 657 .IR sscanf (3)
wolffd@0 658 format
wolffd@0 659 .IR fmt .
wolffd@0 660 The values are stored in the addresses following \fIfmt\fP,
wolffd@0 661 addresses having the form \fB&\fP\fIv\fP, where \fIv\fP is some declared
wolffd@0 662 variable of the correct type.
wolffd@0 663 Returns the number of items successfully scanned.
wolffd@0 664 .SS "I/O"
wolffd@0 665 .TP
wolffd@0 666 \fBprint\fP(\fI...\fP) : \fBvoid\fP
wolffd@0 667 .BI print( " expr" , " ...\fB )
wolffd@0 668 prints a string representation of each argument in turn onto
wolffd@0 669 \fBstdout\fP, followed by a newline.
wolffd@0 670 .TP
wolffd@0 671 \fBprintf\fP(\fIfmt\fP : \fBstring\fP, \fI...\fP) : \fBint\fP
wolffd@0 672 .TP
wolffd@0 673 \fBprintf\fP(\fIfd\fP : \fBint\fP, \fIfmt\fP : \fBstring\fP, \fI...\fP) : \fBint\fP
wolffd@0 674 prints the string resulting from formatting
wolffd@0 675 the values of the expressions following \fIfmt\fP
wolffd@0 676 according to the
wolffd@0 677 .IR printf (3)
wolffd@0 678 format
wolffd@0 679 .IR fmt .
wolffd@0 680 Returns 0 on success.
wolffd@0 681 By default, it prints on \fBstdout\fP.
wolffd@0 682 If the optional integer \fIfd\fP is given, output is written on the open
wolffd@0 683 stream associated with \fIfd\fP.
wolffd@0 684 .TP
wolffd@0 685 \fBscanf\fP(\fIfmt\fP : \fBstring\fP, \fI...\fP) : \fBint\fP
wolffd@0 686 .TP
wolffd@0 687 \fBscanf\fP(\fIfd\fP : \fBint\fP, \fIfmt\fP : \fBstring\fP, \fI...\fP) : \fBint\fP
wolffd@0 688 scans in values from an input stream according to the
wolffd@0 689 .IR scanf (3)
wolffd@0 690 format
wolffd@0 691 .IR fmt .
wolffd@0 692 The values are stored in the addresses following \fIfmt\fP,
wolffd@0 693 addresses having the form \fB&\fP\fIv\fP, where \fIv\fP is some declared
wolffd@0 694 variable of the correct type.
wolffd@0 695 By default, it reads from \fBstdin\fP.
wolffd@0 696 If the optional integer \fIfd\fP is given, input is read from the open
wolffd@0 697 stream associated with \fIfd\fP.
wolffd@0 698 Returns the number of items successfully scanned.
wolffd@0 699 .TP
wolffd@0 700 \fBopenF\fP(\fIs\fP : \fBstring\fP, \fIt\fP : \fBstring\fP) : \fBint\fP
wolffd@0 701 opens the file \fIs\fP as an I/O stream. The string argument \fIt\fP
wolffd@0 702 specifies how the file is opened. The arguments are the same as for
wolffd@0 703 the C function
wolffd@0 704 .IR fopen (3).
wolffd@0 705 It returns an integer denoting the stream, or \-1 on error.
wolffd@0 706 .sp
wolffd@0 707 As usual, streams 0, 1 and 2 are already open as \fBstdin\fP, \fBstdout\fP,
wolffd@0 708 and \fBstderr\fP, respectively. Since \fBgvpr\fP may use \fBstdin\fP to
wolffd@0 709 read the input graphs, the user should avoid using this stream.
wolffd@0 710 .TP
wolffd@0 711 \fBcloseF\fP(\fIfd\fP : \fBint\fP) : \fBint\fP
wolffd@0 712 closes the open stream denoted by the integer \fIfd\fP.
wolffd@0 713 Streams 0, 1 and 2 cannot be closed.
wolffd@0 714 Returns 0 on success.
wolffd@0 715 .TP
wolffd@0 716 \fBreadL\fP(\fIfd\fP : \fBint\fP) : \fBstring\fP
wolffd@0 717 returns the next line read from the input stream \fIfd\fP. It returns
wolffd@0 718 the empty string "" on end of file. Note that the newline character is
wolffd@0 719 left in the returned string.
wolffd@0 720 .SS "Math"
wolffd@0 721 .TP
wolffd@0 722 \fBexp\fP(\fId\fP : \fBdouble\fP) : \fBdouble\fP
wolffd@0 723 returns e to the \fId\fPth power.
wolffd@0 724 .TP
wolffd@0 725 \fBlog\fP(\fId\fP : \fBdouble\fP) : \fBdouble\fP
wolffd@0 726 returns the natural log of \fId\fP.
wolffd@0 727 .TP
wolffd@0 728 \fBsqrt\fP(\fId\fP : \fBdouble\fP) : \fBdouble\fP
wolffd@0 729 returns the square root of the double \fId\fP.
wolffd@0 730 .TP
wolffd@0 731 \fBpow\fP(\fId\fP : \fBdouble\fP, \fIx\fP : \fBdouble\fP) : \fBdouble\fP
wolffd@0 732 returns \fId\fP raised to the \fIx\fPth power.
wolffd@0 733 .TP
wolffd@0 734 \fBcos\fP(\fId\fP : \fBdouble\fP) : \fBdouble\fP
wolffd@0 735 returns the cosine of \fId\fP.
wolffd@0 736 .TP
wolffd@0 737 \fBsin\fP(\fId\fP : \fBdouble\fP) : \fBdouble\fP
wolffd@0 738 returns the sine of \fId\fP.
wolffd@0 739 .TP
wolffd@0 740 \fBatan2\fP(\fIy\fP : \fBdouble\fP, \fIx\fP : \fBdouble\fP) : \fBdouble\fP
wolffd@0 741 returns the arctangent of \fIy/x\fP in the range \-pi to pi.
wolffd@0 742 .TP
wolffd@0 743 \fBMIN\fP(\fIy\fP : \fBdouble\fP, \fIx\fP : \fBdouble\fP) : \fBdouble\fP
wolffd@0 744 returns the minimum of \fIy\fP and \fIx\fP.
wolffd@0 745 .TP
wolffd@0 746 \fBMAX\fP(\fIy\fP : \fBdouble\fP, \fIx\fP : \fBdouble\fP) : \fBdouble\fP
wolffd@0 747 returns the maximum of \fIy\fP and \fIx\fP.
wolffd@0 748 .SS "Miscellaneous"
wolffd@0 749 .TP
wolffd@0 750 \fBexit\fP(\fIv\fP : \fBint\fP) : \fBvoid\fP
wolffd@0 751 causes
wolffd@0 752 .B gvpr
wolffd@0 753 to exit with the exit code
wolffd@0 754 .IR v .
wolffd@0 755 .TP
wolffd@0 756 \fBsystem\fP(\fIcmd\fP : \fBstring\fP) : \fBint\fP
wolffd@0 757 provides the standard C function
wolffd@0 758 .IR system (3).
wolffd@0 759 It executes \fIcmd\fP if the user's shell environment, and
wolffd@0 760 returns the exit status of the shell.
wolffd@0 761 .TP
wolffd@0 762 \fBrand\fP() : \fBdouble\fP
wolffd@0 763 returns a pseudo\(hyrandom double between 0 and 1.
wolffd@0 764 .TP
wolffd@0 765 \fBsrand\fP() : \fBint\fP
wolffd@0 766 .TP
wolffd@0 767 \fBsrand\fP(\fIv\fP : \fBint\fP) : \fBint\fP
wolffd@0 768 sets a seed for the random number generator. The optional argument gives
wolffd@0 769 the seed; if it is omitted, the current time is used. The previous seed
wolffd@0 770 value is returned. \fBsrand\fP should be called before any calls to
wolffd@0 771 \fBrand\fP.
wolffd@0 772 .SH "BUILT\(hyIN VARIABLES"
wolffd@0 773 .PP
wolffd@0 774 .B gvpr
wolffd@0 775 provides certain special, built\(hyin variables, whose values are set
wolffd@0 776 automatically by \fBgvpr\fP depending on the context. Except as noted,
wolffd@0 777 the user cannot modify their values.
wolffd@0 778 .TP
wolffd@0 779 \fB$\fP : \fBobj_t\fP
wolffd@0 780 denotes the current object (node, edge, graph) depending on the
wolffd@0 781 context. It is not available in \fBBEGIN\fP or \fBEND\fP clauses.
wolffd@0 782 .TP
wolffd@0 783 \fB$F\fP : \fBstring\fP
wolffd@0 784 is the name of the current input file.
wolffd@0 785 .TP
wolffd@0 786 \fB$G\fP : \fBgraph_t\fP
wolffd@0 787 denotes the current graph being processed. It is not available
wolffd@0 788 in \fBBEGIN\fP or \fBEND\fP clauses.
wolffd@0 789 .TP
wolffd@0 790 \fB$O\fP : \fBgraph_t\fP
wolffd@0 791 denotes the output graph. Before graph traversal, it is initialized
wolffd@0 792 to the target graph. After traversal and any \fBEND_G\fP actions,
wolffd@0 793 if it refers to a non\(hyempty graph, that graph is printed onto the output stream.
wolffd@0 794 It is only valid in \fBN\fP, \fBE\fP and \fBEND_G\fP clauses.
wolffd@0 795 The output graph may be set by the user.
wolffd@0 796 .TP
wolffd@0 797 \fB$T\fP : \fBgraph_t\fP
wolffd@0 798 denotes the current target graph. It is a subgraph of \fB$G\fP
wolffd@0 799 and is available only in \fBN\fP, \fBE\fP and \fBEND_G\fP clauses.
wolffd@0 800 .TP
wolffd@0 801 \fB$tgtname\fP : \fBstring\fP
wolffd@0 802 denotes the name of the target graph.
wolffd@0 803 By default, it is set to \fB"gvpr_result"\fP.
wolffd@0 804 If used multiple times during the execution of
wolffd@0 805 .BR gvpr ,
wolffd@0 806 the name will be appended with an integer.
wolffd@0 807 This variable may be set by the user.
wolffd@0 808 .TP
wolffd@0 809 \fB$tvroot\fP : \fBnode_t\fP
wolffd@0 810 indicates the starting node for a (directed or undirected)
wolffd@0 811 depth\(hyfirst traversal of the
wolffd@0 812 graph (cf. \fB$tvtype\fP below).
wolffd@0 813 The default value is \fBNULL\fP for each input graph.
wolffd@0 814 .TP
wolffd@0 815 \fB$tvtype\fP : \fBtvtype_t\fP
wolffd@0 816 indicates how \fBgvpr\fP traverses a graph. It can only take
wolffd@0 817 one of the constant values with the previx "TV_" described below.
wolffd@0 818 \fBTV_flat\fP is the default.
wolffd@0 819 .IP
wolffd@0 820 In the underlying graph library
wolffd@0 821 .IR cgraph (3),
wolffd@0 822 edges in undirected graphs are given an arbitrary direction. This is
wolffd@0 823 used for traversals, such as \fBTV_fwd\fR, requiring directed edges.
wolffd@0 824 .
wolffd@0 825 .TP
wolffd@0 826 \fBARGC\fP : \fBint\fP
wolffd@0 827 denotes the number of arguments specified by the
wolffd@0 828 \fB\-a\fP \fIargs\fP command\(hyline argument.
wolffd@0 829 .TP
wolffd@0 830 \fBARGV\fP : \fBstring array\fP
wolffd@0 831 denotes the array of arguments specified by the
wolffd@0 832 \fB\-a\fP \fIargs\fP
wolffd@0 833 command\(hyline argument. The \fIi\fPth argument is given
wolffd@0 834 by \fBARGV[\fIi\fP]\fR.
wolffd@0 835 .SH "BUILT\(hyIN CONSTANTS"
wolffd@0 836 .PP
wolffd@0 837 There are several symbolic constants defined by \fBgvpr\fP.
wolffd@0 838 .TP
wolffd@0 839 \fBNULL\fR : \fIobj_t\fR
wolffd@0 840 a null object reference, equivalent to 0.
wolffd@0 841 .TP
wolffd@0 842 \fBTV_flat\fR : \fItvtype_t\fR
wolffd@0 843 a simple, flat traversal, with graph objects visited in
wolffd@0 844 seemingly arbitrary order.
wolffd@0 845 .TP
wolffd@0 846 \fBTV_ne\fR : \fItvtype_t\fR
wolffd@0 847 a traversal which first visits all of the nodes, then all
wolffd@0 848 of the edges.
wolffd@0 849 .TP
wolffd@0 850 \fBTV_en\fR : \fItvtype_t\fR
wolffd@0 851 a traversal which first visits all of the edges, then all
wolffd@0 852 of the nodes.
wolffd@0 853 .TP
wolffd@0 854 \fBTV_dfs\fR : \fItvtype_t\fR
wolffd@0 855 .TQ
wolffd@0 856 \fBTV_postdfs\fR : \fItvtype_t\fR
wolffd@0 857 .TQ
wolffd@0 858 \fBTV_prepostdfs\fR : \fItvtype_t\fR
wolffd@0 859 a traversal of the graph using a depth\(hyfirst search on the
wolffd@0 860 underlying undirected graph.
wolffd@0 861 To do the traversal, \fBgvpr\fP will check the value of
wolffd@0 862 \fB$tvroot\fP. If this has the same value that it had previously
wolffd@0 863 (at the start, the previous value is initialized to \fBNULL\fP.), \fBgvpr\fP
wolffd@0 864 will simply look for some unvisited node and traverse its connected
wolffd@0 865 component. On the other hand, if \fB$tvroot\fP has changed, its connected
wolffd@0 866 component will be toured, assuming it has not been previously visited or,
wolffd@0 867 if \fB$tvroot\fP is \fBNULL\fP, the traversal will stop. Note that using
wolffd@0 868 \fBTV_dfs\fP and \fB$tvroot\fP, it is possible to create an infinite loop.
wolffd@0 869 .
wolffd@0 870 .IP
wolffd@0 871 By default, the traversal is done in pre-order. That is, a node is
wolffd@0 872 visited before all of its unvisited edges. For \fBTV_postdfs\fR,
wolffd@0 873 all of a node's unvisited edges are visited before the node. For
wolffd@0 874 \fBTV_prepostdfs\fR, a node is visited twice, before and after all of
wolffd@0 875 its unvisited edges.
wolffd@0 876 .
wolffd@0 877 .TP
wolffd@0 878 \fBTV_fwd\fR : \fItvtype_t\fR
wolffd@0 879 .TQ
wolffd@0 880 \fBTV_postfwd\fR : \fItvtype_t\fR
wolffd@0 881 .TQ
wolffd@0 882 \fBTV_prepostfwd\fR : \fItvtype_t\fR
wolffd@0 883 A traversal of the graph using a depth\(hyfirst search on the
wolffd@0 884 graph following only forward arcs.
wolffd@0 885 The choice of roots for the traversal is the
wolffd@0 886 same as described for \fBTV_dfs\fR above.
wolffd@0 887 The different order of visitation specified by \fBTV_fwd\fR,
wolffd@0 888 \fBTV_postfwd\fR and \fBTV_prepostfwd\fR are the same as those
wolffd@0 889 specified by the analogous traversals \fBTV_dfs\fR,
wolffd@0 890 \fBTV_postdfs\fR and \fBTV_prepostdfs\fR.
wolffd@0 891 .TP
wolffd@0 892 \fBTV_rev\fR : \fItvtype_t\fR
wolffd@0 893 .TQ
wolffd@0 894 \fBTV_postrev\fR : \fItvtype_t\fR
wolffd@0 895 .TQ
wolffd@0 896 \fBTV_prepostrev\fR : \fItvtype_t\fR
wolffd@0 897 A traversal of the graph using a depth\(hyfirst search on the
wolffd@0 898 graph following only reverse arcs.
wolffd@0 899 The choice of roots for the traversal is the
wolffd@0 900 same as described for \fBTV_dfs\fR above.
wolffd@0 901 The different order of visitation specified by \fBTV_rev\fR,
wolffd@0 902 \fBTV_postrev\fR and \fBTV_prepostrev\fR are the same as those
wolffd@0 903 specified by the analogous traversals \fBTV_dfs\fR,
wolffd@0 904 \fBTV_postdfs\fR and \fBTV_prepostdfs\fR.
wolffd@0 905 .TP
wolffd@0 906 \fBTV_bfs\fR : \fItvtype_t\fR
wolffd@0 907 A traversal of the graph using a bread\(hyfirst search on the
wolffd@0 908 graph ignoring edge directions. See the item on \fBTV_dfs\fR above
wolffd@0 909 for the role of \fB$tvroot\fP.
wolffd@0 910 .SH EXAMPLES
wolffd@0 911 .PP
wolffd@0 912 .ta \w'\f(CWdelete array[expression]'u
wolffd@0 913 .RS
wolffd@0 914 .nf
wolffd@0 915 \fBgvpr \-i 'N[color=="blue"]' file.dot\fP
wolffd@0 916 .fi
wolffd@0 917 .RE
wolffd@0 918 .DT
wolffd@0 919 .PP
wolffd@0 920 Generate the node\(hyinduced subgraph of all nodes with color blue.
wolffd@0 921 .PP
wolffd@0 922 .ta \w'\f(CWdelete array[expression]'u
wolffd@0 923 .RS
wolffd@0 924 .nf
wolffd@0 925 \fBgvpr \-c 'N[color=="blue"]{color = "red"}' file.dot\fP
wolffd@0 926 .fi
wolffd@0 927 .RE
wolffd@0 928 .DT
wolffd@0 929 .PP
wolffd@0 930 Make all blue nodes red.
wolffd@0 931 .PP
wolffd@0 932 .ta \w'\f(CWdelete array[expression]'u
wolffd@0 933 .RS
wolffd@0 934 .nf
wolffd@0 935 \fBBEGIN { int n, e; int tot_n = 0; int tot_e = 0; }
wolffd@0 936 BEG_G {
wolffd@0 937 n = nNodes($G);
wolffd@0 938 e = nEdges($G);
wolffd@0 939 printf ("%d nodes %d edges %s\n", n, e, $G.name);
wolffd@0 940 tot_n += n;
wolffd@0 941 tot_e += e;
wolffd@0 942 }
wolffd@0 943 END { printf ("%d nodes %d edges total\n", tot_n, tot_e) }\fP
wolffd@0 944 .fi
wolffd@0 945 .RE
wolffd@0 946 .DT
wolffd@0 947 .PP
wolffd@0 948 Version of the program \fBgc\fP.
wolffd@0 949 .PP
wolffd@0 950 .ta \w'\f(CWdelete array[expression]'u
wolffd@0 951 .RS
wolffd@0 952 .nf
wolffd@0 953 \fBgvpr \-c ""\fP
wolffd@0 954 .fi
wolffd@0 955 .RE
wolffd@0 956 .DT
wolffd@0 957 .PP
wolffd@0 958 Equivalent to \fBnop\fP.
wolffd@0 959 .PP
wolffd@0 960 .ta \w'\f(CWdelete array[expression]'u
wolffd@0 961 .RS
wolffd@0 962 .nf
wolffd@0 963 \fBBEG_G { graph_t g = graph ("merge", "S"); }
wolffd@0 964 E {
wolffd@0 965 node_t h = clone(g,$.head);
wolffd@0 966 node_t t = clone(g,$.tail);
wolffd@0 967 edge_t e = edge(t,h,"");
wolffd@0 968 e.weight = e.weight + 1;
wolffd@0 969 }
wolffd@0 970 END_G { $O = g; }\fP
wolffd@0 971 .fi
wolffd@0 972 .RE
wolffd@0 973 .DT
wolffd@0 974 .PP
wolffd@0 975 Produces a strict version of the input graph, where the weight attribute
wolffd@0 976 of an edge indicates how many edges from the input graph the edge represents.
wolffd@0 977 .PP
wolffd@0 978 .ta \w'\f(CWdelete array[expression]'u
wolffd@0 979 .RS
wolffd@0 980 .nf
wolffd@0 981 \fBBEGIN {node_t n; int deg[]}
wolffd@0 982 E{deg[head]++; deg[tail]++; }
wolffd@0 983 END_G {
wolffd@0 984 for (deg[n]) {
wolffd@0 985 printf ("deg[%s] = %d\n", n.name, deg[n]);
wolffd@0 986 }
wolffd@0 987 }\fP
wolffd@0 988 .fi
wolffd@0 989 .RE
wolffd@0 990 .DT
wolffd@0 991 .PP
wolffd@0 992 Computes the degrees of nodes with edges.
wolffd@0 993 .SH ENVIRONMENT
wolffd@0 994 .TP
wolffd@0 995 .B GPRPATH
wolffd@0 996 Colon\(hyseparated list of directories to be searched to find
wolffd@0 997 the file specified by the \-f option.
wolffd@0 998 .SH BUGS AND WARNINGS
wolffd@0 999 When the program is given as a command line argument, the usual
wolffd@0 1000 shell interpretation takes place, which may affect some of the
wolffd@0 1001 special names in \fBgvpr\fP. To avoid this, it is best to wrap the
wolffd@0 1002 program in single quotes.
wolffd@0 1003 .PP
wolffd@0 1004 As of 24 April 2008, \fBgvpr\fP switched to using a new, underlying
wolffd@0 1005 graph library, which uses the simpler model that there is only one
wolffd@0 1006 copy of a node, not one copy for each subgraph logically containing
wolffd@0 1007 it. This means that iterators such as \Inxtnode\P cannot traverse
wolffd@0 1008 a subgraph using just a node argument. For this reason, subgraph
wolffd@0 1009 traversal requires new functions ending in "_sg", which also take
wolffd@0 1010 a subgraph argument. The versions without that suffix will always
wolffd@0 1011 traverse the root graph.
wolffd@0 1012 .PP
wolffd@0 1013 There is a single global scope, except for formal function parameters,
wolffd@0 1014 and even these can interfere with the type system. Also, the
wolffd@0 1015 extent of all variables is the entire life of the program.
wolffd@0 1016 It might be preferable for scope
wolffd@0 1017 to reflect the natural nesting of the clauses, or for the program
wolffd@0 1018 to at least reset locally declared variables.
wolffd@0 1019 For now, it is advisable to use distinct names for all variables.
wolffd@0 1020 .PP
wolffd@0 1021 If a function ends with a complex statement, such as an
wolffd@0 1022 IF statement, with each branch doing a return, type checking may fail.
wolffd@0 1023 Functions should use a return at the end.
wolffd@0 1024 .PP
wolffd@0 1025 The expr library does not support string values of (char*)0.
wolffd@0 1026 This means we can't distinguish between "" and (char*)0 edge keys.
wolffd@0 1027 For the purposes of looking up and creating edges, we translate ""
wolffd@0 1028 to be (char*)0, since this latter value is
wolffd@0 1029 necessary in order to look up any edge with a matching head and tail.
wolffd@0 1030 .PP
wolffd@0 1031 Related to this, strings converted to integers act like char pointers,
wolffd@0 1032 getting the value 0 or 1 depending on whether the string consists
wolffd@0 1033 solely of zeroes or not. Thus, the ((int)"2") evaluates to 1.
wolffd@0 1034 .PP
wolffd@0 1035 The language inherits the usual C problems such as dangling references
wolffd@0 1036 and the confusion between '=' and '=='.
wolffd@0 1037 .SH AUTHOR
wolffd@0 1038 Emden R. Gansner <erg@research.att.com>
wolffd@0 1039 .SH "SEE ALSO"
wolffd@0 1040 .PP
wolffd@0 1041 awk(1), gc(1), dot(1), nop(1), libexpr(3), libcgraph(3)