yargi 0.1.0

data/lib/yargi/element_set.rb

@@ -0,0 +1,166 @@
+require 'delegate'
+
+module Yargi
+  
+  # Main module of VertexSet and EdgeSet
+  class ElementSet < Array
+    
+    ### Factory section #######################################################
+    
+    # Creates a ElementSet instance using _elements_ varargs.
+    def self.[](*elements)
+      ElementSet.new(elements)
+    end
+    
+    
+    ### Array handling ########################################################
+
+    # Same as Array.dup
+    def dup() # :nodoc: #
+      extend_result(super) 
+    end
+    
+    # See Array.compact
+    def compact() # :nodoc: #
+      extend_result(super) 
+    end
+    
+    # See Array.flatten
+    def flatten() # :nodoc: #
+      extend_result(super) 
+    end
+    
+    # See Array.reverse
+    def reverse() # :nodoc: #
+      extend_result(super) 
+    end
+    
+    # See Array.uniq
+    def uniq() # :nodoc: #
+      extend_result(super) 
+    end
+    
+    # See Array.sort
+    def sort(&block) # :nodoc: #
+      extend_result(super(&block)) 
+    end
+    
+    # See Array.concat
+    def concat(other) # :nodoc: #
+      extend_result(super(other))
+    end
+    
+    # See Array.[]
+    def [](*args) # :nodoc: #
+      result = super(*args)
+      Array===result ? extend_result(result) : result 
+    end
+    
+    # See Array.+
+    def +(right) # :nodoc: #
+      extend_result(super(right)) 
+    end
+    
+    # See Array.-
+    def -(right) # :nodoc: #
+      extend_result(super(right)) 
+    end
+      
+      
+    ### Enumerable handling ###################################################
+    
+    # See Enumerable.each_cons
+    def each_cons(n) # :nodoc: #
+      super(n) {|c| yield extend_result(c)} 
+    end
+    
+    # See Enumerable.each_slice
+    def each_slice(n) # :nodoc: #
+      super(n) {|c| yield extend_result(c)} 
+    end
+    
+    # See Enumerable.select
+    def select(&block) # :nodoc: #
+      extend_result(super(&block)) 
+    end
+      
+    # See Enumerable.find_all
+    def find_all(&block) # :nodoc: #
+      extend_result(super(&block)) 
+    end
+      
+    # See Enumerable.grep
+    def grep(pattern, &block) # :nodoc: #
+      greped = super(pattern, &block)
+      block_given? ? greped : extend_result(greped)
+    end
+      
+    # See Enumerable.reject
+    def partition(&block) # :nodoc: #
+      p = super(&block)
+      [extend_result(p[0]), extend_result(p[1])]
+    end
+      
+    # See Enumerable.reject
+    def reject(&block) # :nodoc: #
+      extend_result(super(&block)) 
+    end
+  
+    
+    ### Markable handling #####################################################
+    
+    # Fired to each element of the group. 
+    def tag(*modules)
+      self.each {|elm| elm.tag(*modules)}
+    end
+    
+    # Collects result of get_mark invocation on each element of the 
+    # group and returns it as an array.
+    def get_mark(key)
+      self.collect {|elm| elm.get_mark(key)}
+    end
+
+    # Fired to each element of the group. Values are duplicated by default. 
+    # Put dup to false to avoid this behavior.
+    def set_mark(key, value, dup=true)
+      self.each {|elm| elm.set_mark(key, (dup and not(Symbol===value)) ? value.dup : value)}
+    end
+    
+    # When _marks_ is provided, the invocation is fired to all group
+    # elements. When a block is given, it is called on each element,
+    # passing it as argument. If the block returns a hash, that hash
+    # is installed as marks on the iterated element. 
+    # The two usages (_marks_ and block) can be used conjointly.
+    def add_marks(marks=nil)
+      self.each {|elm| elm.add_marks(marks)} if marks
+      if block_given? 
+        self.each do |elm|
+          hash = yield elm
+          elm.add_marks(hash) if hash
+        end
+      end
+    end
+    alias :merge_marks :add_marks
+  
+    
+    ### Query handling ########################################################
+    
+    # Filters this set with a 'predicate and block' predicate 
+    # (see Yargi::Predicate)
+    def filter(predicate=nil, &block)
+      pred = Yargi::Predicate.to_predicate(predicate, &block)
+      extend_result(self.select{|e| pred===e})
+    end
+    
+    ### Protected section #####################################################
+    protected
+        
+    # Extends a resulting array with the module. This method is intended
+    # to be overrided by specialization of this module.
+    def extend_result(result)
+      ElementSet.new(result)
+    end
+
+  end # class ElementSet
+  
+end

