traversal 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+.idea
+Gemfile.lock
+pkg/*
+coverage/*

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in traversal.gemspec
+gemspec
+
+group :development do
+  gem 'rspec'
+  gem 'simplecov'
+end

data/README.rdoc

@@ -0,0 +1,96 @@
+== Synopsys
+Simple traversal API for pure Ruby objects. Also it can be used it with ActiveRecord or DataMapper (or any other ORM).
+
+== Installation
+Install it via rubygems:
+  gem install traversal
+
+In your Gemfile:
+  gem 'traversal'
+
+== Usage
+Imagine tree(-ish) structure:
+  plants:
+    vegetables:
+      - cucumber
+      - tomato
+    fruits:
+      - apple
+      - banana
+
+In Ruby it'll look like this:
+  class Node
+    attr_reader :name, :children
+
+    def initialize(name)
+      @name = name
+      @children = []
+    end
+  end
+
+  # lets recreate tree structure from above
+  root     = Node.new('plants')
+  veg      = Node.new('vegetables')
+  fruits   = Node.new('fruits')
+  cucumber = Node.new('cucumber')
+  tomato   = Node.new('tomato')
+  apple    = Node.new('apple')
+  banana   = Node.new('banana')
+
+  root.children << veg << fruits
+  veg.children << cucumber << tomato
+  fruits.children << apple << banana
+
+So, we have a simple tree with <code>root</code> element on the top of it.
+Now let's create a <b>traversal description</b>.
+  require 'traversal'
+
+  traversal = Traversal::Description.new
+  traversal.traverse(root).    # start from root node
+            follow(:children)  # move forward via children relations
+
+It's a minimal traversal description. It has <b>start node</b> and <b>relation</b> pointer (<code>children</code>, in this case).
+Traversal description is <code>Enumerable</code> object. Let's examine our traverse:
+  traversal.map { |n| n.name } # should be equal to [root, vegetables, cucumber, tomato, fruits, apple, banana]
+
+Let's look closer:
+1. We are starting from <code>root</code> node. It's first element.
+2. Traversal cursor moves to the first child of <code>root</code>: <code>vegetables</code>
+3. By default cursor moves deeper, to first child of <code>vegetables</code> node: <code>cucumber</code>
+4. <code>cucumber</code> has no children, traversal cursor moves to the next child of <code>vegetables</code>: <code>tomato</code>
+5. Traversal cursor moves to the next child of <code>root</code> - <code>fruits</code>
+6. Traversal cursor visits children of <code>fruits</code>: <code>apple</code> and <code>banana</code>
+7. All nodes are visited, cursor closed.
+
+If you want the cursor to visit all children before visiting grandchildren, then you have to declare <code>breadth_first</code> traversal visiting strategy:
+  traversal.breadth_first # in opposite of traversal.depth_first
+
+You can exclude nodes (but allow cursor to follow relations) from final result:
+  traversal.exclude { |node| node.children.length > 0 } # all nodes with children will be excluded from result
+
+You can prune away any node children (but leave the node in final result):
+  traversal.prune { |node| node.name == "vegetables" }.
+            map(&:name) # will produce [root, vegetables, fruits, apple, banana]
+
+Or, you can exclude node and prune away it's children:
+  traversal.prune_and_exclude { |node| node.name == "vegetables" }.
+            map(&:name) # will produce [root, fruits, apple, banana]
+
+Also, you can mark any node as "loop terminator":
+  traversal.stop_before { |node| node.name == "vegetables" }.to_a # will produce only [root]
+  traversal.stop_after { |node| node.name == "vegetables" }.to_a # will produce [root, vegetables]
+
+== Real world example
+  require "traversable"
+
+  class Page < ActiveRecord::Base
+    acts_as_tree
+    acts_as_traversable
+  end
+
+  lim = 15
+
+  Page.root.traverse(:children).
+            exclude(:root?).
+            exclude_and_prune(:is_deleted?).
+            stop_after { (lmt -= 1) == 0 }

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/traversal.rb

@@ -0,0 +1,11 @@
+require "traversal/version"
+
+module Traversal
+  autoload :Description,       "traversal/description"
+  autoload :Iterator,          "traversal/iterator"
+  autoload :ActsAsTraversable, "traversal/acts_as_traversable"
+
+  class IncompleteDescription < Exception; end
+end
+
+Object.extend(Traversal::ActsAsTraversable)

data/lib/traversal/acts_as_traversable.rb

@@ -0,0 +1,39 @@
+module Traversal
+  module ActsAsTraversable
+    # == Synopsys
+    # Mix-in <tt>#traverse</tt> method
+    #
+    # == Example
+    #   class TreeNode
+    #     attr_accessor :siblings
+    #
+    #     acts_as_traversable
+    #   end
+    #
+    #   t = TreeNode.new
+    #   t.traverse            # equivalent to Traversal::Description.new.traverse(t)
+    #   t.traverse(:siblings) # equivalent to Traversal::Description.new.traverse(t).follow(:siblings)
+    def acts_as_traversable
+      include InstanceMethods
+    end
+    alias acts_like_traversable acts_as_traversable
+
+    module InstanceMethods
+      # Shortcut method, simplified interface to Traversal::Description
+      #
+      # == Example
+      #   class TreeNode
+      #     attr_accessor :siblings
+      #
+      #     acts_as_traversable
+      #   end
+      #
+      #   t = TreeNode.new
+      #   t.traverse            # equivalent to Traversal::Description.new.traverse(t)
+      #   t.traverse(:siblings) # equivalent to Traversal::Description.new.traverse(t).follow(:siblings)
+      def traverse(relation = nil)
+        Traversal::Description.new.traverse(self).tap { |desc| desc.follow(relation) if relation }
+      end
+    end
+  end
+end

data/lib/traversal/description.rb

@@ -0,0 +1,133 @@
+# coding: utf-8
+module Traversal
+  # Traversal description
+  class Description
+    include Enumerable
+
+    DEPTH_FIRST = 0
+    BREADTH_FIRST = 1
+
+    attr_reader :start_node, :relation
+
+    # Create blank traversal description
+    def initialize
+      @exclude = []
+      @prune = []
+      @stop_before = []
+      @stop_after = []
+
+      @start_node = nil
+      @relation = nil
+
+      @order = DEPTH_FIRST
+    end
+
+    # Declare a traversal start point. From which node you want to follow relations?
+    def traverse(start_node)
+      tap { @start_node = start_node }
+    end
+
+    # Declare which relation you want to follow in your traversal.
+    # It can be Symbol, Method, Proc or block.
+    #
+    # Relation should return something enumerable, otherwise it will be ignored in traversal.
+    #
+    # == Example
+    #   traversal.follow(:children)               # for each node will call node#children method
+    #   traversal.follow { |node| node.children } # same effect
+    def follow(relation = nil, &blk)
+      tap { @relation = condition("Relation", relation, &blk) }
+    end
+
+    # Declare exclude condition. Which nodes you want to
+    # exclude (ignore them but not their relations) from your traversal?
+    def exclude(cond = nil, &blk)
+      tap { @exclude << condition("Exclude condition", cond, &blk) }
+    end
+
+    # Declare prune condition. Which nodes relations you want to ignore?
+    #
+    # Example:
+    #   traversal.follow(:children).
+    #   prune { |node| node.name == "A" } # node "A" will be included, but not its children
+    def prune(cond = nil, &blk)
+      tap { @prune << condition("Prune condition", cond, &blk) }
+    end
+
+    # Declare exclude AND prune condition.
+    # Matching node and its relations will be excluded from traversal.
+    def exclude_and_prune(cond = nil, &blk)
+      exclude(cond, &blk)
+      prune(cond, &blk)
+    end
+    alias prune_and_exclude exclude_and_prune
+
+    # Declare +stop pre-condition+.
+    # When met, matched node will be excluded from traversal and iteration will be stopped.
+    def stop_before(cond = nil, &blk)
+      tap { @stop_before << condition("Stop condition", cond, &blk) }
+    end
+
+    # Declare +stop post-condition+.
+    # When met, matched node will be included in traversal and iteration will be stopped.
+    def stop_after(cond = nil, &blk)
+      tap { @stop_after << condition("Stop condition", cond, &blk) }
+    end
+
+    # Declare traversal order strategy as +depth first+
+    def depth_first
+      tap { @order = DEPTH_FIRST }
+    end
+
+    # Declare traversal order strategy as +breadth first+
+    def breadth_first
+      tap { @order = BREADTH_FIRST }
+    end
+
+    def each
+      assert_complete_description
+
+      iter = Traversal::Iterator.new(self)
+
+      if iterator?
+        iter.each do |node|
+          yield node
+        end
+      else
+        iter
+      end
+    end
+
+    # Predicates section
+
+    # Does node matches one of stop conditions?
+    def stop?(node, type = :before) #:nodoc:
+      (type == :after ? @stop_after : @stop_before).any? { |cond| cond[node] }
+    end
+
+    def exclude?(node) #:nodoc:
+      @exclude.any? { |cond| cond[node] }
+    end
+
+    def prune?(node) #:nodoc:
+      @prune.any? { |cond| cond[node] }
+    end
+
+    def breadth_first? #:nodoc:
+      @order == BREADTH_FIRST
+    end
+
+    private
+    def condition(name, arg, &blk) #:nodoc:
+      raise TypeError, "#{name} must be Symbol, Method, Proc or block" unless
+          (arg ||= blk).respond_to?(:to_proc)
+
+      arg.to_proc
+    end
+
+    def assert_complete_description #:nodoc:
+      raise IncompleteDescription, "Traversal description should contain start node. Use #traverse method" unless @start_node
+      raise IncompleteDescription, "Traversal description should contain relation. Use #follow method" unless @relation
+    end
+  end
+end

data/lib/traversal/iterator.rb

@@ -0,0 +1,90 @@
+# coding: utf-8
+
+require "enumerator"
+
+module Traversal
+  # Traversal iterator.
+  class Iterator < Enumerator
+    # Create new traversal iterator from traversal description
+    def initialize(description)
+      raise TypeError,
+            'Traversal::Description expected, %s given' % description.class.name \
+            unless description.is_a?(Traversal::Description)
+
+      @description = description
+      start_node = @description.start_node
+
+      # Create Enumerator
+      super() do |yielder|
+        @yielder = yielder
+
+        begin
+          yield_node(start_node)
+
+          expand_node(start_node)
+        rescue StopIteration
+          # ignore
+        end
+      end
+    end
+
+    private
+    def push(*args) #:nodoc:
+      @yielder.yield(*args)
+    end
+
+    def yield_node(node) #:nodoc:
+      # check stop pre-condition
+      raise StopIteration if @description.stop?(node, :before)
+
+      # do yield
+      push(node) unless @description.exclude?(node)
+
+      # check stop post-condition
+      raise StopIteration if @description.stop?(node, :after)
+    end
+
+    # Expand node
+    def expand_node(node) #:nodoc:
+      if @description.breadth_first?
+        expand_breadth(node)
+      else
+        expand_depth(node)
+      end
+    end
+
+    # Expand node with DEPTH_FIRST strategy
+    def expand_depth(node) #:nodoc:
+      relations_for(node).each do |rel|
+        yield_node(rel)
+
+        expand_node(rel) unless @description.prune?(rel)
+      end
+    end
+
+    # Expand node with BREADTH_FIRST strategy
+    def expand_breadth(node) #:nodoc:
+      cached_relations = []
+
+      # 1. yield direct relations first
+      relations_for(node).each do |rel|
+        yield_node(rel)
+
+        # memoize relation for next iteration
+        cached_relations << rel unless @description.prune?(rel)
+      end
+
+      # 2. dig deeper
+      cached_relations.each do |rel|
+        expand_breadth(rel)
+      end
+    end
+
+    # Expand relations for node
+    def relations_for(node) #:nodoc:
+      relation = @description.relation[node]
+
+      relation.is_a?(Enumerable) ? relation : []
+    end
+  end
+end

data/lib/traversal/version.rb

@@ -0,0 +1,3 @@
+module Traversal
+  VERSION = "0.0.1"
+end

data/spec/test_helper.rb

@@ -0,0 +1,8 @@
+require "rubygems"
+require "bundler"
+Bundler.setup
+
+require 'simplecov'
+
+SimpleCov.start
+require "traversal"

data/spec/traversal_spec.rb

@@ -0,0 +1,151 @@
+require File.expand_path('../test_helper', __FILE__)
+
+# Tree structure:
+#
+#         +root+
+#        /     \
+#      +a+     +b+
+#      / \       \
+#   +c+  +d+     +f+
+#  /             / \
+# +e+         +g+  +h+
+
+class Node
+  attr_accessor :children
+  attr_accessor :level
+  attr_accessor :id
+  acts_as_traversable
+
+  def initialize(id, level)
+    @id = id
+    @level = level
+    @children = []
+  end
+
+  def inspect
+    "#<Node: #{id.to_s}>"
+  end
+end
+
+# create tree
+root = Node.new(0, 0)
+a    = Node.new(1, 1)
+b    = Node.new(2, 1)
+c    = Node.new(3, 2)
+d    = Node.new(4, 2)
+e    = Node.new(5, 3)
+f    = Node.new(6, 2)
+g    = Node.new(7, 3)
+h    = Node.new(8, 3)
+
+# link nodes
+root.children << a << b
+a.children << c << d
+c.children << e
+b.children << f
+f.children << g << h
+
+describe Traversal do
+  let(:iter) { Traversal::Description.new }
+
+  it "should traverse all descendants" do
+    # traverse whole tree, with default strategy (depth first)
+    iter.follow(:children).
+         traverse(root).
+         to_a.
+         should eq([root, a, c, e, d, b, f, g, h])
+  end
+
+  it "should exclude some nodes" do
+    # this traverse will exclude only +c+ node, but not it's children
+    iter.traverse(root).
+         follow(:children).
+         exclude { |node| node == c }.
+         to_a.should eq([root, a, e, d, b, f, g, h])
+  end
+
+  it "should disjunct excludes" do
+    # this traverse will exclude +c+ and +d+ nodes, but not their children
+    iter.traverse(root).
+         follow(:children).
+         exclude { |node| node == c }.
+         exclude { |node| node == d }.
+         to_a.should eq([root, a, e, b, f, g, h])
+  end
+
+  it "should prune some nodes" do
+    # this traverse will exclude all +c+ children
+    iter.traverse(root).
+         follow(:children).
+         prune { |node| node == c }.
+         to_a.should eq([root, a, c, d, b, f, g, h])
+  end
+
+  it "should disjunct prunes" do
+    # this traverse will exclude all +c+ and +f+ children
+    iter.traverse(root).
+         follow(:children).
+         prune { |node| node == c }.
+         prune { |node| node == f }.
+         to_a.should eq([root, a, c, d, b, f])
+  end
+
+  it "should exclude and prune some nodes" do
+    # this traverse will exclude +c+ and its children
+    iter.traverse(root).
+         follow(:children).
+         exclude_and_prune { |node| node == c }.
+         to_a.should eq([root, a, d, b, f, g, h])
+  end
+
+  it "should stop traversal after some condition met" do
+    # this traversal will stop after visiting +d+ node
+    iter.traverse(root).
+         follow(:children).
+         stop_after { |node| node == d }.
+         to_a.should eq([root, a, c, e, d])
+  end
+
+  it "should stop traversal before some condition met" do
+    # this traversal will stop before visiting +d+ node
+    iter.traverse(root).
+         follow(:children).
+         stop_before { |node| node == d }.
+         to_a.should eq([root, a, c, e])
+  end
+
+  it "should traverse with depth_first strategy" do
+    iter.traverse(root).
+         follow(:children).
+         depth_first.
+         exclude { |node| node.level == 3 }.
+         to_a.should eq([root, a, c, d, b, f])
+  end
+
+  it "should traverse with breadth_first strategy" do
+    iter.traverse(root).
+         follow(:children).
+         breadth_first.
+         exclude { |node| node.level == 3 }.
+         to_a.should eq([root, a, b, c, d, f])
+  end
+
+  it "should raise exception when no start node given" do
+    lambda { iter.follow(:children).to_a }.should raise_error(Traversal::IncompleteDescription)
+  end
+
+  it "should raise exception when no relations given" do
+    lambda { iter.traverse(root).to_a }.should raise_error(Traversal::IncompleteDescription)
+  end
+
+  it "should have shortcut" do
+    root.should respond_to(:traverse)
+
+    root.traverse(:children).count.should eq(9)
+  end
+
+  it "should return Enumerable when called without block" do
+    iter.traverse(root).follow(:children).each.should be_a(Enumerable)
+
+  end
+end

data/traversal.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "traversal/version"
+
+Gem::Specification.new do |s|
+  s.name        = "traversal"
+  s.version     = Traversal::VERSION
+  s.authors     = ["Alexey Mikhaylov"]
+  s.email       = ["amikhailov83@gmail.com"]
+  s.homepage    = "https://github.com/take-five/traversal"
+  s.summary     = %q{Simple traversal API for pure Ruby objects}
+  s.date        = "2012-01-22"
+
+  s.rubyforge_project = "traversal"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "simplecov"
+  # s.add_runtime_dependency "rest-client"
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification 
+name: traversal
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Alexey Mikhaylov
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-01-22 00:00:00 +06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: simplecov
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: 
+email: 
+- amikhailov83@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.rdoc
+- Rakefile
+- lib/traversal.rb
+- lib/traversal/acts_as_traversable.rb
+- lib/traversal/description.rb
+- lib/traversal/iterator.rb
+- lib/traversal/version.rb
+- spec/test_helper.rb
+- spec/traversal_spec.rb
+- traversal.gemspec
+has_rdoc: true
+homepage: https://github.com/take-five/traversal
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: traversal
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Simple traversal API for pure Ruby objects
+test_files: []
+