ancestry 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9455bbdda28f2f0084ff4b1e96af32ca5d6b3efe40ae062c51f75b3fee84fb30
-  data.tar.gz: 5b06653e17bbe2a238c4d49d9147dd79f2156c33432298290b5b17da190ce203
+  metadata.gz: d11437b15407107e0d4690084bc462a50d97d4fe9615445ff295a96d74943c67
+  data.tar.gz: e2bdffb78316b524828c0a6d38c0c0e4101ef71c57bda836272d41e0381b44c3
 SHA512:
-  metadata.gz: 4cb481c338a78cd5c294a40ccc43ccbad27232cc0a646b4827fd2446ad3d3fd626410f4a35d3b9361b367c2474ba229113aa191ba7799ddcc7930b1d29eab106
-  data.tar.gz: 6876e974e00c0ee4c5bb4ea4facbfb9ce12fe04eebfab2bc4623d6a74c9591781d3945b4999437054a81fb1ea82a656822c679e38c434541173ee7d192d664dc
+  metadata.gz: 533b6b0cc2db821091081f09c7680cbe163abbcc85500d278c52625861bdd901a7623232cde8ccbf21f3e0960a5231adb889055555e4849d75ede13651f626ad
+  data.tar.gz: 6f754739730731009eee294e9a6fed1d268d3f0cbf4024cec96221a0a68b5f59569ac47bb42f13e3e7798f76982d35ff35b03a01fe44f4d217b7e3e37c9c62d4

data/README.md

@@ -3,10 +3,10 @@
 # Ancestry
 
 Ancestry is a gem that allows the records of a Ruby on Rails
-ActiveRecord model to be organised as a tree structure (or hierarchy). It uses
-a single database column, employing the materialised path pattern. It exposes all the standard tree structure
-relations (ancestors, parent, root, children, siblings, descendants) and allows all
-of them to be fetched in a single SQL query. Additional features are STI
+ActiveRecord model to be organised as a tree structure (or hierarchy). It employs
+the materialised path pattern and exposes all the standard tree structure
+relations (ancestors, parent, root, children, siblings, descendants), allowing all
+of them to be fetched in a single SQL query. Additional features include STI
 support, scopes, depth caching, depth constraints, easy migration from older
 gems, integrity checking, integrity restoration, arrangement of
 (sub)trees into hashes, and various strategies for dealing with orphaned
@@ -14,14 +14,13 @@ records.
 
 NOTE:
 
-- Ancestry 2.x supports Rails 4.1, and earlier
-- Ancestry 3.x supports Rails 5.0, and 4.2
+- Ancestry 2.x supports Rails 4.1 and earlier
+- Ancestry 3.x supports Rails 5.0 and 4.2
 - Ancestry 4.0 only supports rails 5.0 and higher
 
 # Installation
 
-To apply Ancestry to any `ActiveRecord` model, follow these simple steps:
-
+Follow these simple steps to apply Ancestry to any ActiveRecord model:
 
 ## Install
 
@@ -82,115 +81,38 @@ parent_id can be set using parent= and parent_id= on a record or by including
 them in the hash passed to new, create, create!, update_attributes and
 update_attributes!. For example:
 
-```ruby
-TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')
-```
+`TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')`.
 
-You can also create children through the children relation on a node:
+Children can be created through the children relation on a node: `node.children.create :name => 'Stinky'`.
 
-```ruby
-node.children.create :name => 'Stinky'
-```
+# Tree Navigation
+
+The node with the large border is the reference node (the node from which the navigation method is invoked.)
+The yellow nodes are those returned by the method.
+
+|                               |                                                     |                                 |
+|:-:                            |:-:                                                  |:-:                              |
+|**parent**                     |**root**<sup><a href="#fn1" id="ref1">1</a></sup>    |**ancestors**                    |
+|![parent](/img/parent.png)     |![root](/img/root.png)                               |![ancestors](/img/ancestors.png) |
+| nil for a root node           |self for a root node                                 |root..parent                     |
+| `parent_id`                   |`root_id`                                            |`ancestor_ids`                   |
+| `has_parent?`                 |`is_root?`                                           |`ancestors?`                     |
+|`parent_of?`                   |`root_of?`                                           |`ancestor_of?`                   |
+|**children**                   |**descendants**                                      |**indirects**                    |
+|![children](/img/children.png) |![descendants](/img/descendants.png)                 |![indirects](/img/indirects.png) |
+| `child_ids`                   |`descendant_ids`                                     |`indirect_ids`                   |
+| `has_children?`               |                                                     |                                 |
+| `child_of?`                   |`descendant_of?`                                     |`indirect_of?`                   |
+|**siblings**                   |**subtree**                                          |**path**                         |
+|![siblings](/img/siblings.png) |![subtree](/img/subtree.png)                         |![path](/img/path.png)           |
+| includes self                 |self..indirects                                      |root..self                       |
+|`sibling_ids`                  |`subtree_ids`                                        |`path_ids`                       |
+|`has_siblings?`                |                                                     |                                 |
+|`sibling_of?(node)`            |                                                     |                                 |
 
