hyrarchy 0.3.3

data/lib/hyrarchy/collection_proxy.rb

@@ -0,0 +1,75 @@
+module Hyrarchy
+  # This is a shameful hack to create has_many associations with no foreign key
+  # and an option for running a post-processing procedure on the array of
+  # records. Hyrarchy uses this class to provide the features of a has_many
+  # association on a node's ancestors and descendants arrays.
+  class CollectionProxy < ActiveRecord::Associations::HasManyAssociation # :nodoc:
+    def initialize(owner, name, options = {})
+      @after = options.delete(:after)
+      @count = options.delete(:count)
+      @index = options.delete(:index)
+      reflection = ActiveRecord::Base.create_reflection(
+        :has_many, name, options.merge(:class_name => owner.class.to_s), owner.class)
+      super(owner, reflection)
+    end
+    
+    # This is ripped right from the construct_sql method in HasManyAssociation,
+    # but the foreign key condition has been removed.
+    def construct_sql
+      if @reflection.options[:finder_sql]
+        @finder_sql = interpolate_sql(@reflection.options[:finder_sql])
+      else
+        @finder_sql = conditions
+      end
+      
+      if @reflection.options[:counter_sql]
+        @counter_sql = interpolate_sql(@reflection.options[:counter_sql])
+      elsif @reflection.options[:finder_sql]
+        # replace the SELECT clause with COUNT(*), preserving any hints within /* ... */
+        @reflection.options[:counter_sql] = @reflection.options[:finder_sql].sub(/SELECT (\/\*.*?\*\/ )?(.*)\bFROM\b/im) { "SELECT #{$1}COUNT(*) FROM" }
+        @counter_sql = interpolate_sql(@reflection.options[:counter_sql])
+      else
+        @counter_sql = @finder_sql
+      end
+    end
+    
+    # Overrides find to run the association's +after+ procedure on the results.
+    def find(*args)
+      records = super
+      @after.call(records) if @after
+      records
+    end
+    
+    # Overrides count to run the association's +count+ procedure, with caching.
+    def count
+      if @count
+        if @count.respond_to?(:call)
+          @count = @count.call
+        else
+          @count
+        end
+      else
+        super
+      end
+    end
+    
+    # Overrides index to run the association's +index+ procedure.
+    def index(obj)
+      if @index && !loaded?
+        @index.call(obj)
+      else
+        super
+      end
+    end
+    
+  protected
+    
+    # Overrides find_target to run the association's +after+ procedure on the
+    # results.
+    def find_target
+      records = super
+      @after.call(records) if @after
+      records
+    end
+  end
+end

data/lib/hyrarchy/encoded_path.rb

