DanaDanger-hyrarchy 0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 The Indianapolis Star
+ 
+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,69 @@
+= Hyrarchy
+
+Hyrarchy (Hybrid hieRarchy) is a gem and Rails plugin for working with hierarchic data in ActiveRecord. Your models gain methods for finding an instance's parent, children, ancestors, descendants, and depth, as well as a named scope for finding root nodes.
+
+To use Hyrarchy in your Rails app, copy the plugin from the gem into your app's vendors/plugins directory. (The plugin is just a two-liner that loads and activates the gem.)
+
+To use Hyrarchy in one of your models, add the following line to the class:
+
+  class Comment < ActiveRecord::Base
+    is_hierarchic
+  end
+
+Then add the hierarchic columns to the model's database table:
+
+  class MakeCommentsHierarchic < ActiveRecord::Migration
+    def self.up
+      add_hierarchy :comments
+    end
+    
+    def self.down
+      remove_hierarchy :comments
+    end
+  end
+
+Or you can put it in the same migration as the table's creation:
+
+  class CreateCommentsTable < ActiveRecord::Migration
+    def self.up
+      create_table :comments do |t|
+        t.integer :author_id
+        t.text :body
+      end
+      add_hierarchy :comments
+    end
+    
+    def self.down
+      drop_table :comments
+    end
+  end
+
+== Performance
+
+On MySQL, Hyrarchy scales to at least one million nodes with insertion and access times below 100ms. On SQLite, times are below 200ms.
+
+== Database Compatibility
+
+Hyrarchy has been tested on MySQL 5 and SQLite 3.
+
+== Replacing awesome_nested_set
+
+Hyrarchy is designed to be an almost-drop-in replacement for awesome_nested_set. All of awesome_nested_set's methods are implemented by Hyrarchy, but you'll need to replace calls to acts_as_nested_set with is_hierarchic. You'll also need to replace awesome_nested_set's database columns with Hyrarchy's, which you can do with an option to the add_hierarchy migration method:
+
+  add_hierarchy :comments, :convert => :awesome_nested_set
+
+The convert option will modify the table structure but it won't rebuild the hierarchy information. You can rebuild it by calling rebuild! on your hierarchic model class:
+
+  Comment.rebuild!
+
+The same option can be used with remove_hierarchy for the down half of a migration.
+
+Hyrarchy doesn't yet support awesome_nested_set's scoping feature or its view helper.
+
+== Implementation Details
+
+Under the hood, Hyrarchy uses a combination of an adjacency list and a rational nested set. The nested set uses a technique developed by (I think) Vadim Tropashko, in which the left and right values are generated using Farey sequences. This makes it possible to insert new records without adjusting the left and right values of any other records. It also makes it possible to do many operations (like determining a record's depth in the tree) without accessing the database. For operations where rational nested sets perform poorly (such as finding a node's immediate descendants), the adjacency list is used.
+
+== Credits and Copyright
+
+Heavily based on works by Vadim Tropashko and Wim Lewis. Implemented by Dana Danger. Tolerated by VivaZoya. Copyright (c) 2008 The Indianapolis Star, released under the MIT license. See LICENSE for details.

data/lib/hyrarchy.rb

