hierarchy 1.0.6 → 1.0.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3216ee2327673134cabc227dba69a8c0c65aea3a76de131147882a1b469e06b5
+  data.tar.gz: be02935315adf7c8aa28c5509524cd770fe12c0f46c35a3cf8284e8f8dc4bbb8
+SHA512:
+  metadata.gz: 529e2c8961cde1ecf43f4eb709238e4fed99d2be60b62db09421e39261bc1023684494f9130fdd0af533dee5fd1b7261538836b7ad1fe5c4e27cc937f4170eaa
+  data.tar.gz: b266febc4eff1430db81651581052d326126b4717da80b293424a825c40adcbc49fbe5809f2ae85f7dd0d1506ea55514ed9e893899c82121ab7d65503057dfb6

data/README.md

@@ -0,0 +1,106 @@
+> ⚠️ **DEPRECATED:** `hierarchy` is no longer maintained. Consider `ancestry`,
+> `closure_tree`, or `acts_as_tree` for tree-structured ActiveRecord data. The
+> final release is v1.0.7.
+
+Hierarchy
+=========
+
+**Use PostgreSQL `LTREE` columns in ActiveRecord**
+
+|             |                                 |
+|:------------|:--------------------------------|
+| **Author**  | Tim Morgan                      |
+| **Version** | 1.0.6 (Nov 27, 2010)            |
+| **License** | Released under the MIT license. |
+
+About
+-----
+
+The `LTREE` column type is a PostgreSQL-specific type (available from the ltree
+extension) for representing hierarchies. It is more efficient than the typical
+way of accomplishing hierarchical 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 module you can include in your models,
+providing an abundance of methods to help you navigate and manipulate the
+hierarchy.
+
+Installation
+------------
+
+**Important Note:** This gem requires Ruby 1.9+ and Rails 3.0+.
+
+Firstly, add the gem to your Rails project's `Gemfile`:
+
+```` ruby
+gem 'hierarchy'
+````
+
+Then, run the generator to install the migration:
+
+```` sh
+rails generate hierarchy
+````
+
+Note that *this migration must precede any tables using `LTREEs`*, so reorder
+the migration if you have to.
+
+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:
+
+```` sql
+path LTREE NOT NULL DEFAULT ''
+````
+
+Once you've got that column in your model, feel free to include the `Hierarchy`
+module:
+
+```` ruby
+class Person < ActiveRecord::Base
+  include Hierarchy
+end
+````
+
+You can now define hierarchy by setting a model's `parent`, like so:
+
+```` ruby
+person.parent = mother #=> Sets the `path` column appropriately
+````
+
+You also have access to a wealth of ways to traverse the hierarchy:
+
+```` ruby
+person.children.where(gender: :male)
+person.top_level?
+Person.treeified #=> returns a traversible tree of all people
+````
+
+For more information on what you can do, see the {Hierarchy} module
+documentation.
+
+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:
+
+```` sh
+createuser hierarchy_tester # answer "no" to all prompts
+createdb -O hierarchy_tester hierarchy_test
+````
+
+With those steps done you should be able to run `rake spec` and see the Glorious
+Green.

data/hierarchy.gemspec

@@ -2,23 +2,24 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
+# stub: hierarchy 1.0.7 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "hierarchy"
-  s.version = "1.0.6"
+  s.version = "1.0.7"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tim Morgan"]
-  s.date = "2011-12-02"
+  s.date = "2013-12-08"
   s.description = "Adds ActiveRecord support for hierarchical data structures using PostgreSQL's LTREE column type."
   s.email = "git@timothymorgan.info"
   s.extra_rdoc_files = [
     "LICENSE",
-    "README.textile"
+    "README.md"
   ]
   s.files = [
     "LICENSE",
-    "README.textile",
+    "README.md",
     "hierarchy.gemspec",
     "lib/hierarchy.rb",
     "lib/hierarchy/index_path.rb",
@@ -29,11 +30,20 @@ Gem::Specification.new do |s|
   s.homepage = "http://github.com/riscfuture/hierarchy"
   s.require_paths = ["lib"]
   s.required_ruby_version = Gem::Requirement.new(">= 1.9")
-  s.rubygems_version = "1.8.11"
-  s.summary = "Use PostgreSQL LTREE type with ActiveRecord"
+  s.rubygems_version = "2.1.11"
+  s.summary = "[DEPRECATED] Use PostgreSQL LTREE type with ActiveRecord"
+  s.post_install_message = <<~MSG
+
+    ⚠️  DEPRECATED: hierarchy is no longer maintained.
+
+    No longer maintained. Consider `ancestry`, `closure_tree`, or `acts_as_tree` for tree-structured ActiveRecord data.
+
+    This is the final release. No further updates are planned.
+
+  MSG
 
   if s.respond_to? :specification_version then
-    s.specification_version = 3
+    s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<rails>, [">= 3.0.2"])