data/lib/yargi/markable.rb

@@ -0,0 +1,59 @@
+module Yargi
+  
+  #
+  # Allows users to put its own marks on graph elements. A Hash-like API for setting 
+  # and getting these marks is provided through <tt>[]</tt> and <tt>[]=</tt>. When a 
+  # Symbol object is used as a mark key (and provided it does'nt lead to a name 
+  # collision), accessors are automatically defined as singleton methods (without 
+  # creating an instance variable however).
+  #
+  module Markable
+
+    # Tag this element with some modules
+    def tag(*modules)
+      modules.each {|mod| self.extend(mod)}
+    end
+
+    # Returns the mark value installed under _key_. Returns nil if no such mark.
+    def get_mark(key)
+      @marks ? @marks[key] : nil; 
+    end
+    alias :[] :get_mark
+    
+    # Sets a key/value pair as a mark. Overrides previous mark value if _key_ is
+    # already in used. Automatically creates accessors if _key_ is a Symbol and such
+    # methods do not already exists.
+    def set_mark(key, value)
+      @marks = {} unless @marks
+      @marks[key] = value
+      if Symbol===key and not(self.respond_to?(key) or self.respond_to?("#{key}=".to_sym))
+        instance_eval %Q{
+          class << self
+            def #{key}() @marks[:#{key}]; end
+            def #{key}=(value) @marks[:#{key}]=value; end
+          end
+        }
+      end
+    end
+    alias :[]= :set_mark
+    
+    # Add all marks provided by a Hash instance _marks_.
+    def add_marks(marks)
+      marks.each_pair {|k,v| self[k]=v}
+    end
+    alias :merge_marks :add_marks
+    
+    # Converts this Markable to a Hash. When _nonil_ is true, nil mark values
+    # do not lead to hash entries.
+    def to_h(nonil=true)
+      return {} unless @marks
+      marks = @marks.dup
+      if nonil
+        marks.delete_if {|k,v| v.nil?}
+      end
+      marks
+    end
+    
+  end # module Markable
+  
+end

data/lib/yargi/predicate.rb

