hierarchy 1.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,25 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+.bundle
+.rvmrc
+
+## PROJECT::DOCUMENTATION
+.yardoc
+doc

data/.rspec

@@ -0,0 +1 @@
+-cfs

data/Gemfile

@@ -0,0 +1,13 @@
+source :rubygems
+
+# DEPENDENCIES
+gem 'rails', '>= 3.0'
+
+# DEVELOPMENT
+gem 'jeweler'
+gem 'yard'
+gem 'RedCloth', require: 'redcloth'
+gem 'pg'
+
+# TEST
+gem 'rspec'

data/Gemfile.lock

@@ -0,0 +1,100 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    RedCloth (4.2.3)
+    abstract (1.0.0)
+    actionmailer (3.0.1)
+      actionpack (= 3.0.1)
+      mail (~> 2.2.5)
+    actionpack (3.0.1)
+      activemodel (= 3.0.1)
+      activesupport (= 3.0.1)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4.1)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.12)
+      rack-test (~> 0.5.4)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.1)
+      activesupport (= 3.0.1)
+      builder (~> 2.1.2)
+      i18n (~> 0.4.1)
+    activerecord (3.0.1)
+      activemodel (= 3.0.1)
+      activesupport (= 3.0.1)
+      arel (~> 1.0.0)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.1)
+      activemodel (= 3.0.1)
+      activesupport (= 3.0.1)
+    activesupport (3.0.1)
+    arel (1.0.1)
+      activesupport (~> 3.0.0)
+    builder (2.1.2)
+    diff-lcs (1.1.2)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    gemcutter (0.6.1)
+    git (1.2.5)
+    i18n (0.4.2)
+    jeweler (1.4.0)
+      gemcutter (>= 0.1.0)
+      git (>= 1.2.5)
+      rubyforge (>= 2.0.0)
+    json_pure (1.4.6)
+    mail (2.2.9)
+      activesupport (>= 2.3.6)
+      i18n (~> 0.4.1)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.16)
+    pg (0.9.0)
+    polyglot (0.3.1)
+    rack (1.2.1)
+    rack-mount (0.6.13)
+      rack (>= 1.0.0)
+    rack-test (0.5.6)
+      rack (>= 1.0)
+    rails (3.0.1)
+      actionmailer (= 3.0.1)
+      actionpack (= 3.0.1)
+      activerecord (= 3.0.1)
+      activeresource (= 3.0.1)
+      activesupport (= 3.0.1)
+      bundler (~> 1.0.0)
+      railties (= 3.0.1)
+    railties (3.0.1)
+      actionpack (= 3.0.1)
+      activesupport (= 3.0.1)
+      rake (>= 0.8.4)
+      thor (~> 0.14.0)
+    rake (0.8.7)
+    rspec (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+      rspec-mocks (~> 2.0.1)
+    rspec-core (2.0.1)
+    rspec-expectations (2.0.1)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+    rubyforge (2.0.4)
+      json_pure (>= 1.1.7)
+    thor (0.14.3)
+    treetop (1.4.8)
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.23)
+    yard (0.6.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  RedCloth
+  jeweler
+  pg
+  rails (>= 3.0)
+  rspec
+  yard

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Tim Morgan
+
+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.textile

@@ -0,0 +1,96 @@
+h1. Hierarchy -- Use PostgreSQL @LTREE@ columns in ActiveRecord
+
+| *Author* | Tim Morgan |
+| *Version* | 1.0 (Oct 30, 2010) |
+| *License* | Released under the MIT license. |
+
+h2. About
+
+The @LTREE@ column type is a PostgreSQL-specific type (installation script is
+available in the @contrib@ directory in your PostgreSQL installation) for
+representing hierarchies. It is more efficient than the typical way of
+accomplishing hierarchal structures in SQL, the @parent_id@ column (or similar).
+
+This gem lets you use an @LTREE@-utilizing hierarchy in ActiveRecord. Including
+this gem in your project gets you a) monkey-patches* to Arel to support @LTREE@
+columns, and b) a module you can include in your models, providing an abundance
+of methods to help you navigate and manipulate the hierarchy.
+
+*Though I don't know for sure, I suspect when Arel 2.0 is supported in Rails, I
+will be able to remove this monkey-patching ugliness.
+
+h2. Installation
+
+*Important Note:* This gem requires Ruby 1.9 and Rails 3.0.
+
+Firstly, add the gem to your Rails project's @Gemfile@:
+
+<pre><code>
+gem 'hierarchy'
+</code></pre>
+
+Then, run the generator to install the migration:
+
+<pre><code>
+rails generate hierarchy
+</code></pre>
+
+Note that *this migration must precede any tables using @LTREEs@*, so reorder
+the migration if you have to.
+
+h2. Usage
+
+Because this gem was hastily extracted from a personal project, it's a little
+constraining in how it can be used. (Sorry.) Currently the gem requires that
+your table schema have a column named @path@ of type @LTREE@, defined as in the
+example below:
+
+<pre><code>
+path LTREE NOT NULL DEFAULT ''
+</code></pre>
+
+Once you've got that column in your model, feel free to include the @Hierarchy@
+module:
+
+<pre><code>
+class Person < ActiveRecord::Base
+  include Hierarchy
+end
+</code></pre>
+
+You can now define hierarchy by setting a model's @parent@, like so:
+
+<pre><code>
+person.parent = mother #=> Sets the `path` column appropriately
+</code></pre>
+
+You also have access to a wealth of ways to traverse the hierarchy:
+
+<pre><code>
+person.children.where(gender: :male)
+person.top_level?
+Person.treeified #=> returns a traversable tree of all people
+</code></pre>
+
+For more information on what you can do, see the {Hierarchy} module
+documentation.
+
+h2. Development
+
+If you wish to develop for Hierarchy, the first thing you will want to do is get
+specs up and running. This requires a call to @bundle install@ (obviously) and
+setting up your test database.
+
+As you can see in the @spec/spec_helper.rb@ file, the specs require that a
+PostgreSQL database named @hierarchy_test@ exist and be owned by a
+@hierarchy_tester@ user. Unfortunately I haven't written a way to configure this
+(though patches are welcome). So, the following commands should suffice to get
+you started:
+
+<pre><code>
+createuser hierarchy_tester # answer "no" to all prompts
+createdb -O hierarchy_tester hierarchy_test
+</code></pre>
+
+With those steps done you should be able to run @rake spec@ and see the Glorious
+Green.