-# Navigating your tree
-
-To navigate an Ancestry model, use the following instance methods:
-
-|  method           |return value|
-|-------------------|------------|
-|`parent`           |parent of the record, nil for a root node|
-|`parent_id`        |parent id of the record, nil for a root node|
-|`root`             |root of the record's tree, self for a root node|
-|`root_id`          |root id of the record's tree, self for a root node|
-|`root?` <br/> `is_root?` |  true if the record is a root node, false otherwise|
-|`ancestors`        |ancestors of the record, starting with the root and ending with the parent|
-|`ancestors?`       |true if the record has ancestors (aka not a root node)|
-|`ancestor_ids`     |ancestor ids of the record|
-|`path`             |path of the record, starting with the root and ending with self|
-|`path_ids`         |a list of the path ids, starting with the root id and ending with the node's own id|
-|`children`         |direct children of the record|
-|`child_ids`        |direct children's ids|
-|`has_parent?`    <br/> `ancestors?` |true if the record has a parent, false otherwise|
-|`has_children?`  <br/> `children?`  |true if the record has any children, false otherwise|
-|`is_childless?`  <br/> `childless?` |true is the record has no children, false otherwise|
-|`siblings`         |siblings of the record, including the record itself*|
-|`sibling_ids`      |sibling ids|
-|`has_siblings?`  <br/> `siblings?`   |true if the record's parent has more than one child|
-|`is_only_child?` <br/> `only_child?` |true if the record is the only child of its parent|
-|`descendants`      |direct and indirect children of the record|
-|`descendant_ids`   |direct and indirect children's ids of the record|
-|`indirects`        |indirect children of the record|
-|`indirect_ids`     |indirect children's ids of the record|
-|`subtree`          |the model on descendants and itself|
-|`subtree_ids`      |a list of all ids in the record's subtree|
-|`depth`            |the depth of the node (root nodes are at depth 0)|
-
-\*   If the record is a root, other root records are considered siblings
-\*   Siblings returns the record itself
-
-There are also instance methods to determine the relationship between 2 nodes:
-
-|method             |return value|
-|-------------------|---------------|
-|`parent_of?(node)`  | node's parent is this record|
-|`root_of?(node)`    | node's root is this record|
-|`ancestor_of?(node)`| node's ancestors include this record|
-|`child_of?(node)`   | node is record's parent|
-|`descendant_of?(node)` | node is one of this record's ancestors|
-|`indirect_of?(node)` | node is one of this record's ancestors but not a parent|
-
-## Visual guide for navigation
-
-In all examples the node with the large border is the reference node, the node
-from which the navigation method is invoked. The yellow nodes are the nodes
-returned by the method.
-
-<table>
-  <tr>
-    <td>
-      <p align="center">parent</p>
-      <img src="img/parent.png" alt="parent"/>
-    </td>
-    <td>
-      <p align="center">root</p>
-      <img src="img/root.png" alt="root"/>
-    </td>
-    <td>
-      <p align="center">ancestors</p>
-      <img src="img/ancestors.png" alt="ancestors"/>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <p align="center">path</p>
-      <img src="img/path.png" alt="path"/>
-    </td>
-    <td>
-      <p align="center">children</p>
-      <img src="img/children.png" alt="children"/>
-    </td>
-    <td>
-      <p align="center">siblings</p>
-      <img src="img/siblings.png" alt="siblings"/>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <p align="center">descendants</p>
-      <img src="img/descendants.png" alt="descendants"/>
-    </td>
-    <td>
-      <p align="center">indirects</p>
-      <img src="img/indirects.png" alt="indirects"/>
-    </td>
-    <td>
-      <p align="center">subtree</p>
-      <img src="img/subtree.png" alt="subtree"/>
-    </td>
-  </tr>
-</table>
-
-# Options for `has_ancestry`
+<sup id="fn1">1. [other root records are considered siblings]<a href="#ref1" title="Jump back to footnote 1.">↩</a></sup>
+
+# `has_ancestry` options
 
 The has_ancestry method supports the following options:
 
