Mercurial > hg > camir-aes2014
comparison toolboxes/graph_visualisation/share/man/man3/graph.3 @ 0:e9a9cd732c1e tip
first hg version after svn
author | wolffd |
---|---|
date | Tue, 10 Feb 2015 15:05:51 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:e9a9cd732c1e |
---|---|
1 .TH LIBGRAPH 3 "01 MARCH 1993" | |
2 .SH NAME | |
3 \fBlibgraph\fR \- abstract graph library | |
4 .SH SYNOPSIS | |
5 .ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i | |
6 .PP | |
7 .nf | |
8 \f5 | |
9 #include <graphviz/graph.h> | |
10 void aginit(); | |
11 Agraph_t *agread(FILE*); | |
12 int agwrite(Agraph_t*, FILE*); | |
13 int agerrors(); | |
14 Agraph_t *agopen(char *name, int kind); | |
15 void agclose(Agraph_t *g); | |
16 Agraph_t *agsubg(Agraph_t *g, char *name); | |
17 Agraph_t *agfindsubg(Agraph_t *g, char *name); | |
18 Agnode_t *agmetanode(Agraph_t *g); | |
19 Agraph_t *agusergraph(Agnode_t *metanode); | |
20 int agnnodes(Agraph_t *g), agnedges(Agraph_t *g); | |
21 .sp .i1 | |
22 int agcontains(Agraph_t *g, void *obj); | |
23 int aginsert(Agraph_t *g, void *obj); | |
24 int agdelete(Agraph_t *g, void *obj); | |
25 .sp .1i | |
26 Agnode_t *agnode(Agraph_t *g, char *name); | |
27 Agnode_t *agfindnode(Agraph_t *g, char *name); | |
28 Agnode_t *agfstnode(Agraph_t *g); | |
29 Agnode_t *agnxtnode(Agraph_t *g, Agnode_t *n); | |
30 Agnode_t *aglstnode(Agraph_t *g); | |
31 Agnode_t *agprvnode(Agraph_t *g, Agnode_t *n); | |
32 .sp .1i | |
33 Agedge_t *agedge(Agraph_t *g, Agnode_t *tail, Agnode_t *head); | |
34 Agedge_t *agfindedge(Agraph_t *g, Agnode_t *tail, Agnode_t *head); | |
35 Agedge_t *agfstedge(Agraph_t *g, Agnode_t *n); | |
36 Agedge_t *agnxtedge(Agraph_t *g, Agedge_t *e, Agnode_t *n); | |
37 Agedge_t *agfstin(Agraph_t *g, Agnode_t *n); | |
38 Agedge_t *agnxtin(Agraph_t *g, Agedge_t *e); | |
39 Agedge_t *agfstout(Agraph_t *g, Agnode_t *n); | |
40 Agedge_t *agnxtout(Agraph_t *g, Agedge_t *e); | |
41 .sp .1i | |
42 char *agget(void *obj, char *name); | |
43 char *agxget(void *obj, int index); | |
44 void agset(void *obj, char *name, char *value); | |
45 void agxset(void *obj, int index, char *value); | |
46 int agindex(void *obj, char *name); | |
47 .sp .1i | |
48 Agsym_t* agraphattr(Agraph_t *g,char *name,char *value); | |
49 Agsym_t* agnodeattr(Agraph_t *g,char *name,char *value); | |
50 Agsym_t* agedgeattr(Agraph_t *g,char *name,char *value); | |
51 Agsym_t* agfindattr(void *obj,char *name); | |
52 \fP | |
53 .fi | |
54 .SH DESCRIPTION | |
55 \fIlibgraph\fP maintains directed and undirected attributed graphs | |
56 in memory and reads and writes graph files. Graphs are composed of | |
57 nodes, edges, and nested subgraphs. A subgraph may contain any | |
58 nodes and edges of its parents, and may be passed to any | |
59 \fIlibgraph\fP function taking a graph pointer, except the three | |
60 that create new attributes (where a main graph is required). | |
61 | |
62 Attributes are internal or external. | |
63 Internal attributes are fields in the graph, node and edge structs | |
64 defined at compile time. | |
65 These allow efficient representation and direct access to values | |
66 such as marks, weights, and pointers for writing graph algorithms. | |
67 External attributes, on the other hand, are character strings | |
68 (name\(hyvalue pairs) dynamically allocated at runtime and accessed | |
69 through \fIlibgraph\fP calls. External attributes are used in | |
70 graph file I/O; internal attributes are not. Conversion between | |
71 internal and external attributes must be explicitly programmed. | |
72 | |
73 The subgraphs in a main graph are represented by an auxiliary directed | |
74 graph (a meta\(hygraph). Meta\(hynodes correspond to subgraphs, and meta\(hyedges | |
75 signify containment of one subgraph in another. | |
76 \f5agmetanode\fP and \f5agusergraph\fP map between | |
77 subgraphs and meta\(hynodes. The nodes and edges of the meta\(hygraph may | |
78 be traversed by the usual \fIlibgraph\fP functions for this purpose. | |
79 | |
80 .SH USE | |
81 1. Define types \f5Agraphinfo_t\fP, \f5Agnodeinfo_t\fP, | |
82 and \f5Agedgeinfo_t\fP (usually in a header file) before | |
83 including \f5<graphviz/graph.h>\fP. | |
84 | |
85 2. Call \f5aginit()\fP before any other \fIlibgraph\fP functions. | |
86 (This is a macro that calls \f5aginitlib()\fP to define the sizes | |
87 of Agraphinfo_t, Agnodeinfo_t, and Agedgeinfo_t.) | |
88 | |
89 3. Compile with \-lgraph \-lcdt. | |
90 | |
91 Except for the \fBu\fP fields, \fIlibgraph\fP | |
92 data structures must be considered read\(hyonly. | |
93 Corrupting their contents by direct updates can cause | |
94 catastrophic errors. | |
95 | |
96 .SH "GRAPHS" | |
97 .nf | |
98 \f5 | |
99 typedef struct Agraph_t { | |
100 char kind; | |
101 char *name; | |
102 Agraph_t *root; | |
103 char **attr; | |
104 graphdata_t *univ; | |
105 Dict_t *nodes,*inedges,*outedges; | |
106 proto_t *proto; | |
107 Agraphinfo_t u; | |
108 } Agraph_t; | |
109 | |
110 typedef struct graphdata_t { | |
111 Dict_t *node_dict; | |
112 attrdict_t *nodeattr, *edgeattr, *globattr; | |
113 } graphdata_t; | |
114 | |
115 typedef struct proto_t { | |
116 Agnode_t *n; | |
117 Agedge_t *e; | |
118 proto_t *prev; | |
119 } proto_t; | |
120 \fP | |
121 .fi | |
122 A graph \fIkind\fP is one of: | |
123 AGRAPH, AGRAPHSTRICT, AGDIGRAPH, or AGDIGRAPHSTRICT. | |
124 There are related macros for testing the properties of a graph: | |
125 AG_IS_DIRECTED(g) and AG_IS_STRICT(g). | |
126 Strict graphs cannot have self\(hyarcs or multi\(hyedges. | |
127 \fBattr\fP is the array of external attribute values. | |
128 \fBuniv\fP points to values shared by all subgraphs of a main graph. | |
129 \fBnodes\fP, \fBinedges\fP, and \fBoutedges\fP are sets maintained | |
130 by \fBcdt(3)\fP. Normally you don't access these dictionaries | |
131 directly, though the edge dictionaries may be re\(hyordered to support | |
132 programmer\(hydefined ordered edges (see \f5dtreorder\fP in \fIcdt(3)\fP). | |
133 \fBproto\fP is a stack of templates for node and edge initialization. | |
134 The attributes of these nodes and edges are set in the usual way (\f5agget\fP, | |
135 \f5agset\fP, etc.) to set defaults. | |
136 .PP | |
137 \f5agread\fP reads a file and returns a new graph if one | |
138 was succesfully parsed, otherwise returns NULL if | |
139 \f5EOF\fP or a syntax error was encountered. | |
140 Errors are reported on stderr and a count is returned from | |
141 \g5agerrors()\fP. | |
142 \f5write_graph\fP prints a graph on a file. | |
143 \f5agopen\fP and \f5agsubg\fP create new empty graph and subgraphs. | |
144 \f5agfindsubg\fP searches for a subgraph by name, returning NULL | |
145 when the search fails. | |
146 | |
147 .SH ALL OBJECTS | |
148 \f5agcontains\fP, \f5aginsert\fP, \f5agdelete\fP are generic functions | |
149 for nodes, edges, and graphs. \f5gcontains\fP is a predicate that tests | |
150 if an object belongs to the given graph. \f5aginsert\fP inserts an | |
151 object in a graph and \f5agdelete\fP undoes this operation. | |
152 A node or edge is destroyed (and its storage freed) at the time it | |
153 is deleted from the main graph. Likewise a subgraph is destroyed | |
154 when it is deleted from its last parent or when its last parent is deleted. | |
155 | |
156 .SH NODES | |
157 .nf | |
158 \f5 | |
159 typedef struct Agnode_t { | |
160 char *name; | |
161 Agraph_t *graph; | |
162 char **attr; | |
163 Agnodeinfo_t u; | |
164 } Agnode_t; | |
165 \fP | |
166 .fi | |
167 | |
168 \f5agnode\fP attempts to create a node. | |
169 If one with the requested name already exists, the old node | |
170 is returned unmodified. | |
171 Otherwise a new node is created, with attributed copied from g\->proto\->n. | |
172 \f5agfstnode\fP (\f5agnxtnode\fP) return the first (next) element | |
173 in the node set of a graph, respectively, or NULL. | |
174 \f5aglstnode\fP (\f5agprvnode\fP) return the last (previous) element | |
175 in the node set of a graph, respectively, or NULL. | |
176 | |
177 .SH EDGES | |
178 .nf | |
179 \f5 | |
180 typedef struct Agedge_t { | |
181 Agnode_t *head,*tail; | |
182 char **attr; | |
183 Agedgeinfo_t u; | |
184 } Agedge_t; | |
185 \fP | |
186 .fi | |
187 \f5agedge\fP creates a new edge with the attributes of g\->proto\->e | |
188 including its key if not empty. | |
189 \f5agfindedge\fP finds the first (u,v) edge in \f5g\fP. | |
190 \f5agfstedge\fP (\f5agnxtedge\fP) return the first (next) element | |
191 in the edge set of a graph, respectively, or NULL. | |
192 \f5agfstin\fP, \f5agnxtin\fP, \f5agfstout\fP, \f5agnxtout\fP | |
193 refer to in\(hy or out\(hyedge sets. | |
194 The idiomatic usage in a directed graph is: | |
195 .sp | |
196 \f5 for (e = agfstout(g,n); e; e = agnextout(g,e)) your_fun(e);\fP | |
197 .P | |
198 An edge is uniquely identified by its endpoints and its \f5key\fP | |
199 attribute (if there are multiple edges). | |
200 If the \f5key\fP of \f5g\->proto\->e\fP is empty, | |
201 new edges are assigned an internal value. | |
202 Edges also have \f5tailport\fP and \f5headport\fP values. | |
203 These have special syntax in the graph file language but are | |
204 not otherwise interpreted. | |
205 .PP | |
206 .SH ATTRIBUTES | |
207 .nf | |
208 \f5 | |
209 typedef struct attrsym_t { | |
210 char *name,*value; | |
211 int index; | |
212 unsigned char printed; | |
213 } attrsym_t; | |
214 .bp | |
215 typedef struct attrdict_t { | |
216 char *name; | |
217 Dict_t *dict; | |
218 attrsym_t **list; | |
219 } attrdict_t; | |
220 \fP | |
221 .fi | |
222 \f5agraphattr\fP, \f5agnodeattr\fP, and \f5agedgeattr\fP make new attributes. | |
223 \f5g\fP should be a main graph, or \f5NULL\fP for declarations | |
224 applying to all graphs subsequently read or created. | |
225 \f5agfindattr\fP searches for an existing attribute. | |
226 .PP | |
227 External attributes are accessed by \f5agget\fP and \f5agset\fP | |
228 These take a pointer to any graph, node, or edge, and an attribute name. | |
229 Also, each attribute has an integer index. For efficiency this index | |
230 may be passed instead of the name, by calling \f5agxget\fP and \f5agxset\fP. | |
231 The \f5printed\fP flag of an attribute may be set to 0 to skip it | |
232 when writing a graph file. | |
233 .PP | |
234 The \f5list\fP in an attribute dictionary is maintained in order of creation | |
235 and is NULL terminated. | |
236 Here is a program fragment to print node attribute names: | |
237 .nf | |
238 \f5attrsym_t *aptr; | |
239 for (i = 0; aptr = g\->univ\->nodedict\->list[i]; i++) puts(aptr\->name);\fP | |
240 .fi | |
241 .SH EXAMPLE GRAPH FILES | |
242 .nf | |
243 graph any_name { /* an undirected graph */ | |
244 a \-\- b; /* a simple edge */ | |
245 a \-\- x1 \-\- x2 \-\- x3; /* a chain of edges */ | |
246 "x3.a!" \-\- a; /* quotes protect special characters */ | |
247 b \-\- {q r s t}; /* edges that fan out */ | |
248 b [color="red",size=".5,.5"]; /* set various node attributes */ | |
249 node [color=blue]; /* set default attributes */ | |
250 b \-\- c [weight=25]; /* set edge attributes */ | |
251 subgraph sink_nodes {a b c}; /* make a subgraph */ | |
252 } | |
253 | |
254 digraph G { | |
255 size="8.5,11"; /* sets a graph attribute */ | |
256 a \-> b; /* makes a directed edge */ | |
257 chip12.pin1 \-> chip28.pin3; /* uses named node "ports" */ | |
258 } | |
259 .fi | |
260 | |
261 .SH SEE ALSO | |
262 .BR dot (1), | |
263 .BR neato (1), | |
264 .BR libdict (3) | |
265 .br | |
266 S. C. North and K. P. Vo, "Dictionary and Graph Libraries'' | |
267 1993 Winter USENIX Conference Proceedings, pp. 1\(hy11. | |
268 | |
269 .SH AUTHOR | |
270 Stephen North (north@ulysses.att.com), AT&T Bell Laboratories. |