fertile_forest 0.0.0 → 1.0.0

data/lib/fertile_forest/modules/states.rb

@@ -0,0 +1,271 @@
+##
+#
+# states methods for Table
+#
+#
+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 States
+          #
+          # Are all nodes siblings?
+          # @param args [Array] Nodes.
+          # @return [Boolean] Returns true is those are sibling nodes.
+          # @todo is full flag
+          #
+          def siblings?(*args)
+            sibling_nodes = ff_resolve_nodes(args.flatten)
+
+            # get id hash by nested information
+            eldest_node = sibling_nodes.values.first
+            full_sibling_nodes = siblings_of(eldest_node, [@_id]).all
+
+            child_hash = {}
+            bingo_count = sibling_nodes.length
+            full_sibling_nodes.each do |the_node|
+              the_id = the_node.id
+              child_hash[the_id] = the_node
+              # ruby has no --xxxx
+              bingo_count -= 1 if sibling_nodes.has_key?(the_id)
+            end
+
+            # return value
+            if bingo_count == 0
+              child_hash
+            else
+              false
+            end
+          end
+
+          #
+          # Is root node?
+          # @param node_obj [Entity|Integer] Node of Entity|int to check.
+          # @return [Boolean] Returns true is this is root node.
+          #
+          def root?(node_obj)
+            aim_node = ff_resolve_nodes(node_obj)
+            return nil if aim_node.blank?       # nil as dubious
+
+            aim_node.ff_depth == ROOT_DEPTH     # never ===
+          end
+
+          #
+          # Has descendant?
+          # @param node_obj [Entity|Integer] Node of Entity|int to check.
+          # @return [Boolean] Returns true is this has descendant node.
+          #
+          def has_descendant?(node_obj)
+            aim_node = ff_resolve_nodes(node_obj)
+            return nil if aim_node.blank?       # nil as dubious
+
+            aim_query = ff_subtree_scope(
+                aim_node,
+                false,          # without top
+                true            # use COALESCE()
+              )
+              .select(@_id)
+
+            # FIXME: When use COALESCE(), can not act query.count
+            # 0 < aim_query.count
+            aim_query.first.present?
+          end
+
+          #
+          # Is leaf node?
+          # @param node_obj [Entity|Integer] Node of Entity|int to check.
+          # @return [Boolean] Returns true is this is leaf node.
+          #
+          def leaf?(node_obj)
+            result = has_descendant?(node_obj)    # nil as dubious
+            return nil if result.nil?
+
+            !result
+          end
+
+          #
+          # Is internal node?
+          #   "internal" means non-leaf and non-root.
+          # @param node_obj [Entity|Integer] Node of Entity|int to check.
+          # @return [Boolean] Returns true is this is leaf node.
+          #
+          def internal?(node_obj)
+            aim_node = ff_resolve_nodes(node_obj)
+            return nil if aim_node.blank?       # nil as dubious
+
+            aim_node.ff_depth != ROOT_DEPTH && has_descendant?(node_obj)
+          end
+
+          #
+          # Has sibling node?
+          # @param node_obj [Entity|Integer] Node of Entity|int to check.
+          # @return [Boolean] Returns true is this has sibling node.
+          #
+          def has_sibling?(node_obj)
+            aim_node = ff_resolve_nodes(node_obj)
+            return nil if aim_node.blank?       # nil as dubious
+
+            aim_depth = aim_node.ff_depth
+            # root node has no sibling
+            return false if aim_depth == ROOT_DEPTH
+
+            parent_node = genitor(aim_node)
+            # null as dubious, because no parent is irregular
+            return nil if parent_node.blank?
+
+            ffdd = arel_table[@_ff_depth]
+            aim_query = ff_subtree_scope(
+                parent_node,
+                false,          # without top
+                false           # use COALESCE()
+                # true          # FIXME: COALESCE() true makes error
+              )
+              .where(ffdd.eq(aim_depth))
+
+            1 < aim_query.count
+          end
+
+          #
+          # Is only child?
+          # @param node_obj [Entity|Integer] Node of Entity|int to check.
+          # @return [Boolean] Returns true is this is only child node.
+          #
+          def only_child?(node_obj)
+            has_sibling = has_sibling?(node_obj)
+            return nil if has_sibling.nil?    # nil as dubious
+
+            !has_sibling
+          end
+
+          #
+          # Is reserching node descendant of base node?
+          # @param base_obj [Entity|Integer] Entity|int of base node to check.
+          # @param researches [Array] Research nodes.
+          # @return [Array] Item of array true is it is descendant node of base node.
+          #
+          def descendant?(base_obj, researches = [])
+            aim_node = ff_resolve_nodes(base_obj)
+            return nil if aim_node.blank?   # nil as dubious
+
+            is_plural = researches.is_a?(Array)
+            return (is_plural ? [] : nil) if researches.blank?
+
+            # need to be "id => node" for checking grove
+            research_nodes = ff_resolve_nodes(
+              is_plural ? researches : [researches],
+              true    # refresh
+            )
+
+            boundary_queue = ff_get_boundary_queue(aim_node)
+            aim_tail_queue = (boundary_queue.blank? \
+              ? QUEUE_MAX_VALUE
+              : boundary_queue - 1
+            )
+
+            aim_queue = aim_node.ff_queue
+            aim_grove = aim_node.ff_grove
+
+            res = {}
+
+            research_nodes.each_pair do |the_id, the_node|
+              if the_node.present? && the_node.ff_grove == aim_grove
+                the_queue = the_node.ff_queue
+                res[the_id] = aim_queue < the_queue && the_queue <= aim_tail_queue
+              else
+                res[the_id] = nil
+              end
+            end
+
+            is_plural ? res : res.values.first
+          end
+
+          #
+          # Is reserching node ancestor of base node?
+          # @param base_obj [Entity|Integer] Entity|int of base node to check.
+          # @param researches [Array] Research nodes.
+          # @return [Array] Item of array true is it is ancestor node of base node.
+          #
+          def ancestor?(base_obj, researches = [])
+            aim_node = ff_resolve_nodes(base_obj)
+            return nil if aim_node.blank?   # nil as dubious
+
+            is_plural = researches.is_a?(Array)
+            return (is_plural ? [] : nil) if researches.blank?
+
+            # need to be "id => node" for checking grove
+            research_nodes = ff_resolve_nodes(
+              is_plural ? researches : [researches],
+              true    # refresh
+            )
+
+            exists_hash = {}
+            Array(ancestors(aim_node)).each { |node| exists_hash[node.id] = true }
+
+            res = {}
+            research_nodes.each_pair do |the_id, the_node|
+              res[the_id] = exists_hash[the_id]
+            end
+
+            is_plural ? res : res.values.first
+          end
+
+          #
+          # Calculate height of subtree.
+          #   When want to get root height as:
+          #    (1) get height of any node.
+          #    (2) root height = height of the node + depth of the node.
+          # Height of empty tree is "-1"<br>
+          # http://en.wikipedia.org/wiki/Tree_(data_structure)
+          # @param base_obj [Entity|Integer] Base node|id to check.
+          # @return [Integer] Height of subtree of base node.
+          # @return [nil] Invalid input (base node is nil).
+          #
+          def height(base_obj)
+            aim_node = ff_resolve_nodes(base_obj)
+            return nil if aim_node.blank?   # nil as dubious
+
+            ffdd = arel_table[@_ff_depth]
+
+            # with top, use COALESCE()
+            height_res = ff_subtree_scope(aim_node, SUBTREE_WITH_TOP_NODE, true)
+              .select(ffdd.maximum.as('ff_height'))
+              .first
+
+            return nil if height_res.blank?   # nil as dubious
+
+            height_res.ff_height - aim_node.ff_depth
+          end
+
+          #
+          # Calculate size of subtree.
+          # @param base_obj [Entity|Integer] Base node|id to check.
+          # @return [Integer] Size of subtree of base node.
+          # @return [nil] Invalid input (base node is nil).
+          #
+          def size(base_obj)
+            aim_node = ff_resolve_nodes(base_obj)
+            return nil if aim_node.blank?   # nil as dubious
+
+            ffdd = arel_table[@_ff_depth]
+
+            # with top, use COALESCE()
+            size_res = ff_subtree_scope(aim_node, SUBTREE_WITH_TOP_NODE, true)
+                .select(ffdd.count.as('ff_count'))
+                .first
+
+            return nil if size_res.blank?   # nil as dubious
+
+            size_res.ff_count
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/fertile_forest/modules/utilities.rb