data/Rakefile

@@ -0,0 +1,37 @@
+require 'rake'
+begin
+  require 'bundler'
+rescue LoadError
+  puts "Bundler is not installed; install with `gem install bundler`."
+  exit 1
+end
+
+Bundler.require :default
+
+Jeweler::Tasks.new do |gem|
+  gem.name = "hierarchy"
+  gem.summary = %Q{Use PostgreSQL LTREE type with ActiveRecord}
+  gem.description = %Q{Adds ActiveRecord support for hierarchial data structures using PostgreSQL's LTREE column type.}
+  gem.email = "git@timothymorgan.info"
+  gem.homepage = "http://github.com/riscfuture/hierarchy"
+  gem.authors = [ "Tim Morgan" ]
+  gem.required_ruby_version = '>= 1.9'
+  gem.add_dependency 'activerecord', '>= 3.0'
+  gem.add_dependency 'activesupport', '>= 3.0'
+end
+Jeweler::GemcutterTasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+YARD::Rake::YardocTask.new('doc') do |doc|
+  doc.options << "-m" << "textile"
+  doc.options << "--protected"
+  doc.options << "-r" << "README.textile"
+  doc.options << "-o" << "doc"
+  doc.options << "--title" << "Hierarchy Documentation".inspect
+  
+  doc.files = [ 'lib/**/*', 'README.textile' ]
+end
+
+task(default: :spec)

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/hierarchy.gemspec

@@ -0,0 +1,67 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{hierarchy}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Tim Morgan"]
+  s.date = %q{2010-10-30}
+  s.description = %q{Adds ActiveRecord support for hierarchial data structures using PostgreSQL's LTREE column type.}
+  s.email = %q{git@timothymorgan.info}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.textile"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     ".rspec",
+     "Gemfile",
+     "Gemfile.lock",
+     "LICENSE",
+     "README.textile",
+     "Rakefile",
+     "VERSION",
+     "hierarchy.gemspec",
+     "lib/hierarchy.rb",
+     "lib/hierarchy/index_path.rb",
+     "lib/hierarchy/node.rb",
+     "lib/hierarchy_generator.rb",
+     "spec/hierarchy_spec.rb",
+     "spec/index_path_spec.rb",
+     "spec/spec_helper.rb",
+     "templates/add_ltree_type.rb"
+  ]
+  s.homepage = %q{http://github.com/riscfuture/hierarchy}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.required_ruby_version = Gem::Requirement.new(">= 1.9")
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Use PostgreSQL LTREE type with ActiveRecord}
+  s.test_files = [
+    "spec/hierarchy_spec.rb",
+     "spec/index_path_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activerecord>, [">= 3.0"])
+      s.add_runtime_dependency(%q<activesupport>, [">= 3.0"])
+    else
+      s.add_dependency(%q<activerecord>, [">= 3.0"])
+      s.add_dependency(%q<activesupport>, [">= 3.0"])
+    end
+  else
+    s.add_dependency(%q<activerecord>, [">= 3.0"])
+    s.add_dependency(%q<activesupport>, [">= 3.0"])
+  end
+end
+

data/lib/hierarchy/index_path.rb

@@ -0,0 +1,59 @@
+module Hierarchy
+  
+  # An array of integers representing an ordered list of IDs. Duck-types an
+  # @Array@ in many ways.
+
+  class IndexPath
+    include Enumerable
+
+    delegate :&, :+, :-, :<<, :==, :[], :[]=, :at, :clear, :collect, :collect!,
+             :concat, :count, :delete_at, :delete_if, :drop, :drop_while, :each,
+             :each_index, :empty?, :eql?, :fetch, :index, :first, :include?,
+             :insert, :join, :keep_if, :last, :length, :map, :map!, :pop, :push,
+             :reject, :reject!, :reverse, :reverse!, :rindex, :select, :select!,
+             :shift, :size, :slice, :slice!, :take, :take_while, :to_a, :to_ary,
+             :unshift, :values_at, :|, to: :indexes
+
+    # @overload initialize(id, ...)
+    #   Creates an index path from a list of integer IDs.
+    #   @param [Fixnum] id An integer ID.
+    # @return [IndexPath] A new instance.
+    # @raise [ArgumentError] If an invalid ID is given.
+
+    def initialize(*indexes)
+      raise ArgumentError, "IndexPath indexes must be integers" unless indexes.all? { |index| index.kind_of?(Fixnum) }
+      @indexes = indexes
+    end
+
+    # Creates an index path from a PostgreSQL @LTREE@ column.
+    #
+    # @param [String] string An @LTREE@ column value, such as "1.10.22".
+    # @return [IndexPath] A corresponding index path.
+
+    def self.from_ltree(string)
+      new(*(string.split('.').map(&:to_i)))
+    end
+
+    # Defines a natural ordering of index paths. Paths with lower IDs at the same
+    # index level will come before those with higher IDs at that index level.
+    # Lower IDs at shallower index levels come before lower IDs at deeper index
+    # levels.
+    #
+    # @param [IndexPath] other An index path to compare.
+    # @return [-1, 0, 1] -1 if this index path comes before the other one, 0 if
+    #   they are identical, or 1 if this index path comes after the other one.
+    # @raise [ArgumentError] If something other than an index path is given.
+
+    def <=>(other)
+      raise ArgumentError, "Can't compare IndexPath and #{other.class.to_s}" unless other.kind_of?(IndexPath)
+      indexes <=> other.send(:indexes)
+    end
+
+    # @private
+    def inspect() "#<#{self.class.to_s} #{@indexes.inspect}>" end
+
+    private
+
+    def indexes() @indexes end
+  end
+end

data/lib/hierarchy/node.rb

@@ -0,0 +1,53 @@
+module Hierarchy
+  
+  # A node in a tree structure. A node can have zero or more {#children}, and
+  # has a reverse link back to its parent.
+
+  class Node
+    # @return [Array<Node>] This node's children.
+    attr_reader :children
+
+    # @return [Node, nil] This node's parent, or @nil@ if it is a root node.
+    attr_reader :parent
+
+    # @return The object this node contains.
+    attr_accessor :content
+
+    # Creates a new root node with no children.
+    #
+    # @param content The content the node will contain.
+
+    def initialize(content)
+      @children = []
+      @content = content
+    end
+
+    # Adds a node as a child of this one. Sets the {#parent} of the given node.
+    #
+    # @param [Node] child The node to add as a child of this node.
+
+    def <<(child)
+      children << child
+      child.instance_variable_set :@parent, self
+    end
+
+    # Performs a depth-first traversal using this as the root node of the tree.
+    # @yield [node] Each node in depth-first order.
+    # @yieldparam [Node] node A child node.
+
+    def traverse(&block)
+      children.each { |child| child.traverse &block }
+      block[self]
+    end
+
+    # @private
+    def inspect
+      str = "#<#{self.class.to_s} #{content.inspect}"
+      unless children.empty?
+        str << ": [ #{children.map(&:inspect).join(', ')} ]"
+      end
+      str << ">"
+      str
+    end
+  end
+end

data/lib/hierarchy.rb

@@ -0,0 +1,166 @@
+# @private
+module Arel
+  # @private
+  module Sql
+    # @private
+    module Attributes
+      # @private
+      def self.for_with_psql(column)
+        case column.sql_type
+          when 'ltree' then String
+          else for_without_psql(column)
+        end
+      end
+      unless singleton_class.method_defined?(:for_without_psql)
+        singleton_class.send :alias_method, :for_without_psql, :for
+        singleton_class.send :alias_method, :for, :for_with_psql
+      end
+    end
+  end
+end
+
+require 'hierarchy_generator'
+require 'hierarchy/index_path'
+require 'hierarchy/node'
+
+# Adds a tree structure to a model. This is very similar to @acts_as_nested_set@
+# but uses the PostgreSQL-specific @ltree@ feature for schema storage.
+#
+# Your model must have a @path@ field of type @ltree@. This field will be a
+# period-delimited list of IDs of records above this one in the hierarchy. In
+# addition, you should also consider the following indexes:
+#
+# <pre><code>
+# CREATE INDEX index1 ON table USING gist(path)
+# CREATE INDEX index2 ON table USING btree(path)
+# </code></pre>
+#
+# replacing @table@ with your table and @index1@/@index2@ with appropriate names
+# for these indexes.
+#
+# @example
+#   class MyModel < ActiveRecord::Base
+#     include Hierarchy
+#   end
+
+module Hierarchy
+  extend ActiveSupport::Concern
+  
+  # @private
+  included do |base|
+    base.extend ActiveSupport::Memoizable
+    base.memoize :index_path, :ancestors
+    
+    base.scope :parent_of, ->(obj) { obj.top_level? ? base.where('false') : base.where(id: obj.index_path.last) }
+    base.scope :children_of, ->(obj) { base.where(path: obj.my_path) }
+    base.scope :ancestors_of, ->(obj) { base.where(id: obj.index_path.to_a) }
+    base.scope :descendants_of, ->(obj) { base.where([ "path <@ ?", obj.my_path ]) }
+    base.scope :siblings_of, ->(obj) { base.where(path: obj.path) }
+    base.scope :priority_order, base.order("NLEVEL(path) ASC")
+    
+    base.before_save { |obj| obj.path ||= '' }
+  end
+
+  module ClassMethods
+
+    # @overload treeified
+    #   @return [Hash<ActiveRecord::Base, Hash<...>>] All models organized
+    #     into a tree structure. Returns a hash where each key is a tree root,
+    #     and the values are themselves hashes whose keys are the children of the
+    #     respective model.
+
+    def treeified(root=nil, objects=nil)
+      path = root ? root.content.my_path : ''
+      root ||= Node.new(nil)
+      objects ||= order('id ASC').all.sort_by { |o| [ o.index_path, o.id ] }
+
+      while objects.first and objects.first.path == path
+        child = objects.shift
+        root << Node.new(child)
+      end
+
+      root.children.each do |child|
+        treeified child, objects
+      end
+
+      return root
+    end
+  end
+
+  # Methods added to instances of the class this module is included into.
+
+  module InstanceMethods
+    # Sets the object above this one in the hierarchy.
+    #
+    # @param [ActiveRecord::Base] parent The parent object.
+    # @raise [ArgumentError] If @parent@ is an unsaved record with no primary key.
+
+    def parent=(parent)
+      raise ArgumentError, "Parent cannot be a new record" if parent.try(:new_record?)
+      self.path = parent.try(:my_path)
+    end
+
+    # Returns an array of ancestors above this object. Note that a) this array
+    # is ordered with the most senior ancestor at the beginning of the list, and
+    # b) this is an _array_, not a _relation_. For that reason, you can pass
+    # any additional scope options to the method.
+    #
+    # @param [Hash] options Additional finder options.
+    # @return [Array] The objects above this one in the hierarchy.
+
+    def ancestors(options={})
+      objects = self.class.ancestors_of(self).scoped(options).group_by(&:id)
+      index_path.map { |id| objects[id].first }
+    end
+
+    # @return [ActiveRecord::Relation] The objects below this one in the
+    #   hierarchy.
+
+    def descendants
+      self.class.descendants_of self
+    end
+
+    # @return [ActiveRecord::Base] The object directly above this one in the
+    #   hierarchy.
+
+    def parent
+      top_level? ? nil : self.class.parent_of(self).first
+    end
+
+    # @return [ActiveRecord::Relation] The objects directly below this one
+    #   in the hierarchy.
+
+    def children
+      self.class.children_of self
+    end
+
+    # @return [Array] The objects at the same hierarchical level of this one.
+
+    def siblings
+      self.class.siblings_of(self) - [ self ]
+    end
+
+    # @return [true, false] Whether or not this object has no parents.
+
+    def top_level?
+      path == ''
+    end
+
+    # @return [true, false] Whether or not this object has no children. Makes a
+    #   database call.
+
+    def bottom_level?
+      children.empty?
+    end
+
+    # @private
+    def my_path
+      path.blank? ? id.to_s : "#{path}.#{id}"
+    end
+
+    # @private
+    def index_path
+      IndexPath.from_ltree path
+    end
+  end
+end

data/lib/hierarchy_generator.rb

@@ -0,0 +1,22 @@
+require 'rails/generators'
+require 'rails/generators'
+require 'rails/generators/migration'
+
+# @private
+class HierarchyGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  
+  source_root "#{File.dirname __FILE__}/../templates"
+  
+  def self.next_migration_number(dirname)
+    if ActiveRecord::Base.timestamped_migrations then
+      Time.now.utc.strftime "%Y%m%d%H%M%S"
+    else
+      "%.3d" % (current_migration_number(dirname) + 1)
+    end
+  end
+  
+  def copy_files
+    migration_template "add_ltree_type.rb", "db/migrate/add_ltree_type.rb"
+  end
+end

data/spec/hierarchy_spec.rb

@@ -0,0 +1,110 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Hierarchy do
+  before :each do
+    @objects = Hash.new
+    2.times { |i| @objects[:"grandparent_#{i + 1}"] = Model.create! }
+    2.times do |gp_num|
+      2.times { |i| @objects[:"parent_#{gp_num + 1}_#{i + 1}"] = Model.create!(parent: @objects[:"grandparent_#{gp_num + 1}"]) }
+    end
+    2.times do |gp_num|
+      2.times do |p_num|
+        2.times { |i| @objects[:"child_#{gp_num + 1}_#{p_num + 1}_#{i + 1}"] = Model.create!(parent: @objects[:"parent_#{gp_num + 1}_#{p_num + 1}"]) }
+      end
+    end
+  end
+
+  describe ".parent_of" do
+    it "should return the parent object" do
+      Model.parent_of(@objects[:parent_1_1]).should == [ @objects[:grandparent_1] ]
+      Model.parent_of(@objects[:parent_2_2]).should == [ @objects[:grandparent_2] ]
+    end
+
+    it "should return an empty relation for top-level objects" do
+      Model.parent_of(@objects[:grandparent_1]).should be_empty
+      Model.parent_of(@objects[:grandparent_2]).should be_empty
+    end
+  end
+
+  describe ".children_of" do
+    it "should return the direct children of an object" do
+      Model.children_of(@objects[:grandparent_1]).should == [ :parent_1_1, :parent_1_2 ].map { |name| @objects[name] }
+      Model.children_of(@objects[:parent_2_1]).should == [ :child_2_1_1, :child_2_1_2 ].map { |name| @objects[name] }
+    end
+
+    it "should return an empty relation for leaf objects" do
+      Model.children_of(@objects[:child_1_1_1]).should be_empty
+      Model.children_of(@objects[:child_2_2_2]).should be_empty
+    end
+  end
+
+  describe ".ancestors_of" do
+    it "should return all ancestors of an object" do
+      Model.ancestors_of(@objects[:child_1_2_1]).should == [ :grandparent_1, :parent_1_2 ].map { |name| @objects[name] }
+      Model.ancestors_of(@objects[:parent_2_1]).should == [ @objects[:grandparent_2] ]
+    end
+
+    it "should return an empty relation for top-level objects" do
+      Model.ancestors_of(@objects[:grandparent_1]).should be_empty
+    end
+  end
+
+  describe ".descendants_of" do
+    it "should return all descendants of an object" do
+      Model.descendants_of(@objects[:grandparent_2]).should == [ :parent_2_1, :parent_2_2, :child_2_1_1, :child_2_1_2, :child_2_2_1, :child_2_2_2 ].map { |name| @objects[name] }
+      Model.descendants_of(@objects[:parent_2_1]).should == [ :child_2_1_1, :child_2_1_2 ].map { |name| @objects[name] }
+    end
+
+    it "should return an empty relation for leaf objects" do
+      Model.children_of(@objects[:child_1_1_1]).should be_empty
+      Model.children_of(@objects[:child_2_2_2]).should be_empty
+    end
+  end
+
+  describe ".siblings_of" do
+    it "should return all sibling objects" do
+      Model.siblings_of(@objects[:parent_1_1]).should == [ :parent_1_1, :parent_1_2 ].map { |name| @objects[name] }
+    end
+  end
+
+  describe "#parent=" do
+    it "should raise an error if parent is unsaved" do
+      expect { Model.create!.parent = Model.new }.to raise_error(ArgumentError)
+    end
+
+    it "should set the path ltree appropriately" do
+      ggp = Model.create!
+      gp = Model.create!(path: ggp.id.to_s)
+      pa = Model.create!(path: "#{ggp.id}.#{gp.id}")
+      path = [ ggp.id, gp.id, pa.id ].join('.')
+
+      object = Model.new
+      parent = Model.create!(path: path)
+      object.parent = parent
+      object.save!
+      object.path.should eql("#{path}.#{parent.id}")
+    end
+  end
+
+  describe "#top_level?" do
+    it "should return true for a top-level object" do
+      Model.create!.should be_top_level
+    end
+
+    it "should return false for an object with a parent" do
+      parent = Model.create!
+      Model.create!(parent: parent).should_not be_top_level
+    end
+  end
+
+  describe "#bottom_level?" do
+    it "should return true for an object with no children" do
+      Model.create!.should be_bottom_level
+    end
+    it "should return false for an object with children" do
+      parent = Model.create!
+      Model.create!(parent: parent)
+      parent.should_not be_bottom_level
+    end
+  end
+end

data/spec/index_path_spec.rb

@@ -0,0 +1,31 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Hierarchy::IndexPath do
+  describe ".<=>" do
+    def compare(ip1, ip2)
+      Hierarchy::IndexPath.new(*ip1) <=> Hierarchy::IndexPath.new(*ip2)
+    end
+
+    it "should return -1 if this index path comes before the given index path" do
+      # all except last digit equal
+      compare([ 1,2,3 ], [ 1,2,4 ]).should eql(-1)
+      # unequal in higher precedence
+      compare([ 1,2,3 ], [ 1,3,2 ]).should eql(-1)
+      # other is longer
+      compare([ 1,2,3 ], [ 1,2,3,4 ]).should eql(-1)
+    end
+
+    it "should return 1 if this index path comes after the given index path" do
+      # all except last digit equal
+      compare([ 1,2,4 ], [ 1,2,3 ]).should eql(1)
+      # unequal in higher precedence
+      compare([ 1,3,2 ], [ 1,2,3 ]).should eql(1)
+      # this is longer
+      compare([ 1,2,3,4 ], [ 1,2,3, ]).should eql(1)
+    end
+
+    it "should return 0 if the index paths are equal" do
+      compare([ 1,2,3 ], [ 1,2,3 ]).should eql(0)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,26 @@
+Bundler.require :default, :test
+require 'active_support'
+require 'active_record'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'hierarchy'
+
+ActiveRecord::Base.establish_connection(
+  adapter: 'postgresql',
+  database: 'hierarchy_test',
+  username: 'hierarchy_tester'
+)
+system "psql -f `pg_config --sharedir`/contrib/ltree.sql hierarchy_test &>/dev/null"
+
+class Model < ActiveRecord::Base
+  include Hierarchy
+end
+
+RSpec.configure do |config|
+  config.before(:each) do
+    Model.connection.execute "DROP TABLE IF EXISTS models"
+    Model.connection.execute "CREATE TABLE models (id SERIAL PRIMARY KEY, path LTREE NOT NULL DEFAULT '')"
+  end
+end

data/templates/add_ltree_type.rb

@@ -0,0 +1,15 @@
+class AddLtreeType < ActiveRecord::Migration
+  def self.up
+    cmd = "psql -f `pg_config --sharedir`/contrib/ltree.sql #{ActiveRecord::Base.connection.instance_variable_get(:@config)[:database]}"
+    puts cmd
+    result = system(cmd)
+    raise "Bad exit" unless result
+  end
+
+  def self.down
+    cmd = "psql -f `pg_config --sharedir`/contrib/uninstall_ltree.sql #{ActiveRecord::Base.connection.instance_variable_get(:@config)[:database]}"
+    puts cmd
+    result = system(cmd)
+    raise "Bad exit" unless result
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification 
+name: hierarchy
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Tim Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-30 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        version: "3.0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        version: "3.0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id002
+description: Adds ActiveRecord support for hierarchial data structures using PostgreSQL's LTREE column type.
+email: git@timothymorgan.info
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.textile
+files: 
+- .document
+- .gitignore
+- .rspec
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.textile
+- Rakefile
+- VERSION
+- hierarchy.gemspec
+- lib/hierarchy.rb
+- lib/hierarchy/index_path.rb
+- lib/hierarchy/node.rb
+- lib/hierarchy_generator.rb
+- spec/hierarchy_spec.rb
+- spec/index_path_spec.rb
+- spec/spec_helper.rb
+- templates/add_ltree_type.rb
+has_rdoc: true
+homepage: http://github.com/riscfuture/hierarchy
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 9
+      version: "1.9"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Use PostgreSQL LTREE type with ActiveRecord
+test_files: 
+- spec/hierarchy_spec.rb
+- spec/index_path_spec.rb
+- spec/spec_helper.rb