@@ -0,0 +1,229 @@
+module Yargi
+  
+  #
+  # Predicate for graph elements.
+  #
+  # The following automatic conversions apply on Ruby standard classes
+  # when using predicates (see to_predicate in particular):
+  # [Predicate] itself
+  # [Module] TagPredicate
+  # [Proc] LambdaPredicate
+  # [TrueClass, NilClass] TruePredicate
+  # [FalseClass] FalsePredicate
+  # [otherwise] an ArgumentError is raised.
+  #
+  class Predicate
+    
+    class << self
+      # Builds a 'what and block' predicate, according the automatic conversions
+      # descibed above.
+      def to_predicate(what=nil, &block)
+        (what, block = block, nil) if what.nil?
+        p = case what
+          when Predicate
+            what
+          when Module
+            TagPredicate.new(what)
+          when Proc
+            LambdaPredicate.new(&what)
+          when TrueClass, NilClass
+            ALL
+          when FalseClass
+            NONE
+          else
+            raise ArgumentError, "Unable to convert #{what} to a predicate"
+        end
+        if block
+          p & LambdaPredicate.new(&block)
+        else
+          p
+        end
+      end
+    end
+  
+    # Builds a 'self and right' predicate
+    def &(right)
+      AndPredicate.new(*[self, Predicate.to_predicate(right)])
+    end
+    
+    # Builds a 'self or right' predicate
+    def |(right)
+      OrPredicate.new(*[self, Predicate.to_predicate(right)])
+    end
+    
+    # Builds a 'not(self)' predicate
+    def not()
+      NotPredicate.new(self)
+    end
+    
+  end # class Predicate
+
+  # Decorates _true_ as a predicate
+  class TruePredicate < Predicate
+    
+    # Always returns true
+    def ===(elm)
+      true
+    end
+    
+    # Returns 'true'
+    def inspect
+      "true"
+    end
+    
+  end # class TruePredicate
+
+  # Decorates _false_ as a predicate
+  class FalsePredicate < Predicate
+    
+    # Always returns false
+    def ===(elm)
+      false
+    end
+    
+    # Returns 'false'
+    def inspect
+      "false"
+    end
+    
+  end # class TruePredicate
+
+  # Decorates a module instance as a predicate
+  class TagPredicate < Predicate
+    
+    # Creates a Tag predicate
+    def initialize(mod)
+      raise ArgumentError, "Module expected, #{mod} received" unless Module===mod
+      @mod = mod
+    end
+    
+    # Predicate implementation
+    def ===(elm)
+      @mod===elm
+    end
+    
+    # Helps debugging predicates
+    def inspect
+      "is_a?(#{@mod})"
+    end
+    
+  end # class TagPredicate
+  
+  # Decorates a block as a predicate
+  class LambdaPredicate < Predicate
+    
+    # Creates a Tag predicate
+    def initialize(&block)
+      raise ArgumentError, "Block of arity 1 expected" unless (block and block.arity==1)
+      @block = block
+    end
+    
+    # Predicate implementation
+    def ===(elm)
+      @block.call(elm)
+    end
+    
+    # Helps debugging predicates
+    def inspect
+      "lambda{...}"
+    end
+    
+  end # class LambdaPredicate
+  
+  # Negates another predicate
+  class NotPredicate < Predicate
+    
+    # Creates a 'not(negated)' predicate
+    def initialize(negated)
+      @negated = Predicate.to_predicate(negated)
+    end
+    
+    # Predicate implementation
+    def ===(elm)
+      not(@negated === elm)
+    end
+    
+    # Helps debugging predicates
+    def inspect
+      "not(#{@negated})"
+    end
+    
+  end # class NotPredicate
+  
+  # Conjunction predicate
+  class AndPredicate < Predicate
+    
+    # Builds a AND predicate
+    def initialize(*anded)
+      raise ArgumentError, "Predicates expected" unless anded.all?{|p| Predicate===p}
+      @anded = anded
+    end
+    
+    # Predicate implementation
+    def ===(elm)
+      @anded.all?{|p| p===elm}
+    end
+    
+    # Pushes _right_ in the anded array
+    def &(right)
+      @anded << Predicate.to_predicate(right)
+      self
+    end
+    
+    # Helps debugging predicates
+    def inspect
+      @anded.inject('') do |memo,p|
+        if memo.empty?
+          p.inspect
+        else
+          "#{memo} and #{p.inspect}"
+        end
+      end
+    end
+    
+  end # class AndPredicate
+  
+  # Disjunction predicate
+  class OrPredicate < Predicate
+    
+    # Builds a OR predicate
+    def initialize(*ored)
+      raise ArgumentError, "Predicates expected" unless ored.all?{|p| Predicate===p}
+      @ored = ored
+    end
+    
+    # Predicate implementation
+    def ===(elm)
+      @ored.any?{|p| p===elm}
+    end
+    
+    # Pushes _right_ in the ored array
+    def |(right)
+      @ored << Predicate.to_predicate(right)
+      self
+    end
+    
+    # Helps debugging predicates
+    def inspect
+      @ored.inject('') do |memo,p|
+        if memo.empty?
+          p.inspect
+        else
+          "#{memo} or #{p.inspect}"
+        end
+      end
+    end
+    
+  end # class OrPredicate
+  
+  class Predicate
+    
+    # Predicates that always return true
+    ALL = TruePredicate.new
+  
+    # Predicates that always return false
+    NONE = FalsePredicate.new
+  
+  end # class Predicate
+  
+end

