yargi 0.1.2 → 0.2.0

data/CHANGELOG.md

@@ -0,0 +1,54 @@
+# 0.2.0 / 2012-02-17
+
+* Enhancements
+
+  * Digraph.new now yields self if a block is given. This allows building a 
+    graph more smoothly:
+    
+        graph = Digraph.new{|d|
+          d.add_n_vertices(5)
+          ...
+        }
+        
+  * An integer is now automatically recognized as a selection predicate. This 
+    means that the following will also work:
+    
+        # connect 1-th and 2-th vertices
+        graph.connect(1, 2)
+
+  * Added Digraph#ith_vertex and Digraph#ith_edge 
+  * Added Digraph#vertex_count and Digraph#edge_count
+  * Added Digraph.random to generate graph for tests and benchmarks
+
+* Bug fixes
+
+  * Misused of $STDERR has been replaced by $stderr
+
+* Internals & Devel
+
+  * The project structure is now handled by Noe.
+
+# 0.1.2
+
+* Enhancements
+
+  * Markable.add_marks also accepts a block to mimic add_n_vertices and 
+    ElementSet.add_marks
+  * EdgeSet forwards source= and target= to its elements, allowing bulk 
+    reconnection
+  * Digraph.to_dot_attributes made much more smart on typical array values
+
+* Bug fixes
+
+  * Markable.has_key? is used to avoid predicate side-effects on v[:mark] when 
+    the mark is false
+    
+# 0.1.1
+
+  * Bug fix in dot generation
+  * Examples started and documentation improved
+  * Web site index generation using wlang
+
+# 0.1.0
+
+  * Birthday!

data/Gemfile

@@ -0,0 +1,7 @@
+source 'http://rubygems.org'
+
+group :development do
+  gem "rake", "~> 0.9.2"
+  gem "rspec", "~> 2.8.0"
+  gem "wlang", "~> 0.10.2"
+end

data/Gemfile.lock

@@ -0,0 +1,23 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    rake (0.9.2.2)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+    wlang (0.10.2)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  rake (~> 0.9.2)
+  rspec (~> 2.8.0)
+  wlang (~> 0.10.2)

data/LICENCE.md

@@ -0,0 +1,22 @@
+# The MIT Licence
+
+    Copyright (c) 2009-2011 - Bernard Lambeau
+
+    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/Manifest.txt

@@ -0,0 +1,15 @@
+yargi.gemspec
+yargi.noespec
+CHANGELOG.md
+Gemfile
+Gemfile.lock
+bin/**/*
+lib/**/*
+examples/**/*
+LICENCE.md
+Manifest.txt
+Rakefile
+README.md
+spec/**/*
+tasks/**/*
+test/**/*

data/README.md

