yargi 0.1.0

data/LICENCE

@@ -0,0 +1,25 @@
+= Licence
+
+	The MIT License
+
+	Copyright (c) 2009 Bernard Lambeau and the University of Louvain 
+	(Universite Catholique de Louvain, Louvain-la-Neuve, Belgium)
+	
+	Permission is hereby granted, free of charge, to any person obtaining a copy
+	of this software and associated documentation files (the "Software"), to deal
+	in the Software without restriction, including without limitation the rights
+	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+	copies of the Software, and to permit persons to whom the Software is
+	furnished to do so, subject to the following conditions:
+
+	The above copyright notice and this permission notice shall be included in
+	all copies or substantial portions of the Software.
+
+	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+	THE SOFTWARE.
+	

data/README

@@ -0,0 +1,79 @@
+= Yargi
+
+Yargi aims at providing a powerful mutable digraph implementation. As reflected by its name,
+Yargi is Yet Another (Ruby) Graph Implementation: we all have implemented a graph data structure
+in almost every language that we use, probably many times. The reason is probably that each 
+implementation has its own design decisions that makes the data-structure well-designed for
+the task at hand, or not. Below are the main design decisions made by Yargi; this way you can
+easily see if it fits your needs.
+
+[Digraph, Vertex and Edge] Unlike {RGL}[http://rubyforge.org/projects/rgl/], Yargi implements
+                           graph components through concrete classes, not modules (that is, in 
+                           a standard-but-closed way). See Digraph, Digraph::Vertex and Digraph::Edge
+                           respectively.
+[Markable pattern] Graphs, vertices and edges are markable through a Hash-like API: users can
+                   install their own key/value pairs on each graph element. When keys are Symbol
+                   objects, accessors are automatically generated to provide a friendly object-oriented
+                   API (this feature must be used with care, for obvious reasons).
+                   Example:
+                     graph = Yargi::Digraph.new
+                     v1 = graph.add_vertex(:kind => "simple vertex")
+                     puts v1.kind    # prints "simple vertex"
+                     
+[Typed elements] Graph elements (vertices and edges) can be tagged with your own modules (at creation,
+                 or later). This is the standard Yargi way to apply a 'select-and-do' feature described
+                 below.
+                 Example:
+                   module Diamond; end
+                   module Circle; end
+                   graph = Yargi::Digraph.new
+                   graph.add_n_vertices(5, Diamond) do |v,i|
+                     v[:color] = (i%2==0 ? 'red' : 'blue')
+                   end
+                   graph.add_n_vertices(5, Circle)
+                   graph.connect(Diamond, Circle)  # connect all diamonds to all circles
+                 
+[Selection mechanism] Yargi helps you finding the nodes and edges you are looking for through a 
+                      declarative selection mechanism: almost all methods that return a set of 
+                      vertices or edges (Vertex.out_edges, for example) accept a predicate
+                      argument to filter the result, module names being most-used shortcuts. 
+                      See Yargi::Predicate for details.
+                      Example:
+                        [... previous example continued ...]
+                        graph.vertices(Diamond)                       # selects all diamonds
+                        graph.vertices(Diamond){|v| v.color=='blue'}  # selects blue diamonds only
+                        
+                        # Proc variant, find sink states
+                        sink = Yargi.predicate {|v| v.out_edges.empty?}
+                        graph.vertices(sink & Circle)                 # select all Circle sink states (no one)
+                        
+                        # Or selection
+                        is_blue = Yargi.predicate {|v| Diamond===v and v.color=='blue'}
+                        graph.vertices(is_blue|Circle)                # select blue diamonds and circles
+                      
+[VertexSet and EdgeSet] The selection mechanism always returns arrays ... being instances
+                        of Yargi::VertexSet and Yargi::EdgeSet. These classes help you walking
+                        your graph easily.
+                        Example:
+                          [... previous example continued ...]
+                          circles = graph.vertices(Diamond).adjacent
+                          puts graph.vertices(Circle)==circles        # puts true
+                        
+[Select-and-do] Many graph methods accept sets of vertices and edges as well as selection queries
+                to work. Instead of connecting one source to one target at a time by passing the 
+                vertices, describe what you want and Yardi does it. Add, connect, remove, mark,
+                reconnect many vertices/edges with a single method call !
+                Example:
+                  graph.vertices(Diamond).add_marks(:label => '', :shape => 'diamond')
+                  graph.vertices(Circle).add_marks(:label => '', :shape => 'circle')
+                  puts graph.to_dot
+                  graph.remove_vertices(Circle) # remove all circles
+                
+[Mutable graphs] Graphs here are mutable, mutable and mutable and this is the reason why Yargi
+                 exists. It comes from a project where manipulating graphs by reconnecting edges,
+                 removing vertices is the norm, not the exception.
+[Complexity don't care] The digraph implementation uses an incident list data structure. This graph
+                        library has not been designed with efficiency in mind so that complexities 
+                        are not documented nor guaranteed. That is not to say that improvements are
+                        not welcome, of course.
+[Ruby minded] Because we love that language!

data/lib/yargi/digraph.rb

@@ -0,0 +1,287 @@
+require 'yargi/digraph_vertex'
+require 'yargi/digraph_edge'
+
+module Yargi
+
+  #
+  # Directed graph implementation.
+  #
+  # * All selection methods (vertices, each_vertex, edges, each_edge) implement the 
+  #   predicate-selection mechanism (they accept a predicate filter as well as a 
+  #   predicate block, with a AND semantics when used conjointly).
+  # * Removal methods (remove_vertex, remove_vertices, remove_edge, remove_edges)
+  #   accept varying arguments that are automatically converted to set of vertices 
+  #   or edges. Recognized arguments are Vertex and Edge instances, VertexSet and 
+  #   EdgeSet instances, Array instances, and predicates. When multiple arguments
+  #   are used conjointly, a OR-semantics is applied.
+  #
+  #   Example:
+  #     graph.remove_vertices(Circle, Diamond)               # removes all vertices tagged as Circle OR Diamond
+  #     graph.remove_vertices(Yargi::ALL & Circle & Diamond) # remove vertices that are both Circle and Diamond
+  #
+  class Digraph
+    include Yargi::Markable
+  
+    # Creates an empty graph instance
+    def initialize
+      @vertices = VertexSet[]
+      @edges = EdgeSet[]
+      @marks = {}
+    end
+    
+    ### Vertex management ################################################
+    
+    # Returns all graph vertices for which the 'filter and block' predicate
+    # evaluates to true (see Yargi::Predicate).
+    def vertices(filter=nil, &block)
+      @vertices.filter(filter, &block)
+    end
+    
+    # Calls block on each graph vertex for with the 'filter and block' predicate
+    # evaluates to true.
+    def each_vertex(filter=nil, &block)
+      return unless block_given?
+      if filter.nil?
+        @vertices.each &block
+      else
+        vertices(filter).each &block
+      end
+    end
+    
+    # Adds a vertex. _args_ can be module instances or hashes, 
+    # which are all installed on the vertex _v_ using  <tt>v.tag</tt> 
+    # and <tt>v.add_marks</tt>, respectively. 
+    def add_vertex(*args)
+      vertex = Digraph::Vertex.new(self, @vertices.length)
+      apply_arg_conventions(vertex, args)
+      @vertices << vertex
+      vertex
+    end
+    
+    # Creates n vertices. _args_ can be module instances or hashes, 
+    # which are all installed on vertices _v_ using  <tt>v.tag</tt> 
+    # and <tt>v.add_marks</tt>, respectively. If a block is given, 
+    # it is called after each vertex creation. The vertex is passed
+    # as first argument and the iteration index (from 0 to n-1) as
+    # second one.
+    def add_n_vertices(n, *args)
+      vertices = []
+      n.times do |i|
+        vertex = add_vertex(*args)
+        vertices << vertex
+        yield vertex, i if block_given?
+      end
+      VertexSet.new(vertices)
+    end
+    
+    # Removes all vertices returned by evaluating the _vertices_ selection 
+    # expression.
+    def remove_vertices(*vertices)
+      vertices = to_vertices(*vertices).sort{|v1,v2| v2<=>v1}
+      vertices.each do |vertex|
+        remove_edges(vertex.in_edges+vertex.out_edges)
+        @vertices.delete_at(vertex.index)
+        vertex.index=-1
+      end
+      @vertices.each_with_index {|v,i| v.index=i}
+      self
+    end
+    alias :remove_vertex :remove_vertices 
+    
+    ### Edge management ##################################################
+    
+    # Returns all graph edges for which the 'filter and block' predicate
+    # evaluates to true (see Yargi::Predicate).
+    def edges(filter=nil, &block)
+      @edges.filter(filter, &block)
+    end
+    
+    # Calls block on each graph edge for with the 'filter and block' predicate
+    # evaluates to true.
+    def each_edge(filter=nil, &block)
+      return unless block_given?
+      if filter.nil?
+        @edges.each &block
+      else
+        edges(filter).each &block
+      end
+    end
+    
+    # Connects source to target state(s). _source_ and _target_ may be any 
+    # selection expression that can lead to vertex sets. _args_ can be module 
+    # instances or hashes,  which are all installed on edges _e_ using 
+    # <tt>e.tag</tt> and <tt>e.add_marks</tt>, respectively.
+    def add_edge(source, target, *args)
+      if Vertex===source and Vertex===target
+        edge = Digraph::Edge.new(self, @edges.length, source, target)
+        apply_arg_conventions(edge, args)
+        source.add_out_edge(edge)
+        target.add_in_edge(edge)
+        @edges << edge
+        edge
+      else
+        sources, targets = to_vertices(source), to_vertices(target)
+        created = EdgeSet[]
+        sources.each do |src|
+          targets.each do |trg|
+            created << add_edge(src, trg, *args)
+          end
+        end
+        created
+      end
+    end
+    alias :connect :add_edge
+    
+    # Adds many edges at once
+    def add_edges(*extremities)
+      extremities.collect do |extr|
+        add_edge(extr[0], extr[1], *extr[2..-1])
+      end
+    end
+    alias :connect_all :add_edges
+    
+    # Removes all edges returned by evaluating the _edges_ selection 
+    # expression.
+    def remove_edges(*edges)
+      edges = to_edges(edges).sort{|e1,e2| e2<=>e1}
+      edges.each do |edge|
+        edge.source.remove_out_edge(edge)
+        edge.target.remove_in_edge(edge)
+        @edges.delete_at(edge.index)
+        edge.index = -1
+      end
+      @edges.each_with_index {|edge,i| edge.index=i}
+      self
+    end
+    alias :remove_edge :remove_edges
+    
+    # Reconnects some edge(s). _source_ and _target_ are expected to be
+    # Vertex instances, or nil. _edges_ may be any selection expression 
+    # that can be converted to an edge set. This method reconnects all
+    # edges to the specified source and target vertices (at least one is
+    # expected not to be nil).
+    def reconnect(edges, source, target)
+      raise ArgumentError, "Vertices expected as source and target"\
+        unless (source.nil? or Vertex===source) and (target.nil? or Vertex===target)
+      to_edges(edges).each do |edge|
+        if source
+          edge.source.remove_out_edge(edge)
+          source.add_out_edge(edge)
+        end 
+        if target
+          edge.target.remove_in_edge(edge)
+          target.add_in_edge(edge)
+        end
+        edge.reconnect(source, target)
+        edge
+      end
+    end
+
+    ### Standard exports #################################################
+    
+    # Encodes this graph for dot graphviz
+    def to_dot(buffer='')
+      buffer << "digraph G {\n"
+      buffer << "  graph[#{to_dot_attributes(self.to_h(true))}]\n"
+      each_vertex do |v|
+        buffer << "  V#{v.index} [#{to_dot_attributes(v.to_h(true))}]\n"
+      end
+      each_edge do |e|
+        buffer << "  V#{e.source.index} -> V#{e.target.index} [#{to_dot_attributes(e.to_h(true))}]\n"
+      end
+      buffer << "}\n"
+    end
+    
+    ### Argument conventions #############################################
+    protected
+    
+    # Converts a hash to dot attributes
+    def to_dot_attributes(hash)
+      # TODO: fix uncompatible key names
+      # TODO: some values must be encoded (backquoting and the like)
+      buffer = ""
+      hash.each_pair do |k,v|
+        buffer << "#{k}=\"#{v}\""
+      end
+      buffer
+    end
+    
+    # Checks if _arg_ looks like an element set
+    def looks_a_set?(arg)
+      Array===arg or ElementSet===arg
+    end
+    
+    # Checks graph sanity
+    def check_sanity
+      @vertices.each_with_index do |v,i| 
+        raise "Removed vertex in vertex list" unless v.index==i
+        v.in_edges.each do |ine|
+          raise "Removed edge in vertex incoming edges" if ine.index<0
+          raise "Vertex and edge don't agree on target" unless ine.target==v 
+        end
+        v.out_edges.each do |oute|
+          raise "Removed edge in vertex outgoing edges" if oute.index<0
+          raise "Vertex and edge don't agree on source" unless oute.source==v 
+        end
+      end
+      @edges.each_with_index do |e,i| 
+        raise "Removed edge in edge list" unless e.index==i
+        raise "Edge in-connected to a removed vertex" if e.source.index<0
+        raise "Edge out-connected to a removed vertex" if e.target.index<0
+      end
+    end
+    
+    # Applies argument conventions about selection of vertices
+    def to_vertices(*args)
+      selected = args.collect do |arg|
+        case arg
+          when VertexSet
+            arg
+          when Array
+            arg.collect{|v| to_vertices(v)}.flatten.uniq
+          when Digraph::Vertex
+            [arg]
+          else
+            pred = Predicate.to_predicate(arg)
+            vertices(pred)
+        end
+      end.flatten.uniq
+      VertexSet.new(selected)
+    end
+  
+    # Applies argument conventions about selection of edges
+    def to_edges(*args)
+      selected = args.collect do |arg|
+        case arg
+          when EdgeSet
+            arg
+          when Array
+            arg.collect{|v| to_edges(v)}.flatten.uniq
+          when Digraph::Edge
+            [arg]
+          else
+            pred = Predicate.to_predicate(arg)
+            edges(pred)
+        end
+      end.flatten.uniq
+      EdgeSet.new(selected)
+    end
+  
+    # Applies argument conventions on _element_
+    def apply_arg_conventions(element, args)
+      args.each do |arg|
+        case arg
+          when Module
+            element.tag(arg)
+          when Hash
+            element.add_marks(arg)
+          else
+            raise ArgumentError, "Unable to apply argument conventions on #{arg.inspect}", caller
+        end
+      end
+      element
+    end
+    
+  end # class Digraph
+  
+end

data/lib/yargi/digraph_edge.rb

@@ -0,0 +1,81 @@
+module Yargi
+  class Digraph
+    
+    #
+    # Edge inside a digraph
+    #
+    # Methods reconnect, index= are provided for Digraph itself and are not 
+    # intended to be used directly. Probably unexpectedly, source and target 
+    # writers are provided as reconnection shortcuts and can be used by users.
+    #
+    class Edge
+      include Yargi::Markable
+      
+      # Owning graph
+      attr_reader :graph
+      alias :digraph :graph
+    
+      # Index in the vertices list of the owner
+      attr_accessor :index
+      
+      # Source vertex
+      attr_reader :source
+      
+      # Target vertex
+      attr_reader :target
+    
+      # Creates an edge instance
+      def initialize(graph, index, source, target)
+        @graph, @index = graph, index
+        @source, @target = source, target
+      end
+
+    
+      ### Pseudo-protected section ##########################################
+      
+      # Reconnects source and target
+      def reconnect(source, target)
+        @source = source if source
+        @target = target if target
+      end
+
+      
+      ### Query section #######################################################
+      
+      # Returns edge extremities
+      def extremities
+        VertexSet[source, target]
+      end
+      
+      # Shortcut for digraph.reconnect(edge, source, nil)
+      def source=(source)
+        @graph.reconnect(self, source, nil)
+      end
+    
+      # Shortcut for digraph.reconnect(edge, nil, target)
+      def target=(target)
+        @graph.reconnect(self, nil, target)
+      end
+      
+      
+      ### Sort, Hash, etc. section ############################################
+      
+      # Compares indexes
+      def <=>(other)
+        return nil unless Edge===other and self.graph==other.graph
+        self.index <=> other.index
+      end
+      
+      
+      ### Export section ######################################################
+      
+      # Returns a string representation
+      def to_s; "e#{index}:#{source.to_s}->#{target.to_s}" end
+          
+      # Inspects the vertex
+      def inspect; "e#{index}:#{source.inspect}->#{target.inspect}" end
+      
+    end # class Edge
+    
+  end
+end

data/lib/yargi/digraph_vertex.rb

@@ -0,0 +1,98 @@
+module Yargi
+  class Digraph
+    
+    #
+    # Vertex inside a digraph.
+    #
+    # Methods add_in_edge, remove_in_edge, add_out_edge, remove_out_edge and index= 
+    # are provided for Digraph itself and are not intended to be used directly.
+    #
+    class Vertex
+      include Yargi::Markable
+    
+      # Owning graph
+      attr_reader :graph
+      alias :digraph :graph
+    
+      # Index in the vertices list of the owner
+      attr_accessor :index
+      
+      # Creates a vertex instance
+      def initialize(graph, index)
+        @graph, @index = graph, index
+        @in_edges, @out_edges = EdgeSet[], EdgeSet[]
+      end
+
+      
+      ### Query section #######################################################
+      
+      # Returns a copy of the incoming edges list.
+      def in_edges(filter=nil, &block)
+        @in_edges.filter(filter, &block)
+      end
+    
+      # Returns a copy of the outgoing edges list.
+      def out_edges(filter=nil, &block)
+        @out_edges.filter(filter, &block)
+      end
+      
+      # Returns all adjacent vertices
+      def adjacent(filter=nil, &block)
+        (in_adjacent(filter, &block) + out_adjacent(filter, &block)).uniq
+      end
+      
+      # Returns back-adjacent vertices 
+      def in_adjacent(filter=nil, &block)
+        @in_edges.source.filter(filter, &block)
+      end
+    
+      # Returns forward-adjacent vertices 
+      def out_adjacent(filter=nil, &block)
+        @out_edges.target.filter(filter, &block)
+      end
+
+    
+      ### Pseudo-protected section ##########################################
+      
+      # Adds an incoming edge
+      def add_in_edge(edge)
+        @in_edges << edge
+      end
+      
+      # Removes an incoming edge
+      def remove_in_edge(edge)
+        @in_edges.delete(edge)
+      end
+      
+      # Adds an outgoing edge
+      def add_out_edge(edge)
+        @out_edges << edge
+      end
+    
+      # Removes an outgoing edge
+      def remove_out_edge(edge)
+        @out_edges.delete(edge)
+      end
+      
+      
+      ### Sort, Hash, etc. section ############################################
+      
+      # Compares indexes
+      def <=>(other)
+        return nil unless Vertex===other and self.graph==other.graph
+        self.index <=> other.index
+      end
+      
+      
+      ### Export section ######################################################
+      
+      # Returns a string representation
+      def to_s; "V#{index}" end
+    
+      # Inspects the vertex
+      def inspect; "V#{index}" end
+    
+    end # class Vertex
+    
+  end
+end

data/lib/yargi/edge_set.rb

@@ -0,0 +1,38 @@
+module Yargi
+  
+  # A set of edges
+  class EdgeSet < ElementSet
+    
+    ### Factory section #######################################################
+    
+    # Creates a VertexSet instance using _elements_ varargs.
+    def self.[](*elements)
+      EdgeSet.new(elements)
+    end
+    
+    ### Walking section #######################################################
+    
+    # Returns a VertexSet with reachable vertices using the edges of this set.
+    def target
+      VertexSet.new(self.collect {|e| e.target}).uniq
+    end
+    alias :targets :target
+    
+    # Returns a VertexSet with back-reachable vertices using the edges of this 
+    # set.
+    def source
+      VertexSet.new(self.collect {|e| e.source}).uniq
+    end
+    alias :sources :source
+    
+    ### Protected section #####################################################
+    protected
+        
+    # Extends with EdgeSet instead of ElementSet
+    def extend_result(result)
+      EdgeSet.new(result)
+    end
+
+  end # module EdgeSet
+
+end