@@ -0,0 +1,317 @@
+require 'hyrarchy/encoded_path'
+require 'hyrarchy/collection_proxy'
+require 'hyrarchy/awesome_nested_set_compatibility'
+
+module Hyrarchy
+  # Fudge factor to account for imprecision with floating point approximations
+  # of a node's left and right fractions.
+  FLOAT_FUDGE_FACTOR = 0.0000000000001 # :nodoc:
+  
+  # Mixes Hyrarchy into ActiveRecord.
+  def self.activate!
+    ActiveRecord::Base.extend IsHierarchic
+    ActiveRecord::Migration.extend Migrations
+  end
+  
+  # These methods are available in ActiveRecord migrations for adding and
+  # removing columns and indexes required by Hyrarchy.
+  module Migrations
+    def add_hierarchy(table, options = {})
+      convert = options.delete(:convert)
+      unless options.empty?
+        raise(ArgumentError, "unknown keys: #{options.keys.join(', ')}")
+      end
+      
+      case convert
+      when :awesome_nested_set
+        remove_column table, :lft
+        remove_column table, :rgt
+      when '', nil
+      else
+        raise(ArgumentError, "don't know how to convert hierarchy from #{convert}")
+      end
+      
+      add_column table, :lft,       :float
+      add_column table, :rgt,       :float
+      add_column table, :lft_numer, :integer
+      add_column table, :lft_denom, :integer
+      add_column table, :parent_id, :integer unless convert == :awesome_nested_set
+      add_index table, :lft
+      add_index table, [:lft_numer, :lft_denom], :unique => true
+      add_index table, :parent_id
+    end
+    
+    def remove_hierarchy(table, options = {})
+      convert = options.delete(:convert)
+      unless options.empty?
+        raise(ArgumentError, "unknown keys: #{options.keys.join(', ')}")
+      end
+      
+      remove_column table, :lft
+      remove_column table, :rgt
+      remove_column table, :lft_numer
+      remove_column table, :lft_denom
+      remove_column table, :parent_id, :integer unless convert == :awesome_nested_set
+      
+      case convert
+      when :awesome_nested_set
+        add_column table, :lft, :integer
+        add_column table, :rgt, :integer
+      when '', nil
+      else
+        raise(ArgumentError, "don't know how to convert hierarchy to #{convert}")
+      end
+    end
+  end
+  
+  module IsHierarchic
+    # Declares that a model represents hierarchic data. Adds a has_many
+    # association for instances' children, and a named scope for the model's
+    # root nodes (called +roots+).
+    def is_hierarchic
+      extend ClassMethods
+      include InstanceMethods
+      
+      has_many :children,
+        :foreign_key => 'parent_id',
+        :order       => 'rgt DESC, lft',
+        :class_name  => self.to_s,
+        :dependent   => :destroy
+      
+      before_save :set_encoded_paths
+      before_save :set_parent_id
+      after_destroy :mark_path_free
+      
+      named_scope :roots,
+        :conditions => { :parent_id => nil },
+        :order      => 'rgt DESC, lft'
+    end
+  end
+  
+  # These private methods are available to model classes that have been
+  # declared is_hierarchic. They're used internally and aren't intended to be
+  # used by application developers.
+  module ClassMethods # :nodoc:
+    include Hyrarchy::AwesomeNestedSetCompatibility::ClassMethods
+    
+  private
+    
+    # Returns an array of unused child paths beneath +parent_path+.
+    def free_child_paths(parent_path)
+      @@free_child_paths ||= {}
+      @@free_child_paths[parent_path] ||= []
+    end
+    
+    # Stores +path+ in the arrays of free child paths.
+    def child_path_is_free(path)
+      parent_path = path.parent(false)
+      free_child_paths(parent_path) << path
+      free_child_paths(parent_path).sort!
+    end
+    
+    # Removes all paths from the array of free child paths for +parent_path+.
+    def reset_free_child_paths(parent_path)
+      free_child_paths(parent_path).clear
+    end
+    
+    # Removes all paths from the array of free child paths.
+    def reset_all_free_child_paths
+      @@free_child_paths = {}
+    end
+    
+    # Finds the first unused child path beneath +parent_path+.
+    def next_child_encoded_path(parent_path)
+      p = free_child_paths(parent_path).shift || parent_path.first_child
+      while true do
+        if exists?(:lft_numer => p.numerator, :lft_denom => p.denominator)
+          p = parent_path.mediant(p)
+        else
+          if free_child_paths(parent_path).empty?
+            child_path_is_free(parent_path.mediant(p))
+          end
+          return p
+        end
+      end
+    end
+    
+    # Returns the node with the specified encoded path.
+    def find_by_encoded_path(p)
+      find(:first, :conditions => {
+        :lft_numer => p.numerator,
+        :lft_denom => p.denominator
+      })
+    end
+  end
+  
+  # These methods are available to instances of models that have been declared
+  # is_hierarchic.
+  module InstanceMethods
+    include Hyrarchy::AwesomeNestedSetCompatibility::InstanceMethods
+    
+    # Returns this node's parent, or +nil+ if this is a root node.
+    def parent
+      return @new_parent if @new_parent
+      p = encoded_path.parent
+      return nil if p.nil?
+      self.class.send(:find_by_encoded_path, p)
+    end
+    
+    # Sets this node's parent. To make this node a root node, set its parent to
+    # +nil+.
+    def parent=(other)
+      @make_root = false
+      if other.nil?
+        @new_parent = nil
+        @make_root = true
+      elsif encoded_path && other.encoded_path == (encoded_path.parent rescue nil)
+        @new_parent = nil
+      else
+        @new_parent = other
+      end
+      other
+    end
+    
+    # Returns an array of this node's descendants: its children, grandchildren,
+    # and so on. The array returned by this method is a named scope.
+    def descendants
+      cached[:descendants] ||=
+        self_and_descendants.scoped :conditions => "id <> #{id}"
+    end
+    
+    # Returns an array of this node's ancestors--its parent, grandparent, and
+    # so on--ordered from parent to root. The array returned by this method is
+    # a has_many association, so you can do things like this:
+    #
+    #   node.ancestors.find(:all, :conditions => { ... })
+    #
+    def ancestors(with_self = false)
+      cache_key = with_self ? :self_and_ancestors : :ancestors
+      return cached[cache_key] if cached[cache_key]
+      
+      paths = []
+      path = with_self ? encoded_path : encoded_path.parent
+      while path do
+        paths << path
+        path = path.parent
+      end
+      
+      cached[cache_key] = CollectionProxy.new(
+        self,
+        cache_key,
+        :conditions => paths.empty? ? "id <> id" : [
+          paths.collect {|p| "(lft_numer = ? AND lft_denom = ?)"}.join(" OR "),
+          *(paths.collect {|p| [p.numerator, p.denominator]}.flatten)
+        ],
+        :order => 'rgt DESC, lft'
+      )
+    end
+    
+    # Returns the root node related to this node, or nil if this node is a root
+    # node.
+    def root
+      return cached[:root] if cached[:root]
+      
+      path = encoded_path.parent
+      while path do
+        parent = path.parent
+        break if parent.nil?
+        path = parent
+      end
+      
+      if path
+        self.class.send :find_by_encoded_path, path
+      else
+        nil
+      end
+    end
+    
+    # Returns the number of nodes between this one and the top of the tree.
+    def depth
+      encoded_path.depth - 1
+    end
+    
+    # Overrides ActiveRecord's reload method to clear cached scopes and ad hoc
+    # associations.
+    def reload(options = nil) # :nodoc:
+      @cached = {}
+      super
+    end
+
+  protected
+    
+    # Sets the node's encoded path, updating all relevant database columns to
+    # match.
+    def encoded_path=(r) # :nodoc:
+      @cached = {}
+      if r.nil?
+        self.lft_numer = nil
+        self.lft_denom = nil
+        self.lft = nil
+        self.rgt = nil
+      else
+        self.lft_numer = r.numerator
+        self.lft_denom = r.denominator
+        self.lft = r.to_f
+        self.rgt = encoded_path.next_farey_fraction.to_f
+      end
+      r
+    end
+    
+    # Returns the node's encoded path (its rational left value).
+    def encoded_path # :nodoc:
+      return nil if lft_numer.nil? || lft_denom.nil?
+      Hyrarchy::EncodedPath(lft_numer, lft_denom)
+    end
+    
+    # Returns a hash for caching scopes and ad hoc associations.
+    def cached # :nodoc:
+      @cached ||= {}
+    end
+    
+  private
+    
+    # before_save callback to ensure that this node's encoded path is a child
+    # of its parent, and that its descendants' paths are updated if this node
+    # has moved.
+    def set_encoded_paths # :nodoc:
+      p = nil
+      self.lft_numer = self.lft_denom = nil if @make_root
+      
+      if @new_parent.nil?
+        if lft_numer.nil? || lft_denom.nil?
+          p = Hyrarchy::EncodedPath::ROOT
+        end
+      else
+        p = @new_parent.encoded_path
+      end
+      
+      if p
+        new_path = self.class.send(:next_child_encoded_path, p)
+        if encoded_path != new_path
+          self.class.send(:reset_free_child_paths, encoded_path)
+          self.encoded_path = new_path
+          children.each do |c|
+            c.parent = self
+            c.save!
+          end
+        end
+      end
+      
+      true
+    end
+    
+    # before_save callback to ensure that this node's parent_id attribute
+    # agrees with its encoded path.
+    def set_parent_id # :nodoc:
+      parent = self.class.send(:find_by_encoded_path, encoded_path.parent(false))
+      self.parent_id = parent ? parent.id : nil
+      true
+    end
+    
+    # after_destroy callback to add this node's encoded path to its parent's
+    # list of available child paths.
+    def mark_path_free # :nodoc:
+      self.class.send(:child_path_is_free, encoded_path)
+    end
+  end
+end