@@ -213,10 +135,8 @@ The has_ancestry method supports the following options:
 
 # (Named) Scopes
 
-Where possible, the navigation methods return scopes instead of records. This
-means additional ordering, conditions, limits, etc. can be applied and that
-the result can be either retrieved, counted, or checked for existence. For
-example:
+The navigation methods return scopes instead of records, where possible. Additional ordering,
+conditions, limits, etc. can be applied and the results can be retrieved, counted, or checked for existence:
 
 ```ruby
 node.children.where(:name => 'Mary').exists?
@@ -224,7 +144,7 @@ node.subtree.order(:name).limit(10).each { ... }
 node.descendants.count
 ```
 
-For convenience, a couple of named scopes are included at the class level:
+A couple of class-level named scopes are included:
 
     roots                   Root nodes
     ancestors_of(node)      Ancestors of node, node can be either a record or an id
@@ -234,8 +154,7 @@ For convenience, a couple of named scopes are included at the class level:
     subtree_of(node)        Subtree of node, node can be either a record or an id
     siblings_of(node)       Siblings of node, node can be either a record or an id
 
-Thanks to some convenient rails magic, it is even possible to create nodes
-through the children and siblings scopes:
+It is possible thanks to some convenient rails magic to create nodes through the children and siblings scopes:
 
     node.children.create
     node.siblings.create!
@@ -244,8 +163,8 @@ through the children and siblings scopes:
 
 # Selecting nodes by depth
 
-When depth caching is enabled (see has_ancestry options), five more named
-scopes can be used to select nodes on their depth:
+With depth caching enabled (see has_ancestry options), an additional five named
+scopes can be used to select nodes by depth:
 
     before_depth(depth)     Return nodes that are less deep than depth (node.depth < depth)
     to_depth(depth)         Return nodes up to a certain depth (node.depth <= depth)
@@ -253,42 +172,27 @@ scopes can be used to select nodes on their depth:
     from_depth(depth)       Return nodes starting from a certain depth (node.depth >= depth)
     after_depth(depth)      Return nodes that are deeper than depth (node.depth > depth)
 
-The depth scopes are also available through calls to descendants,
-descendant_ids, subtree, subtree_ids, path and ancestors. In this case, depth
-values are interpreted relatively. Some examples:
-
-    node.subtree(:to_depth => 2)      Subtree of node, to a depth of node.depth + 2 (self, children and grandchildren)
-    node.subtree.to_depth(5)          Subtree of node to an absolute depth of 5
-    node.descendants(:at_depth => 2)  Descendant of node, at depth node.depth + 2 (grandchildren)
-    node.descendants.at_depth(10)     Descendants of node at an absolute depth of 10
-    node.ancestors.to_depth(3)        The oldest 4 ancestors of node (its root and 3 more)
-    node.path(:from_depth => -2)      The node's grandparent, parent and the node itself
+Depth scopes are also available through calls to `descendants`,
+`descendant_ids`, `subtree`, `subtree_ids`, `path` and `ancestors` (with relative depth).
+Note that depth constraints cannot be passed to `ancestor_ids` or `path_ids` as both relations
+can be fetched directly from the ancestry column without needing a query. Use
+`ancestors(depth_options).map(&:id)` or `ancestor_ids.slice(min_depth..max_depth)` instead.
 
     node.ancestors(:from_depth => -6, :to_depth => -4)
     node.path.from_depth(3).to_depth(4)
     node.descendants(:from_depth => 2, :to_depth => 4)
     node.subtree.from_depth(10).to_depth(12)
 
-Please note that depth constraints cannot be passed to ancestor_ids and
-path_ids. The reason for this is that both these relations can be fetched
-directly from the ancestry column without performing a database query. It
-would require an entirely different method of applying the depth constraints
-which isn't worth the effort of implementing. You can use
-ancestors(depth_options).map(&:id) or ancestor_ids.slice(min_depth..max_depth)
-instead.
-
 # STI support
 
-Ancestry works fine with STI. Just create a STI inheritance hierarchy and
-build an Ancestry tree from the different classes/models. All Ancestry
-relations that were described above will return nodes of any model type. If
-you do only want nodes of a specific subclass you'll have to add a condition
-on type for that.
+To use with STI: create a STI inheritance hierarchy and build a tree from the different
+classes/models. All Ancestry relations that were described above will return nodes of any model type. If
+you do only want nodes of a specific subclass, a type condition is required.
 
 # Arrangement
 
-Ancestry can arrange an entire subtree into nested hashes for easy navigation
-after retrieval from the database.  `TreeNode.arrange` could for example return:
+A subtree can be arranged into nested hashes for easy navigation after database retrieval.
+`TreeNode.arrange` could, for instance, return:
 
 ```ruby
 {
@@ -301,43 +205,20 @@ after retrieval from the database.  `TreeNode.arrange` could for example return:
 }
 ```
 
-The `arrange` method also works on a scoped class, for example:
-
-```ruby
-TreeNode.find_by_name('Crunchy').subtree.arrange
-```
-
-The `arrange` method takes `ActiveRecord` find options. If you want your hashes to
-be ordered, you should pass the order to the `arrange` method instead of to the
-scope. example:
+The `arrange` method can work on a scoped class (`TreeNode.find_by(:name => 'Crunchy').subtree.arrange`),
+and can take ActiveRecord find options. If you want ordered hashes, pass the order to the method instead of
+the scope as follows:
 
-```ruby
-TreeNode.find_by_name('Crunchy').subtree.arrange(:order => :name)
-```
+`TreeNode.find_by(:name => 'Crunchy').subtree.arrange(:order => :name)`.
 
-To get the arranged nodes as a nested array of hashes for serialization:
+The `arrange_serializable` method returns the arranged nodes as a nested array of hashes. Order
+can be passed in the same fashion as to the `arrange` method:
+`TreeNode.arrange_serializable(:order => :name)` The result can easily be serialized to json with `to_json`
+or other formats. You can also supply your own serialization logic with blocks.
 
-`TreeNode.arrange_serializable`
+Using `ActiveModel` serializers:
 
-```ruby
-[
-  {
-    "ancestry" => nil, "id" => 1, "children" => [
-      { "ancestry" => "1", "id" => 2, "children" => [] }
-    ]
-  }
-]
-```
-
-You can also supply your own serialization logic using blocks:
-
-For example, using `ActiveModel` Serializers:
-
-```ruby
-TreeNode.arrange_serializable do |parent, children|
-  MySerializer.new(parent, children: children)
-end
-```
+`TreeNode.arrange_serializable { |parent, children| MySerializer.new(parent, children: children) }`.
 
 Or plain hashes:
 
@@ -350,39 +231,22 @@ TreeNode.arrange_serializable do |parent, children|
 end
 ```
 
-The result of `arrange_serializable` can easily be serialized to json with
-`to_json`, or some other format:
-
-```
-TreeNode.arrange_serializable.to_json
-```
-
-You can also pass the order to the `arrange_serializable` method just as you can
-pass it to the `arrange` method:
-
-```
-TreeNode.arrange_serializable(:order => :name)
-```
-
 # Sorting
 
-If you just want to sort an array of nodes as if you were traversing them in
-preorder, you can use the sort_by_ancestry class method:
-
-```
-TreeNode.sort_by_ancestry(array_of_nodes)
-```
-
-Note that since materialised path trees don't support ordering within a rank,
-the order of siblings depends on their order in the original array.
+The `sort_by_ancestry` class method: `TreeNode.sort_by_ancestry(array_of_nodes)` can be used
+to sort an array of nodes as if traversing in preorder. (Note that since materialised path
+trees do not support ordering within a rank, the order of siblings is
+dependant upon their original array order.)
 
 # Migrating from plugin that uses parent_id column
 
 Most current tree plugins use a parent_id column (has_ancestry,
-awesome_nested_set, better_nested_set, acts_as_nested_set). With ancestry it is
+awesome_nested_set, better_nested_set, acts_as_nested_set). With Ancestry it is
 easy to migrate from any of these plugins. To do so, use the
-`build_ancestry_from_parent_ids!` method on your ancestry model. These steps
-provide a more detailed explanation:
+`build_ancestry_from_parent_ids!` method on your ancestry model.
+
+<details>
+<summary>Details</summary>
 
 1.  Add ancestry column to your table
     *   Create migration: **rails g migration [add_ancestry_to_](table)
@@ -392,7 +256,7 @@ provide a more detailed explanation:
     *   Migrate your database: **rake db:migrate**
 
 
-2.  Remove old tree gem and add in Ancestry to `Gemfile`
+2.  Remove old tree gem and add in Ancestry to Gemfile
     *   See 'Installation' for more info on installing and configuring gems
 
 
@@ -403,7 +267,7 @@ provide a more detailed explanation:
 
 
 4.  Generate ancestry columns
-    *   In 'rails console': **[model].build_ancestry_from_parent_ids!**
+    *   In rails console: **[model].build_ancestry_from_parent_ids!**
     *   Make sure it worked ok: **[model].check_ancestry_integrity!**
 
 
@@ -417,42 +281,7 @@ provide a more detailed explanation:
     *   Create migration: `rails g migration [remove_parent_id_from_](table)`
     *   Add to migration: `remove_column [table], :parent_id`
     *   Migrate your database: `rake db:migrate`
-
-# Integrity checking and restoration
-
-I don't see any way Ancestry tree integrity could get compromised without
-explicitly setting cyclic parents or invalid ancestry and circumventing
-validation with update_attribute. If you do, please let me know.
-
-Ancestry includes some methods for detecting integrity problems and restoring
-integrity just to be sure. To check integrity, use:
-`[Model].check_ancestry_integrity!`. An AncestryIntegrityException will be
-raised if there are any problems. You can also specify :report => :list to
-return an array of exceptions or :report => :echo to echo any error messages.
-To restore integrity use: `[Model].restore_ancestry_integrity!`.
-
-For example, from IRB:
-
-```
->> stinky = TreeNode.create :name => 'Stinky'
-$  #<TreeNode id: 1, name: "Stinky", ancestry: nil>
->> squeeky = TreeNode.create :name => 'Squeeky', :parent => stinky
-$  #<TreeNode id: 2, name: "Squeeky", ancestry: "1">
->> stinky.update_attribute :parent, squeeky
-$  true
->> TreeNode.all
-$  [#<TreeNode id: 1, name: "Stinky", ancestry: "1/2">, #<TreeNode id: 2, name: "Squeeky", ancestry: "1/2/1">]
->> TreeNode.check_ancestry_integrity!
-!! Ancestry::AncestryIntegrityException: Conflicting parent id in node 1: 2 for node 1, expecting nil
->> TreeNode.restore_ancestry_integrity!
-$  [#<TreeNode id: 1, name: "Stinky", ancestry: 2>, #<TreeNode id: 2, name: "Squeeky", ancestry: nil>]
-```
-
-Additionally, if you think something is wrong with your depth cache:
-
-```
->> TreeNode.rebuild_depth_cache!
-```
+</details>
 
 # Running Tests
 

data/ancestry.gemspec

@@ -7,12 +7,12 @@ Gem::Specification.new do |s|
   s.summary     = 'Organize ActiveRecord model into a tree structure'
   s.description = <<-EOF
   Ancestry allows the records of a ActiveRecord model to be organized in a tree
-  structure, using a single, intuitively formatted database column. It exposes
-  all the standard tree structure relations (ancestors, parent, root, children,
-  siblings, descendants) and all of them can be fetched in a single sql query.
-  Additional features are named_scopes, integrity checking, integrity restoration,
-  arrangement of (sub)tree into hashes and different strategies for dealing with
-  orphaned records.
+  structure, using the materialized path pattern. It exposes the standard
+  relations (ancestors, parent, root, children, siblings, descendants)
+  and allows them to be fetched in a single query. Additional features include
+  named scopes, integrity checking, integrity restoration, arrangement
+  of (sub)tree into hashes and different strategies for dealing with orphaned
+  records.
 EOF
   s.metadata = {
     "homepage_uri" => "https://github.com/stefankroes/ancestry",

data/lib/ancestry.rb

@@ -4,6 +4,34 @@ require_relative 'ancestry/instance_methods'
 require_relative 'ancestry/exceptions'
 require_relative 'ancestry/has_ancestry'
 require_relative 'ancestry/materialized_path'
+require_relative 'ancestry/materialized_path_pg'
+
+I18n.load_path += Dir[File.join(File.expand_path(File.dirname(__FILE__)),
+                                 'ancestry', 'locales', '*.{rb,yml}').to_s]
 
 module Ancestry
+  @@default_update_strategy = :ruby
+
+  # @!default_update_strategy
+  #   @return [Symbol] the default strategy for updating ancestry
+  #
+  # The value changes the default way that ancestry is updated for associated records
+  #
+  #    :ruby (default and legacy value)
+  #
+  #        Child records will be loaded into memory and updated. callbacks will get called
+  #        The callbacks of interest are those that cache values based upon the ancestry value
+  #
+  #    :sql (currently only valid in postgres)
+  #
+  #        Child records are updated in sql and callbacks will not get called.
+  #        Associated records in memory will have the wrong ancestry value
+
+  def self.default_update_strategy
+    @@default_update_strategy
+  end
+
+  def self.default_update_strategy=(value)
+    @@default_update_strategy = value
+  end
 end

data/lib/ancestry/class_methods.rb

@@ -16,7 +16,7 @@ module Ancestry
         if [:before_depth, :to_depth, :at_depth, :from_depth, :after_depth].include? scope_name
           scope.send scope_name, depth + relative_depth
         else
-          raise Ancestry::AncestryException.new("Unknown depth option: #{scope_name}.")
+          raise Ancestry::AncestryException.new(I18n.t("ancestry.unknown_depth_option", {:scope_name => scope_name}))
         end
       end
     end
@@ -27,11 +27,17 @@ module Ancestry
       if [:rootify, :adopt, :restrict, :destroy].include? orphan_strategy
         class_variable_set :@@orphan_strategy, orphan_strategy
       else
-        raise Ancestry::AncestryException.new("Invalid orphan strategy, valid ones are :rootify,:adopt, :restrict and :destroy.")
+        raise Ancestry::AncestryException.new(I18n.t("ancestry.invalid_orphan_strategy"))
       end
     end
 
-    # Get all nodes and sorting them into an empty hash
+
+    # these methods arrange an entire subtree into nested hashes for easy navigation after database retrieval
+    # the arrange method also works on a scoped class
+    # the arrange method takes ActiveRecord find options
+    # To order your hashes pass the order to the arrange method instead of to the scope
+
+    # Get all nodes and sort them into an empty hash
     def arrange options = {}
       if (order = options.delete(:order))
         arrange_nodes self.ancestry_base_class.order(order).where(options)
@@ -54,7 +60,9 @@ module Ancestry
       end
     end
 
-     # Arrangement to nested array
+     # Arrangement to nested array for serialization
+     # You can also supply your own serialization logic using blocks
+     # also allows you to pass the order just as you can pass it to the arrange method
     def arrange_serializable options={}, nodes=nil, &block
       nodes = arrange(options) if nodes.nil?
       nodes.map do |parent, children|
@@ -67,7 +75,6 @@ module Ancestry
     end
 
     # Pseudo-preordered array of nodes.  Children will always follow parents,
-    # for ordering nodes within a rank provide block, eg. Node.sort_by_ancestry(Node.all) {|a, b| a.rank <=> b.rank}.
     def sort_by_ancestry(nodes, &block)
       arranged = nodes if nodes.is_a?(Hash)
 
@@ -94,6 +101,9 @@ module Ancestry
     end
 
     # Integrity checking
+    # compromised tree integrity is unlikely without explicitly setting cyclic parents or invalid ancestry and circumventing validation
+    # just in case, raise an AncestryIntegrityException if issues are detected
+    # specify :report => :list to return an array of exceptions or :report => :echo to echo any error messages
     def check_ancestry_integrity! options = {}
       parents = {}
       exceptions = [] if options[:report] == :list
@@ -103,20 +113,30 @@ module Ancestry
         scope.find_each do |node|
           begin
             # ... check validity of ancestry column
-            if !node.valid? and !node.errors[node.class.ancestry_column].blank?
-              raise Ancestry::AncestryIntegrityException.new("Invalid format for ancestry column of node #{node.id}: #{node.read_attribute node.ancestry_column}.")
+            if !node.sane_ancestor_ids?
+              raise Ancestry::AncestryIntegrityException.new(I18n.t("ancestry.invalid_ancestry_column",
+                                                                    :node_id => node.id,
+                                                                    :ancestry_column => "#{node.read_attribute node.ancestry_column}"
+                                                                    ))
             end
             # ... check that all ancestors exist
             node.ancestor_ids.each do |ancestor_id|
               unless exists? ancestor_id
-                raise Ancestry::AncestryIntegrityException.new("Reference to non-existent node in node #{node.id}: #{ancestor_id}.")
+                raise Ancestry::AncestryIntegrityException.new(I18n.t("ancestry.reference_nonexistent_node",
+                                                                      :node_id => node.id,
+                                                                      :ancestor_id => ancestor_id
+                                                                      ))
               end
             end
             # ... check that all node parents are consistent with values observed earlier
             node.path_ids.zip([nil] + node.path_ids).each do |node_id, parent_id|
               parents[node_id] = parent_id unless parents.has_key? node_id
               unless parents[node_id] == parent_id
-                raise Ancestry::AncestryIntegrityException.new("Conflicting parent id found in node #{node.id}: #{parent_id || 'nil'} for node #{node_id} while expecting #{parents[node_id] || 'nil'}")
+                raise Ancestry::AncestryIntegrityException.new(I18n.t("ancestry.conflicting_parent_id",
+                                                                      :node_id => node_id,
+                                                                      :parent_id => parent_id || 'nil',
+                                                                      :expected => parents[node_id] || 'nil'
+                                                                      ))
               end
             end
           rescue Ancestry::AncestryIntegrityException => integrity_exception
@@ -140,7 +160,7 @@ module Ancestry
           # For each node ...
           scope.find_each do |node|
             # ... set its ancestry to nil if invalid
-            if !node.valid? and !node.errors[node.class.ancestry_column].blank?
+            if !node.sane_ancestor_ids?
               node.without_ancestry_callbacks do
                 node.update_attribute :ancestor_ids, []
               end
@@ -171,7 +191,7 @@ module Ancestry
       end
     end
 
-    # Build ancestry from parent id's for migration purposes
+    # Build ancestry from parent ids for migration purposes
     def build_ancestry_from_parent_ids! column=:parent_id, parent_id = nil, ancestor_ids = []
       unscoped_where do |scope|
         scope.where(column => parent_id).find_each do |node|
@@ -185,7 +205,7 @@ module Ancestry
 
     # Rebuild depth cache if it got corrupted or if depth caching was just turned on
     def rebuild_depth_cache!
-      raise Ancestry::AncestryException.new("Cannot rebuild depth cache for model without depth caching.") unless respond_to? :depth_cache_column
+      raise Ancestry::AncestryException.new(I18n.t("ancestry.cannot_rebuild_depth_cache")) unless respond_to? :depth_cache_column
 
       self.ancestry_base_class.transaction do
         unscoped_where do |scope|

data/lib/ancestry/has_ancestry.rb

@@ -2,10 +2,10 @@ module Ancestry
   module HasAncestry
     def has_ancestry options = {}
       # Check options
-      raise Ancestry::AncestryException.new("Options for has_ancestry must be in a hash.") unless options.is_a? Hash
+      raise Ancestry::AncestryException.new(I18n.t("ancestry.option_must_be_hash")) unless options.is_a? Hash
       options.each do |key, value|
-        unless [:ancestry_column, :orphan_strategy, :cache_depth, :depth_cache_column, :touch, :counter_cache, :primary_key_format].include? key
-          raise Ancestry::AncestryException.new("Unknown option for has_ancestry: #{key.inspect} => #{value.inspect}.")
+        unless [:ancestry_column, :orphan_strategy, :cache_depth, :depth_cache_column, :touch, :counter_cache, :primary_key_format, :update_strategy].include? key
+          raise Ancestry::AncestryException.new(I18n.t("ancestry.unknown_option", {:key => key.inspect, :value => value.inspect}))
         end
       end
 
@@ -30,6 +30,9 @@ module Ancestry
       validates_format_of self.ancestry_column, :with => derive_ancestry_pattern(options[:primary_key_format]), :allow_nil => true
       extend Ancestry::MaterializedPath
 
+      update_strategy = options[:update_strategy] || Ancestry.default_update_strategy
+      include Ancestry::MaterializedPathPg if update_strategy == :sql
+
       # Create orphan strategy accessor and set to option or default (writer comes from DynamicClassMethods)
       cattr_reader :orphan_strategy
       self.orphan_strategy = options[:orphan_strategy] || :destroy
@@ -75,7 +78,9 @@ module Ancestry
       # Create named scopes for depth
       {:before_depth => '<', :to_depth => '<=', :at_depth => '=', :from_depth => '>=', :after_depth => '>'}.each do |scope_name, operator|
         scope scope_name, lambda { |depth|
-          raise Ancestry::AncestryException.new("Named scope '#{scope_name}' is only available when depth caching is enabled.") unless options[:cache_depth]
+          raise Ancestry::AncestryException.new(I18n.t("ancestry.named_scope_depth_cache",
+                                                       :scope_name => scope_name
+                                                       )) unless options[:cache_depth]
           where("#{depth_cache_column} #{operator} ?", depth)
         }
       end

data/lib/ancestry/instance_methods.rb

@@ -2,7 +2,7 @@ module Ancestry
   module InstanceMethods
     # Validate that the ancestors don't include itself
     def ancestry_exclude_self
-      errors.add(:base, "#{self.class.model_name.human} cannot be a descendant of itself.") if ancestor_ids.include? self.id
+      errors.add(:base, I18n.t("ancestry.exclude_self", {:class_name => self.class.name.humanize})) if ancestor_ids.include? self.id
     end
 
     # Update descendants with new ancestry (before save)
@@ -43,7 +43,7 @@ module Ancestry
             end
           end
         when :restrict # throw an exception if it has children
-          raise Ancestry::AncestryException.new('Cannot delete record because it has descendants.') unless is_childless?
+          raise Ancestry::AncestryException.new(I18n.t("ancestry.cannot_delete_descendants")) unless is_childless?
         end
       end
     end
@@ -116,6 +116,10 @@ module Ancestry
       end
     end
 
+    def sane_ancestor_ids?
+      valid? || errors[self.ancestry_base_class.ancestry_column].blank?
+    end
+
     def ancestors depth_options = {}
       return self.ancestry_base_class.none unless ancestors?
       self.ancestry_base_class.scope_depth(depth_options, depth).ordered_by_ancestry.ancestors_of(self)

data/lib/ancestry/materialized_path.rb

@@ -71,14 +71,14 @@ module Ancestry
     def siblings_of(object)
       t = arel_table
       node = to_node(object)
-      where(t[ancestry_column].eq(node[ancestry_column]))
+      where(t[ancestry_column].eq(node[ancestry_column].presence))
     end
 
     def ordered_by_ancestry(order = nil)
       if %w(mysql mysql2 sqlite sqlite3).include?(connection.adapter_name.downcase)
         reorder(arel_table[ancestry_column], order)
       elsif %w(postgresql).include?(connection.adapter_name.downcase) && ActiveRecord::VERSION::STRING >= "6.1"
-        reorder(Arel::Nodes.new(arel_table[ancestry_column]).nulls_first)
+        reorder(Arel::Nodes::Ascending.new(arel_table[ancestry_column]).nulls_first)
       else
         reorder(
           Arel::Nodes::Ascending.new(Arel::Nodes::NamedFunction.new('COALESCE', [arel_table[ancestry_column], Arel.sql("''")])),
@@ -139,7 +139,7 @@ module Ancestry
       # This is technically child_ancestry_was
       def child_ancestry
         # New records cannot have children
-        raise Ancestry::AncestryException.new('No child ancestry for new record. Save record before performing tree operations.') if new_record?
+        raise Ancestry::AncestryException.new(I18n.t("ancestry.no_child_for_new_record")) if new_record?
         path_was = self.send("#{self.ancestry_base_class.ancestry_column}#{IN_DATABASE_SUFFIX}")
         path_was.blank? ? id.to_s : "#{path_was}/#{id}"
       end

data/lib/ancestry/version.rb

@@ -1,3 +1,3 @@
 module Ancestry
-  VERSION = "3.1.0"
+  VERSION = "3.2.0"
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: ancestry
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Stefan Kroes
 - Keenan Brock
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-03 00:00:00.000000000 Z
+date: 2020-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -83,12 +83,12 @@ dependencies:
         version: '0'
 description: |2
     Ancestry allows the records of a ActiveRecord model to be organized in a tree
-    structure, using a single, intuitively formatted database column. It exposes
-    all the standard tree structure relations (ancestors, parent, root, children,
-    siblings, descendants) and all of them can be fetched in a single sql query.
-    Additional features are named_scopes, integrity checking, integrity restoration,
-    arrangement of (sub)tree into hashes and different strategies for dealing with
-    orphaned records.
+    structure, using the materialized path pattern. It exposes the standard
+    relations (ancestors, parent, root, children, siblings, descendants)
+    and allows them to be fetched in a single query. Additional features include
+    named scopes, integrity checking, integrity restoration, arrangement
+    of (sub)tree into hashes and different strategies for dealing with orphaned
+    records.
 email: keenan@thebrocks.net
 executables: []
 extensions: []
@@ -114,7 +114,7 @@ metadata:
   changelog_uri: https://github.com/stefankroes/ancestry/blob/master/CHANGELOG.md
   source_code_uri: https://github.com/stefankroes/ancestry/
   bug_tracker_uri: https://github.com/stefankroes/ancestry/issues
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -129,9 +129,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
+rubyforge_project:
 rubygems_version: 2.7.6.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Organize ActiveRecord model into a tree structure
 test_files: []