graph_builder 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in graph_builder.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Thomas Sonntag
+
+MIT License
+
+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.md

@@ -0,0 +1,100 @@
+# GraphBuilder
+
+ DSL to build directed graphs
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'graph_builder'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install graph_builder
+
+## Usage
+
+GraphBuilder provides a DSL to build a graph of arbritary objects.
+
+The objects must implement 
+
+    link_to( other ) 
+
+which must implement a link between self and other.
+
+
+### Examples:
+
+#### A simple chain: a → b → c
+
+    GraphBuilder::Builder.build do |builder|
+       builder.add a 
+       builder.add b 
+       builder.add c 
+    end
+
+#### A simple branch: a → b, a → c
+
+    GraphBuilder::Builder.build do |builder|
+       builder.add a  
+       builder.branch do 
+         builder.add b 
+         builder.add c 
+       end
+    end
+
+#### Diamond shaped graph: a → l → b,  a → r → b
+
+    GraphBuilder::Builder.build do |builder|
+       builder.add a  
+       builder.branch do 
+         builder.add l 
+         builder.add r 
+       end
+       builder.add b  
+    end
+
+#### Diamond with chains: a →  l1 → l2 → b, a →  r1 → r2 → r3 → b 
+
+    GraphBuilder::Builder.build do |builder|
+       builder.add a  
+       builder.branch do 
+         builder.chain do 
+           builder.add l1
+           builder.add l2
+         end
+         builder.chain do 
+           builder.add r1
+           builder.add r2
+           builder.add r3
+         end
+       end
+       builder.add b  
+    end
+
+### Implemention of #link_to 
+
+graph_builder comes with the module GraphBuilder::Linkable which implements
+
+    # links self to other
+    link_to( other ) 
+
+    # returns an array of objects self is linked to
+    link_to
+
+    # returns an array of pairs [ [ self, other1 ], [ self, other2 ], ... ]
+    # for linked objects other1,  other2, ...
+    links
+    
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/graph_builder.gemspec

@@ -0,0 +1,17 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/graph_builder/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Thomas Sonntag"]
+  gem.email         = ["git@sonntagsbox.de"]
+  gem.description   = %q{DSL for building directed graphs}
+  gem.summary       = %q{DSL for building directed graphs}
+  gem.homepage      = ""
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "graph_builder"
+  gem.require_paths = ["lib"]
+  gem.version       = GraphBuilder::VERSION
+end

data/lib/graph_builder/linkable.rb

@@ -0,0 +1,17 @@
+module GraphBuilder
+  module Linkable
+
+    def link_to other
+      linked_to << other
+    end
+
+    def linked_to
+      @linked_to ||= []
+    end
+
+    def links
+      linked_to.map{|to|[self,to]}
+    end
+
+  end
+end

data/lib/graph_builder/version.rb

@@ -0,0 +1,3 @@
+module GraphBuilder
+  VERSION = "1.0.0"
+end

data/lib/graph_builder.rb