data/lib/hierarchy/index_path.rb

@@ -1,7 +1,7 @@
 module Hierarchy
-  
+
   # An array of integers representing an ordered list of IDs. Duck-types an
-  # @Array@ in many ways.
+  # `Array` in many ways.
 
   class IndexPath
     include Enumerable
@@ -25,9 +25,9 @@ module Hierarchy
       @indexes = indexes
     end
 
-    # Creates an index path from a PostgreSQL @LTREE@ column.
+    # Creates an index path from a PostgreSQL `LTREE` column.
     #
-    # @param [String] string An @LTREE@ column value, such as "1.10.22".
+    # @param [String] string An `LTREE` column value, such as "1.10.22".
     # @return [IndexPath] A corresponding index path.
 
     def self.from_ltree(string)

data/lib/hierarchy/node.rb

@@ -1,5 +1,5 @@
 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.
 
@@ -7,7 +7,7 @@ module Hierarchy
     # @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.
+    # @return [Node, nil] This node's parent, or `nil` if it is a root node.
     attr_reader :parent
 
     # @return The object this node contains.

data/lib/hierarchy.rb

@@ -2,19 +2,19 @@ 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.
+# 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
+# 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>
+# ```` sql
 # 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
+# replacing `table` with your table and `index1`/`index2` with appropriate names
 # for these indexes.
 #
 # @example
@@ -24,19 +24,16 @@ require 'hierarchy/node'
 
 module Hierarchy
   extend ActiveSupport::Concern
-  
+
   # @private
   included do
-    extend ActiveSupport::Memoizable
-    memoize :index_path, :ancestors
-    
     scope :parent_of, ->(obj) { obj.top_level? ? where('false') : where(id: obj.index_path.last) }
     scope :children_of, ->(obj) { where(path: obj.my_path) }
     scope :ancestors_of, ->(obj) { obj.top_level? ? where('false') : where(id: obj.index_path.to_a) }
     scope :descendants_of, ->(obj) { where("path <@ ?", obj.my_path) }
     scope :siblings_of, ->(obj) { where(path: obj.path) }
-    scope :priority_order, order("NLEVEL(path) ASC")
-    scope :top_level, where("path IS NULL or path = ?", '')
+    scope :priority_order, -> { order("NLEVEL(path) ASC") }
+    scope :top_level, -> { where("path IS NULL or path = ?", '') }
 
     before_save { |obj| obj.path ||= '' }
     before_save :update_children_with_new_parent
@@ -68,91 +65,94 @@ module Hierarchy
     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.
+  # 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
+  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.
+  # 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={})
+  def ancestors(options={})
+    @ancestors ||= begin
       return [] if top_level?
       objects = self.class.ancestors_of(self).scoped(options).group_by(&:id)
       index_path.map { |id| objects[id].first }
     end
+  end
 
-    # @return [ActiveRecord::Relation] The objects below this one in the
-    #   hierarchy.
+  # @return [ActiveRecord::Relation] The objects below this one in the
+  #   hierarchy.
 
-    def descendants
-      self.class.descendants_of self
-    end
+  def descendants
+    self.class.descendants_of self
+  end
 
-    # @return [ActiveRecord::Base] The object directly above this one in the
-    #   hierarchy.
+  # @return [ActiveRecord::Base] The object directly above this one in the
+  #   hierarchy.
 
-    def parent
-      top_level? ? nil : self.class.parent_of(self).first
-    end
+  def parent
+    top_level? ? nil : self.class.parent_of(self).first
+  end
 
-    # @return [ActiveRecord::Relation] The objects directly below this one
-    #   in the hierarchy.
+  # @return [ActiveRecord::Relation] The objects directly below this one
+  #   in the hierarchy.
 
-    def children
-      self.class.children_of self
-    end
+  def children
+    self.class.children_of self
+  end
 
-    # @return [Array] The objects at the same hierarchical level of this one.
+  # @return [Array] The objects at the same hierarchical level of this one.
 
-    def siblings
-      self.class.siblings_of(self) - [ self ]
-    end
+  def siblings
+    self.class.siblings_of(self) - [ self ]
+  end
 
-    # @return [true, false] Whether or not this object has no parents.
+  # @return [true, false] Whether or not this object has no parents.
 
-    def top_level?
-      path.blank?
-    end
+  def top_level?
+    path.blank?
+  end
 
-    # @return [true, false] Whether or not this object has no children. Makes a
-    #   database call.
+  # @return root parent or nil(if current obj is top level)
+  def root
+    self.top_level? ? nil : self.class.find(self.path.split('.').first)
+  end
 
