arboreal 0.0.4 → 0.0.5

data/README.rdoc

@@ -0,0 +1,73 @@
+= Arboreal
+
+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.
+
+== 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:
+
+    class MakeThingsArboreal < ActiveRecord::Migration
+
+      def self.up
+        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"
+      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:
+
+    class Thing < ActiveRecord::Base
+    
+      acts_arboreal
+      
+      # .. etc etc ...
+      
+    end
+    
+== Navigating the tree
+
+Arboreal adds the relationships you'd expect:
+
+* <tt>parent</tt>
+* <tt>children</tt>
+
+In addition, it provides the following handy methods on each tree-node:
+
+* <tt>ancestors</tt>
+* <tt>descendants</tt>
+* <tt>subtree</tt> (the node itself, plus descendants)
+* <tt>siblings</tt>
+* <tt>root</tt> (the topmost ancestor)
+
+The first four return scopes, to which additional filtering, ordering or limits may be applied.
+
+At the class-level:
+
+* <tt>roots</tt> is a named-scope returning all the nodes without parents
+* <tt>rebuild_ancestry</tt> rebuilds the ancestry cache, as described below
+
+== Rebuilding the ancestry cache
+ 
+Internally, Arboreal uses the +ancestry_string+ column to cache the path down the tree to each node (or more correctly, it's parent.  This technique - a variant of "path enumeration" or "materialized paths" - allows efficient retrieval of both ancestors and descendants.
+
+It's conceivable that the computed ancestry-string values may get out of whack, particularly if changes are made directly to the database.  If you suspect corruption, you can restore sanity using <tt>rebuild_ancestry</tt>, e.g
+
+    Thing.rebuild_ancestry
+
+The ancestry rebuild is implemented in SQL to leverage the underlying DBMS, and so is pretty efficient, even on large trees.

data/lib/arboreal.rb

@@ -1,17 +1,3 @@
-# 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.
-#
-module Arboreal
-end
-
 require 'arboreal/active_record_extensions'
 require 'arboreal/class_methods'
 require 'arboreal/instance_methods'

data/lib/arboreal/active_record_extensions.rb

@@ -1,6 +1,7 @@
 module Arboreal
   module ActiveRecordExtensions
     
+    # Declares that this ActiveRecord::Base model has a tree-like structure.
     def acts_arboreal
 
       belongs_to :parent, :class_name => self.name

data/lib/arboreal/class_methods.rb

@@ -36,6 +36,7 @@ module Arboreal
           JOIN _arboreals_ AS parent ON parent.id = child.parent_id
           SET child.ancestry_string = CONCAT(parent.ancestry_string, parent.id, '-')
           WHERE child.ancestry_string IS NULL
+            AND parent.ancestry_string IS NOT NULL
         SQL
       elsif connection.adapter_name == "JDBC" && connection.config[:url] =~ /sqlserver/
         <<-SQL
@@ -44,6 +45,7 @@ module Arboreal
           FROM _arboreals_ AS child
           JOIN _arboreals_ AS parent ON parent.id = child.parent_id
           WHERE child.ancestry_string IS NULL
+            AND parent.ancestry_string IS NOT NULL
         SQL
       else # SQLite, PostgreSQL, most others (SQL-92)
         <<-SQL
@@ -52,6 +54,7 @@ module Arboreal
             SELECT (parent.ancestry_string || _arboreals_.parent_id || '-')
             FROM _arboreals_ AS parent
             WHERE parent.id = _arboreals_.parent_id
+              AND parent.ancestry_string IS NOT NULL
           )
           WHERE ancestry_string IS NULL
         SQL

data/lib/arboreal/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: arboreal
 version: !ruby/object:Gem::Version 
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors: 
 - Mike Williams
@@ -47,6 +47,7 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
+- README.rdoc
 - LICENSE
 files: 
 - lib/arboreal/active_record_extensions.rb
@@ -57,6 +58,7 @@ files:
 - spec/arboreal_spec.rb
 - spec/spec_helper.rb
 - Rakefile
+- README.rdoc
 - LICENSE
 has_rdoc: true
 homepage: http://github.com/mdub/arboreal
@@ -64,8 +66,10 @@ licenses: []
 
 post_install_message: 
 rdoc_options: 
-- --main
+- --title
 - Arboreal
+- --main
+- README.rdoc
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement