fertile_forest 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 20188f6dbc2388fcfdbe3fe5b0759955a200bc36
-  data.tar.gz: c2f95eb0e924a6c8a05ea1c33ab7d69cc63eb9cc
+  metadata.gz: e7fb8b7fe6a221ca6fa537152448626b03bfa453
+  data.tar.gz: 55da6e1a5fcb682e8e0a1cc2239df52e32bfb53f
 SHA512:
-  metadata.gz: ea5732a9f44c1208526c7f6767c7b606905e97b40602f7b874c4a2cecbeb437afcc8aa244adaab5be8a79fbed1d8479ce357a0462a2bbac757ea10516edd4384
-  data.tar.gz: 1a54b09adf164e7d40693a795789ddf2e35cfa7216a269ac3fbc1815029d2719107b8d59286f05156c4b87abc569366a1c0832a06b9b4a2fe31f6dc576dab839
+  metadata.gz: 3600025777793045fc0faaa17c1b3a150dc91bb11432589fd199b64b12f62ae4295960a6e2d5b5aa088880e6528dfb5cf7853800138ab9dc109637bf477653bf
+  data.tar.gz: 9eaf893afade620cbdae109ce6144b36fac204dcae85d2a18fb87b555784543c6a5b7bbb14f4e4a7a4b19deff3c8ca562174b5fb977cf7c849056569b614d623

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Stew Eucen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.rdoc

@@ -0,0 +1,3 @@
+= FertileForest
+
+This project rocks and uses MIT-LICENSE.

data/config/routes.rb

@@ -0,0 +1,2 @@
+FertileForest::Engine.routes.draw do
+end

data/lib/fertile_forest/engine.rb

@@ -0,0 +1,13 @@
+module FertileForest
+  #
+  # Template of Engine for Demo of Fertile Forest in future.
+  # @private
+  #
+  class Engine < ::Rails::Engine
+    isolate_namespace FertileForest
+
+    #### setting demo start
+
+    #### setting demo end
+  end
+end

data/lib/fertile_forest/modules/calculators.rb