data/lib/yargi/vertex_set.rb

@@ -0,0 +1,56 @@
+module Yargi
+  
+  # A set of vertices
+  class VertexSet < ElementSet
+    
+    ### Factory section #######################################################
+    
+    # Creates a VertexSet instance using _elements_ varargs.
+    def self.[](*elements)
+      VertexSet.new(elements)
+    end
+    
+    
+    ### Walking section #######################################################
+    
+    # Returns incoming edges of all vertices of this set
+    def in_edges(filter=nil, &block)
+      r = self.collect {|v| v.in_edges(filter, &block) }
+      EdgeSet.new(r).flatten.uniq
+    end
+    
+    # Returns all back-adjacent vertices reachable from this set
+    def in_adjacent(filter=nil, &block)
+      r = self.collect {|v| v.in_adjacent(filter, &block) }
+      VertexSet.new(r).flatten.uniq
+    end
+    
+    # Returns all outgoing edges of all vertices of this set
+    def out_edges(filter=nil, &block)
+      r = self.collect {|v| v.out_edges(filter, &block) }
+      EdgeSet.new(r).flatten.uniq
+    end
+
+    # Returns all forward-adjacent vertices reachable from this set
+    def out_adjacent(filter=nil, &block)
+      r = self.collect {|v| v.out_adjacent(filter, &block) }
+      VertexSet.new(r).flatten.uniq
+    end
+    
+    # Returns all adjacent vertices reachable from this set
+    def adjacent(filter=nil, &block)
+      (in_adjacent(filter, &block)+out_adjacent(filter, &block)).uniq
+    end
+    
+    
+    ### Protected section #####################################################
+    protected
+        
+    # Extends with VertexSet instead of ElementSet
+    def extend_result(result)
+      VertexSet.new(result)
+    end
+
+  end # module VertexSet
+
+end

data/lib/yargi.rb

@@ -0,0 +1,30 @@
+require 'yargi/predicate'
+
+module Yargi
+  
+  # Current Yargi version
+  VERSION = "0.1.0".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
+
+require 'yargi/markable'
+require 'yargi/digraph'
+require 'yargi/digraph_vertex'
+require 'yargi/digraph_edge'
+require 'yargi/element_set'
+require 'yargi/vertex_set'
+require 'yargi/edge_set'
+

data/test/test_all.rb

@@ -0,0 +1,8 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__),'..', 'lib'))
+require 'yargi'
+require 'test/unit'
+test_files = Dir[File.join(File.dirname(__FILE__), '**/*_test.rb')]
+test_files.each { |file|
+  require(file) 
+}
+

data/test/yargi/README-example.dot

@@ -0,0 +1,33 @@
+digraph G {
+  graph[]
+  V0 [shape="circle"label=""]
+  V1 [shape="circle"label=""]
+  V2 [shape="circle"label=""]
+  V3 [shape="circle"label=""]
+  V4 [shape="circle"label=""]
+  V0 -> V0 [label="From 0 to 0"]
+  V0 -> V1 [label="From 0 to 1"]
+  V0 -> V2 [label="From 0 to 2"]
+  V0 -> V3 [label="From 0 to 3"]
+  V0 -> V4 [label="From 0 to 4"]
+  V1 -> V0 [label="From 1 to 0"]
+  V1 -> V1 [label="From 1 to 1"]
+  V1 -> V2 [label="From 1 to 2"]
+  V1 -> V3 [label="From 1 to 3"]
+  V1 -> V4 [label="From 1 to 4"]
+  V2 -> V0 [label="From 2 to 0"]
+  V2 -> V1 [label="From 2 to 1"]
+  V2 -> V2 [label="From 2 to 2"]
+  V2 -> V3 [label="From 2 to 3"]
+  V2 -> V4 [label="From 2 to 4"]
+  V3 -> V0 [label="From 3 to 0"]
+  V3 -> V1 [label="From 3 to 1"]
+  V3 -> V2 [label="From 3 to 2"]
+  V3 -> V3 [label="From 3 to 3"]
+  V3 -> V4 [label="From 3 to 4"]
+  V4 -> V0 [label="From 4 to 0"]
+  V4 -> V1 [label="From 4 to 1"]
+  V4 -> V2 [label="From 4 to 2"]
+  V4 -> V3 [label="From 4 to 3"]
+  V4 -> V4 [label="From 4 to 4"]
+}

