arboreal 0.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Mike Williams <mdub@dogbiscuit.org>
+
+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.rdoc

@@ -0,0 +1,7 @@
+= Arboreal
+
+Arboreal is yet another extension to ActiveRecord to support tree-shaped data structures.
+
+Internally, Arboreal maintains a computed "ancestry_string" column, which caches the path from the root of a tree to each node, allowing efficient retrieval of both ancestors and descendants.
+
+Arboreal surfaces relationships within the tree like +children+, +ancestors+, +descendants+, and +siblings+ as scopes, so that additional filtering/pagination can be performed.

data/Rakefile

@@ -0,0 +1,9 @@
+task :default => :spec
+
+require "spec/rake/spectask"
+
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.spec_opts << "-fnested" << "--color"
+end

data/lib/arboreal.rb

@@ -0,0 +1,4 @@
+require 'arboreal/active_record_extensions'
+require 'arboreal/class_methods'
+require 'arboreal/instance_methods'
+require 'arboreal/version'

data/lib/arboreal/active_record_extensions.rb

@@ -0,0 +1,31 @@
+module Arboreal
+  module ActiveRecordExtensions
+    
+    def acts_arboreal
+
+      belongs_to :parent, :class_name => self.name
+      has_many   :children, :class_name => self.name, :foreign_key => :parent_id
+
+      extend Arboreal::ClassMethods
+      include Arboreal::InstanceMethods
+
+      before_validation :populate_ancestry_string
+      
+      validate do |record|
+        record.send(:validate_parent_not_ancestor)
+      end
+
+      before_save :detect_ancestry_change
+      after_save  :apply_ancestry_change_to_descendants
+      
+      named_scope :roots, {
+        :conditions => ["parent_id IS NULL"]
+      }
+      
+    end
+    
+  end
+end
+
+require 'active_record'
+ActiveRecord::Base.extend(Arboreal::ActiveRecordExtensions)

data/lib/arboreal/class_methods.rb

