rgl 0.4.0 → 0.5.0

data/lib/rgl/enumerable_ext.rb

@@ -1,13 +1,16 @@
 module Enumerable
+
   # Fixnum()
   #
   # Return the number of elements of the Enumerable. Same as _size_ but not all
   # Enumerables implement size.
   #--
   # Should we call the methods _size_?
+  #
   def length
-    inject(0) do |sum,v|
+    inject(0) do |sum, v|
       sum + 1
     end
   end
+
 end

data/lib/rgl/graph_iterator.rb

@@ -0,0 +1,15 @@
+require 'stream'
+
+require 'rgl/graph_wrapper'
+
+module RGL
+
+  # A GraphIterator is the abstract basis for all Iterators on graphs.
+  # Each graph iterator should implement the protocol defined in module Stream.
+  #
+  module GraphIterator
+    include Stream
+    include GraphWrapper
+  end
+
+end # RGL

data/lib/rgl/graph_visitor.rb

@@ -0,0 +1,138 @@
+require 'rgl/graph_wrapper'
+
+module RGL
+
+  # Module GraphVisitor defines the BGL
+  # BFS[http://www.boost.org/libs/graph/doc/BFSVisitor.html] Visitor Concept).
+  #
+  # Visitors provide a mechanism for extending an algorithm (i.e., for
+  # customizing what is done at each step of the algorithm). They allow users
+  # to insert their own operations at various steps within a graph algorithm.
+  #
+  # Graph algorithms typically have multiple event points where one may want to
+  # insert a call-back. Therefore, visitors have several methods that
+  # correspond to the various event points. Each algorithm has a different
+  # set of event points. The following are common to both DFS and BFS search.
+  #
+  #  * examine_vertex
+  #  * examine_edge
+  #  * tree_edge
+  #  * back_edge
+  #  * forward_edge
+  #  * finish_vertex
+  #
+  # These methods are all called handle_* and can be set to appropriate blocks,
+  # using the methods set_*_event_handler, which are defined for each event
+  # mentioned above.
+  #
+  # As an alternative, you can also override the handle_* methods in a
+  # subclass, to configure the algorithm (as an example, see TarjanSccVisitor).
+  #
+  # During a graph traversal, vertices are *colored* using the colors :GRAY
+  # (when waiting) and :BLACK when finished. All other vertices are :WHITE.
+  # The color_map is also maintained in the visitor.
+  #
+  module GraphVisitor
+
+    include GraphWrapper
+
+    attr_reader :color_map
+
+    # Create a new GraphVisitor on _graph_.
+    #
+    def initialize(graph)
+      super(graph)
+      reset
+    end
+
+    # Mark each vertex unvisited (i.e. :WHITE)
+    #
+    def reset
+      @color_map = Hash.new(:WHITE)
+    end
+
+    # Returns true if vertex _v_ is colored :BLACK (i.e. finished).
+    #
+    def finished_vertex?(v)
+      @color_map[v] == :BLACK
+    end
+
+    # Shall we follow the edge (u,v); i.e. v has color :WHITE
+    #
+    def follow_edge?(u, v) # :nodoc:
+      @color_map[v] == :WHITE
+    end
+
+    # Attach a map to the visitor which records the distance of a visited
+    # vertex to the start vertex.
+    #
+    # This is similar to BGLs
+    # distance_recorder[http://www.boost.org/libs/graph/doc/distance_recorder.html].
+    #
+    # After the distance_map is attached, the visitor has a new method
+    # distance_to_root, which answers the distance to the start vertex.
+    #
+    def attach_distance_map(map = Hash.new(0))
+      @distance_map = map
+
+      # add distance map support to the current visitor instance
+      extend(DistanceMapSupport)
+    end
+
+    module DistanceMapSupport
+
+      def handle_tree_edge(u, v)
+        super
+        @distance_map[v] = @distance_map[u] + 1
+      end
+
+      # Answer the distance to the start vertex.
+
+      def distance_to_root(v)
+        @distance_map[v]
+      end
+
+    end # module DistanceMapSupport
+
+    module ClassMethods
+
+      # Defines an event handler.
+      #
+      def def_event_handlers(*events)
+        events.each do |event|
+          params = event.to_s.include?('edge') ? 'u, v' : 'u'
+
+          handler = "@#{event}_event_handler"
+
+          class_eval <<-END
+            def handle_#{event}(#{params})
+              #{handler}.call(#{params}) if defined? #{handler}
+            end
+
+            def set_#{event}_event_handler(&block)
+              #{handler} = block
+            end
+          END
+        end
+      end
+
+      alias def_event_handler def_event_handlers
+
+    end # module ClassMethods
+
+    extend ClassMethods # add class methods to GraphVisitor class itself
+
+    def self.included(base)
+      base.extend ClassMethods # when GraphVisitor is included into a class/module, add class methods as well
+    end
+
+    def_event_handlers :examine_vertex,
+                       :examine_edge,
+                       :tree_edge,
+                       :back_edge,
+                       :forward_edge,
+                       :finish_vertex
+
+  end # module GraphVisitor
+
+end # module RGL