-    def bottom_level?
-      children.empty?
-    end
+  # @return [true, false] Whether or not this object has no children. Makes a
+  #   database call.
 
-    # @private
-    def my_path
-      path.blank? ? id.to_s : "#{path}.#{id}"
-    end
+  def bottom_level?
+    children.empty?
+  end
 
-    # @private
-    def index_path
-      IndexPath.from_ltree path.to_s
-    end
+  # @private
+  def my_path
+    path.blank? ? id.to_s : "#{path}.#{id}"
+  end
+
+  # @private
+  def index_path
+    @index_path ||= IndexPath.from_ltree path.to_s
+  end
 
-    private
+  private
 
-    # if our parent has changed, update our children's paths
-    def update_children_with_new_parent
-      if path_changed? and not new_record? then
-        old_path = (path_was.blank? ? id.to_s : "#{path_was}.#{id}")
-        self.class.where("path <@ ?", old_path).update_all([ "path = TEXT2LTREE(REPLACE(LTREE2TEXT(path), ?, ?))", old_path, my_path ])
-      end
+  # if our parent has changed, update our children's paths
+  def update_children_with_new_parent
+    if path_changed? and not new_record? then
+      old_path = (path_was.blank? ? id.to_s : "#{path_was}.#{id}")
+      self.class.where("path <@ ?", old_path).update_all([ "path = TEXT2LTREE(REPLACE(LTREE2TEXT(path), ?, ?))", old_path, my_path ])
     end
   end
 end

data/lib/hierarchy_generator.rb

@@ -5,18 +5,18 @@ 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"
+      Time.now.utc.strftime '%Y%m%d%H%M%S'
     else
-      "%.3d" % (current_migration_number(dirname) + 1)
+      '%.3d' % (current_migration_number(dirname) + 1)
     end
   end
-  
+
   def copy_files
-    migration_template "add_ltree_type.rb", "db/migrate/add_ltree_type.rb"
+    migration_template 'add_ltree_type.rb', 'db/migrate/add_ltree_type.rb'
   end
 end

metadata

@@ -1,82 +1,98 @@
 --- !ruby/object:Gem::Specification
 name: hierarchy
 version: !ruby/object:Gem::Version
-  version: 1.0.6
-  prerelease: 
+  version: 1.0.7
 platform: ruby
 authors:
 - Tim Morgan
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-02 00:00:00.000000000 Z
+date: 2013-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70260260128220 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 3.0.2
   type: :runtime
   prerelease: false
-  version_requirements: *70260260128220
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.2
 - !ruby/object:Gem::Dependency
   name: pg
-  requirement: &70260260127240 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70260260127240
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70260260126200 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70260260126200
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70260260125260 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70260260125260
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: RedCloth
-  requirement: &70260260124220 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70260260124220
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70260260123540 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70260260123540
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Adds ActiveRecord support for hierarchical data structures using PostgreSQL's
   LTREE column type.
 email: git@timothymorgan.info
@@ -84,10 +100,10 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - LICENSE
-- README.textile
+- README.md
 files:
 - LICENSE
-- README.textile
+- README.md
 - hierarchy.gemspec
 - lib/hierarchy.rb
 - lib/hierarchy/index_path.rb
@@ -96,26 +112,31 @@ files:
 - templates/add_ltree_type.rb
 homepage: http://github.com/riscfuture/hierarchy
 licenses: []
-post_install_message: 
+metadata: {}
+post_install_message: |2+
+
+  ⚠️  DEPRECATED: hierarchy is no longer maintained.
+
+  No longer maintained. Consider `ancestry`, `closure_tree`, or `acts_as_tree` for tree-structured ActiveRecord data.
+
+  This is the final release. No further updates are planned.
+
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '1.9'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.11
-signing_key: 
-specification_version: 3
-summary: Use PostgreSQL LTREE type with ActiveRecord
+rubygems_version: 4.0.11
+specification_version: 4
+summary: "[DEPRECATED] Use PostgreSQL LTREE type with ActiveRecord"
 test_files: []
+...

data/README.textile

@@ -1,93 +0,0 @@
-h1. Hierarchy -- Use PostgreSQL @LTREE@ columns in ActiveRecord
-
-| *Author* | Tim Morgan |
-| *Version* | 1.0.6 (Nov 27, 2010) |
-| *License* | Released under the MIT license. |
-
-h2. About
-
-The @LTREE@ column type is a PostgreSQL-specific type (available from the ltree
-extension) for representing hierarchies. It is more efficient than the typical
-way of accomplishing hierarchical 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 module you can include in your models,
-providing an abundance of methods to help you navigate and manipulate the
-hierarchy.
-
-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 traversible 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.