@@ -0,0 +1,34 @@
+module Arboreal
+  module ClassMethods
+    
+    def rebuild_ancestry
+      clear_ancestry_strings
+      populate_root_ancestry_strings
+      begin
+        n_changes = extend_ancestry_strings 
+      end until n_changes.zero?
+    end
+    
+    private
+    
+    def clear_ancestry_strings
+      connection.update("UPDATE #{table_name} SET ancestry_string = NULL")
+    end
+
+    def populate_root_ancestry_strings
+      connection.update("UPDATE #{table_name} SET ancestry_string = '-' WHERE parent_id IS NULL")
+    end
+
+    def extend_ancestry_strings
+      connection.update(<<-SQL.squish)
+        UPDATE #{table_name}
+        SET ancestry_string = 
+          (SELECT (parent.ancestry_string || CAST(#{table_name}.parent_id AS varchar) || '-')
+             FROM #{table_name} AS parent
+            WHERE parent.id = #{table_name}.parent_id)
+        WHERE ancestry_string IS NULL
+      SQL
+    end
+    
+  end
+end

data/lib/arboreal/instance_methods.rb

@@ -0,0 +1,94 @@
+module Arboreal
+  module InstanceMethods
+
+    def path_string
+      "#{ancestry_string}#{id}-"
+    end
+
+    def ancestry_string
+      read_attribute(:ancestry_string) || "-"
+    end
+
+    def ancestor_ids
+      ancestry_string.sub(/^-/, "").split("-").map { |x| x.to_i }
+    end
+
+    def ancestors
+      base_class.scoped(
+      :conditions => ["id in (?)", ancestor_ids], 
+      :order => [:ancestry_string]
+      )
+    end
+
+    def descendants
+      ancestry_pattern = 
+      base_class.scoped(
+      :conditions => ["#{base_class.table_name}.ancestry_string like ?", path_string + "%"]
+      )
+    end
+
+    def subtree
+      ancestry_pattern = path_string + "%"
+      base_class.scoped(
+      :conditions => [
+        "#{base_class.table_name}.id = ? OR #{base_class.table_name}.ancestry_string like ?",
+        id, path_string + "%"
+      ]
+      )
+    end
+    
+    def siblings
+      base_class.scoped(
+      :conditions => [
+        "#{base_class.table_name}.id <> ? AND #{base_class.table_name}.parent_id = ?",
+        id, parent_id
+      ]
+      )
+    end
+
+    def root
+      ancestors.first || self
+    end
+    
+    private
+
+    def base_class
+      self.class.base_class
+    end
+
+    def populate_ancestry_string
+      self.ancestry_string = (parent.path_string unless parent.nil?)
+    end
+
+    def validate_parent_not_ancestor
+      if self.id 
+        if parent_id == self.id
+          errors.add(:parent, "can't be the record itself")
+        end
+        if ancestor_ids.include?(self.id)
+          errors.add(:parent, "can't be an ancestor")
+        end
+      end
+    end
+    
+    def detect_ancestry_change
+      if ancestry_string_changed? && !new_record?
+        old_path_string = "#{ancestry_string_was}#{id}-"
+        @ancestry_change = [old_path_string, path_string]
+      end
+    end
+    
+    def apply_ancestry_change_to_descendants
+      if @ancestry_change
+        old_ancestry_string, new_ancestry_string = *@ancestry_change
+        connection.update(<<-SQL.squish)
+          UPDATE #{base_class.table_name} 
+            SET ancestry_string = REPLACE(ancestry_string, '#{old_ancestry_string}', '#{new_ancestry_string}')
+            WHERE ancestry_string LIKE '#{old_ancestry_string}%'
+        SQL
+        @ancestry_change = nil
+      end
+    end
+    
+  end
+end

data/lib/arboreal/version.rb

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

data/spec/arboreal_spec.rb

@@ -0,0 +1,250 @@
+require 'spec_helper'
+
+require 'arboreal'
+
+class Node < ActiveRecord::Base
+  
+  acts_arboreal
+  
+  class Migration < ActiveRecord::Migration
+
+    def self.up
+      create_table "nodes", :force => true do |t|
+        t.string "name"
+        t.integer "parent_id"
+        t.string "ancestry_string"
+      end
+    end
+
+    def self.down
+      drop_table "nodes"
+    end
+
+  end
+  
+end
+
+describe "{Arboreal}" do
+
+  before(:all) do
+    Node::Migration.up
+  end
+  
+  after(:all) do
+    Node::Migration.down
+  end
+
+  before do
+    @australia = Node.create!(:name => "Australia")
+    @victoria = Node.create!(:name => "Victoria", :parent => @australia)
+    @melbourne = Node.create!(:name => "Melbourne", :parent => @victoria)
+    @nsw = Node.create!(:name => "New South Wales", :parent => @australia)
+    @sydney = Node.create!(:name => "Sydney", :parent => @nsw)
+  end
+  
+  describe "node" do
+  
+    describe "#parent" do
+      it "returns the parent" do
+        @victoria.parent.should == @australia
+      end
+    end
+
+    describe "#children" do
+      it "returns the children" do
+        @australia.children.to_set.should == [@victoria, @nsw].to_set
+      end
+    end
+
+    describe "#siblings" do
+      it "returns other nodes with the same parent" do
+        @victoria.siblings.should == [@nsw]
+      end
+    end
+    
+    it "cannot be it's own parent" do
+      lambda do
+        @australia.update_attributes!(:parent => @australia)
+      end.should raise_error(ActiveRecord::RecordInvalid)
+    end
+
+    it "cannot be it's own ancestor" do
+      lambda do
+        @australia.update_attributes!(:parent => @melbourne)
+      end.should raise_error(ActiveRecord::RecordInvalid)
+    end
+
+  end
+    
+  describe "root node" do
+  
+    describe "#parent" do
+      it "returns nil" do
+        @australia.parent.should == nil
+      end
+    end
+
+    describe "#ancestors" do
+      it "is empty" do
+        @australia.ancestors.should be_empty
+      end
+    end
+    
+    describe "#ancestry_string" do
+      it "is a single dash" do
+        @australia.ancestry_string.should == "-"
+      end
+    end
+
+    describe "#path_string" do
+      it "contains only the id of the root" do
+        @australia.path_string.should == "-#{@australia.id}-"
+      end
+    end
+
+    describe "#descendants" do
+
+      it "includes children" do
+        @australia.descendants.should include(@victoria)
+        @australia.descendants.should include(@nsw)
+      end
+
+      it "includes grand-children" do
+        @australia.descendants.should include(@melbourne)
+        @australia.descendants.should include(@sydney)
+      end
+
+      it "excludes self" do
+        @australia.descendants.should_not include(@australia)
+      end
+
+    end
+
+    describe "#subtree" do
+
+      it "includes children" do
+        @australia.subtree.should include(@victoria)
+        @australia.subtree.should include(@nsw)
+      end
+
+      it "includes grand-children" do
+        @australia.subtree.should include(@melbourne)
+        @australia.subtree.should include(@sydney)
+      end
+
+      it "includes self" do
+        @australia.subtree.should include(@australia)
+      end
+
+    end
+
+    describe "#root" do
+      
+     it "is itself" do
+       @australia.root.should == @australia
+     end
+     
+    end
+    
+  end
+  
+  describe "leaf node" do
+
+    describe "#ancestry_string" do
+      it "contains ids of all ancestors" do
+        @melbourne.ancestry_string.should == "-#{@australia.id}-#{@victoria.id}-"
+      end
+    end
+
+    describe "#path_string" do
+      it "contains ids of all ancestors, plus self" do
+        @melbourne.path_string.should == "-#{@australia.id}-#{@victoria.id}-#{@melbourne.id}-"
+      end
+    end
+
+    describe "#ancestors" do
+      
+      it "returns all ancestors, depth-first" do
+        @melbourne.ancestors.all.should == [@australia, @victoria]
+      end
+      
+    end
+
+    describe "#children" do
+      it "returns an empty collection" do
+        @melbourne.children.should be_empty
+      end
+    end
+
+    describe "#descendants" do
+      it "returns an empty collection" do
+        @melbourne.children.should be_empty
+      end
+    end
+
+    describe "#root" do
+
+      it "is the root of the tree" do
+        @melbourne.root.should == @australia
+      end
+
+    end
+
+  end
+  
+  describe ".roots" do
+    
+    it "returns root nodes" do
+      @nz = Node.create!(:name => "New Zealand")
+      Node.roots.to_set.should == [@australia, @nz].to_set
+    end
+    
+  end
+
+  describe "when a node changes parent" do
+
+    before do
+      @box_hill = Node.create!(:name => "Box Hill", :parent => @melbourne)
+      @nz = Node.create!(:name => "New Zealand")
+      @victoria.update_attributes!(:parent => @nz)
+    end
+    
+    describe "each descendant" do
+      
+      it "follows" do
+
+        @melbourne.reload
+        @melbourne.ancestors.should include(@nz, @victoria)
+        @melbourne.ancestors.should_not include(@australia)
+
+        @box_hill.reload
+        @box_hill.ancestors.should include(@nz, @victoria, @melbourne)
+        @box_hill.ancestors.should_not include(@australia)
+
+      end
+      
+    end
+    
+  end
+  
+  describe ".rebuild_ancestry" do
+
+    before do
+      Node.connection.update("UPDATE nodes SET ancestry_string = 'corrupt'")
+      Node.rebuild_ancestry
+    end
+    
+    it "re-populates all ancestry_strings" do
+      Node.count(:conditions => {:ancestry_string => 'corrupt'}).should == 0
+    end
+
+    it "fixes the hierarchy" do
+      @melbourne.reload.ancestors.should == [@australia, @victoria]
+      @sydney.reload.ancestors.should == [@australia, @nsw]
+    end
+    
+  end
+  
+end
+
+