@@ -0,0 +1,231 @@
+#
+# Calcurators methods
+# Fertile Forest for Ruby: The new model for storing hierarchical data in a database.
+#
+# @author StewEucen
+# @copyright Copyright (c) 2015 Stew Eucen (http://lab.kochlein.com)
+# @license   http://www.opensource.org/licenses/mit-license.php  MIT License
+#
+# @link       http://lab.kochlein.com/FertileForest
+# @since      File available since Release 1.0.0
+# @version    1.0.0
+#
+module StewEucen
+  # Name space of Stew Eucen's Acts
+  module Acts
+    # Name space of Fertile Forest
+    module FertileForest
+      # Name space of class methods for Fertile Forest
+      module Table
+        # This module is for extending into derived class by ActiveRecord.<br>
+        # The caption contains "Instance Methods",
+        # but it means "Class Methods" of each derived class.
+        # @private
+        module Calculators
+
+          def fill_required_columns_to_append!(node)
+            # calculate depth and queue for appending.
+            # If no interval, try to scoot over queue.
+            if node.ff_base_id.to_i <= 0
+              fill_info = ff_calc_required_columns_for_appending_as_root(node)
+            else
+              fill_info = ff_calc_required_columns_for_appending_as_internal(node)
+            end
+
+            # When fail to calc, can not save.
+            # no need to set error message here.
+            return false if fill_info.blank?
+
+            # not need to set ff_grove, because posted node has it already.
+            node.ff_queue = fill_info[:ff_queue]
+            node.ff_depth = fill_info[:ff_depth]
+
+            true
+          end
+
+          def ff_parse_kinship(node)
+            ff_kinship_key = node.ff_kinship
+            if /true|false/i.match(ff_kinship_key)
+              ff_kinship_key === 'true'
+            else
+              ff_kinship_key.to_i
+            end
+          end
+
+          #
+          # Calculate depth and queue as root node to append.
+          # @return [Hash] Calculated queue and depth.
+          # @return [false] Can not calculate.
+          #
+          def ff_calc_required_columns_for_appending_as_root(node)
+            # can be null=zero
+            posted_grove = node.ff_grove.to_i
+
+            # When append as root, need to post ff_grove.
+            if has_grove? && posted_grove <= 0
+              # TODO: set error message 'append_empty_column'
+              return false
+            end
+
+            # depth is fixed value
+            fill_info = {ff_depth: ROOT_DEPTH}
+
+            ####################################################################
+            #
+            # calculate queue
+            #
+
+            # get max queue in grove
+            last_queue = ff_get_last_queue(posted_grove)  # can be nil
+
+            if last_queue.nil?
+              append_queue = 0
+            elsif QUEUE_MAX_VALUE <= last_queue
+              # Try to scoot over pre-nodes.
+              evenize_res = ff_evenize(posted_grove, nil, nil, 1) # 1: append node count
+
+              # When fail to evenize, filled all id.
+              if evenize_res.blank?
+                # TODO: set error append.canNotScootsOver'
+                return false
+              end
+
+              append_queue = evenize_res[SPROUT_VACANT_QUEUE_KEY]
+            elsif QUEUE_MAX_VALUE - last_queue < QUEUE_DEFAULT_INTERVAL
+              append_queue = QUEUE_MAX_VALUE
+            else
+              append_queue = last_queue + QUEUE_DEFAULT_INTERVAL
+            end
+
+            # return value
+            fill_info.merge({ff_queue: append_queue})
+          end
+
+          #
+          # Calculate depth and queue as internal node to append.
+          #  (1) has space before base-node, calc median queue.
+          #  (2) When no space befre base node, try to evenize.
+          #  (3) can not evenize, can not append.
+          # @return [Hash] Calculated queue and depth.
+          # @return [false] Can not calculate.
+          #
+          def ff_calc_required_columns_for_appending_as_internal(node)
+            base_id = node.ff_base_id.to_i
+            grove_id = node.ff_grove.to_i
+
+            # get base node by ff_base_id
+            # use ff_grove for find, because grove means USER_ID
+            base_node = ff_required_columns_scope()
+              .ff_usual_conditions_scope(grove_id)
+              .where(id: base_id)
+              .first
+
+            # When has ff_base_id and the node is nothing, fail to append.
+            if base_node.blank?
+              # TODO: set errors append.baseNodeIsNull
+              return false
+            end
+
+            kinship = ff_parse_kinship(node)
+            is_sibling = ff_is_bool(kinship)
+
+            # depth is fixed value
+            fill_info = {ff_depth: base_node.ff_depth.to_i + (is_sibling ? 0 : 1)}
+
+            # pick up node for wedged node to scoot over. (can be null)
+            wedged_node = ff_get_wedged_node(base_node, kinship)
+
+            # When wedged node is nothing, it means last queue.
+            # In the case, calc appending queue is "lastQueue + INTERVAL"
+
+            if wedged_node.blank?
+              last_queue = ff_get_last_queue(grove_id, 0)
+              if last_queue < QUEUE_MAX_VALUE
+                if QUEUE_DEFAULT_INTERVAL <= QUEUE_MAX_VALUE - last_queue
+                  calc_queue = last_queue + QUEUE_DEFAULT_INTERVAL
+                else
+                  calc_queue = QUEUE_MAX_VALUE
+                end
+
+                return fill_info.merge({ff_queue: calc_queue})
+              end
+            else
+              #
+              # When got wedged node, calc median queue.
+              #  (1) get previous node of the wedge node.
+              #  (2) calc median queue.
+              #
+              append_queue = ff_calc_median_queue(wedged_node)
+
+              return fill_info.merge({ff_queue: append_queue}) \
+                  if append_queue.present?
+            end
+
+            # When no space before wedged node, try to scoot over.
+            append_queue = ff_evenize_for_appending(base_node, wedged_node)
+
+            return fill_info.merge({ff_queue: append_queue}) \
+                if append_queue.present?
+
+            # TODO: set error message append.canNotScootsOver
+            false
+          end
+
+          def ff_calc_median_queue(wedged_node)
+            tail_node = ff_get_previous_node(wedged_node)
+
+            # tail_node never be null, because parent-node exists.
+            return nil if tail_node.blank?
+
+            tail_queue = tail_node.ff_queue
+            wedged_queue = wedged_node.ff_queue
+
+            return nil if wedged_queue - tail_queue <= 1
+
+            # not need to use (int)
+            (tail_queue + wedged_queue) / 2
+          end
+
+          def ff_evenize_for_appending(base_node, wedged_node)
+            append_node_count = 1
+
+            grove_id     = base_node.ff_grove
+            base_queue   = base_node.blank?   ? nil : base_node .ff_queue
+            wedged_queue = wedged_node.blank? ? nil : wedged_node.ff_queue
+
+            # try to evenize all pre-nodes from this base node.
+            evenize_res = ff_evenize(grove_id, base_queue, wedged_queue, append_node_count)
+            return evenize_res[SPROUT_VACANT_QUEUE_KEY] if evenize_res.present?
+
+            # try to evenize all pre-nodes from this root node.
+            # {
+            #     $rootNode = $this->root($baseNode);
+            #     $evenizeRes = $this->_evenize($grove, $rootNode, $wedgedQueue, $appendNodeCount);
+            #     if (!empty($evenizeRes)) {
+            #         return $evenizeRes[self::SPROUT_VACANT_QUEUE_KEY];
+            #     }
+            # }
+
+            # try to evenize all pre-nodes.
+            evenize_res = ff_evenize(grove_id, nil, wedged_queue, append_node_count)
+            return evenize_res[SPROUT_VACANT_QUEUE_KEY] if evenize_res.present?
+
+            # try to evenize all post-nodes.
+            evenize_res = ff_evenize(grove_id, wedged_queue, nil, append_node_count, true)
+            return evenize_res[SPROUT_VACANT_QUEUE_KEY] if evenize_res.present?
+
+            # can not evenize.
+            false
+          end
+
+          protected :ff_parse_kinship,
+                    :ff_calc_required_columns_for_appending_as_root,
+                    :ff_calc_required_columns_for_appending_as_internal,
+                    :ff_calc_median_queue,
+                    :ff_evenize_for_appending
+
+        end
+      end
+    end
+  end
+end

