arboreal 0.0.5 → 0.1.0

data/README.rdoc

@@ -2,35 +2,43 @@
 
 Arboreal is yet another extension to ActiveRecord to support tree-shaped
 data structures.
- 
+
 Arboreal surfaces relationships within the tree like +children+,
 +ancestors+, +descendants+, and +siblings+ as scopes, so that additional
 filtering/pagination can be performed.
+ 
+It delegates as much work as possible to the underlying DBMS, making it efficient to:
+
+* fetch all ancestors, descendants or siblings of a node
+* move nodes (or subtrees) around
+* prevent loops
+* rebuild the hierarchy
 
 == Getting started
 
 First, install the "arboreal" gem, and add it to your Rails project's <tt>config/environment.rb</tt>.  
 
-Next, you'll need a migration to add an +ancestry_string+ column, and index thereupon:
+Next, you'll need a migration to add +parent_id+ and +ancestry_string+ columns, and indices:
 
     class MakeThingsArboreal < ActiveRecord::Migration
 
       def self.up
+        add_column "things", "parent_id", :integer
+        add_index "things", ["parent_id"]
         add_column "things", "ancestry_string", :string
         add_index "things", ["ancestry_string"]
-        Thing.rebuild_ancestry      
       end
 
       def self.down
         remove_index "things", ["ancestry_string"]
         remove_column "things", "ancestry_string"
+        remove_index "things", ["parent_id"]
+        remove_column "things", "parent_id"
       end
 
     end
 
-This assumes that the table concerned already has a +parent_id+ column; if not, add that too (type +integer+, with a supporting index).
-
-Finally, you can declare you model arboreal:
+Finally, you can declare your model arboreal:
 
     class Thing < ActiveRecord::Base
     
@@ -39,10 +47,10 @@ Finally, you can declare you model arboreal:
       # .. etc etc ...
       
     end
-    
+
 == Navigating the tree
 
-Arboreal adds the relationships you'd expect:
+Arboreal adds the basic relationships you'd expect:
 
 * <tt>parent</tt>
 * <tt>children</tt>

data/lib/arboreal/class_methods.rb

@@ -1,3 +1,5 @@
+require "active_support/core_ext/string/filters"
+
 module Arboreal
   module ClassMethods
     

data/lib/arboreal/instance_methods.rb

@@ -1,3 +1,5 @@
+require "active_support/core_ext/string/filters"
+
 module Arboreal
   module InstanceMethods
 
@@ -11,22 +13,22 @@ module Arboreal
     
     # return a scope matching all ancestors of this node
     def ancestors
-      self.class.scoped(:conditions => ancestor_conditions, :order => [:ancestry_string])
+      model_base_class.scoped(:conditions => ancestor_conditions, :order => [:ancestry_string])
     end
 
     # return a scope matching all descendants of this node
     def descendants
-      self.class.scoped(:conditions => descendant_conditions)
+      model_base_class.scoped(:conditions => descendant_conditions)
     end
     
     # return a scope matching all descendants of this node, AND the node itself
     def subtree
-      self.class.scoped(:conditions => subtree_conditions)
+      model_base_class.scoped(:conditions => subtree_conditions)
     end
     
     # return a scope matching all siblings of this node (NOT including the node itself)
     def siblings
-      self.class.scoped(:conditions => sibling_conditions)
+      model_base_class.scoped(:conditions => sibling_conditions)
     end
 
     # return the root of the tree
@@ -36,30 +38,38 @@ module Arboreal
     
     private
 
+    def model_base_class
+      self.class.base_class
+    end
+    
+    def table_name
+      self.class.table_name
+    end
+    
     def ancestor_conditions
       ["id in (?)", ancestor_ids]
     end
 
     def descendant_conditions
