ltree_hierarchy 0.0.4

data/Gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+if ENV["EDGE_RAILS"]
+  gem 'pg'
+  gem 'rails', :git => 'git://github.com/rails/rails'
+else
+  gemspec
+end

data/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: .
+  specs:
+    ltree_hierarchy (0.0.4)
+      activerecord (= 3.2)
+      pg
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.2.0)
+      activesupport (= 3.2.0)
+      builder (~> 3.0.0)
+    activerecord (3.2.0)
+      activemodel (= 3.2.0)
+      activesupport (= 3.2.0)
+      arel (~> 3.0.0)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.0)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.4)
+    i18n (0.6.1)
+    multi_json (1.5.0)
+    pg (0.14.1)
+    rake (10.0.3)
+    tzinfo (0.3.35)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ltree_hierarchy!
+  rake

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Rob Worley
+
+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.md

@@ -0,0 +1,54 @@
+# ltree_hierarchy
+
+A simplistic gem that allows ActiveRecord models to be organized in a tree or hierarchy. It uses a materialized path implementation based around PostgreSQL's [ltree](http://www.postgresql.org/docs/current/static/ltree.html) data type, associated functions and operators.
+
+[![Build Status](https://api.travis-ci.org/robworley/ltree_hierarchy.png)](https://travis-ci.org/robworley/ltree_hierarchy)
+
+## Why might you want to use it?
+
+- You want to be able to construct optimized hierarchical queries with ease, both from Ruby AND raw SQL.
+- You want to be able to compose complex arel expressions from pre-defined building blocks.
+- You prefer PostgreSQL over other relational DBs.
+
+## Getting started
+
+Follow these steps to apply to any ActiveRecord model:
+
+1. Install
+ - Add to Gemfile: **gem 'ltree_hierarchy', :git => 'git://github.com/robworley/ltree_hierarchy.git'**
+ - Install required gems: **bundle install**
+2. Add parent_id (integer) and path (ltree) columns to your table.
+3. Add ltree hierarchy to your model
+   - Add to app/models/[model].rb: has_ltree_hierarchy
+
+## Organizing records into a tree
+
+Set the parent association or parent_id:
+
+Node.create! :name => 'New York', :parent => Node.create!(:name => 'USA')
+
+## Navigating the tree
+
+The usual basic tree stuff. Use the following methods on any model instance:
+
+- parent
+- ancestors
+- self_and_ancestors
+- siblings
+- self_and_siblings
+- children
+- self_and_children
+- descendents
+- self_and_descendents
+- leaves
+
+Useful class methods:
+
+- roots
+- leaves
+- at_depth(n)
+- lowest_common_ancestors(scope)
+
+## TODO
+
+- Better error message for circular references. Don't neglect i18n.

data/Rakefile

@@ -0,0 +1,12 @@
+require 'rake'
+require 'rake/testtask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the ltree_hierarchy plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end

data/lib/ltree_hierarchy.rb

@@ -0,0 +1,4 @@
+require "ltree_hierarchy/hierarchy"
+require "ltree_hierarchy/version"
+
+ActiveRecord::Base.extend(Ltree::Hierarchy)

data/lib/ltree_hierarchy/hierarchy.rb

@@ -0,0 +1,190 @@
+module Ltree
+  module Hierarchy
+    def has_ltree_hierarchy(options = {})
+      options = {
+        :fragment => :id,
+        :parent_fragment => :parent_id,
+        :path => :path
+      }.merge(options)
+
+      options.assert_valid_keys(:fragment, :parent_fragment, :path)
+
+      cattr_accessor :ltree_fragment_column, :ltree_parent_fragment_column, :ltree_path_column
+
+      self.ltree_fragment_column        = options[:fragment]
+      self.ltree_parent_fragment_column = options[:parent_fragment]
+      self.ltree_path_column            = options[:path]
+
+      belongs_to :parent, :class_name => self.name, :foreign_key => self.ltree_parent_fragment_column
+
+      validate :prevent_circular_paths, :if => :ltree_parent_fragment_changed?
+
+      after_create  :commit_path
+      before_update :assign_path, :cascade_path_change, :if => :ltree_parent_fragment_changed?
+
+      include InstanceMethods
+    end
+
+    def roots
+      where(self.ltree_parent_fragment_column => nil)
+    end
+
+    def at_depth(depth)
+      where(["nlevel(#{ltree_path_column}) = ?", depth])
+    end
+
+    def leaves
+      subquery = select("DISTINCT #{ltree_parent_fragment_column}")
+      where("#{ltree_fragment_column} NOT IN(#{subquery.to_sql})")
+    end
+
+    def lowest_common_ancestor_paths(paths)
+      sql = if paths.respond_to?(:to_sql)
+        "SELECT lca(array(#{paths.to_sql}))"
+      else
+        return [] if paths.empty?
+        safe_paths = paths.map { |p| "#{connection.quote(p)}::ltree" }
+        "SELECT lca(ARRAY[#{safe_paths.join(', ')}])"
+      end
+      connection.select_values(sql)
+    end
+
+    def lowest_common_ancestors(paths)
+      where(ltree_path_column => lowest_common_ancestor_paths(paths))
+    end
+
+    module InstanceMethods
+      def ltree_scope
+        self.class.base_class
+      end
+
+      def ltree_fragment_column
+        self.class.ltree_fragment_column
+      end
+
+      def ltree_fragment
+        send(self.ltree_fragment_column)
+      end
+
+      def ltree_parent_fragment_column
+        self.class.ltree_parent_fragment_column
+      end
+
+      def ltree_parent_fragment
+        send(ltree_parent_fragment_column)
+      end
+
+      def ltree_parent_fragment_changed?
+        changed_attributes.key?(ltree_parent_fragment_column.to_s)
+      end
+
+      def ltree_path_column
+        self.class.ltree_path_column
+      end
+
+      def ltree_path
+        send(ltree_path_column)
+      end
+
+      def ltree_path_was
+        send("#{ltree_path_column}_was")
+      end
+
+      def prevent_circular_paths
+        if parent && parent.ltree_path.split('.').include?(ltree_fragment.to_s)
+          errors.add(ltree_parent_fragment_column, :invalid)
+        end
+      end
+
+      def compute_path
+        if parent
+          "#{parent.ltree_path}.#{ltree_fragment}"
+        else
+          ltree_fragment.to_s
+        end
+      end
+
+      def assign_path
+        self.send("#{ltree_path_column}=", compute_path)
+      end
+
+      def commit_path
+        update_column(ltree_path_column, compute_path)
+      end
+
+      def cascade_path_change
+        # Typically equivalent to:
+        #  UPDATE whatever
+        #  SET    path = NEW.path || subpath(path, nlevel(OLD.path))
+        #  WHERE  path <@ OLD.path AND id != NEW.id;
+        ltree_scope.where(
+          ["#{ltree_path_column} <@ :old_path AND #{ltree_fragment_column} != :id", :old_path => ltree_path_was, :id => ltree_fragment]
+        ).update_all(
+          ["#{ltree_path_column} = :new_path || subpath(#{ltree_path_column}, nlevel(:old_path))", :new_path => ltree_path, :old_path => ltree_path_was]
+        )
+      end
+
+      def root?
+        if self.ltree_parent_fragment
+          false
+        else
+          parent.nil?
+        end
+      end
+
+      def leaf?
+        !children.any?
+      end
+
+      def depth # 1-based, for compatibility with ltree's nlevel().
+        if root?
+          1
+        elsif ltree_path
+          ltree_path.split('.').length
+        elsif parent
+          parent.depth + 1
+        end
+      end
+
+      def ancestors
+        ltree_scope.where("#{ltree_path_column} @> ? AND #{ltree_fragment_column} != ?", ltree_path, ltree_fragment)
+      end
+
+      def self_and_ancestors
+        ltree_scope.where("#{ltree_path_column} @> ?", ltree_path)
+      end
+      alias :and_ancestors :self_and_ancestors
+
+      def siblings
+        ltree_scope.where("#{ltree_parent_fragment_column} = ? AND #{ltree_fragment_column} != ?", ltree_parent_fragment, ltree_fragment)
+      end
+
+      def self_and_siblings
+        ltree_scope.where(ltree_parent_fragment_column => ltree_parent_fragment)
+      end
+      alias :and_siblings :self_and_siblings
+
+      def descendents
+        ltree_scope.where("#{ltree_path_column} <@ ? AND #{ltree_fragment_column} != ?", ltree_path, ltree_fragment)
+      end
+
+      def self_and_descendents
+        ltree_scope.where("#{ltree_path_column} <@ ?", ltree_path)
+      end
+      alias :and_descendents :self_and_descendents
+
+      def children
+        ltree_scope.where(ltree_parent_fragment_column => ltree_fragment)
+      end
+
+      def self_and_children
+        ltree_scope.where("#{ltree_fragment_column} = :id OR #{ltree_parent_fragment_column} = :id", :id => ltree_fragment)
+      end
+      alias :and_children :self_and_children
+
+      def leaves
+        descendents.leaves
+      end
+    end
+  end
+end

data/lib/ltree_hierarchy/version.rb

@@ -0,0 +1,5 @@
+module Ltree
+  module Hierarchy
+    VERSION = "0.0.4"
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: ltree_hierarchy
+version: !ruby/object:Gem::Version
+  version: 0.0.4
+  prerelease: 
+platform: ruby
+authors:
+- Rob Worley
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Organizes ActiveRecord models into a tree/hierarchy using a materialized
+  path implementation based around PostgreSQL's ltree datatype. ltree's operators
+  ensure that queries are fast and easily understood.
+email:
+- robert.worley@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/ltree_hierarchy/hierarchy.rb
+- lib/ltree_hierarchy/version.rb
+- lib/ltree_hierarchy.rb
+- Gemfile
+- Gemfile.lock
+- MIT-LICENSE
+- Rakefile
+- README.md
+homepage: https://github.com/robworley/ltree_hierarchy
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: ltree_hierarchy
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Organize ActiveRecord models into a tree using PostgreSQL's ltree datatype
+test_files: []