data/lib/fertile_forest/modules/configs.rb

@@ -0,0 +1,96 @@
+#
+# Configs methods
+# Fertile Forest for Ruby: The new model for storing hierarchical data in a database.
+#
+# @author StewEucen
+# @copyright Copyright (c) 2015 Stew Eucen (http://lab.kochlein.com)
+# @license   http://www.opensource.org/licenses/mit-license.php  MIT License
+#
+# @link       http://lab.kochlein.com/FertileForest
+# @since      File available since Release 1.0.0
+# @version    1.0.0
+#
+module StewEucen
+  # Name space of Stew Eucen's Acts
+  module Acts
+    # Name space of Fertile Forest
+    module FertileForest
+      # Name space of class methods for Fertile Forest
+      module Table
+        # This module is for extending into derived class by ActiveRecord.<br>
+        # The caption contains "Instance Methods",
+        # but it means "Class Methods" of each derived class.
+        module Configs
+
+          #
+          # Exists grove field in table?
+          #
+          # @author StewEucen
+          # @return [Boolean] true: has grove column.
+          # @return [Boolean] false: no grove column.
+          # @since  Release 1.0.0
+          #
+          def has_grove?
+            ff_has_column? :ff_grove
+          end
+
+          #
+          # Exists soft-delete field in table?
+          #
+          # @author StewEucen
+          # @return [Boolean] true: has soft-delete column.
+          # @return [Boolean] false: no soft-delete column.
+          # @since  Release 1.0.0
+          #
+          def has_soft_delete?
+            ff_has_column? :ff_soft_delete
+          end
+
+          #
+          # Is enable to use soft-delete by grove field?
+          #
+          # @author StewEucen
+          # @return [Boolean] true: enable.
+          # @return [Boolean] false: disable.
+          # @since  Release 1.0.0
+          #
+          def enable_grove_delete?
+            has_grove? \
+                && !has_soft_delete? \
+                && ff_options[:enable_grove_delete]
+            # Need back slashes for this writing.
+          end
+
+          #
+          # Exists field in table?
+          #
+          # @author StewEucen
+          # @param  column [Symbol] Column symbol to check.
+          # @return [Boolean] true: has specified column.
+          # @return [Boolean] false: no specified column.
+          # @since  Release 1.0.0
+          #
+          def ff_has_column?(column)
+            key = column.to_s
+            attribute_aliases[key] || column_names.include?(key)
+          end
+
+          #
+          # Recommended queue interval for appending node.
+          # Can overwrite [queue interval] at setup()/initialize().
+          #
+          # @author StewEucen
+          # @return [Integer] Default queue interval.
+          # @since  Release 1.0.0
+          #
+          def ff_get_query_interval
+            QUEUE_DEFAULT_INTERVAL
+          end
+
+          protected :ff_has_column?,
+                    :ff_get_query_interval
+        end
+      end
+    end
+  end
+end

data/lib/fertile_forest/modules/entities.rb

