@@ -8,14 +8,13 @@ check the [wiki](https://github.com/moaxcp/graph-dsl/wiki).
88
99``` groovy
1010#!/usr/bin/env groovy
11- @Grab(group='com.github.moaxcp', module='graph-dsl', version='0.11 .0')
11+ @Grab(group='com.github.moaxcp', module='graph-dsl', version='0.15 .0')
1212```
1313
1414## Creating a graph
1515
16- The basic graph structure is held in a map of named vertices and a set of edges.
17-
18- All referenced vertices are created if they don't exist.
16+ The entry-point to the dsl is the ` Graph.graph(Closure) ` method. This method applies the closure to a new Graph object
17+ and returns it.
1918
2019``` groovy
2120def graph = graph {
@@ -26,44 +25,65 @@ assert graph.edges.size() == 1
2625assert graph.edges.first() == new Edge(one:'step1', two:'step2') //edge was created!
2726```
2827
29- This example of a graph creates two vertices named 'step1' and 'step2' as well as an edge between them. There are many
30- other methods for creating vertices and edges.
28+ This example of a graph creates two vertices named 'step1' and 'step2' as well as an edge between them. The basic graph
29+ structure is held in a map of named Vertex objects and a set of Edge objects. Each Edge contains the names of the two
30+ vertices it connects.
31+
32+ There are a few rules the dsl follows as it is being processed:
33+
34+ 1 . At the end of an operation all referenced vertices are created if they don't exist.
35+ 2 . If an edge or vertex already exists it will be reused by and operation.
36+
37+ This gives the developer flexibility to create and modify the graph in many different ways.
3138
3239``` groovy
33- graph.with {
40+ def workQueue = new LinkedList()
41+ graph {
3442 edge (A, B) {
35- traits Mapping, Mapping
36- queue = new LinkedList()
43+ traits Mapping, Weight
44+ queue = workQueue
3745 weight { queue.size() }
3846 }
3947
4048 vertex A(traits:Mapping) {
4149 action = {
4250 println "processing"
51+ workQueue << "work"
4352 }
4453 }
4554
4655 vertex B {
4756 traits Mapping
4857 action = {
49- println "done processing"
58+ println "done processing ${workQueue.poll()} "
5059 }
5160 }
5261}
5362```
5463
64+ In this graph the edge method creates the vertices A and B as well as an edge. It also configures the edge to have a
65+ queue and a weight that is the size of the queue. The vertices A and B are also configured to perform an action. A adds
66+ work to the queue and B processes the work.
67+
5568The Default behavior of a graph is that of an undirected graph. These graphs have a set of edges where only one edge
56- can connect any two vertices. This behavior can be changed to a directed graph at any time using the DirectedGraphPlugin
69+ can connect any two vertices. An undirected graph can be changed to a directed graph at any time using
70+ ` DirectedGraphPlugin ` .
5771
5872``` groovy
59- graph.apply DirectedGraphPlugin
73+ graph {
74+ //lots of code
75+ apply DirectedGraphPlugin
76+ //lots of code
77+ }
6078```
6179
62- Traits can be added to all edges and vertices.
80+ Traits can be added to all edges and vertices using ` edgeTraits ` and ` vertexTraits ` .
6381
6482``` groovy
65- graph.edgeTraits Mapping, Weight
66- graph.vertexTraits Mapping
83+ graph {
84+ edgeTraits Mapping, Weight
85+ vertexTraits Mapping
86+ }
6787```
6888
6989## Traversing a graph
@@ -74,23 +94,23 @@ Once a graph is created there is a dsl for depthFirstTraversal and breadthFirstT
7494graph {
7595 apply DirectedGraphPlugin
7696 vertex A {
77- edgesFirst 'B', 'D', 'E'
78- edgesSecond 'D'
97+ connectsTo 'B', 'D', 'E'
98+ connectsFrom 'D'
7999 }
80-
100+
81101 vertex D {
82- edgesFirst 'C', 'E'
83- edgesSecond 'B'
102+ connectsTo 'C', 'E'
103+ connectsFrom 'B'
84104 }
85-
105+
86106 edge B, C
87107 depthFirstTraversal {
88108 root = 'A'
89109 preorder { vertex ->
90110 println vertex.name
91111 }
92112 }
93-
113+
94114 breadthFirstTraversal {
95115 root = 'A'
96116 visit { vertex ->
@@ -100,26 +120,29 @@ graph {
100120}
101121```
102122
103- ## Functional methods
123+ ## Functional search methods
104124
105- There are functional methods build on the depthFirstTraversal and breadthFirstTraversal method.
125+ There are functional search methods build on the depthFirstTraversal and breadthFirstTraversal method. These methods
126+ follow the standard names in groovy: each, find, inject, findAll, collect. The methods can specify which type of
127+ search to perform such as ` eachBfs ` or ` eachDfs ` . When a search type is not specified the methods default to depth
128+ first search.
106129
107130``` groovy
108131eachBfs {
109132 println it.name
110133}
111-
134+
112135def vertex = findBfs {
113136 it.name == 'A'
114137}
115-
138+
116139def bfsOrder = collectBfs {
117140 it.name
118141}
119142```
120143
121- Note: These methods are not yet implemented for depth first traversal. The depth first traversal methods will be the
122- defaults for each, find, inject, findAll, and collect .
144+ Note: These methods are not yet implemented for depth first traversal. The depth first search methods will be the
145+ defaults when a search type is not specified .
123146
124147## Edge Classification
125148
@@ -130,10 +153,70 @@ Depth first traversal supports edge classification where an edge is classified a
130153* forward-edge - when the destination vertex is black
131154* cross-edge - when the destination vertex is black and in a different tree
132155
156+ To classify edges use the ` classifyEdges(Closure) ` method.
157+
158+ ```
159+ graph {
160+ //setup graph
161+ classifyEdges { from, to, edgeType ->
162+ println "$from $to is $edgeType"
163+ }
164+ }
165+ ```
166+
167+ ` classifyEdges ` returns an EdgeClassification object. This object contains lists of all back edges, tree-edges,
168+ forward edges, and cross edges. There is also a new Graph called forest that gets created.
169+ ` EdgeClassification.forrest ` contains the forrest created by tree edges. It uses the vertex and edge objects
170+ from the original graph object.
171+
172+ # Plugins
173+
174+ Plugins provide graphs with extra functionality. They can:
175+
176+ 1 . Modify all edges and vertices by adding traits or replacing them
177+ 2 . modify the factories so they create different edges and vertices
178+ 3 . perform meta-programming on the graph to change or add methods
179+
180+ ## DirectedGraphPlugin
181+
182+ The DirectedGraphPlugin changes the behavior of a graph to that of a directed graph. In a directed graph edges
183+ become directional. Only two edges can exist between any two vertices. In that case, the edges need to go in
184+ opposite directions.
185+
186+ Traversal methods will only follow out edges from a vertex.
187+
133188## EdgeWeightPlugin
134189
135190This plugin applies Weight to all edges and changes all traversal methods to follow edges in order of their weight.
136191
192+ ## EdgeMapPlugin
193+
194+ All edges and all future edges will have the Mapping triat.
195+
196+ Note: will probably be deleted in the future.
197+
198+ ## VertexMapPlugin
199+
200+ All vertices and all future vertices will have the Mapping trait.
201+
202+ Note: will probably be deleted in the future.
203+
204+ # Traits
205+
206+ Traits are standard groovy traits that developers or plugins can apply to Vertex or Edge
207+ delegates. The Vertex and Edge objects call their delegate when a method or property is
208+ missing. This allows properties and methods to be added to a Vertex or Edge at runtime.
209+
210+ ## Mapping
211+
212+ Allows a vertex or edge to act like a Map. When a property is missing in the delegate this
213+ trait will return or set the value in its map.
214+
215+ ## Weight
216+
217+ Adds a weight property to a vertex or map. The weight is set with the ` weight ` method passing
218+ in a closure. This makes the weight lazy so it can change dynamically.
219+
137220# Getting Started With Development/Contributing
138221
139222## install git
@@ -189,12 +272,17 @@ If there are any issues contact me moaxcp@gmail.com.
189272* [ groovy] ( http://www.groovy-lang.org/ )
190273* [ spock] ( http://spockframework.org/ )
191274* [ jacoco] ( http://www.eclemma.org/jacoco/ )
192- * [ sonarqube.com] ( https://sonarqube.com/dashboard?id=com.github.moaxcp%3Agraph-dsl )
193275* [ travis-ci.org] ( https://travis-ci.org/moaxcp/graph-dsl )
194276* [ oss sonatype] ( https://oss.sonatype.org/#welcome )
195277
196278# Releases
197279
280+ ## 0.16.0
281+
282+ * [ #80 ] ( https://github.com/moaxcp/graph-dsl/issues/80 ) Removed sonarqube since it no longer supports groovy
283+ * [ #78 ] ( https://github.com/moaxcp/graph-dsl/issues/78 ) Changed edgesFirst and edgesSecond in dsl to connectsTo and connectsFrom.
284+ * [ #77 ] ( https://github.com/moaxcp/graph-dsl/issues/77 ) renameOne and renameTwo in edge methods will not add extra vertex objects to the graph.
285+
198286## 0.15.0
199287
200288This release combines fixes for a few issues on github.
0 commit comments