traversal 0.0.1 → 0.0.2

data/lib/traversal/acts_as_traversable.rb

@@ -31,8 +31,8 @@ module Traversal
       #   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 }
+      def traverse(*relations)
+        Traversal::Description.new.traverse(self).tap { |desc| desc.follow(*relations) unless relations.empty? }
       end
     end
   end

data/lib/traversal/description.rb

@@ -1,25 +1,49 @@
 # coding: utf-8
+
+require "forwardable"
+
 module Traversal
   # Traversal description
   class Description
+    class EmptyArgument; end
+
+    extend Forwardable
     include Enumerable
 
     DEPTH_FIRST = 0
     BREADTH_FIRST = 1
 
-    attr_reader :start_node, :relation
+    attr_reader :start_node, :relations
+    def_delegators :each, :[], :at, :empty?,
+                          :fetch, :find_index, :index,
+                          :last, :reverse, :values_at
 
     # Create blank traversal description
     def initialize
-      @exclude = []
-      @prune = []
-      @stop_before = []
-      @stop_after = []
+      @exclude        = []
+      @include_only   = []
+
+      @prune          = []
+      @expand_only    = []
+      @stop_before    = []
+      @stop_after     = []
 
-      @start_node = nil
-      @relation = nil
+      @start_node     = nil
+      @relations      = []
 
-      @order = DEPTH_FIRST
+      @order          = DEPTH_FIRST
+      @uniq           = true
+    end
+
+    # Tests equality of traversal descriptions
+    def ==(other)
+      return super unless other.is_a?(Description)
+
+      [:@start_node, :@relations, :@include_only,
+       :@exclude, :@prune, :@stop_before, :@uniq,
+       :@stop_after, :@order, :@expand_only].all? do |sym|
+        instance_variable_get(sym) == other.instance_variable_get(sym)
+      end
     end
 
     # Declare a traversal start point. From which node you want to follow relations?
@@ -35,14 +59,34 @@ module 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) }
+    def follow(*relations, &blk)
+      raise ArgumentError, 'arguments or block expected' if relations.empty? && !block_given?
+
+      tap do
+        relations << blk if block_given?
+
+        relations.each do |relation|
+          @relations << condition(relation)
+        end
+        #@relations = condition(*relations, &blk)
+      end
     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) }
+    def exclude(*nodes, &blk)
+      tap { @exclude << condition(*nodes, &blk) }
+    end
+
+    # Declare inverted exclude condition. Which nodes you want to keep?
+    def include_only(*nodes, &blk)
+      tap { @include_only << condition(*nodes, &blk) }
+    end
+    alias exclude_unless include_only
+
+    # Declare which nodes you want to expand. Others will be pruned.
+    def expand_only(*nodes, &blk)
+      tap { @expand_only << condition(*nodes, &blk) }
     end
 
     # Declare prune condition. Which nodes relations you want to ignore?
@@ -50,28 +94,28 @@ module Traversal
     # 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) }
+    def prune(*nodes, &blk)
+      tap { @prune << condition(*nodes, &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)
+    def exclude_and_prune(*nodes, &blk)
+      exclude(*nodes, &blk)
+      prune(*nodes, &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) }
+    def stop_before(*nodes, &blk)
+      tap { @stop_before << condition(*nodes, &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) }
+    def stop_after(*nodes, &blk)
+      tap { @stop_after << condition(*nodes, &blk) }
     end
 
     # Declare traversal order strategy as +depth first+
@@ -84,7 +128,14 @@ module Traversal
       tap { @order = BREADTH_FIRST }
     end
 
-    def each
+    # Set uniqueness behaviour
+    # By default it is set to +true+
+    def uniq(v = true)
+      tap { @uniq = !!v }
+    end
+
+    # Iterate through nodes defined by DSL and optionally execute given +block+ for each node.
+    def each # :yields: node
       assert_complete_description
 
       iter = Traversal::Iterator.new(self)
@@ -105,29 +156,60 @@ module Traversal
       (type == :after ? @stop_after : @stop_before).any? { |cond| cond[node] }
     end
 
+    def include?(node) #:nodoc:
+      @include_only.all? { |cond| cond[node] } &&
+      @exclude.none? { |cond| cond[node] }
+    end
+
     def exclude?(node) #:nodoc:
-      @exclude.any? { |cond| cond[node] }
+      !include?(node)
+    end
+
+    def expand?(node) #:nodoc:
+      @expand_only.all? { |cond| cond[node] } &&
+      @prune.none? { |cond| cond[node] }
     end
 
     def prune?(node) #:nodoc:
-      @prune.any? { |cond| cond[node] }
+      !expand?(node)
     end
 
     def breadth_first? #:nodoc:
       @order == BREADTH_FIRST
     end
 
+    def uniq? #:nodoc:
+      @uniq
+    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)
+    def condition(*args, &blk) #:nodoc:
+      # on empty argument use given block
+      args << blk if block_given?
+      raise ArgumentError, 'arguments or block expected' if args.empty?
 
-      arg.to_proc
+      args.length == 1 ? arg_to_proc(args.first) : args_to_proc(args)
     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
+      raise IncompleteDescription, "Traversal description should contain relation(s). Use #follow method" if @relations.empty?
+    end
+
+    def args_to_proc(args)
+      procs = args.map { |arg| arg_to_proc(arg) }
+      proc { |node| procs.any? { |pr| pr[node] } }
+    end
+
+    # convert argument to callable proc
+    def arg_to_proc(arg) #:nodoc:
+      return arg.to_proc if arg.respond_to?(:to_proc)
+
+      [:===, :==, :eql?].each do |meth|
+        return arg.method(meth) if arg.respond_to?(meth)
+      end
+
+      raise TypeError, 'argument must respond to one of the following method: #to_proc, #===, #==, #eql?'
     end
   end
 end

data/lib/traversal/iterator.rb

@@ -1,10 +1,17 @@
 # coding: utf-8
 
 require "enumerator"
+require "forwardable"
 
 module Traversal
   # Traversal iterator.
-  class Iterator < Enumerator
+  class Iterator < Enumerator #:nodoc: all
+    extend Forwardable
+
+    def_delegators :to_ary!, :[], :at, :empty?,
+                             :fetch, :find_index, :index,
+                             :last, :reverse, :values_at
+
     # Create new traversal iterator from traversal description
     def initialize(description)
       raise TypeError,
@@ -14,23 +21,33 @@ module Traversal
       @description = description
       start_node = @description.start_node
 
-      # Create Enumerator
-      super() do |yielder|
+      # Map of visited nodes
+      @visited = {}
+
+      # Create underlying Enumerator
+      @enumerator = Enumerator.new do |yielder|
         @yielder = yielder
 
         begin
           yield_node(start_node)
 
-          expand_node(start_node)
+          expand_node(start_node) if @description.expand?(start_node)
         rescue StopIteration
           # ignore
         end
       end
+
+      # Wrap underlying enumerator
+      super() do |y|
+        @enumerator.each { |e| y << e }
+      end
     end
 
     private
-    def push(*args) #:nodoc:
-      @yielder.yield(*args)
+    def push(node) #:nodoc:
+      @visited[node] = true if @description.uniq? # memo visited node
+
+      @yielder.yield(node)
     end
 
     def yield_node(node) #:nodoc:
@@ -38,7 +55,7 @@ module Traversal
       raise StopIteration if @description.stop?(node, :before)
 
       # do yield
-      push(node) unless @description.exclude?(node)
+      push(node) unless @description.exclude?(node) || visited?(node)
 
       # check stop post-condition
       raise StopIteration if @description.stop?(node, :after)
@@ -82,9 +99,28 @@ module Traversal
 
     # Expand relations for node
     def relations_for(node) #:nodoc:
-      relation = @description.relation[node]
+      Enumerator.new do |yielder|
+        @description.relations.each do |relation_accessor|
+          begin
+            relations  = relation_accessor[node]
+            enumerable = relations.is_a?(Enumerable) ? relations : [relations].compact
+
+            enumerable.each { |e| yielder << e unless visited?(e) }
+          rescue NoMethodError
+            # ignore errors on relation_accessor[node]
+          end
+        end
+      end
+    end
+
+    def visited?(node) #:nodoc:
+      @description.uniq? && @visited.key?(node)
+    end
 
-      relation.is_a?(Enumerable) ? relation : []
+    # convert underlying enumerator to array
+    def to_ary! #:nodoc:
+      @enumerator = @enumerator.to_a unless @enumerator.is_a?(Array)
+      @enumerator
     end
-  end
-end
+  end # module Iterator
+end # module Traversal

data/lib/traversal/version.rb

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

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Alexey Mikhaylov
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-22 00:00:00 +06:00
+date: 2012-01-26 00:00:00 +06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -53,18 +53,11 @@ 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: []

data/.gitignore

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

data/Gemfile

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

data/README.rdoc

@@ -1,96 +0,0 @@
-== 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

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

data/spec/test_helper.rb

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

data/spec/traversal_spec.rb

@@ -1,151 +0,0 @@
-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

@@ -1,24 +0,0 @@
-# -*- 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