-      ["#{self.class.table_name}.ancestry_string like ?", path_string + "%"]
+      ["#{table_name}.ancestry_string like ?", path_string + "%"]
     end
 
     def subtree_conditions
       [
-        "#{self.class.table_name}.id = ? OR #{self.class.table_name}.ancestry_string like ?",
+        "#{table_name}.id = ? OR #{table_name}.ancestry_string like ?",
         id, path_string + "%"
       ]
     end
     
     def sibling_conditions
       [
-        "#{self.class.table_name}.id <> ? AND #{self.class.table_name}.parent_id = ?",
+        "#{table_name}.id <> ? AND #{table_name}.parent_id = ?",
         id, parent_id
       ]
     end
 
     def populate_ancestry_string
-      self.class.send(:with_exclusive_scope) do
+      model_base_class.send(:with_exclusive_scope) do
         self.ancestry_string = parent ? parent.path_string : "-"
       end
     end
@@ -86,7 +96,7 @@ module Arboreal
       if @ancestry_change
         old_ancestry_string, new_ancestry_string = *@ancestry_change
         connection.update(<<-SQL.squish)
-          UPDATE #{self.class.table_name} 
+          UPDATE #{table_name} 
             SET ancestry_string = REPLACE(ancestry_string, '#{old_ancestry_string}', '#{new_ancestry_string}')
             WHERE ancestry_string LIKE '#{old_ancestry_string}%'
         SQL

data/lib/arboreal/version.rb

@@ -1,3 +1,3 @@
 module Arboreal
-  VERSION = "0.0.5"
+  VERSION = "0.1.0"
 end

data/spec/arboreal_spec.rb

@@ -11,6 +11,7 @@ class Node < ActiveRecord::Base
     def self.up
       create_table "nodes", :force => true do |t|
         t.string "name"
+        t.string "type"
         t.integer "parent_id"
         t.string "ancestry_string"
       end
@@ -24,7 +25,7 @@ class Node < ActiveRecord::Base
   
 end
 
-describe "{Arboreal}" do
+describe "Arboreal hierarchy" do
 
   before(:all) do
     Node::Migration.up
@@ -259,4 +260,42 @@ describe "{Arboreal}" do
   
 end
 
+class RedNode < Node; end
+class GreenNode < Node; end
+class BlueNode < Node; end
+  
+describe "polymorphic hierarchy" do
+
+  before(:all) do
+    Node::Migration.up
+  end
+  
+  after(:all) do
+    Node::Migration.down
+  end
+
+  before do
+    @red = RedNode.create!
+    @green = GreenNode.create!(:parent => @red)
+    @blue = BlueNode.create!(:parent => @green)
+  end
+  
+  describe "#descendants" do
+    it "includes nodes of other types" do
+      @red.descendants.should include(@green, @blue)
+    end
+  end
 
+  describe "#subtree" do
+    it "includes nodes of other types" do
+      @red.subtree.should include(@red, @green, @blue)
+    end
+  end
+
+  describe "#ancestors" do
+    it "includes nodes of other types" do
+      @blue.ancestors.should include(@red, @green)
+    end
+  end
+  
+end

data/spec/spec_helper.rb

@@ -41,7 +41,7 @@ DB_CONFIGS = {
   }
 }
 
-test_adapter = (ENV["ARBOREAL_TEST_ADAPTER"] || "sqlite3")
+test_adapter = (ENV["AR_ADAPTER"] || "sqlite3")
 test_db_config = DB_CONFIGS[test_adapter].merge(:adapter => test_adapter)
 
 Spec::Runner.configure do |config|

metadata

@@ -1,7 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: arboreal
 version: !ruby/object:Gem::Version 
-  version: 0.0.5
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Mike Williams
@@ -9,29 +14,51 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-06 00:00:00 +10:00
+date: 2010-04-18 00:00:00 +10:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 3
+        - 0
+        version: 2.3.0
   type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 3
+        - 0
         version: 2.3.0
-    version: 
+  type: :runtime
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: rspec
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 9
         version: 1.2.9
-    version: 
+  type: :development
+  version_requirements: *id003
 description: |
   Arboreal is yet another extension to ActiveRecord to support tree-shaped data structures.
   
@@ -76,18 +103,22 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 8
+      - 7
       version: 1.8.7
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: Efficient tree structures for ActiveRecord