data/test/yargi/digraph_set_features_test.rb

@@ -0,0 +1,96 @@
+require 'test/unit'
+require 'yargi'
+
+module Yargi
+  
+  # Tests all set-based features on graphs
+  class DigraphSetFeaturesTest < Test::Unit::TestCase
+    
+    module Source; end
+    module Sink; end
+    module Additional; end
+    
+    # Installs the souce-sink graph example under @graph
+    def setup
+      @graph = Yargi::Digraph.new
+      sources = @graph.add_n_vertices(5, Source)
+      sinks = @graph.add_n_vertices(5, Sink)
+      @graph.connect(sources, sinks)
+    end
+    
+    def test_tag
+      @graph.vertices{|v| Source===v}.tag(Additional)
+      @graph.vertices.each {|v| assert_equal((Source===v), (Additional===v))}
+      assert @graph.vertices{|v| Source===v}.all?{|v|Additional===v}
+      assert @graph.vertices{|v| Sink===v}.all?{|v|not(Additional===v)}
+    end
+    
+    def test_set_and_get_mark
+      @graph.vertices{|v| Source===v}.set_mark(:kind, :source)
+      @graph.vertices{|v| Sink===v}.set_mark(:kind, :sink)
+      @graph.vertices.each do |v|
+        if Source===v
+          assert_equal :source, v.get_mark(:kind)
+        else
+          assert_equal :sink, v.get_mark(:kind)
+        end
+      end
+    end
+    
+    def test_add_marks
+      @graph.vertices{|v| Source===v}.add_marks(:kind => :source, :priority => 1.0)
+      @graph.vertices.each do |v|
+        if Source===v
+          assert_equal :source, v.kind
+          assert_equal 1.0, v.priority
+        end      
+      end
+    end
+    
+    def test_add_marks_with_block
+      @graph.vertices{|v| Source===v}.add_marks do |v|
+        v.set_mark(:test, true)
+        {:kind => :source, :priority => 1.0}
+      end
+      @graph.vertices{|v| Source===v}.all? do |v|
+        assert v.test==true 
+        assert_equal :source, v.kind
+        assert_equal 1.0, v.priority
+      end
+    end
+    
+    def test_add_marks_with_both
+      @graph.vertices{|v| Source===v}.add_marks(:test2 => false) do |v|
+        v.set_mark(:test, true)
+        {:kind => :source, :priority => 1.0}
+      end
+      @graph.vertices{|v| Source===v}.all? do |v|
+        assert v.test2==false
+        assert v.test==true
+        assert_equal :source, v.kind
+        assert_equal 1.0, v.priority
+      end
+    end
+    
+    def test_to_dot
+      @graph.vertices{|v|Source===v}.add_marks(:label => '', :shape => 'diamond', :fixedsize => true, :width => 0.5)
+      @graph.vertices{|v|Sink===v}.add_marks(:label => '', :shape => 'doublecircle', :fixedsize => true, :width => 0.5)
+      @graph.edges.add_marks do |e|
+        {:label => "from #{e.source.index} to #{e.target.index}"}
+      end
+      dir = File.expand_path(File.dirname(__FILE__))
+      dotfile = File.join(dir,"source-sink.dot")
+      gitfile = File.join(dir,"source-sink.gif")
+      File.open(dotfile, 'w') {|f| f << @graph.to_dot}
+      begin
+        `dot -Tgif -o #{gitfile} #{dotfile}`
+      rescue => ex
+        $STDERR << "dot test failed, probably not installed\n#{ex.message}"
+      end
+    end
+    
+    
+    
+  end # class DigraphSetFeaturesSet
+  
+end