@@ -0,0 +1,111 @@
+require 'rational'
+
+module Hyrarchy
+  # Returns a new path with numerator +n+ and denominator +d+, which will be
+  # reduced if possible. Paths must be in the interval [0,1]. This method
+  # correlates to the Rational(n, d) method.
+  def self.EncodedPath(n, d) # :nodoc:
+    r = EncodedPath.reduce n, d
+    raise(RangeError, "paths must be in the interval [0,1]") if r < 0 || r > 1
+    r
+  end
+  
+  # An encoded path is a rational number that represents a node's position in
+  # the tree. By using rational numbers instead of integers, new nodes can be
+  # inserted arbitrarily without having to adjust the left and right values of
+  # any other nodes. Farey sequences are used to prevent denominators from
+  # growing exponentially and quickly exhausting the database's integer range.
+  # For more information, see "Nested Intervals with Farey Fractions" by Vadim
+  # Tropashko: http://arxiv.org/html/cs.DB/0401014
+  class EncodedPath < Rational # :nodoc:
+    # Path of the uppermost node in the tree. The node at this path has no
+    # siblings, and all nodes descend from it.
+    ROOT = Hyrarchy::EncodedPath(0, 1)
+    
+    # Returns the path of the parent of the node at this path. If +root_is_nil+
+    # is true (the default) and the parent is the root node, returns nil.
+    def parent(root_is_nil = true)
+      r = next_farey_fraction
+      p = Hyrarchy::EncodedPath(
+        numerator - r.numerator,
+        denominator - r.denominator)
+      (root_is_nil && p == ROOT) ? nil : p
+    end
+    
+    # Returns the depth of the node at this path, starting from the root node.
+    # Paths in the uppermost layer (considered "root nodes" by the ActiveRecord
+    # methods) have a depth of one.
+    def depth
+      n = self
+      depth = 0
+      while n != ROOT
+        n = n.parent(false)
+        depth += 1
+      end
+      depth
+    end
+    
+    # Returns the path of the first child of the node at this path.
+    def first_child
+      mediant(next_farey_fraction)
+    end
+    
+    # Returns the path of the sibling immediately after the node at this path.
+    def next_sibling
+      parent(false).mediant(self)
+    end
+    
+    # Returns the path of the sibling immediately before the node at this path.
+    # If this is the path of the first sibling, returns nil.
+    def previous_sibling
+      p = parent(false)
+      return nil if self == p.first_child
+      Hyrarchy::EncodedPath(
+        numerator - p.numerator,
+        denominator - p.denominator)
+    end
+    
+    # Finds the mediant of this fraction and +other+.
+    def mediant(other)
+      Hyrarchy::EncodedPath(
+        numerator + other.numerator,
+        denominator + other.denominator)
+    end
+    
+    # Returns the fraction immediately after this one in the Farey sequence
+    # whose order is this fraction's denominator. This is the find-neighbors
+    # algorithm from "Rounding rational numbers using Farey/Cauchy sequence" by
+    # Wim Lewis: http://www.hhhh.org/wiml/proj/farey
+    def next_farey_fraction
+      # Handle the special case of the last fraction.
+      return nil if self == Rational(1, 1)
+      # Compute the modular multiplicative inverses of the numerator and
+      # denominator using an iterative extended Euclidean algorithm. These
+      # inverses are the denominator and negative numerator of the fraction
+      # preceding this one, modulo the numerator and denominator of this
+      # fraction.
+      a, b = [numerator, denominator]
+      x, lastx, y, lasty = [0, 1, 1, 0]
+      while b != 0
+        a, b, q = [b, a % b, a / b]
+        x, lastx = [lastx - q * x, x]
+        y, lasty = [lasty - q * y, y]
+      end
+      qL, pL = [lastx, -lasty]
+      # Find the numerator and denominator of the fraction following this one
+      # using the mediant relationship between it, this fraction, and the
+      # preceding fraction. The modulo ambiguity is resolved by brute force,
+      # which is probably not the smartest way to do it, but it's fast enough.
+      i = 0
+      while true do
+        a = pL + numerator * i
+        b = qL + denominator * i
+        if (numerator * b - denominator * a == 1) &&
+          (Rational(numerator - a, denominator - b).denominator <= denominator)
+          return Hyrarchy::EncodedPath(numerator - a, denominator - b)
+        end
+        i += 1
+      end
+    end
+  end
+end

data/rails_plugin/init.rb

@@ -0,0 +1,2 @@
+require 'hyrarchy'
+Hyrarchy.activate!

data/spec/create_nodes_table.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+gem 'sqlite3-ruby'
+require 'activerecord'
+require 'yaml'
+
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'hyrarchy'
+Hyrarchy.activate!
+
+db_specs = YAML.load_file(File.join(File.dirname(__FILE__), 'database.yml'))
+which_spec = ENV['DB'] || 'mysql'
+ActiveRecord::Base.establish_connection(db_specs[which_spec])
+
+class CreateNodesTable < ActiveRecord::Migration
+  def self.up
+    create_table :nodes do |t|
+      t.string :name, :null => false
+    end
+    add_hierarchy :nodes
+  end
+  
+  def self.down
+    drop_table :nodes
+  end
+end

data/spec/database.yml

@@ -0,0 +1,10 @@
+mysql:
+  adapter: mysql
+  host: localhost
+  database: hyrarchy_test
+  username: root
+  password:
+
+sqlite:
+  adapter: sqlite3
+  database: spec/test.sqlite3

data/spec/hyrarchy_spec.rb