data/lib/rgl/graph_wrapper.rb

@@ -0,0 +1,15 @@
+module RGL
+
+  module GraphWrapper # :nodoc:
+
+    attr_accessor :graph
+
+    # Creates a new GraphWrapper on _graph_.
+    #
+    def initialize(graph)
+      @graph = graph
+    end
+
+  end # module GraphWrapper
+
+end # RGL

data/lib/rgl/graphxml.rb

@@ -1,7 +1,7 @@
 # graphxml.rb
 #
 # This file contains minimal support for creating RGL graphs from the GraphML
-# format (see http://www.graphdrawing.org/graphml).  The main purpose is to
+# format (see http://www.graphdrawing.org/graphml). The main purpose is to
 # have a rich set of example graphs to have some more tests.
 #
 # See the examples directory, which contains a subdirectory _north_ with the
@@ -16,36 +16,46 @@ require 'rexml/document'
 require 'rexml/streamlistener'
 
 module RGL
+
   module MutableGraph
+
     # Used to parse a subset of GraphML into an RGL graph implementation.
+    #
     class MutableGraphParser
+
       include REXML::StreamListener
 
       # First resets +graph+ to be empty and stores a reference for use with
       # #tag_start.
-      def initialize (graph)
+      #
+      def initialize(graph)
         @graph = graph
         @graph.remove_vertices(@graph.vertices)
       end
 
       # Processes incoming edge and node elements from GraphML in order to
       # populate the graph given to #new.
-      def tag_start (name, attrs)
+      #
+      def tag_start(name, attrs)
         case name
-        when 'edge'
-          @graph.add_edge(attrs['source'], attrs['target'])
-        when 'node'
-          @graph.add_vertex(attrs['id'])
+          when 'edge'
+            @graph.add_edge(attrs['source'], attrs['target'])
+          when 'node'
+            @graph.add_vertex(attrs['id'])
         end
       end
-    end		# class MutableGraphParser
+
+    end # class MutableGraphParser
 
     # Initializes an RGL graph from a subset of the GraphML format given in
     # +source+ (see http://www.graphdrawing.org/graphml).
+    #
     def from_graphxml(source)
       listener = MutableGraphParser.new(self)
       REXML::Document.parse_stream(source, listener)
       self
     end
-  end                           # module MutableGraph
-end                             # module RGL
+
+  end # module MutableGraph
+
+end # module RGL

data/lib/rgl/implicit.rb

@@ -1,19 +1,19 @@
-# implicit.rb 
+# implicit.rb
 #
 # This file contains the definition of the class RGL::ImplicitGraph, which
 # defines vertex and edge iterators using blocks (which again call blocks).
-# 
+#
 # An ImplicitGraph provides a handy way to define graphs on the fly, using two
-# blocks for the two iterators defining a graph.  A directed cyclic graph,
+# blocks for the two iterators defining a graph. A directed cyclic graph,
 # with five vertices can be created as follows:
 #
-#   g = RGL::ImplicitGraph.new { |g|
+#   g = RGL::ImplicitGraph.new do |g|
 #     g.vertex_iterator { |b| 0.upto(4,&b) }
 #     g.adjacent_iterator { |x, b| b.call((x+1)%5) }
 #     g.directed = true
-#   }
+#   end
 #
-#   g.to_s => "(0-1)(1-2)(2-3)(3-4)(4-0)"
+#   g.to_s # => "(0-1)(1-2)(2-3)(3-4)(4-0)"
 #
 # Other examples are given by the methods vertices_filtered_by and
 # edges_filtered_by, which can be applied to any graph.
@@ -28,110 +28,109 @@ module RGL
 
     attr_writer :directed
 
-    EMPTY_VERTEX_ITERATOR   = proc { |b|    }
+    EMPTY_VERTEX_ITERATOR   = proc { |b| }
     EMPTY_NEIGHBOR_ITERATOR = proc { |x, b| }
-        
-    # Create a new ImplicitGraph, which is empty by default.  The caller should
-    # configure the graph using vertex and neighbor iterators.  If the graph is
-    # directed, the client should set _directed_ to true.  The default value
-    # for _directed_ is false. 
 
+    # Create a new ImplicitGraph, which is empty by default. The caller should
+    # configure the graph using vertex and neighbor iterators. If the graph is
+    # directed, the client should set _directed_ to true. The default value
+    # for _directed_ is false.
+    #
     def initialize
-      @directed = false
+      @directed          = false
       @vertex_iterator   = EMPTY_VERTEX_ITERATOR
       @adjacent_iterator = EMPTY_NEIGHBOR_ITERATOR
-      yield self if block_given?  # Let client overwrite defaults.
+      yield self if block_given? # Let client overwrite defaults.
     end
 
     # Returns the value of @directed.
-
+    #
     def directed?
       @directed
     end
-        
-    def each_vertex (&block)			# :nodoc:
+
+    def each_vertex(&block) # :nodoc:
       @vertex_iterator.call(block)
     end
 
-    def each_adjacent (v, &block)		# :nodoc:
+    def each_adjacent(v, &block) # :nodoc:
       @adjacent_iterator.call(v, block)
     end
 
-    def each_edge (&block)			# :nodoc:
+    def each_edge(&block) # :nodoc:
       if defined? @edge_iterator
         @edge_iterator.call(block)
       else
-        super					# use default implementation
+        super # use default implementation
       end
     end
 
     # Sets the vertex_iterator to _block_,
     # which must be a block of one parameter
     # which again is the block called by each_vertex.
-
-    def vertex_iterator (&block)
+    #
+    def vertex_iterator(&block)
       @vertex_iterator = block
     end
 
     # Sets the adjacent_iterator to _block_,
-    # which must be a block of two parameters: 
+    # which must be a block of two parameters:
     #
     #   The first parameter is the vertex the neighbors of which are to be
     #   traversed.
     #
     #   The second is the block which will be called for each neighbor
     #   of this vertex.
-
-    def adjacent_iterator (&block)
+    #
+    def adjacent_iterator(&block)
       @adjacent_iterator = block
     end
 
     # Sets the edge_iterator to _block_, which must be a block of two
     # parameters: The first parameter is the source of the edges; the
     # second is the target of the edge.
-
-    def edge_iterator (&block)
+    #
+    def edge_iterator(&block)
       @edge_iterator = block
     end
 
-  end		# class ImplicitGraph
-
+  end # class ImplicitGraph
 
   module Graph
 
-    # ---
     # === Graph adaptors
     #
     # Return a new ImplicitGraph which has as vertices all vertices of the
     # receiver which satisfy the predicate _filter_.
     #