@@ -0,0 +1,203 @@
+module GraphBuilder
+  class BuilderError < StandardError; end
+
+  DEBUG = false
+
+  # implements an AND/OR tree
+  # An Branch represents a branch 
+  # An Chain represents a chain
+  # A Leaf contains a thing
+  class Base
+    attr_reader :parent, :opts, :children
+
+    def initialize parent, opts = {}
+      @parent, @opts, @children = parent, opts, []
+    end
+
+    def process; children.each &:process; end
+    def empty?;  children.all? &:empty?;  end
+
+    def dump recursive = true
+      debug{self.to_s} or return false
+      children.each{|c|c.dump(recursive)} if recursive
+    end
+
+    def debug &proc 
+      DEBUG or return false
+      puts indent + proc.call
+      true
+    end
+
+    def indent;    "   " * depth;   end    
+    def depth;     ancestors.count; end
+    def ancestors; parent ? parent.ancestors << parent : [];  end
+  end
+
+  class Node < Base
+    def add_leaf child
+      add_node Leaf.new(self,child)
+    end
+
+    def add_node node
+      @children << node
+      node
+    end
+
+    def to_s
+      "[#{self.class.name.split('::').last},empty?=#{empty?},f=#{first_things},l=#{last_things}]"
+    end
+
+  end
+  
+  class Leaf < Base
+    attr_reader :thing
+    def initialize parent, thing
+      @thing = thing
+      super parent
+    end
+
+    def empty?;       false;         end
+    def last_things;  thing;         end
+    def first_things; thing;         end
+    def to_s;         "[#{thing}]";  end
+  end
+
+  class Chain < Node
+    def last_things;   children.map(&:last_things).last;   end
+    def first_things;  children.map(&:first_things).first; end
+
+    def process
+      children.each &:process
+
+      debug{"processing #{self}"}
+      debug{"       children: #{children.map(&:to_s).join(',')}" }
+      
+      # Connect the pairs of a chain:
+      # connect all last_things of child with the first_things of the following child
+      children.each_cons(2) do |pair|
+        debug{"       pair: (#{pair.first},#{pair.last})"}
+        froms = [pair.first.last_things].flatten
+        tos   = [pair.last.first_things].flatten
+        debug{"       froms= last_things of #{pair.first}: #{froms.map(&:to_s).join(',')}"}
+        debug{"       tos=  first_things of #{pair.last}:  #{tos.map(&:to_s).join(',')}"}
+        tos.each do |to|
+          froms.each do |from|
+            debug{"       link from=#{from} to=#{to}"}
+            from.link_to to 
+          end
+        end
+      end
+    end
+
+  end
+
+  class Branch < Node
+    def last_things;   children.map &:last_things;  end
+    def first_things;  children.map &:first_things; end
+  end
+
+  class Builder
+    def self.build opts={}, &proc
+      b = new opts
+      proc.call b
+      b.send :process
+    end
+
+    attr_reader :logger
+    
+    def initialize opts = {}
+      @cur = @root = Chain.new(nil)
+      @logger = opts.delete(:logger)
+      @opts = opts # global opts
+      debug{"initialize"}
+      dump_tree
+    end
+
+    def add thing
+      raise InvalidBlockError if block_given?
+      add_thing thing
+    end
+
+    def chain  opts = {}, &proc ;  node Chain,  opts, proc; end
+    def branch opts = {}, &proc ;  node Branch, opts, proc; end
+    
+    alias_method :with, :chain
+
+    # yield each child of the children of the recent thing
+    def children opts = {}
+      debug{">> children"}
+      debug{"children: @cur=#{@cur}, last_things=#{@cur.last_things}"}
+      recent_things = [@cur.last_things].flatten
+      unless recent_things.size == 1
+        raise BuilderError, "invalid recent_thing #{recent_things}, @cur=#{@cur}. children() expects one recent thing"
+      end
+      recent_thing = recent_things.first
+      unless recent_thing.resource
+        raise BuilderError, "no resource for recent_thing #{recent_thing}"
+      end
+
+      debug{"children: resource=#{recent_thing.resource}"}
+
+      branch opts do
+        recent_thing.children.map do |child|
+          chain(opts.merge(:resource => child)){ yield child }
+        end
+      end
+      debug{"<< children"}
+    end
+
+    def options opts
+      res = @opts.merge(@cur.opts).merge(opts)
+      debug{"options: opts=#{opts.inspect}, current.opts=#{@cur.opts.inspect}, @opts=#{@opts}, options=#{res.inspect}"}
+      res
+    end
+
+    # set or get global opt
+    def global_opt key,value
+      if value
+        @opts[key] = value
+      else
+        @opts[key] 
+      end
+    end
+
+    private
+
+    # perform block with given opts
+    def node clazz, opts, proc
+      debug{">> #{clazz}"}
+      # push 
+      prev = @cur
+      @cur = clazz.new(prev,opts)
+      proc.call
+      debug{"-- @cur=#{@cur}"}
+      prev.add_node @cur unless @cur.empty?
+      # pop
+      raise BuilderError, "stack error: no parent for @cur = #{@cur}" unless @cur.parent
+      @cur = prev
+      dump_tree
+      debug{"<< #{clazz}"}
+    end
+
+    def process
+      @root.process
+    end
+
+    def add_thing thing
+      @cur.add_leaf thing
+      debug{"add_thing #{thing}"}
+      dump_tree
+      thing
+    end
+
+    def dump_tree
+      @root.debug{"*** whole tree ***"} or return
+      @root.dump true
+      @root.debug{'**************'}
+    end
+
+    def debug
+      @root.debug{yield}
+    end
+  end
+end