data/lib/hyrarchy/awesome_nested_set_compatibility.rb

@@ -0,0 +1,295 @@
+module Hyrarchy
+  module AwesomeNestedSetCompatibility
+    module ClassMethods
+      # Returns the first root node.
+      def root
+        roots.first
+      end
+
+      # Returns true if the model's left and right values are valid, and all
+      # root nodes have no ancestors.
+      def valid?
+        left_and_rights_valid? && all_roots_valid?
+      end
+
+      # Returns true if the model's left and right values match the parent_id
+      # attributes.
+      def left_and_rights_valid?
+        # Load all nodes and index them by ID so we can leave the database
+        # alone.
+        nodes = connection.select_all("SELECT id, lft_numer, lft_denom, parent_id FROM #{quoted_table_name}")
+        nodes_by_id = {}
+        nodes.each do |node|
+          node['id']           = node['id'].to_i
+          node['encoded_path'] = Hyrarchy::EncodedPath(node['lft_numer'].to_i, node['lft_denom'].to_i)
+          node['parent_id']    = node['parent_id'] ? node['parent_id'].to_i : nil
+          nodes_by_id[node['id']] = node
+        end
+        # Check to see if the structure defined by the nodes' encoded paths
+        # matches the structure defined by their parent_id attributes.
+        nodes.all? do |node|
+          if node['parent_id'].nil?
+            node['encoded_path'].parent == nil rescue false
+          else
+            parent = nodes_by_id[node['parent_id']]
+            parent && node['encoded_path'].parent == parent['encoded_path']
+          end
+        end
+      end
+
+      # Always returns true. This method exists solely for compatibility with
+      # awesome_nested_set; the test it performs doesn't apply to Hyrarchy.
+      def no_duplicates_for_columns?
+        true
+      end
+
+      # Returns true if all roots have no ancestors.
+      def all_roots_valid?
+        each_root_valid?(roots)
+      end
+
+      # Returns true if all of the nodes in +roots_to_validate+ have no
+      # ancestors.
+      def each_root_valid?(roots_to_validate)
+        roots_to_validate.all? {|r| r.root?}
+      end
+
+      # Rebuilds the model's hierarchy attributes based on the parent_id
+      # attributes.
+      def rebuild!
+        return true if (valid? rescue false)
+        
+        update_all("lft = id, rgt = id, lft_numer = id, lft_denom = id")
+        reset_all_free_child_paths
+        paths_by_id = {}
+        order_by = columns_hash['created_at'] ? :created_at : :id
+        
+        nodes = roots :order => order_by
+        until nodes.empty? do
+          nodes.each do |node|
+            parent_path = paths_by_id[node.parent_id] || Hyrarchy::EncodedPath::ROOT
+            node.send(:encoded_path=, next_child_encoded_path(parent_path))
+            node.send(:create_or_update_without_callbacks) || raise(RecordNotSaved)
+            paths_by_id[node.id] = node.send(:encoded_path)
+          end
+          node_ids = nodes.collect {|n| n.id}
+          nodes = find(:all, :conditions => { :parent_id => node_ids }, :order => order_by)
+        end
+      end
+    end
+    
+    module InstanceMethods
+      # Returns this node's left value. Records that haven't yet been saved
+      # won't have left values.
+      def left
+        encoded_path
+      end
+
+      # Returns this node's left value. Records that haven't yet been saved
+      # won't have right values.
+      def right
+        encoded_path && encoded_path.next_farey_fraction
+      end
+
+      # Returns true if this is a root node.
+      def root?
+        (encoded_path.nil? || depth == 0 || @make_root) && !@new_parent
+      end
+
+      # Returns true if this node has no children.
+      def leaf?
+        children.empty?
+      end
+
+      # Returns true if this node is a child of another node.
+      def child?
+        !root?
+      end
+
+      # Compares two nodes by their left values.
+      def <=>(x)
+        x.left <=> left
+      end
+
+      # Returns an array containing this node and its ancestors, starting with
+      # this node and ending with its root. The array returned by this method
+      # is a has_many association, so you can do things like this:
+      #
+      #   node.self_and_ancestors.find(:all, :conditions => { ... })
+      #
+      def self_and_ancestors
+        ancestors(true)
+      end
+
+      # Returns an array containing this node and its siblings. The array
+      # returned by this method is a has_many association, so you can do things
+      # like this:
+      #
+      #   node.self_and_siblings.find(:all, :conditions => { ... })
+      #
+      def self_and_siblings
+        siblings(true)
+      end
+
+      # Returns an array containing this node's siblings. The array returned by
+      # this method is a has_many association, so you can do things like this:
+      #
+      #   node.siblings.find(:all, :conditions => { ... })
+      #
+      def siblings(with_self = false)
+        cache_key = with_self ? :self_and_siblings : :siblings
+        return cached[cache_key] if cached[cache_key]
+
+        if with_self
+          conditions = { :parent_id => parent_id }
+        else
+          conditions = ["parent_id #{parent_id.nil? ? 'IS' : '='} ? AND id <> ?",
+            parent_id, id]
+        end
+
+        cached[cache_key] = self.class.scoped(
+          :conditions => conditions,
+          :order      => 'rgt DESC, lft'
+        )
+      end
+
+      # Returns an array containing this node's childless descendants. The
+      # array returned by this method is a named scope.
+      def leaves
+        cached[:leaves] ||= descendants.scoped :conditions => "NOT EXISTS (
+          SELECT * FROM #{self.class.quoted_table_name} tt
+          WHERE tt.parent_id = #{self.class.quoted_table_name}.id
+        )"
+      end
+
+      # Alias for depth.
+      def level
+        depth
+      end
+
+      # Returns an array of this node and its descendants: its children,
+      # grandchildren, and so on. The array returned by this method is a
+      # has_many association, so you can do things like this:
+      #
+      #   node.self_and_descendants.find(:all, :conditions => { ... })
+      #
+      def self_and_descendants
+        cached[:self_and_descendants] ||= CollectionProxy.new(
+          self,
+          :descendants,
+          :conditions => { :lft => (lft - FLOAT_FUDGE_FACTOR)..(rgt + FLOAT_FUDGE_FACTOR) },
+          :order => 'rgt DESC, lft',
+          # The query conditions intentionally load extra records that aren't
+          # descendants to account for floating point imprecision. This
+          # procedure removes the extra records.
+          :after => Proc.new do |records|
+            r = encoded_path.next_farey_fraction
+            records.delete_if do |n|
+              n.encoded_path < encoded_path || n.encoded_path >= r
+            end
+          end,
+          # The regular count method doesn't work because of the fudge factor
+          # in the conditions. This procedure uses the length of the records
+          # array if it's been loaded. Otherwise it does a raw SQL query (to
+          # avoid the expense of instantiating a bunch of ActiveRecord objects)
+          # and prunes the results in the same manner as the :after procedure.
+          :count => Proc.new do
+            if descendants.loaded?
+              descendants.length
+            else
+              rows = self.class.connection.select_all("
+                SELECT lft_numer, lft_denom
+                FROM #{self.class.quoted_table_name}
+                WHERE #{descendants.conditions}")
+              r = encoded_path.next_farey_fraction
+              rows.delete_if do |row|
+                p = Hyrarchy::EncodedPath(
+                  row['lft_numer'].to_i,
+                  row['lft_denom'].to_i)
+                p < encoded_path || p >= r
+              end
+              rows.length
+            end
+          end
+        )
+      end
+
+      # Returns true if this node is a descendant of +other+.
+      def is_descendant_of?(other)
+        left > other.left && left <= other.right
+      end
+
+      # Returns true if this node is a descendant of +other+, or if this node
+      # is +other+.    
+      def is_or_is_descendant_of?(other)
+        left >= other.left && left <= other.right
+      end
+
+      # Returns true if this node is an ancestor of +other+.
+      def is_ancestor_of?(other)
+        other.left > left && other.left <= right
+      end
+
+      # Returns true if this node is an ancestor of +other+, or if this node is
+      # +other+.
+      def is_or_is_ancestor_of?(other)
+        other.left >= left && other.left <= right
+      end
+
+      # Always returns true. This method exists solely for compatibility with
+      # awesome_nested_set; Hyrarchy doesn't support scoping (but maybe it will
+      # some day).
+      def same_scope?(other)
+        true
+      end
+
+      def left_sibling # :nodoc:
+        raise NotImplementedError, "awesome_nested_set's left_sibling method isn't implemented in this version of Hyrarchy"
+      end
+
+      def right_sibling # :nodoc:
+        raise NotImplementedError, "awesome_nested_set's right_sibling method isn't implemented in this version of Hyrarchy"
+      end
+
+      def move_left # :nodoc:
+        raise NotImplementedError, "awesome_nested_set's move_left method isn't implemented in this version of Hyrarchy"
+      end
+
+      def move_right # :nodoc:
+        raise NotImplementedError, "awesome_nested_set's move_right method isn't implemented in this version of Hyrarchy"
+      end
+
+      def move_to_left_of(other) # :nodoc:
+        raise NotImplementedError, "awesome_nested_set's move_to_left_of method isn't implemented in this version of Hyrarchy"
+      end
+
+      def move_to_right_of(other) # :nodoc:
+        raise NotImplementedError, "awesome_nested_set's move_to_right_of method isn't implemented in this version of Hyrarchy"
+      end
+
+      # Sets this node's parent to +node+ and calls save!.
+      def move_to_child_of(node)
+        node = self.class.find(node)
+        self.parent = node
+        save!
+      end
+
+      # Makes this node a root node and calls save!.
+      def move_to_root
+        self.parent = nil
+        save!
+      end
+
+      def move_possible?(target) # :nodoc:
+        raise NotImplementedError, "awesome_nested_set's move_possible? method isn't implemented in this version of Hyrarchy"
+      end
+
+      # Returns a textual representation of this node and its descendants.
+      def to_text
+        self_and_descendants.map do |node|
+          "#{'*'*(node.depth+1)} #{node.id} #{node.to_s} (#{node.parent_id}, #{node.left}, #{node.right})"
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/hyrarchy/collection_proxy.rb

@@ -0,0 +1,65 @@
+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)
+      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
+    
+  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,101 @@
+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
+    
+    # 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