-    # The methods provides similar functionaty as the BGL graph adapter
-    # filtered_graph (see BOOST_DOC/filtered_graph.html). 
+    # The methods provides similar functionality as the BGL graph adapter
+    # filtered_graph (see BOOST_DOC/filtered_graph.html).
     #
     # ==== Example
     #
     #   def complete (n)
     #     set = n.integer? ? (1..n) : n
-    #     RGL::ImplicitGraph.new { |g|
-    #           g.vertex_iterator { |b| set.each(&b) }
-    #           g.adjacent_iterator { |x, b|
-    #             set.each { |y| b.call(y) unless x == y }
-    #           }
-    #     }
+    #     RGL::ImplicitGraph.new do |g|
+    #       g.vertex_iterator { |b| set.each(&b) }
+    #       g.adjacent_iterator do |x, b|
+    #         set.each { |y| b.call(y) unless x == y }
+    #       end
+    #     end
     #   end
     #
-    #   complete(4).to_s =>     "(1=2)(1=3)(1=4)(2=3)(2=4)(3=4)"
-    #   complete(4).vertices_filtered_by {|v| v != 4}.to_s => "(1=2)(1=3)(2=3)"
-
-    def vertices_filtered_by (&filter)
-      implicit_graph { |g|
-        g.vertex_iterator { |b|
+    #   complete(4).to_s # => "(1=2)(1=3)(1=4)(2=3)(2=4)(3=4)"
+    #   complete(4).vertices_filtered_by { |v| v != 4 }.to_s # => "(1=2)(1=3)(2=3)"
+    #
+    def vertices_filtered_by(&filter)
+      implicit_graph do |g|
+        g.vertex_iterator do |b|
           self.each_vertex { |v| b.call(v) if filter.call(v) }
-        }
-        g.adjacent_iterator { |v, b|
+        end
+
+        g.adjacent_iterator do |v, b|
           self.each_adjacent(v) { |u| b.call(u) if filter.call(u) }
-        }
-      }
+        end
+      end
     end
 
     # Return a new ImplicitGraph which has as edges all edges of the receiver
@@ -139,36 +138,39 @@ module RGL
     #
     # ==== Example
     #
-    #       g = complete(7).edges_filtered_by {|u,v| u+v == 7}
+    #       g = complete(7).edges_filtered_by { |u,v| u+v == 7 }
     #       g.to_s     => "(1=6)(2=5)(3=4)"
     #       g.vertices => [1, 2, 3, 4, 5, 6, 7]
-
-    def edges_filtered_by (&filter)
-      implicit_graph { |g|
-        g.adjacent_iterator { |v, b|
-          self.each_adjacent(v) { |u|
+    #
+    def edges_filtered_by(&filter)
+      implicit_graph do |g|
+        g.adjacent_iterator do |v, b|
+          self.each_adjacent(v) do |u|
             b.call(u) if filter.call(v, u)
-          }
-        }
-        g.edge_iterator { |b|
-          self.each_edge { |u,v| b.call(u, v) if filter.call(u, v) }
-        }
-      }
+          end
+        end
+
+        g.edge_iterator do |b|
+          self.each_edge { |u, v| b.call(u, v) if filter.call(u, v) }
+        end
+      end
     end
 
     # Return a new ImplicitGraph which is isomorphic (i.e. has same edges and
-    # vertices) to the receiver.  It is a shortcut, also used by
+    # vertices) to the receiver. It is a shortcut, also used by
     # edges_filtered_by and vertices_filtered_by.
-
+    #
     def implicit_graph
-      result = ImplicitGraph.new { |g|
+      result = ImplicitGraph.new do |g|
         g.vertex_iterator { |b| self.each_vertex(&b) }
         g.adjacent_iterator { |v, b| self.each_adjacent(v, &b) }
         g.directed = self.directed?
-      }
+      end
+
       yield result if block_given? # let client overwrite defaults
       result
     end
 
-  end		# module Graph
-end		# module RGL
+  end # module Graph
+
+end # module RGL