data/test/graph_builder_test.rb

@@ -0,0 +1,311 @@
+$:.unshift File.expand_path( '../lib/', File.dirname( __FILE__))
+
+require 'minitest/autorun'
+
+require 'graph_builder'
+require 'graph_builder/linkable'
+
+class MyResource
+  attr_reader :children, :name
+
+  def initialize(name, children = [])
+    @name, @children = name, children
+  end
+
+  def to_s
+    name
+  end
+end
+
+class Thing
+  include GraphBuilder::Linkable
+
+  attr_reader :resource
+  
+  def initialize resource=nil
+    @resource = resource
+  end
+
+  def children
+    resource.children
+  end
+
+  def self.links(things)
+    things.inject([]) {|res,t| r = t.links; res +=r unless r.empty?; res }
+  end
+
+  def self.links_s(things)
+    links(things).map{|r|"#{r.first}=>#{r.last}"}.join(",")
+  end
+
+  def to_s
+    s = "#{self.class}"
+    s += "(#{resource})" if resource
+    s
+  end
+end
+
+class Thing0 < Thing; end
+class Thing1 < Thing; end
+class Thing2 < Thing; end
+class Thing3 < Thing; end
+class Thing4 < Thing; end
+class Thing11 < Thing; end
+class Thing12 < Thing; end
+class Thing21 < Thing; end
+class Thing22 < Thing; end
+class Thing23 < Thing; end
+class Thing31 < Thing; end
+class Thing32 < Thing; end
+class ThingT < Thing; end
+class TestThing < Thing; end
+class ThingA < Thing; end
+class ThingB < Thing; end
+
+class GraphBuilderTest < MiniTest::Unit::TestCase
+
+  # thing1 -> thing2 -> TestThing
+  def test_simple
+    #puts "---------------test_simple-----------------"
+    t1= Thing1.new
+    t2 = nil
+    tt = nil
+    GraphBuilder::Builder.build do |b|
+      b.add t1
+      assert (nil != t2 = b.add(Thing2.new))
+      assert_instance_of Thing2, t2
+      assert (nil != tt = b.add(TestThing.new))
+      assert_instance_of TestThing, tt
+    end
+
+    r = Thing.links([t1,t2,tt])
+    assert_equal 2, r.size
+    assert r.include? [t1,t2]
+    assert r.include? [t2,tt]
+  end
+
+  # thing1
+  def test_empty
+    #puts "---------------test_empty-----------------"
+    t1 = nil
+    GraphBuilder::Builder.build do |b|
+      t1 = b.add(Thing1.new)
+    end
+
+    r = Thing.links([t1])
+    assert_equal 0, r.size
+  end
+
+  # t1 -> (t2 -> t3) -> t4
+  def test_chain
+    #puts "---------------test_chain-----------------"
+
+    t1 = t2 = t3 = t4 = nil
+    GraphBuilder::Builder.build do |b|
+      t1 = b.add(Thing1.new)
+      b.chain do
+        t2 = b.add(Thing2.new)
+        t3 = b.add(Thing3.new)
+      end
+      t4 = b.add(Thing4.new)
+    end
+
+    r = Thing.links([t1,t2,t3,t4])
+    assert_equal 3, r.size
+    assert r.include? [t1,t2]
+    assert r.include? [t2,t3]
+    assert r.include? [t3,t4]
+  end
+
+  # t1 -> () -> t4
+  def test_empty_chain
+    #puts "---------------test_chain-----------------"
+
+    t1 = t2 = t3 = t4 = nil
+    GraphBuilder::Builder.build do |b|
+      t1 = b.add(Thing1.new)
+      b.chain do
+      end
+      t4 = b.add(Thing4.new)
+    end
+
+    r = Thing.links([t1,t4])
+    assert_equal 1, r.size
+    assert r.include? [t1,t4]
+  end
+
+  # t1 -> t11 -> t2, t1 -> t12 -> t2
+  def test_branch
+    #puts "---------------test_branch-----------------"
+    t1= nil
+    t2 = nil
+    t11 = nil
+    t12 = nil
+    GraphBuilder::Builder.build do |b|
+      t1 = b.add(Thing1.new)
+      b.branch do 
+        t11 = b.add(Thing11.new)
+        t12 = b.add(Thing12.new)
+      end
+      t2 = b.add(Thing2.new)
+    end
+
+    r = Thing.links([t1,t2,t11,t12])
+    assert_equal 4, r.size
+    assert r.include? [t1,t11]
+    assert r.include? [t1,t12]
+    assert r.include? [t11,t2]
+    assert r.include? [t12,t2]
+  end
+
+  # t1 -> (empty) -> t2
+  def test_empty_branch
+    #puts "---------------test_branch-----------------"
+    t1 = t2 = nil
+    GraphBuilder::Builder.build do |b|
+      t1 = b.add(Thing1.new)
+      b.branch do 
+      end
+      t2 = b.add(Thing2.new)
+    end
+
+    r = Thing.links([t1,t2])
+    assert_equal 1, r.size
+    assert r.include? [t1,t2]
+  end
+
+  # t1 -> t11 -> t12 -> t2,    t1 -> t21 -> t22 -> t2
+  def test_branch_chain
+    #puts "---------------test_branch_chain-----------------"
+
+    t1= t2 = t11 = t12 = t21 = t22 = nil
+    GraphBuilder::Builder.build do |b|
+      t1 = b.add(Thing1.new)
+      b.branch do
+        b.chain do
+          t11 = b.add(Thing11.new)
+          t12 = b.add(Thing12.new)
+        end
+        b.chain do
+          t21 = b.add(Thing21.new)
+          t22 = b.add(Thing22.new)
+        end
+      end
+      t2 = b.add(Thing2.new)
+    end
+
+    r = Thing.links([t1,t2,t11,t12,t21,t22])
+    assert r.include? [t1,t11]
+    assert r.include? [t11,t12]
+    assert r.include? [t12,t2]
+
+    assert r.include? [t1,t21]
+    assert r.include? [t21,t22]
+    assert r.include? [t22,t2]
+
+    assert_equal 6, r.size
+  end
+
+  # t1 -> t11 -> t12 -> t2,   t1 -> t21 -> t23 -> t2,    t1 -> t31 -> t32 -> t23 -> t2
+  def test_branch_chain2
+    #puts "---------------test_branch_chain2-----------------"
+
+    t1= t2 = t11 = t12 = t21 = t23 = t31 = t32 = nil
+    GraphBuilder::Builder.build do |b|
+      t1 = b.add(Thing1.new)
+      b.branch do
+        b.chain do
+          t11 = b.add(Thing11.new)
+          t12 = b.add(Thing12.new)
+        end
+        b.chain do
+          b.branch do
+            t21 = b.add(Thing21.new)
+            b.chain do
+              t31 = b.add(Thing31.new)
+              t32 = b.add(Thing32.new)
+            end
+          end
+          t23 = b.add(Thing23.new)
+        end
+      end
+      t2 = b.add(Thing2.new)
+    end
+
+    r = Thing.links([t1,t2,t11,t12,t21,t23,t31,t32])
+    assert r.include? [t1,t11]
+    assert r.include? [t1,t21]
+    assert r.include? [t1,t31]
+
+    assert r.include? [t11,t12]
+    assert r.include? [t12,t2]
+
+    assert r.include? [t21,t23]
+    assert r.include? [t23,t2]
+
+    assert r.include? [t31,t32]
+    assert r.include? [t32,t23]
+
+    assert_equal 9, r.size
+  end
+
+
+  # t0(order) -> t1(pos1) -> t11(batch11) -> t12(batch11) -> t2(order)
+  # t0(order) -> t1(pos1) -> t11(batch12) -> t12(batch12) -> t2(order)
+  # t0(order) -> t1(pos2) -> t11(batch21) -> t12(batch21) -> t2(order)
+  # t0(order) -> t1(pos2) -> t11(batch22) -> t12(batch22) -> t2(order)
+  def test_children
+    #puts "---------------test_children-----------------"
+    t= {}
+
+    batch11 = MyResource.new :batch11
+    batch12 = MyResource.new :batch12
+    batch21 = MyResource.new :batch21
+    batch22 = MyResource.new :batch22
+    pos1 = MyResource.new :pos1, [ batch11, batch12 ]
+    pos2 = MyResource.new :pos2, [ batch21, batch22 ]
+    order = MyResource.new :order, [pos1, pos2]
+
+    GraphBuilder::Builder.build do |b|
+      t[:order] = [ b.add(Thing0.new(order)) ]
+      
+      b.children do |pos|
+        t[pos.name] = b.add Thing1.new(pos)
+        b.children do |batch|
+          b1 = b.add Thing11.new(batch)
+          b2 = b.add Thing12.new(batch)
+          t[batch.name] = [b1, b2]
+        end
+      end
+      t[:order] << b.add( Thing2.new(order))
+    end
+
+    r = Thing.links(t.values.flatten)
+    assert_instance_of Thing0, t[:order].first
+    assert_instance_of Thing2, t[:order].last
+    assert_instance_of Thing1, t[:pos1]
+    assert_instance_of Thing1, t[:pos2]
+    assert_instance_of Thing11, t[:batch11].first
+    assert_instance_of Thing12, t[:batch12].last
+    assert_instance_of Thing11, t[:batch21].first
+    assert_instance_of Thing12, t[:batch22].last
+
+    assert r.include? [t[:order].first,t[:pos1]]
+    assert r.include? [t[:order].first,t[:pos2]]
+    assert r.include? [t[:pos1],t[:batch11].first]
+    assert r.include? [t[:pos1],t[:batch12].first]
+    assert r.include? [t[:pos2],t[:batch21].first]
+    assert r.include? [t[:pos2],t[:batch22].first]
+    assert r.include? [t[:batch11].first,t[:batch11].last]
+    assert r.include? [t[:batch12].first,t[:batch12].last]
+    assert r.include? [t[:batch21].first,t[:batch21].last]
+    assert r.include? [t[:batch22].first,t[:batch22].last]
+    assert r.include? [t[:batch11].last,t[:order].last]
+    assert r.include? [t[:batch12].last,t[:order].last]
+    assert r.include? [t[:batch21].last,t[:order].last]
+    assert r.include? [t[:batch22].last,t[:order].last]
+
+    assert_equal 14, r.size
+  end
+
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: graph_builder
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Thomas Sonntag
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-06-04 00:00:00.000000000 Z
+dependencies: []
+description: DSL for building directed graphs
+email:
+- git@sonntagsbox.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- graph_builder.gemspec
+- lib/graph_builder.rb
+- lib/graph_builder/linkable.rb
+- lib/graph_builder/version.rb
+- test/graph_builder_test.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: DSL for building directed graphs
+test_files: []