@@ -0,0 +1,184 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe Hyrarchy do
+  describe "(functionality)" do
+    before(:all) do
+      Node.delete_all
+      
+      @roots = [
+        Node.create!(:name => 'root 0'),
+        Node.create!(:name => 'root 1'),
+        Node.create!(:name => 'root 2')
+      ]
+      @layer1 = [
+        Node.create!(:name => '1.0', :parent => @roots[1]),
+        Node.create!(:name => '1.1', :parent => @roots[1]),
+        Node.create!(:name => '1.2', :parent => @roots[1])
+      ]
+      @layer2 = [
+        Node.create!(:name => '1.0.0', :parent => @layer1[0]),
+        Node.create!(:name => '1.0.1', :parent => @layer1[0]),
+        Node.create!(:name => '1.1.0', :parent => @layer1[1]),
+        Node.create!(:name => '1.1.1', :parent => @layer1[1]),
+        Node.create!(:name => '1.2.0', :parent => @layer1[2]),
+        Node.create!(:name => '1.2.1', :parent => @layer1[2])
+      ]
+    
+      @roots.collect! {|n| Node.find(n.id)}
+      @layer1.collect! {|n| Node.find(n.id)}
+      @layer2.collect! {|n| Node.find(n.id)}
+    end
+  
+    it "should find its parent" do
+      @layer2[0].parent.should == @layer1[0]
+      @layer2[1].parent.should == @layer1[0]
+      @layer2[2].parent.should == @layer1[1]
+      @layer2[3].parent.should == @layer1[1]
+      @layer2[4].parent.should == @layer1[2]
+      @layer2[5].parent.should == @layer1[2]
+      @layer1.each {|n| n.parent.should == @roots[1]}
+      @roots.each {|n| n.parent.should == nil}
+    end
+  
+    it "should find its descendants" do
+      returned_descendants = @roots[1].descendants
+      returned_descendants.sort! {|a,b| a.name <=> b.name}
+      actual_descendants = @layer1 + @layer2
+      actual_descendants.sort! {|a,b| a.name <=> b.name}
+      returned_descendants.should == actual_descendants
+      @roots[0].descendants.should be_empty
+      @roots[2].descendants.should be_empty
+    end
+  
+    it "should find its children" do
+      @roots[0].children.should be_empty
+      @roots[1].children.should == @layer1
+      @roots[2].children.should be_empty
+      @layer1[0].children.should == [@layer2[0], @layer2[1]]
+      @layer1[1].children.should == [@layer2[2], @layer2[3]]
+      @layer1[2].children.should == [@layer2[4], @layer2[5]]
+      @layer2.each {|n| n.children.should be_empty}
+    end
+  
+    it "should find its ancestors" do
+      @layer2[0].ancestors.should == [@layer1[0], @roots[1]]
+      @layer2[1].ancestors.should == [@layer1[0], @roots[1]]
+      @layer2[2].ancestors.should == [@layer1[1], @roots[1]]
+      @layer2[3].ancestors.should == [@layer1[1], @roots[1]]
+      @layer2[4].ancestors.should == [@layer1[2], @roots[1]]
+      @layer2[5].ancestors.should == [@layer1[2], @roots[1]]
+      @layer1.each {|n| n.ancestors.should == [@roots[1]]}
+      @roots.each {|n| n.ancestors.should be_empty}
+    end
+  
+    it "should find all root nodes" do
+      Node.roots.should == @roots
+    end
+  end
+  
+  describe "(data integrity)" do
+    before(:each) do
+      Node.delete_all
+      
+      @roots = [
+        Node.create!(:name => 'root 0'),
+        Node.create!(:name => 'root 1'),
+        Node.create!(:name => 'root 2')
+      ]
+      @layer1 = [
+        Node.create!(:name => '1.0', :parent => @roots[1]),
+        Node.create!(:name => '1.1', :parent => @roots[1]),
+        Node.create!(:name => '1.2', :parent => @roots[1])
+      ]
+      @layer2 = [
+        Node.create!(:name => '1.0.0', :parent => @layer1[0]),
+        Node.create!(:name => '1.0.1', :parent => @layer1[0]),
+        Node.create!(:name => '1.1.0', :parent => @layer1[1]),
+        Node.create!(:name => '1.1.1', :parent => @layer1[1]),
+        Node.create!(:name => '1.2.0', :parent => @layer1[2]),
+        Node.create!(:name => '1.2.1', :parent => @layer1[2])
+      ]
+    
+      @roots.collect! {|n| Node.find(n.id)}
+      @layer1.collect! {|n| Node.find(n.id)}
+      @layer2.collect! {|n| Node.find(n.id)}
+    end
+    
+    it "should keep its descendants if it's moved to a different parent" do
+      @roots[1].parent = @roots[2]
+      @roots[1].save!
+      
+      returned_descendants = @roots[2].descendants
+      returned_descendants.sort! {|a,b| a.name <=> b.name}
+      actual_descendants = @layer1 + @layer2 + [@roots[1]]
+      actual_descendants.sort! {|a,b| a.name <=> b.name}
+      returned_descendants.should == actual_descendants
+      @roots[0].descendants.should be_empty
+      
+      actual_descendants.delete(@roots[1])
+      returned_descendants = @roots[1].descendants
+      returned_descendants.sort! {|a,b| a.name <=> b.name}
+      returned_descendants.should == actual_descendants
+    end
+    
+    it "should destroy its descendants if it's destroyed" do
+      @roots[1].destroy
+      (@layer1 + @layer2).each do |node|
+        lambda { Node.find(node.id) }.should raise_error(ActiveRecord::RecordNotFound)
+      end
+    end
+  end
+  
+  describe "(performance)" do
+    SAMPLE_SIZE = 15000
+    LAYERS = 10
+    TIME_SPEC = ENV['DB'] == 'sqlite' ? 0.2 : 0.1
+    
+    def test_times(times)
+      (times.mean + 3 * times.stddev).should satisfy {|n| n < TIME_SPEC}
+      slope, offset = linear_regression(times)
+      (slope * 1_000_000 + offset).should satisfy {|n| n < TIME_SPEC}
+    end
+    
+    unless ENV['SKIP_PERFORMANCE']
+      it "should scale with constant insertion and access times < #{(TIME_SPEC * 1000).to_i}ms" do
+        Node.connection.execute("TRUNCATE TABLE #{Node.quoted_table_name}") rescue Node.delete_all
+        insertion_times   = NArray.float(SAMPLE_SIZE)
+        parent_times      = NArray.float(SAMPLE_SIZE)
+        children_times    = NArray.float(SAMPLE_SIZE)
+        ancestors_times   = NArray.float(SAMPLE_SIZE)
+        descendants_times = NArray.float(SAMPLE_SIZE)
+      
+        i = -1
+        layer = []
+        (SAMPLE_SIZE / LAYERS).times do |j|
+          insertion_times[i+=1] = measure_time { layer << Node.create!(:name => j.to_s) }
+        end
+        (LAYERS-1).times do
+          new_layer = []
+          (SAMPLE_SIZE / LAYERS).times do |j|
+            parent = layer[rand(layer.length)]
+            insertion_times[i+=1] = measure_time { new_layer << Node.create!(:name => j.to_s, :parent => parent) }
+          end
+          layer = new_layer
+        end
+      
+        ids = Node.connection.select_all("SELECT id FROM #{Node.quoted_table_name}")
+        ids.collect! {|row| row["id"].to_i}
+        SAMPLE_SIZE.times do |i|
+          node = Node.find(ids[rand(ids.length)])
+          parent_times[i]      = measure_time { node.parent      }
+          children_times[i]    = measure_time { node.children    }
+          ancestors_times[i]   = measure_time { node.ancestors   }
+          descendants_times[i] = measure_time { node.descendants }
+        end
+        
+        test_times(insertion_times)
+        test_times(parent_times)
+        test_times(children_times)
+        test_times(ancestors_times)
+        test_times(descendants_times)
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,52 @@
+require 'rubygems'
+gem 'sqlite3-ruby'
+require 'spec'
+require 'activerecord'
+require 'yaml'
+require 'narray'
+
+# Load and activate Hyrarchy.
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'hyrarchy'
+Hyrarchy.activate!
+
+# Set up a logger.
+log_path = File.join(File.dirname(__FILE__), 'log')
+File.unlink(log_path) rescue nil
+ActiveRecord::Base.logger = ActiveSupport::BufferedLogger.new(log_path)
+ActiveRecord::Base.logger.add 0, "\n"
+
+# Connect to the test database.
+db_specs = YAML.load_file(File.join(File.dirname(__FILE__), 'database.yml'))
+which_spec = ENV['DB'] || 'mysql'
+ActiveRecord::Base.establish_connection(db_specs[which_spec])
+
+# Create a model class for testing.
+class Node < ActiveRecord::Base
+  is_hierarchic
+  connection.execute("TRUNCATE TABLE #{quoted_table_name}") rescue delete_all
+  def inspect; name end
+end
+
+# Runs a block and returns how long it took in seconds (with subsecond
+# precision).
+def measure_time(&block)
+  start_time = Time.now
+  yield
+  Time.now - start_time
+end
+
+# Calculates the slope and offset of a data set.
+def linear_regression(data)
+  sxx = sxy = sx = sy = 0
+  data.length.times do |x|
+    y = data[x]
+    sxy += x*y
+    sxx += x*x
+    sx  += x
+    sy  += y
+  end
+  slope = (data.length * sxy - sx * sy) / (data.length * sxx - sx * sx)
+  offset = (sy - slope * sx) / data.length
+  [slope, offset]
+end