rbgraph 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 79cc2737a16f085557a84112f66bf9b0f8478254
-  data.tar.gz: 966a3c89e50ce68437217197c00ba20c39f0a3be
+  metadata.gz: 8284a63b040d1fb014f4ca839ef4e66ca3d8fc19
+  data.tar.gz: b31b8d5cd254f6b9d46320c05bea0ebfa3b13369
 SHA512:
-  metadata.gz: 03c0337048a02c661405d874cd03a2bf8b46f154874a3df2a65d977c14451298e976254d5ef3a29bf822fa2c48765438ba899278d2a57f84be0369e8f34133c1
-  data.tar.gz: 249567dfd34825a58dd5733b7dbfc0d38649d4fc262b73bf1f3b5207e57992af312dace4c70dcfc2dd66326d86f7911309519240a1ebf0124dd48ee62e662fab
+  metadata.gz: 94efb880fb5e11ab8efa02e5df9da6f13cf8daca8f4ccbd4d452e8aa48731b6f699944f131c22a19f1ff5cc7230a062050bbbdc11af3d7111a32f160af50d207
+  data.tar.gz: cd62f60bb91d2bc65421653c8abea219b5e3298ec28d200e41f214edcea4018c51b7c7e5fa0491a7bb0d39d1c0c6160be6e19e08870039b66dc35a6aa0479ffd

data/README.md

@@ -11,7 +11,107 @@ or add it to your Gemfile
 
 ```gem 'rbgraph'```
 
-## Example
+## Basic objects
+
+####*Graph*:
+Graphs can be undirected or directed.
+```ruby
+graph = Rbgraph::UndirectedGraph.new
+graph = Rbgraph::DirectedGraph.new
+```
+Use ```graph.directed?``` to figure out if a graph is directed or not.
+The graph object has the ```nodes``` and ```edges``` properties which are ruby hashes, the keys being the ids of each object respectively.
+
+####*Nodes*:
+Every node should have an already set ```id``` property upon initialization.
+Nodes also carry data, in the data attribute which is a ruby hash.
+Usually you will not need initialize a node directly, but rather just add one with the desired properties in the graph.
+```ruby
+graph = Rbgraph::UndirectedGraph.new
+# graph.add_node!(node_id, node_data, &block)
+# Add a node with id = 5 and attached data t = [0, 4, 19].
+node = graph.add_node!(5, {t: [0, 4, 19]})
+```
+By default if a node with the same id already exists, then ```add_node!``` does nothing unless given a block.
+```ruby
+# Add another node with id = 5 and attached data t = [1, 5, 20].
+node = graph.add_node!(5, {t: [1, 5, 20]}) # does nothing
+node = graph.add_node!(5, {t: [1, 5, 20]}) do |graph, existing_node, new_node_data|
+  existing_node.data[:t] += new_node_data[:t]
+end
+node.data[:t] # => [0, 4, 19, 1, 5, 20]
+graph.nodes[5].data[:t] # => [0, 4, 19, 1, 5, 20]
+```
+Nodes have the following properties:
+* id
+* data
+* neighbors (respects directional/undirectional)
+* edges (will contain both incoming and outgoing edges)
+* graph
+
+and the following methods:
+
+* out_degree
+* outgoing_edges
+* in_degree
+* incoming_edges
+* parent (works only in directed graph - return the node that has only one edge towards this one if any)
+* ancestors (works only in directed graph - returns the list of parents for this node up to the root if the graph is not cyclic)
+* root (works only in directed graph - return the root of this node if the graph is not cyclic)
+
+
+####*Edges*:
+Edges connect nodes with either a one-way (directional graph) or two-way (undirectional graph) link.
+Edges have an internally computed id, which is a string representation of the ids of the nodes they connect.
+Each node can also have a ```weight``` attribute, and a ```kind``` attribute, as well as carry additional data as a ruby hash in its ```data``` attribute.
+Again you do not want to instantiate edges directly, rather you would just add them to the graph.
+```ruby
+graph = Rbgraph::UndirectedGraph.new
+# graph.add_edge!(node1, node2, weight = 1, kind = nil, edge_data = {}, &block)
+# Add an edge connecting nodes with id 2 and 3
+edge1 = graph.add_edge!({id: 2}, {id: 3})
+edge1.weight # => 1
+# Add an edge connecting nodes with id 1 and 4, weight = 3, kind = "friendship" and data = {created_at: <some_date>}
+edge2 = graph.add_edge!({id: 1}, {id: 4}, 3, "friendship", {created_at: <some_date>})
+edge1.weight # => 3
+```
+You can add an edge even if the nodes that will be connected do not yet exist in the graph.
+They will be added automatically when you call ```add_edge!```.
+When adding an edge that already exists, i.e. connects the same nodes and is of the same kind, then the existing edge increases its weight by the amount present in the new edge, unless you specify a block to provide custom behavior.
+```ruby
+edge1 = graph.add_edge!({id: 2}, {id: 3})
+edge1.weight # => 2
+edge1 = graph.add_edge!({id: 2}, {id: 3}, 0)
+edge1.weight # => 2
+edge1 = graph.add_edge!({id: 2}, {id: 3}, 1, nil, {some: :data}) do |graph, existing_edge, new_edge|
+  existing_edge.data.merge!(new_edge.data)
+end
+edge1.weight # => 2 (weight doesn't change when you provide a block it is your responsibility to increase it if you want)
+edge1.data # => {some: :data}
+
+edge3 = graph.add_edge!({id: 2}, {id: 3}, 1, "something")
+edge3.id != edge1.id # => true
+```
+
+Edges have the following properties:
+* id
+* data
+* node1
+* node2
+* weight
+* kind
+* graph
+
+and the following methods:
+
+* has_node?(some_node)
+* other_node(some_node)
+* different_node(some_node)
+* out_for?(some_node)
+* in_for?(some_node)
+
+
+## Examples
 
 ```ruby
 graph = Rbgraph::UndirectedGraph.new()
@@ -103,5 +203,26 @@ t = Rbgraph::Traverser::BfsTraverser.new(graph)
 c = t.connected_components(respect_direction: false)
 ```
 
