nobrainer-tree 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0a7bca7cff2679bd8fbd69bc4ccdbeba8e59f50d
+  data.tar.gz: 75eae734d058953c9e63840e07176b1e325defde
+SHA512:
+  metadata.gz: 3149e67069144dfd3bf675501c7d8ce41f7eb33e152396e07ff14b8cdce77d722f258a3212a6106b536b9ddbf3d34177062916c985b2ae4c0c78d3a030dd8799
+  data.tar.gz: 3eb4a08d9067691283368b9cc04e04f1a64c947366ad7902ae5ffb11e6a4a721ee7a5b40d3a7051e186c2f0e46902eea6b345b96ff34b8c58563a25ae2b54b03

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'guard-rspec', '>= 0.6.0'
+gem 'ruby_gntp',   '>= 0.3.4'
+gem 'rb-fsevent' if RUBY_PLATFORM =~ /darwin/
+gem 'nobrainer', :github => 'nviennot/nobrainer'
+
+platforms :rbx do
+  gem 'rubysl-rake', '~> 2.0'
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010-2013 Benedikt Deicke
+
+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,220 @@
+# nobrainer-tree ![Build Status](https://travis-ci.org/secondimpression/nobrainer-tree.svg?branch=nobrainer) [![Dependency Status](https://gemnasium.com/secondimpression/nobrainer-tree.png)](https://gemnasium.com/secondimpression/nobrainer-tree)
+
+A tree structure for NoBrainer documents using the materialized path pattern
+
+## Requirements
+
+* nobrainer (~> 0.20.0)
+
+
+## Install
+
+To install nobrainer-tree, simply add it to your Gemfile:
+
+    gem 'nobrainer-tree', :require => 'nobrainer/tree'
+
+In order to get the latest development version of nobrainer-tree:
+
+    gem 'nobrainer-tree', :git => 'git://github.com/secondimpression/nobrainer-tree'
+
+You might want to add `:require => nil` option and explicitly `require 'nobrainer/tree'` where needed and finally run
+
+    bundle install
+
+
+## Usage
+
+Read the API documentation at https://github.com/secondimpression/nobrainer-tree and take a look at the `NoBrainer::Tree` module
+
+```ruby
+class Node
+  include NoBrainer::Document
+  include NoBrainer::Tree
+end
+```
+
+
+### Utility methods
+
+There are several utility methods that help getting to other related documents in the tree:
+
+```ruby
+Node.root
+Node.roots
+Node.leaves
+
+node.root
+node.parent
+node.children
+node.ancestors
+node.ancestors_and_self
+node.descendants
+node.descendants_and_self
+node.siblings
+node.siblings_and_self
+node.leaves
+```
+
+In addition it's possible to check certain aspects of the document's position in the tree:
+
+```ruby
+node.root?
+node.leaf?
+node.depth
+node.ancestor_of?(other)
+node.descendant_of?(other)
+node.sibling_of?(other)
+```
+
+See `NoBrainer::Tree` for more information on these methods.
+
+
+### Ordering
+
+`NoBrainer::Tree` doesn't order children by default. To enable ordering of tree nodes include the `NoBrainer::Tree::Ordering` module. This will add a `position` field to your document and provide additional utility methods:
+
+```ruby
+node.lower_siblings
+node.higher_siblings
+node.first_sibling_in_list
+node.last_sibling_in_list
+
+node.move_up
+node.move_down
+node.move_to_top
+node.move_to_bottom
+node.move_above(other)
+node.move_below(other)
+
+node.at_top?
+node.at_bottom?
+```
+
+Example:
+
+```ruby
+class Node
+  include NoBrainer::Document
+  include NoBrainer::Tree
+  include NoBrainer::Tree::Ordering
+end
+```
+
+See `NoBrainer::Tree::Ordering` for more information on these methods.
+
+
+### Traversal
+
+It's possible to traverse the tree using different traversal methods using the `NoBrainer::Tree::Traversal` module.
+
+Example:
+
+```ruby
+class Node
+  include NoBrainer::Document
+  include NoBrainer::Tree
+  include NoBrainer::Tree::Traversal
+end
+
+node.traverse(:breadth_first) do |n|
+  # Do something with Node n
+end
+```
+
+
+### Destroying
+
+`NoBrainer::Tree` does not handle destroying of nodes by default. However it provides several strategies that help you to deal with children of deleted documents. You can simply add them as `before_destroy` callbacks.
+
+Available strategies are:
+
+* `:nullify_children` -- Sets the children's parent_id to null
+* `:move_children_to_parent` -- Moves the children to the current document's parent
+* `:destroy_children` -- Destroys all children by calling their `#destroy` method (invokes callbacks)
+* `:delete_descendants` -- Deletes all descendants using a database query (doesn't invoke callbacks)
+
+Example:
+
+```ruby
+class Node
+  include NoBrainer::Document
+  include NoBrainer::Tree
+
+  before_destroy :nullify_children
+end
+```
+
+
+### Callbacks
+
+There are two callbacks that are called before and after the rearranging process. This enables you to do additional computations after the documents position in the tree is updated. See `NoBrainer::Tree` for details.
+
+Example:
+
+```ruby
+class Page
+  include NoBrainer::Document
+  include NoBrainer::Tree
+
+  after_rearrange :rebuild_path
+
+  field :slug
+  field :path
+
+  private
+
+  def rebuild_path
+    self.path = self.ancestors_and_self.collect(&:slug).join('/')
+  end
+end
+```
+
+
+### Validations
+
+`NoBrainer::Tree` currently does not validate the document's children or parent associations by default. To explicitly enable validation for children and parent documents it's required to add a `validates_associated` validation.
+
+Example:
+
+```ruby
+class Node
+  include NoBrainer::Document
+  include NoBrainer::Tree
+
+  validates_associated :parent, :children
+end
+```
+
+
+## Build Status
+
+nobrainer-tree is on [Travis CI](http://travis-ci.org/secondimpression/nobrainer-tree) running the specs on Ruby Head, Ruby 1.9.3, Ruby 2.0 and Ruby 2.1
+
+
+## Known issues
+
+See [https://github.com/secondimpression/nobrainer-tree/issues](https://github.com/secondimpression/nobrainer-tree/issues)
+
+
+## Repository
+
+See [https://github.com/secondimpression/nobrainer-tree](https://github.com/secondimpression/nobrainer-tree) and feel free to fork it!
+
+
+## Contributors
+
+See a list of all contributors at [https://github.com/benedikt/mongoid-tree/contributors](https://github.com/benedikt/mongoid-tree/contributors) and [https://github.com/secondimpression/nobrainer-tree/contributors](https://github.com/secondimpression/nobrainer-tree/contributors). Thanks a lot everyone!
+
+
+## Support
+
+If you like nobrainer-tree and want to support the development, the original author would appreciate a small donation:
+
+[![Pledgie](http://www.pledgie.com/campaigns/12137.png?skin_name=chrome)](http://www.pledgie.com/campaigns/12137)
+
+[![Flattr](https://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=benediktdeicke&url=https://github.com/benedikt/mongoid-tree&title=mongoid-tree&language=&tags=github&category=software)
+
+
+## Copyright
+
+Copyright (c) 2010-2013 Benedikt Deicke. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,25 @@
+require 'rspec/core/rake_task'
+require 'yard'
+
+spec = Gem::Specification.load("nobrainer-tree.gemspec")
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+YARD::Rake::YardocTask.new(:doc)
+
+desc "Build the .gem file"
+task :build do
+  system "gem build #{spec.name}.gemspec"
+end
+
+desc "Push the .gem file to rubygems.org"
+task :release => :build do
+  system "gem push #{spec.name}-#{spec.version}.gem"
+end
+
+desc "Open an irb session"
+task :console do
+  sh "irb -rubygems -I lib -r ./spec/spec_helper.rb"
+end

data/lib/nobrainer/tree/ordering.rb

@@ -0,0 +1,238 @@
+module NoBrainer
+  module Tree
+    ##
+    # = NoBrainer::Tree::Ordering
+    #
+    # NoBrainer::Tree doesn't order the tree by default. To enable ordering of children
+    # include both NoBrainer::Tree and NoBrainer::Tree::Ordering into your document.
+    #
+    # == Utility methods
+    #
+    # This module adds methods to get related siblings depending on their position:
+    #
+    #    node.lower_siblings
+    #    node.higher_siblings
+    #    node.first_sibling_in_list
+    #    node.last_sibling_in_list
+    #
+    # There are several methods to move nodes around in the list:
+    #
+    #    node.move_up
+    #    node.move_down
+    #    node.move_to_top
+    #    node.move_to_bottom
+    #    node.move_above(other)
+    #    node.move_below(other)
+    #
+    # Additionally there are some methods to check aspects of the document
+    # in the list of children:
+    #
+    #    node.at_top?
+    #    node.at_bottom?
+    module Ordering
+      extend ActiveSupport::Concern
+
+      included do
+        field :position, :type => Integer
+
+        default_scope -> { order_by(:position => :asc) }
+
+        before_save :assign_default_position,    :if => :assign_default_position?
+        before_save :reposition_former_siblings, :if => :sibling_reposition_required?
+        after_destroy :move_lower_siblings_up
+      end
+
+      def inc(increments)
+        update(increments.symbolize_keys.map{ |field, value| { field => (self[field] || 0) + value } }.first)
+        self
+      end
+
+      ##
+      # Returns a chainable criteria for this document's ancestors
+      #
+      # @return [NoBrainer::Criteria] NoBrainer criteria to retrieve the document's ancestors
+      def ancestors
+        base_class.unscoped.without_index.where(:id.in => self.parent_ids).order_by(:depth => :asc)
+      end
+
+      ##
+      # Returns siblings below the current document.
+      # Siblings with a position greater than this document's position.
+      #
+      # @return [NoBrainer::Criteria] NoBrainer criteria to retrieve the document's lower siblings
+      def lower_siblings
+        self.siblings.where(:position.gt => self.position)
+      end
+
+      ##
+      # Returns siblings above the current document.
+      # Siblings with a position lower than this document's position.
+      #
+      # @return [NoBrainer::Criteria] NoBrainer criteria to retrieve the document's higher siblings
+      def higher_siblings
+        self.siblings.where(:position.lt => self.position)
+      end
+
+      ##
+      # Returns siblings between the current document and the other document
+      # Siblings with a position between this document's position and the other document's position.
+      #
+      # @return [NoBrainer::Criteria] NoBrainer criteria to retrieve the documents between this and the other document
+      def siblings_between(other)
+        range = [self.position, other.position].sort
+        self.siblings.where(:position.gt => range.first, :position.lt => range.last)
+      end
+
+      ##
+      # Returns the lowest sibling (could be self)
+      #
+      # @return [NoBrainer::Document] The lowest sibling
+      def last_sibling_in_list
+        siblings_and_self.last
+      end
+
+      ##
+      # Returns the highest sibling (could be self)
+      #
+      # @return [NoBrainer::Document] The highest sibling
+      def first_sibling_in_list
+        siblings_and_self.first
+      end
+
+      ##
+      # Is this the highest sibling?
+      #
+      # @return [Boolean] Whether the document is the highest sibling
+      def at_top?
+        higher_siblings.empty?
+      end
+
+      ##
+      # Is this the lowest sibling?
+      #
+      # @return [Boolean] Whether the document is the lowest sibling
+      def at_bottom?
+        lower_siblings.empty?
+      end
+
+      ##
+      # Move this node above all its siblings
+      #
+      # @return [undefined]
+      def move_to_top
+        return true if at_top?
+        move_above(first_sibling_in_list)
+      end
+
+      ##
+      # Move this node below all its siblings
+      #
+      # @return [undefined]
+      def move_to_bottom
+        return true if at_bottom?
+        move_below(last_sibling_in_list)
+      end
+
+      ##
+      # Move this node one position up
+      #
+      # @return [undefined]
+      def move_up
+        switch_with_sibling_at_offset(-1) unless at_top?
+      end
+
+      ##
+      # Move this node one position down
+      #
+      # @return [undefined]
+      def move_down
+        switch_with_sibling_at_offset(1) unless at_bottom?
+      end
+
+      ##
+      # Move this node above the specified node
+      #
+      # This method changes the node's parent if nescessary.
+      #
+      # @param [NoBrainer::Tree] other document to move this document above
+      #
+      # @return [undefined]
+      def move_above(other)
+        ensure_to_be_sibling_of(other)
+
+        if position > other.position
+          new_position = other.position
+          self.siblings_between(other).each{ |object| object.inc(:position => 1) }
+          other.inc(:position => 1)
+        else
+          new_position = other.position - 1
+          self.siblings_between(other).each{ |object| object.inc(:position => -1) }
+        end
+
+        self.position = new_position
+        save
+      end
+
+      ##
+      # Move this node below the specified node
+      #
+      # This method changes the node's parent if nescessary.
+      #
+      # @param [NoBrainer::Tree] other document to move this document below
+      #
+      # @return [undefined]
+      def move_below(other)
+        ensure_to_be_sibling_of(other)
+
+        if position > other.position
+          new_position = other.position + 1
+          self.siblings_between(other).each{ |object| object.inc(:position => 1) }
+        else
+          new_position = other.position
+          self.siblings_between(other).each{ |object| object.inc(:position => -1) }
+          other.inc(:position => -1)
+        end
+
+        self.position = new_position
+        save
+      end
+
+      private
+
+      def switch_with_sibling_at_offset(offset)
+        siblings.where(:position => self.position + offset).first.inc(:position => -offset)
+        inc(:position => offset)
+      end
+
+      def ensure_to_be_sibling_of(other)
+        return if sibling_of?(other)
+        self.parent_id = other.parent_id
+        save
+      end
+
+      def move_lower_siblings_up
+        lower_siblings.each{ |object| object.inc(:position => -1) }
+      end
+
+      def reposition_former_siblings
+        former_siblings = base_class.where(:parent_id => self.parent_id_was).
+                                     where(:position.gt => (self.position_was || 0)).
+                                     where(:id.ne => self.id)
+        former_siblings.to_a.each{ |object| object.inc(:position => -1) }
+      end
+
+      def sibling_reposition_required?
+        parent_id_changed? && persisted?
+      end
+
+      def assign_default_position
+        self.position = self.last_sibling_in_list.position + 1 rescue 0
+      end
+
+      def assign_default_position?
+        self.position.nil? || self.parent_id_changed?
+      end
+
+    end
+  end
+end

data/lib/nobrainer/tree/traversal.rb

@@ -0,0 +1,122 @@
+module NoBrainer
+  module Tree
+    ##
+    # = NoBrainer::Tree::Traversal
+    #
+    # NoBrainer::Tree::Traversal provides a #traverse method to walk through the tree.
+    # It supports these traversal methods:
+    #
+    # * depth_first
+    # * breadth_first
+    #
+    # == Depth First Traversal
+    #
+    # See http://en.wikipedia.org/wiki/Depth-first_search for a proper description.
+    #
+    # Given a tree like:
+    #
+    #   node1:
+    #    - node2:
+    #      - node3
+    #    - node4:
+    #      - node5
+    #      - node6
+    #    - node7
+    #
+    # Traversing the tree using depth first traversal would visit each node in this order:
+    #
+    #   node1, node2, node3, node4, node5, node6, node7
+    #
+    # == Breadth First Traversal
+    #
+    # See http://en.wikipedia.org/wiki/Breadth-first_search for a proper description.
+    #
+    # Given a tree like:
+    #
+    #   node1:
+    #     - node2:
+    #       - node5
+    #     - node3:
+    #       - node6
+    #       - node7
+    #     - node4
+    #
+    # Traversing the tree using breadth first traversal would visit each node in this order:
+    #
+    #   node1, node2, node3, node4, node5, node6, node7
+    #
+    module Traversal
+      extend ActiveSupport::Concern
+
+
+      ##
+      # This module implements class methods that will be available
+      # on the document that includes NoBrainer::Tree::Traversal
+      module ClassMethods
+        ##
+        # Traverses the entire tree, one root at a time, using the given traversal
+        # method (Default is :depth_first).
+        #
+        # See NoBrainer::Tree::Traversal for available traversal methods.
+        #
+        # @example
+        #
+        #   # Say we have the following tree, and want to print its hierarchy:
+        #   #   root_1
+        #   #     child_1_a
+        #   #   root_2
+        #   #     child_2_a
+        #   #       child_2_a_1
+        #
+        #   Node.traverse(:depth_first) do |node|
+        #     indentation = '  ' * node.depth
+        #
+        #     puts "#{indentation}#{node.name}"
+        #   end
+        #
+        def traverse(type = :depth_first, &block)
+          roots.collect { |root| root.traverse(type, &block) }.flatten
+        end
+      end
+
+      ##
+      # Traverses the tree using the given traversal method (Default is :depth_first)
+      # and passes each document node to the block.
+      #
+      # See NoBrainer::Tree::Traversal for available traversal methods.
+      #
+      # @example
+      #
+      #   results = []
+      #   root.traverse(:depth_first) do |node|
+      #     results << node
+      #   end
+      #
+      #   root.traverse(:depth_first).map(&:name)
+      #   root.traverse(:depth_first, &:name)
+      #
+      def traverse(type = :depth_first, &block)
+        block ||= lambda { |node| node }
+        send("#{type}_traversal", &block)
+      end
+
+      private
+
+      def depth_first_traversal(&block)
+        result = [block.call(self)] + self.children.collect { |c| c.send(:depth_first_traversal, &block) }
+        result.flatten
+      end
+
+      def breadth_first_traversal(&block)
+        result = []
+        queue = [self]
+        while queue.any? do
+          node = queue.shift
+          result << block.call(node)
+          queue += node.children
+        end
+        result
+      end
+    end
+  end
+end