@@ -0,0 +1,233 @@
+#
+# Fertile Forest for Ruby
+# The new model for storing hierarchical data in a database.
+#
+# @author StewEucen
+# @copyright Copyright (c) 2015 Stew Eucen (http://lab.kochlein.com)
+# @license   http://www.opensource.org/licenses/mit-license.php  MIT License
+#
+# @link       http://lab.kochlein.com/FertileForest
+# @since      File available since Release 1.0.0
+# @version    1.0.0
+#
+module StewEucen
+  # Name space of Stew Eucen's Acts
+  module Acts
+    # Name space of Fertile Forest
+    module FertileForest
+      #
+      # Instance methods to include into derived class by ActiveRecord.
+      #
+      # @author StewEucen
+      # @example Include into ActiveRecord class.
+      #   ActiveRecord::Base.send :include, StewEucen::Acts::FertileForest::Entity
+      # @since  Release 1.0.0
+      #
+      module Entity
+        #
+        # Before save listener (must be an instance methoed).
+        # Transparently manages setting the required fields for FertileForestBehavior
+        # if the parent field is included in the parameters to be saved.
+        #
+        # @return boolean true:Continue to save./false:Abort to save.
+        #
+        def ff_before_save
+          # when not new record, to update.
+          # no need to set ff_columns (id, grove, queue, depth)
+          return true unless new_record?
+
+          if self.class.has_grove?
+            posted_grove = self.ff_grove
+            if posted_grove.blank?
+              # TODO: set_error
+              return false
+            end
+          end
+
+          # return value
+          self.class.fill_required_columns_to_append!(self)
+        end
+
+        def ff_before_create
+        end
+
+        def ff_after_save
+        end
+
+        def ff_before_destroy
+        end
+
+        protected :ff_before_save,
+                  :ff_before_create,
+                  :ff_after_save,
+                  :ff_before_destroy
+
+        ########################################################################
+
+        def ff_reset_values
+          {
+              parent: {0 => nil},
+            children: {},
+          }
+        end
+
+        def ff_get_options
+          @fertile_forest ||= ff_reset_values
+        end
+
+        def nest_unset_parent
+          ff_get_options[:parent] = {0 => nil}
+        end
+
+        def nest_unset_children(id = nil)
+          if id.blank?
+            ff_get_options[:children] = {}
+          else
+            ff_get_options[:children][id] = nil
+          end
+        end
+
+        ##
+        #
+        # accessors
+        #
+        #
+        ########################################################################
+
+        def nest_parent_node
+          ff_get_options[:parent].values.first
+        end
+
+        def nest_child_nodes
+          ff_get_options[:children]
+        end
+
+        def nest_parent_id
+          ff_get_options[:parent].keys.first
+        end
+
+        def nest_child_ids
+          ff_get_options[:children].keys
+        end
+
+        alias nest_parent   nest_parent_node
+        alias nest_genitor  nest_parent_node
+        alias nest_children nest_child_nodes
+
+        ########################################################################
+
+        def nest_set_parent_id(aim_id)
+          ff_get_options[:parent] = {aim_id => nil}  # always overwrite
+        end
+
+        def nest_set_child_id(aim_id)
+          ff_get_options[:children][aim_id] = nil
+        end
+
+        ########################################################################
+
+        def nest_set_parent_node(aim_id, node)
+          ff_get_options[:parent] = {aim_id => node} \
+              if aim_id.present? && node.present?
+        end
+
+        def nest_set_child_node(aim_id, node)
+          ff_get_options[:children][aim_id] = node \
+              if aim_id.present? && node.present?
+        end
+
+        ########################################################################
+
+        def nest_leaf?
+          ff_get_options[:children].blank?
+        end
+
+        def nest_parent?
+          !nest_leaf?
+        end
+
+        ########################################################################
+
+        def trunk(range = ANCESTOR_ALL, columns = nil)
+          self.class.trunk(self, range, columns)
+        end
+
+        def ancestors(columns = nil)
+          self.class.ancestors(self, columns)
+        end
+
+        def genitor(columns = nil)
+          self.class.genitor(self, columns)
+        end
+
+        def root(columns = nil)
+          self.class.root(self, columns)
+        end
+
+        def grandparent(columns = nil)
+          self.class.grandparent(self, columns)
+        end
+
+        def subtree(range = DESCENDANTS_ALL, with_top = true, columns = nil)
+          self.class.subtree(self, range, with_top, columns)
+        end
+
+        def descendants(columns = nil)
+          self.class.descendants(self, columns)
+        end
+
+        def children(columns = nil)
+          self.class.children(self, columns)
+        end
+
+        def nth_child(nth = 0, columns = nil)
+          self.class.nth_child(self, nth, columns)
+        end
+
+        def grandchildren(columns = nil)
+          self.class.grandchildren(self, columns)
+        end
+
+        def siblings(columns = nil)
+          self.class.siblings(self, columns)
+        end
+
+        def nth_sibling(nth = 0, columns = nil)
+          self.class.nth_sibling(self, nth, columns)
+        end
+
+        def elder_sibling(columns = nil)
+          self.class.elder_sibling(self, columns)
+        end
+
+        def younger_sibling(columns = nil)
+          self.class.younger_sibling(self, columns)
+        end
+
+        def offset_sibling(offset, columns = nil)
+          self.class.offset_sibling(self, offset, columns)
+        end
+
+        def leaves(columns = nil)
+          self.class.leaves(self, columns)
+        end
+
+        def internals(columns = nil)
+          self.class.internals(self, columns)
+        end
+
+        def height
+          self.class.height(self)
+        end
+
+        def size
+          self.class.size(self)
+        end
+
+        protected :ff_reset_values,
+                  :ff_get_options
+      end
+    end
+
+  end
+end