+Version 0.5.0+
+
+You can now request a path between two nodes in the graph.
+```ruby
+graph = Rbgraph::UndirectedGraph.new()
+... # add nodes and edges
+t = Rbgraph::Traverser::BfsTraverser.new(graph)
+a = graph.nodes[1]
+b = graph.nodes[2]
+path = t.bfs_between_a_and_b(a, b)
+```
+or you can use a directed graph and choose to respect the direction of the edges while search for a path between a and b or not.
+```ruby
+graph = Rbgraph::DirectedGraph.new()
+... # add nodes and edges
+t = Rbgraph::Traverser::BfsTraverser.new(graph)
+a = graph.nodes[1]
+b = graph.nodes[2]
+path = t.bfs_between_a_and_b(a, b, respect_direction: false)
+```
+
 ### Disclaimer
 This project is written on a need to use basis for inclusion to other projects I'm working on for now, so completion is not an immediate goal.

data/lib/rbgraph/traverser/bfs_traverser.rb

@@ -4,52 +4,99 @@ module Rbgraph
     class BfsTraverser
 
       attr_accessor :graph
-      attr_accessor :connected_subgraphs
-      attr_accessor :visited_nodes
-      attr_accessor :unvisited_nodes
-      attr_accessor :queue
 
       def initialize(graph)
         self.graph = graph
-        self.connected_subgraphs = []
-        self.unvisited_nodes = Set.new [*graph.nodes.values]
       end
 
       def connected_components(options = {})
-        self.visited_nodes = Set.new
-        self.queue = Queue.new
+        @connected_subgraphs = []
+        @unvisited_nodes = Set.new [*graph.nodes.values]
+        @visited_nodes = Set.new
+        @queue = Queue.new
 
-        while !unvisited_nodes.empty? do
-          root = unvisited_nodes.to_a.first
-          unvisited_nodes.delete(unvisited_nodes.to_a.first)
-          self.connected_subgraphs << bfs_from_root(root, options)
+        while !@unvisited_nodes.empty? do
+          root = @unvisited_nodes.to_a.first
+          @unvisited_nodes.delete(@unvisited_nodes.to_a.first)
+          @connected_subgraphs << bfs_from_root(root, options.merge(sticky: true))
         end
-        connected_subgraphs
+        @connected_subgraphs
       end
 
       def bfs_from_root(root, options = {})
+        if !options[:sticky]
+          @unvisited_nodes = Set.new [*graph.nodes.values]
+          @visited_nodes = Set.new
+          @queue = Queue.new
+        end
+
+        clear_backtracking_info
+
         subgraph = graph.class.new
-        visited_nodes.add(root)
-        queue.enq(root)
-        while !queue.empty? do
-          t = queue.deq
-          unvisited_nodes.delete(t)
-          yield(t) if block_given? # do sth on current node
+        @visited_nodes.add(root)
+        @queue.enq(root)
+        while !@queue.empty? do
+          t = @queue.deq
+          @unvisited_nodes.delete(t)
+          yield_value = yield(t) if block_given? # do sth on current node
+          break if yield_value == :break
           subgraph.nodes[t.id] ||= t
           t.edges.each do |eid, edge|
             next if graph.directed? && !edge.out_for?(t) unless options[:respect_direction] == false
             neighbor = edge.other_node(t)
             subgraph.edges[eid] ||= edge
             subgraph.nodes[neighbor.id] ||= neighbor
-            if !visited_nodes.include?(neighbor)
-              visited_nodes.add(neighbor)
-              queue.enq(neighbor)
+            if !@visited_nodes.include?(neighbor)
+              @visited_nodes.add(neighbor)
+              @queue.enq(neighbor)
+              neighbor.data[:__bfs_prev_node] ||= t
+              @__bfs_prev_node_dirty = true
             end
           end
         end
         subgraph
       end
 
+      def bfs_between_a_and_b(a, b, options = {})
+        if graph.nodes[a.id].nil? || graph.nodes[b.id].nil?
+          return nil
+        end
+
+        if a.id == b.id # a is the same as b
+          return [a]
+        end
+
+        if !a.neighbors[b.id].nil? # a and b are just one step away
+          return [a, b]
+        end
+
+        bfs_from_root(a, options) do |current_node|
+          :break if current_node.id == b.id # destination node found! return ':break' in the block to stop traversing!
+        end
+
+        if b.data[:__bfs_prev_node].nil?
+          return [] # no path found
+        end
+
+        path = [b]
+
+        while path[-1].id != a.id do
+          path << path[-1].data[:__bfs_prev_node]
+        end
+
+        path.reverse
+      end
+
+      private
+
+      def clear_backtracking_info
+        if @__bfs_prev_node_dirty
+          graph.nodes.each do |node_id, node|
+            node.data[:__bfs_prev_node] = nil
+          end
+        end
+      end
+
     end
 
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rbgraph
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - George Lamprianidis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-14 00:00:00.000000000 Z
+date: 2018-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -86,7 +86,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.14
 signing_key: 
 specification_version: 4
 summary: Ruby graphs!