@@ -0,0 +1,128 @@
+# Yargi
+
+Yet Another Ruby Graph Library 
+
+## Links
+
+* http://rubydoc.info/github/blambeau/yargi/master/frames
+* http://github.com/blambeau/yargi
+* http://rubygems.org/gems/yargi
+
+## Description
+
+Yargi provides a powerful **mutable** digraph implementation. It has been 
+designed to allow full mutability the easy way. A quick tour below.
+
+## Quick tour
+
+### Digraph, Vertex and Edge
+
+Unlike {http://rubyforge.org/projects/rgl/ 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).
+
+    graph = Yargi::Digraph.new
+    v1 = graph.add_vertex(:kind => "simple vertex")
+    puts v1.kind    
+    # => "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:
+
+    # These are node types
+    module Diamond; end
+    module Circle; end
+    
+    # Let build a graph with 5 diamonds
+    graph = Yargi::Digraph.new
+    graph.add_n_vertices(5, Diamond) do |v,i|
+      v[:color] = (i%2==0 ? 'red' : 'blue')
+    end
+
+    # Let add 5 circles
+    graph.add_n_vertices(5, Circle)
+
+    # connect all diamonds to all circles
+    graph.connect(Diamond, Circle)  
+
+### 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.
+
+    # [... 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:
+
+    # [... previous example continued ...]
+    circles = graph.vertices(Diamond).adjacent
+    puts graph.vertices(Circle)==circles        
+    # => 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:
+
+    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.
+
+## Distribution & Credits
+
+_Yargi_ is freely available (under a MIT licence) as a 'yargi' gem on 
+{http://rubygems.org/gems/yargi rubygems.org}. Use 'gem install yargi' to 
+install it. The sources are on {http://github.com/blambeau/yargi github}, which
+is also the place where bugs and issues can be reported.
+
+This work is supported by the {http://www.uclouvain.be/en-ingi.html department 
+of computer science} of the {http://www.uclouvain.be/en-index.html University of 
+Louvain} (EPL/INGI, Universite Catholique de Louvain, UCL, Louvain-la-Neuve, 
+Belgium).
+
+This work was also partially supported by the Regional Government of Wallonia 
+(GISELE project, RW Conv. 616425).

data/Rakefile

@@ -0,0 +1,23 @@
+begin
+  gem "bundler", "~> 1.0"
+  require "bundler/setup"
+rescue LoadError => ex
+  puts ex.message
+  abort "Bundler failed to load, (did you run 'gem install bundler' ?)"
+end
+
+# Dynamically load the gem spec
+$gemspec_file = File.expand_path('../yargi.gemspec', __FILE__)
+$gemspec      = Kernel.eval(File.read($gemspec_file))
+
+# We run tests by default
+task :default => :test
+
+#
+# Install all tasks found in tasks folder
+#
+# See .rake files there for complete documentation.
+#
+Dir["tasks/*.rake"].each do |taskfile|
+  load taskfile
+end

data/examples/fs2dot.rb

@@ -50,7 +50,7 @@ graph.vertices(FileVertex){|v| /\.rb (.*)$/ =~ v.label}.add_marks(
 graph.vertices(FileVertex){|v| /\.rb (.*)$/ =~ v.label}.in_adjacent.add_marks do |v|
   {:fillcolor => 'gold', :fontcolor => 'black'}
 end
- 
+
 # Save it
 File.open(File.join(File.dirname(__FILE__), 'fs2dot.dot'), 'w') do |f|
   f << graph.to_dot

data/examples/random.rb

@@ -0,0 +1,20 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'yargi'
+
+COLORS = ["blue", "red", "yellow", "green"]
+
+# We build a random graph with approximately 20 vertices
+# and 60 edges (will be stripped by default). Each vertex
+# will have a color picked at random.
+graph = Yargi::Digraph.random(20,60) do |r|
+  r.vertex_builder = lambda{|v,i|
+    v[:color] = COLORS[Kernel.rand(COLORS.size)]
+  }
+end
+
+# The label of each vertex will be its depth
+Yargi::Decorate::DEPTH.execute(graph)
+graph.vertices.add_marks{|v| {:label => v[:depth]}}
+
+# Print as a dot graph
+puts graph.to_dot

data/lib/yargi.rb

@@ -1,25 +1,22 @@
+require 'yargi/version'
+require 'yargi/loader'
 require 'yargi/predicate'
-
 module Yargi
-  
-  # Current Yargi version
-  VERSION = "0.1.2".freeze
-  
+
   # When _what_ is not nil, converts it to a predicate (typically a module).
   # Otherwise, a block is expected, which is converted to a LambdaPredicate.
   # Otherwise, return ALL.
   def self.predicate(what=nil, &block)
     Predicate.to_predicate(what, &block)
   end
-  
+
   # Predicates that always return true
   ALL = Yargi::Predicate.to_predicate(true)
-  
+
   # Predicates that always return false
   NONE = Yargi::Predicate.to_predicate(false)
-  
-end
 
+end
 require 'yargi/markable'
 require 'yargi/digraph'
 require 'yargi/digraph_vertex'
@@ -27,4 +24,5 @@ require 'yargi/digraph_edge'
 require 'yargi/element_set'
 require 'yargi/vertex_set'
 require 'yargi/edge_set'
-
+require 'yargi/decorate'
+require 'yargi/random'

data/lib/yargi/decorate.rb

@@ -0,0 +1,55 @@
+module Yargi
+  class Decorate
+    attr_accessor :key
+    attr_accessor :bottom
+    attr_accessor :d0
+    attr_accessor :suppremum
+    attr_accessor :propagate
+
+    def initialize
+      yield(self) if block_given?
+    end
+
+    def execute(digraph, initials = digraph.vertices(0))
+      # all to bottom except initial states
+      digraph.each_vertex{|s| s[key] = bottom}
+      initials.each{|s| s[key] = d0}
+
+      # main loop
+      to_explore = initials
+      until to_explore.empty?
+        source = to_explore.pop
+        source.out_edges.each do |edge|
+          target = edge.target
+          p_decor = propagate.call(source[key], edge)
+          p_decor = suppremum.call(target[key], p_decor)
+          unless p_decor == target[key]
+            target[key] = p_decor
+            to_explore << target unless to_explore.include?(target)
+          end
+        end
+      end
+    end
+
+    DEPTH = Decorate.new{|d|
+      d.key       = :depth
+      d.bottom    = 1.0/0
+      d.d0        = 0
+      d.suppremum = lambda{|d1,d2| d1 < d2 ? d1 : d2}
+      d.propagate = lambda{|d,e| d+1}
+    }
+
+    SHORTEST_PATH = Decorate.new{|d|
+      d.key       = :shortest_path
+      d.bottom    = nil
+      d.d0        = []
+      d.suppremum = lambda{|d1,d2|
+        d1.nil? ? d2 : (d2.nil? ? d1 : (d1.size < d2.size ? d1 : d2))
+      }
+      d.propagate = lambda{|d,e|
+        d.nil? ? [e] : (d + [e])
+      }
+    }
+
+  end # class Decorate
+end # module Yargi

data/lib/yargi/digraph.rb

@@ -6,12 +6,12 @@ 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 
+  # * 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 
+  #   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.
   #
@@ -21,22 +21,33 @@ module Yargi
   #
   class Digraph
     include Yargi::Markable
-  
+
     # Creates an empty graph instance
     def initialize
       @vertices = VertexSet[]
       @edges = EdgeSet[]
       @marks = {}
+      yield(self) if block_given?
     end
-    
+
     ### Vertex management ################################################
-    
+
+    # Returns number of graph vertices
+    def vertex_count
+      @vertices.size
+    end
+
+    # Returns the i-th vertex
+    def ith_vertex(i)
+      @vertices[i]
+    end
+
     # 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)
@@ -46,20 +57,20 @@ module Yargi
         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. 
+
+    # 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, 
+
+    # 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.
@@ -72,8 +83,8 @@ module Yargi
       end
       VertexSet.new(vertices)
     end
-    
-    # Removes all vertices returned by evaluating the _vertices_ selection 
+
+    # Removes all vertices returned by evaluating the _vertices_ selection
     # expression.
     def remove_vertices(*vertices)
       vertices = to_vertices(*vertices).sort{|v1,v2| v2<=>v1}
@@ -85,16 +96,26 @@ module Yargi
       @vertices.each_with_index {|v,i| v.index=i}
       self
     end
-    alias :remove_vertex :remove_vertices 
-    
+    alias :remove_vertex :remove_vertices
+
     ### Edge management ##################################################
-    
+
+    # Returns number of graph edges
+    def edge_count
+      @edges.size
+    end
+
+    # Returns the i-th edge
+    def ith_edge(i)
+      @edges[i]
+    end
+
     # 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)
@@ -104,10 +125,10 @@ module Yargi
         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 
+
+    # 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
@@ -129,7 +150,7 @@ module Yargi
       end
     end
     alias :connect :add_edge
-    
+
     # Adds many edges at once
     def add_edges(*extremities)
       extremities.collect do |extr|
@@ -137,8 +158,8 @@ module Yargi
       end
     end
     alias :connect_all :add_edges
-    
-    # Removes all edges returned by evaluating the _edges_ selection 
+
+    # Removes all edges returned by evaluating the _edges_ selection
     # expression.
     def remove_edges(*edges)
       edges = to_edges(edges).sort{|e1,e2| e2<=>e1}
@@ -152,9 +173,9 @@ module Yargi
       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 
+    # 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).
@@ -165,7 +186,7 @@ module Yargi
         if source
           edge.source.remove_out_edge(edge)
           source.add_out_edge(edge)
-        end 
+        end
         if target
           edge.target.remove_in_edge(edge)
           target.add_in_edge(edge)
@@ -176,7 +197,7 @@ module Yargi
     end
 
     ### Standard exports #################################################
-    
+
     # Encodes this graph for dot graphviz
     def to_dot(buffer='')
       buffer << "digraph G {\n"
@@ -189,10 +210,10 @@ module Yargi
       end
       buffer << "}\n"
     end
-    
+
     ### Argument conventions #############################################
     protected
-    
+
     # Converts a hash to dot attributes
     def to_dot_attributes(hash)
       # TODO: fix uncompatible key names
@@ -214,36 +235,38 @@ module Yargi
       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| 
+      @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 
+          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 
+          raise "Vertex and edge don't agree on source" unless oute.source==v
         end
       end
-      @edges.each_with_index do |e,i| 
+      @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 Integer
+            [@vertices[arg]]
           when VertexSet
             arg
           when Array
@@ -257,11 +280,13 @@ module Yargi
       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 Integer
+            [@edges[arg]]
           when EdgeSet
             arg
           when Array
@@ -275,7 +300,7 @@ module Yargi
       end.flatten.uniq
       EdgeSet.new(selected)
     end
-  
+
     # Applies argument conventions on _element_
     def apply_arg_conventions(element, args)
       args.each do |arg|
@@ -290,7 +315,7 @@ module Yargi
       end
       element
     end
-    
+
   end # class Digraph
-  
+
 end