1 | [[tags:egg]] |
---|
2 | |
---|
3 | == digraph |
---|
4 | |
---|
5 | Directed graph in adjacency list format. |
---|
6 | |
---|
7 | [[toc:]] |
---|
8 | |
---|
9 | == Usage |
---|
10 | |
---|
11 | (require-extension digraph) |
---|
12 | |
---|
13 | == Documentation |
---|
14 | |
---|
15 | |
---|
16 | The {{digraph}} library is an implementation of a directed graph, where |
---|
17 | the edges are stored as adjacency lists indexed by node number. |
---|
18 | |
---|
19 | The library defines a digraph "object" -- a procedure that takes a |
---|
20 | method name as a symbol, and returns the procedure that implements the |
---|
21 | respective operation. |
---|
22 | |
---|
23 | === Directed graph procedures |
---|
24 | |
---|
25 | |
---|
26 | The digraph object is created by procedure {{make-digraph}}, which is the only user-visible procedure defined in this egg: |
---|
27 | |
---|
28 | <procedure>make-digraph:: NAME INFO [NODE-LIST [SUCC-LIST [PRED-LIST]]] -> SELECTOR</procedure> |
---|
29 | |
---|
30 | where: |
---|
31 | |
---|
32 | * {{NAME}} is the graph name (string or symbol) |
---|
33 | * {{INFO}} is an optional metadata object of an arbitrary type or {{#f}} |
---|
34 | * {{NODE-LIST}} is an optional list of nodes to be inserted in the graph; each element of the list must be of the form {{(N INFO)}} where {{N}} is a unique node number (integer), and {{INFO}} is an optional metadata object describing the node. |
---|
35 | * {{SUCC-LIST}} and {{PRED-LIST}} can be used to define the graph edges upon graph creation. If supplied, these arguments must be lists in which every element is of the form {{(I J INFO)}}, where {{I}} and {{J}} are node numbers, and {{INFO}} is an optional metadata object. |
---|
36 | |
---|
37 | |
---|
38 | The returned selector procedure can take one of the following arguments: |
---|
39 | |
---|
40 | ; {{'name}} : returns the graph name (string or symbol) |
---|
41 | ; {{'info}} : returns the graph metadata (arbitrary type) |
---|
42 | ; {{'new-id!}} : returns a procedure with no arguments, which returns the lowest available node number |
---|
43 | ; {{'add-node!}} : returns a procedure {{LAMBDA N INFO}} which inserts in the graph node with number {{N}} and metadata {{INFO}}; if the node already exists in the graph, it will be overwritten with the new metadata |
---|
44 | ; {{'add-edge!}} : returns a procedure {{LAMBDA EDGE}} which inserts in the graph the specifed edge; the edge is given by a list of the form {{(I J INFO)}}, where {{I}} and {{J}} are source and destination nodes, respectively, and {{INFO}} is edge metadata of arbitrary type |
---|
45 | ; {{'remove-node!}} : returns a procedure {{LAMBDA N}} which removes node {{N}} and all its edges from the graph |
---|
46 | ; {{'nodes}} : returns a procedure with no arguments, which returns a list with the nodes of the graph and their metadata |
---|
47 | ; {{'edges}} : returns a procedure with no arguments, which returns a list with the edges of the graph and their metadata |
---|
48 | ; {{'roots}} : returns a procedure with no arguments, which returns a list with all nodes in the graph that do not have an predecessor |
---|
49 | ; {{'terminals}} : returns a procedure with no arguments, which returns a list with all nodes in the graph that do not have a successor |
---|
50 | ; {{'order}} : returns a procedure with no arguments, which returns the number of nodes in the graph |
---|
51 | ; {{'size}} : returns a procedure with no arguments, which returns the number of edges in the graph |
---|
52 | ; {{'capacity}} : returns a procedure with no arguments, which returns the size of the underlying dynamic vector |
---|
53 | ; {{'succ}} : returns a procedure {{LAMBDA N}} which returns a list with the successor nodes of node {{N}} |
---|
54 | ; {{'pred}} : returns a procedure {{LAMBDA N}} which returns a list with the predecessor nodes of node {{N}} |
---|
55 | ; {{'succ-list}} : returns a procedure with no arguments which returns a list containing the successor nodes for each node. |
---|
56 | ; {{'pred-list}} : returns a procedure with no arguments which returns a list containing the predecessor nodes for each node. |
---|
57 | ; {{'out-edges}} : returns a procedure {{LAMBDA N}} which returns a list with the outgoing edges of node {{N}} |
---|
58 | ; {{'in-edges}} : returns a procedure {{LAMBDA N}} which returns a list with the incoming edges of node {{N}} |
---|
59 | ; {{'has-edge}} : returns a procedure {{LAMBDA I J}} which returns true if edge {{I -> J}} exists in the graph and false otherwise |
---|
60 | ; {{'has-node}} : returns a procedure {{LAMBDA N}} which returns true if node {{N}} exists in the graph and false otherwise |
---|
61 | ; {{'node-info}} : returns a procedure {{LAMBDA N}} which returns the metadata for node {{N}} |
---|
62 | ; {{'node-info-set!}} : returns a procedure {{LAMBDA N V}} which sets the metadata for node {{N}} |
---|
63 | ; {{'foreach-node}} : returns an iterator procedure {{LAMBDA F}} which iterates over the nodes in the graph by invoking function {{F}} on the node number and metadata of each node |
---|
64 | ; {{'foreach-edge}} : returns an iterator procedure {{LAMBDA F}} which iterates over the edges in the graph by invoking function {{F}} on each edge |
---|
65 | ; {{'debug}} : returns a list with the internal representation of the graph |
---|
66 | |
---|
67 | |
---|
68 | |
---|
69 | == Examples |
---|
70 | |
---|
71 | |
---|
72 | ;; example adapted from graph example in the Boost library documentation |
---|
73 | (require-extension srfi-1) |
---|
74 | (require-extension digraph) |
---|
75 | (define g (make-digraph 'depgraph "dependency graph")) |
---|
76 | |
---|
77 | (define used-by |
---|
78 | (list |
---|
79 | (cons 'dax_h 'foo_cpp) (cons 'dax_h 'bar_cpp) (cons 'dax_h 'yow_h) |
---|
80 | (cons 'yow_h 'bar_cpp) (cons 'yow_h 'zag_cpp) (cons 'boz_h 'bar_cpp) |
---|
81 | (cons 'boz_h 'zig_cpp) (cons 'boz_h 'zag_cpp) (cons 'zow_h 'foo_cpp) |
---|
82 | (cons 'foo_cpp 'foo_o) (cons 'foo_o 'libfoobar_a) |
---|
83 | (cons 'bar_cpp 'bar_o) (cons 'bar_o 'libfoobar_a) |
---|
84 | (cons 'libfoobar_a 'libzigzag_a) (cons 'zig_cpp 'zig_o) |
---|
85 | (cons 'zig_o 'libzigzag_a) (cons 'zag_cpp 'zag_o) |
---|
86 | (cons 'zag_o 'libzigzag_a) (cons 'libzigzag_a 'killerapp))) |
---|
87 | |
---|
88 | |
---|
89 | (define node-list (delete-duplicates |
---|
90 | (concatenate (list (map car used-by) (map cdr used-by))))) |
---|
91 | |
---|
92 | (define node-ids (list-tabulate (length node-list) values)) |
---|
93 | |
---|
94 | (for-each (lambda (i n) ((g 'add-node!) i n)) node-ids node-list) |
---|
95 | (define node-map (zip node-list node-ids)) |
---|
96 | |
---|
97 | (for-each (lambda (e) |
---|
98 | (match e ((ni . nj) (let ((i (car (alist-ref ni node-map))) |
---|
99 | (j (car (alist-ref nj node-map)))) |
---|
100 | ((g 'add-edge!) (list i j (format "~A->~A" ni nj))))) |
---|
101 | (else (error "invalid edge " e)))) |
---|
102 | used-by) |
---|
103 | (print ((g 'nodes))) |
---|
104 | (print ((g 'edges))) |
---|
105 | |
---|
106 | ((g 'remove-node!) 0) |
---|
107 | (print ((g 'nodes))) |
---|
108 | (print ((g 'edges))) |
---|
109 | |
---|
110 | == About this egg |
---|
111 | |
---|
112 | |
---|
113 | === Author |
---|
114 | |
---|
115 | [[/users/ivan-raikov|Ivan Raikov]] |
---|
116 | |
---|
117 | === Version history |
---|
118 | |
---|
119 | ; 1.16 : Added terminals message to digraph object |
---|
120 | ; 1.15 : Ensure unit test script return proper exit code |
---|
121 | ; 1.13 : Added test as a test dependency |
---|
122 | ; 1.12 : Converted documentation to wiki format |
---|
123 | ; 1.11 : Ported to Chicken 4 |
---|
124 | ; 1.10 : Now using matchable extension |
---|
125 | ; 1.9 : Added procedures pred-list and succ-list |
---|
126 | ; 1.8 : Added procedure node-info-set! |
---|
127 | ; 1.7 : Build script updated for better cross-platform compatibility |
---|
128 | ; 1.6 : Test infrastructure changed to use testbase |
---|
129 | ; 1.5 : Bug fixes in set-out-edges! and set-in-edges! [thanks to Andreas Scholta] |
---|
130 | ; 1.4 : License upgrade to GPL v3 |
---|
131 | ; 1.3 : Updated the roots procedure to match the documentation |
---|
132 | ; 1.2 : Minor changes to the setup script |
---|
133 | ; 1.1 : Added support for chicken-setup -test |
---|
134 | ; 1.0 : Initial release |
---|
135 | |
---|
136 | |
---|
137 | === License |
---|
138 | |
---|
139 | Copyright 2007-2012 Ivan Raikov and the Okinawa Institute of Science and Technology |
---|
140 | |
---|
141 | This program is free software: you can redistribute it and/or modify |
---|
142 | it under the terms of the GNU General Public License as published by |
---|
143 | the Free Software Foundation, either version 3 of the License, or (at |
---|
144 | your option) any later version. |
---|
145 | |
---|
146 | This program is distributed in the hope that it will be useful, but |
---|
147 | WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
148 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
---|
149 | General Public License for more details. |
---|
150 | |
---|
151 | A full copy of the GPL license can be found at |
---|
152 | <http://www.gnu.org/licenses/>. |
---|
153 | |
---|