@@ -0,0 +1,188 @@
+#
+# Utilities 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 Utilities
+
+          def ff_is_bool(aim_obj)
+            aim_obj.kind_of?(TrueClass) || aim_obj.kind_of?(FalseClass)
+          end
+
+          def ff_raw_query(query_string)
+            connection.execute(query_string, :skip_logging)
+          end
+
+          def ff_quoted_column(column, with_table = true)
+            keyString = column.to_s
+            resolved_column = attribute_aliases[keyString] || keyString
+
+            quoted_column = connection.quote_column_name(resolved_column)
+
+            if with_table
+              "#{quoted_table_name}.#{quoted_column}"
+            else
+              quoted_column
+            end
+          end
+
+          #
+          # Update all by raw query with ORDER BY clause and pre-query of user variable.
+          # Update() do not use order() in Ruby on Rails 4.x.
+          # This method is the solution to workaround it.
+          #
+          # 2015/06/01
+          # This method is for raw query to update,
+          # because Rails standard method "update_all()" can not use @ffqq.
+          # Reason why connection is broken from "SET @ffqq = started_value".
+          #
+          # @param predicates [Hash] A hash of predicates for SET clause.
+          # @param conditions [Hash] Conditions to be used, accepts anything Query::where() can take.
+          # @param order      [Hash] Order clause.
+          # @param prequeries [Hash] Execute Prequeries before UPDATE for setting the specified local variables.
+          # @return [Integer|Boolean] Count Returns the affected rows | false.
+          #
+          def ff_update_all_in_order(predicates, conditions, order, prequeries = nil)
+            update_fields = []
+            predicates.each_pair do |key, value|   # NOTICE string value
+              quoted = ff_quoted_column(key)
+              update_fields << "#{quoted} = #{value}"
+            end
+
+            update_conditions = []
+            conditions.each_pair do |key, value|
+              if key.is_a?(Integer)
+                update_conditions << value
+              else
+                quoted = ff_quoted_column(key)
+                if value.is_a?(Array)
+                  joined = value.join(',')
+                  update_conditions << "#{quoted} IN (#{joined})"
+                else
+                  info = key.to_s.split(' ')
+                  if 1 < info.length
+                    picked_column = ff_quoted_column(info.shift.to_sym)
+                    join_list = [picked_column] + info + [value]
+                    update_conditions << join_list.join(' ')
+                  else
+                    update_conditions << "#{quoted} = #{value}"
+                  end
+                end
+              end
+            end
+
+            update_order = []
+            order.each_pair do |key, value|
+              direction = key.is_a?(Integer) ? 'ASC' : value
+              quoted = ff_quoted_column(key)
+              update_order << "#{quoted} #{direction}"
+            end
+
+            # pre-query to SET @xxx := value
+            # can execuete two query() at once, however can not get affectedRows.
+            prequeries = [prequeries] unless prequeries.instance_of?(Array)
+            prequeries.each { |query| ff_raw_query(query) }
+
+            # use raw query, because can not use ORDER BY in standard updateAll().
+            update_query_string = [
+              'UPDATE',
+                quoted_table_name(),   # OK `categories`
+              'SET',
+                update_fields.join(', '),
+              'WHERE',
+                update_conditions.map { |cond| "(#{cond})" }.join(' AND '),
+              'ORDER BY',
+                update_order.join(', '),
+            ].join(' ')
+
+            # return value
+            connection.update(update_query_string)
+          end
+
+          def ff_create_case_expression(key, whens_thens, else_str)
+            joined_list = ["CASE", key]
+            whens_thens.each do |item|
+              joined_list += ["WHEN", item[0], "THEN", item[1]]
+            end
+            joined_list << ["ELSE", else_str, "END"]
+
+            joined_list.join(' ')
+          end
+
+          #
+          # Resolve node from Entity|int params.
+          #
+          # @param nodes [ActiveRecord::Base|Integer|Array] To identify the nodes.
+          # @param refresh [Boolean] true:Refind each Entity by id.
+          # @return [ActiveRecord::Base|Hash] When nodes is array, return value is hash.
+          #
+          def ff_resolve_nodes(nodes, refresh = false)
+            return nodes if nodes.blank?
+            is_plural = nodes.is_a?(Array)
+            nodes = [nodes] unless is_plural
+
+            res_entities = {}
+            refind_ids   = []
+            nodes.each do |item|
+              is_node = item.is_a?(ActiveRecord::Base)
+              if is_node
+                the_id = item.id
+              else
+                the_id = item.to_i
+              end
+
+              if !is_node || refresh
+                refind_ids << the_id
+                res_entities[the_id] = nil
+              else
+                res_entities[the_id] = item
+              end
+            end
+
+            ##
+            # get node orderd by id
+            #
+            if refind_ids.present?
+              aim_query = ff_usual_conditions_scope(nil)
+                .where(id: refind_ids)
+                .ff_required_columns_scope()
+
+              aim_query.all.each do |node|
+                res_entities[node.id] = node
+              end
+            end
+
+            # return value
+            is_plural ? res_entities : res_entities.values.first
+          end
+
+          protected :ff_is_bool,
+                    :ff_raw_query,
+                    :ff_quoted_column,
+                    :ff_update_all_in_order,
+                    :ff_create_case_expression,
+                    :ff_resolve_nodes
+
+        end
+      end
+    end
+  end
+end