data/test/encoded_path_test.rb

@@ -0,0 +1,31 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class EncodedPathTests < Test::Unit::TestCase
+  def setup
+    @path = Hyrarchy::EncodedPath(5, 7)
+  end
+
+  def test_next_farey_fraction
+    assert_equal(Rational(3, 4), @path.send(:next_farey_fraction))
+  end
+
+  def test_mediant
+    assert_equal(Rational(15, 20), @path.send(:mediant, Rational(10, 13)))
+  end
+
+  def test_parent
+    assert_equal(Rational(2, 3), @path.parent)
+  end
+
+  def test_depth
+    assert_equal(3, @path.depth)
+  end
+
+  def test_first_child
+    assert_equal(Rational(8, 11), @path.first_child)
+  end
+  
+  def test_next_sibling
+    assert_equal(Rational(7, 10), @path.next_sibling)
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+require 'rubygems'
+require 'activerecord'
+require 'test/unit'
+
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'hyrarchy'

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: DanaDanger-hyrarchy
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+platform: ruby
+authors: 
+- Dana Danger
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-12-15 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: 
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- LICENSE
+files: 
+- lib/hyrarchy.rb
+- lib/hyrarchy/collection_proxy.rb
+- lib/hyrarchy/encoded_path.rb
+- lib/hyrarchy/awesome_nested_set_compatibility.rb
+- rails_plugin/init.rb
+- README.rdoc
+- spec/create_nodes_table.rb
+- spec/database.yml
+- spec/hyrarchy_spec.rb
+- spec/spec_helper.rb
+- test/encoded_path_test.rb
+- test/test_helper.rb
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/DanaDanger/hyrarchy
+post_install_message: 
+rdoc_options: 
+- --all
+- --inline-source
+- --line-numbers
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A gem and Rails plugin for working with hierarchic data.
+test_files: 
+- spec/create_nodes_table.rb
+- spec/database.yml
+- spec/hyrarchy_spec.rb
+- spec/spec_helper.rb
+- test/encoded_path_test.rb
+- test/test_helper.rb