rubytree 0.9.5 → 1.0.2

data/lib/tree.rb

@@ -9,7 +9,7 @@
 # Author:: Anupam Sengupta (anupamsg@gmail.com)
 #
 
-# Copyright (c) 2006-2015 Anupam Sengupta
+# Copyright (c) 2006-2021 Anupam Sengupta
 #
 # All rights reserved.
 #
@@ -47,7 +47,6 @@ require 'tree/tree_deps'
 # This module also acts as the namespace for all classes in the *RubyTree*
 # package.
 module Tree
-
   # == TreeNode Class Description
   #
   # This class models the nodes for an *N-ary* tree data structure. The
@@ -83,6 +82,7 @@ module Tree
   # {include:file:examples/example_basic.rb}
   #
   # @author Anupam Sengupta
+  # noinspection RubyTooManyMethodsInspection
   class TreeNode
     include Enumerable
     include Comparable
@@ -108,11 +108,11 @@ module Tree
     # +content+ attribute for any non-unique node requirements.
     #
     # If you want to change the name, you probably want to call +rename+
-    # instead.
+    # instead. Note that +name=+ is a protected method.
     #
     # @see content
     # @see rename
-    attr_reader   :name
+    attr_accessor :name
 
     # @!attribute [rw] content
     # Content of this node.  Can be +nil+.  Note that there is no
@@ -132,7 +132,7 @@ module Tree
     # @return [Tree::TreeNode] Root of the (sub)tree.
     def root
       root = self
-      root = root.parent while !root.is_root?
+      root = root.parent until root.is_root?
       root
     end
 
@@ -176,8 +176,8 @@ module Tree
       return nil if is_root?
 
       parentage_array = []
-      prev_parent = self.parent
-      while (prev_parent)
+      prev_parent = parent
+      while prev_parent
         parentage_array << prev_parent
         prev_parent = prev_parent.parent
       end
@@ -215,18 +215,20 @@ module Tree
     #
     # @see #[]
     def initialize(name, content = nil)
-      raise ArgumentError, "Node name HAS to be provided!" if name == nil
-      @name, @content = name, content
+      raise ArgumentError, 'Node name HAS to be provided!' if name.nil?
+
+      @name = name
+      @content = content
 
-      if name.kind_of?(Integer)
-        warn StandardWarning,
-             "Using integer as node name."\
-             " Semantics of TreeNode[] may not be what you expect!"\
+      if name.is_a?(Integer)
+        warn StructuredWarnings::StandardWarning,
+             'Using integer as node name.'\
+             ' Semantics of TreeNode[] may not be what you expect!'\
              " #{name} #{content}"
       end
 
-      self.set_as_root!
-      @children_hash = Hash.new
+      set_as_root!
+      @children_hash = {}
       @children = []
     end
 
@@ -253,27 +255,26 @@ module Tree
     # Alias for {Tree::TreeNode#detached_subtree_copy}
     #
     # @see Tree::TreeNode#detached_subtree_copy
-    alias :dup :detached_subtree_copy
+    alias dup detached_subtree_copy
 
     # Returns a {marshal-dump}[http://ruby-doc.org/core-1.8.7/Marshal.html]
-    # represention of the (sub)tree rooted at this node.
+    # representation of the (sub)tree rooted at this node.
     #
     def marshal_dump
-      self.collect { |node| node.create_dump_rep }
+      collect { |node| node.create_dump_rep }
     end
 
     # Creates a dump representation of this node and returns the same as
     # a hash.
-    def create_dump_rep           # :nodoc:
-      { :name => @name,
-        :parent => (is_root? ? nil : @parent.name),
-        :content => Marshal.dump(@content)
-      }
+    def create_dump_rep # :nodoc:
+      { name: @name,
+        parent: (is_root? ? nil : @parent.name),
+        content: Marshal.dump(@content) }
     end
 
     protected :create_dump_rep
 
-    # Loads a marshalled dump of a tree and returns the root node of the
+    # Loads a marshaled dump of a tree and returns the root node of the
     # reconstructed tree. See the
     # {Marshal}[http://ruby-doc.org/core-1.8.7/Marshal.html] class for
     # additional details.
@@ -283,20 +284,20 @@ module Tree
     #       self and makes itself the root.
     #
     def marshal_load(dumped_tree_array)
-      nodes = { }
+      nodes = {}
       dumped_tree_array.each do |node_hash|
         name        = node_hash[:name]
         parent_name = node_hash[:parent]
         content     = Marshal.load(node_hash[:content])
 
-        if parent_name then
+        if parent_name
           nodes[name] = current_node = Tree::TreeNode.new(name, content)
           nodes[parent_name].add current_node
         else
           # This is the root node, hence initialize self.
           initialize(name, content)
 
-          nodes[name] = self    # Add self to the list of nodes
+          nodes[name] = self # Add self to the list of nodes
         end
       end
     end
@@ -308,11 +309,7 @@ module Tree
     #
     # @return [String] A string representation of the node.
     def to_s
-      "Node Name: #{@name}" +
-        " Content: " + (@content.to_s || "<Empty>") +
-        " Parent: " + (is_root?()  ? "<None>" : @parent.name.to_s) +
-        " Children: #{@children.length}" +
-        " Total Nodes: #{size()}"
+      "Node Name: #{@name} Content: #{@content.to_s || '<Empty>'} Parent: #{is_root? ? '<None>' : @parent.name.to_s} Children: #{@children.length} Total Nodes: #{size}"
     end
 
     # @!group Structure Modification
@@ -354,7 +351,7 @@ module Tree
     #
     #    -children.size..children.size
     #
-    # This is to prevent +nil+ nodes being created as children if a non-existant
+    # This is to prevent +nil+ nodes being created as children if a non-existent
     # position is used.
     #
     # If the new node being added has an existing parent node, then it will be
@@ -380,38 +377,37 @@ module Tree
     # @see #<<
     def add(child, at_index = -1)
       # Only handles the immediate child scenario
-      raise ArgumentError,
-            "Attempting to add a nil node" unless child
-      raise ArgumentError,
-            "Attempting add node to itself" if self.equal?(child)
-      raise ArgumentError,
-            "Attempting add root as a child" if child.equal?(root)
-
-      # Lazy mans unique test, won't test if children of child are unique in
+      raise ArgumentError, 'Attempting to add a nil node' unless child
+
+      raise ArgumentError, 'Attempting add node to itself' if equal?(child)
+
+      raise ArgumentError, 'Attempting add root as a child' if child.equal?(root)
+
+      # Lazy man's unique test, won't test if children of child are unique in
       # this tree too.
       raise "Child #{child.name} already added!"\
             if @children_hash.include?(child.name)
 
-      child.parent.remove! child if child.parent # Detach from the old parent
+      child.parent&.remove! child # Detach from the old parent
 
       if insertion_range.include?(at_index)
         @children.insert(at_index, child)
       else
-        raise "Attempting to insert a child at a non-existent location"\
+        raise 'Attempting to insert a child at a non-existent location'\
               " (#{at_index}) "\
-              "when only positions from "\
+              'when only positions from '\
               "#{insertion_range.min} to #{insertion_range.max} exist."
       end
 
-      @children_hash[child.name]  = child
+      @children_hash[child.name] = child
       child.parent = self
-      return child
+      child
     end
 
     # Return a range of valid insertion positions.  Used in the #add method.
     def insertion_range
       max = @children.size
-      min = -(max+1)
+      min = -(max + 1)
       min..max
     end
 
@@ -427,7 +423,7 @@ module Tree
       old_name = @name
 
       if is_root?
-        self.name=(new_name)
+        self.name = new_name
       else
         @parent.rename_child old_name, new_name
       end
@@ -444,20 +440,10 @@ module Tree
     #   pass a String (Integer names may cause *surprises*)
     def rename_child(old_name, new_name)
       raise ArgumentError, "Invalid child name specified: #{old_name}"\
-            unless @children_hash.has_key?(old_name)
+            unless @children_hash.key?(old_name)
 
       @children_hash[new_name] = @children_hash.delete(old_name)
-      @children_hash[new_name].name=(new_name)
-    end
-
-    # Protected method to set the name of this node.
-    # This method should *NOT* be invoked by client code.
-    #
-    # @param [Object] new_name The node Name to set.
-    #
-    # @return [Object] The new name.
-    def name=(new_name)
-      @name = new_name
+      @children_hash[new_name].name = new_name
     end
 
     # Replaces the specified child node with another child node on this node.
@@ -472,7 +458,7 @@ module Tree
       old_child = remove! old_child
       add new_child, child_index
 
-      return old_child
+      old_child
     end
 
     # Replaces the node with another node
@@ -513,7 +499,7 @@ module Tree
     # @param [Tree::TreeNode] parent The parent node.
     #
     # @return [Tree::TreeNode] The parent node.
-    def parent=(parent)         # :nodoc:
+    def parent=(parent) # :nodoc:
       @parent = parent
       @node_depth = nil
     end
@@ -552,7 +538,7 @@ module Tree
     # Protected method which sets this node as a root node.
     #
     # @return +nil+.
-    def set_as_root!              # :nodoc:
+    def set_as_root! # :nodoc:
       self.parent = nil
     end
 
@@ -563,7 +549,7 @@ module Tree
     # The nodes become immutable after this operation.  In effect, the entire tree's
     # structure and contents become _read-only_ and cannot be changed.
     def freeze_tree!
-      each {|node| node.freeze}
+      each { |node| node.freeze }
     end
 
     # @!endgroup
@@ -603,16 +589,15 @@ module Tree
     #
     # @see #add
     # @see #initialize
-    def [](name_or_index, num_as_name=false)
-      raise ArgumentError,
-            "Name_or_index needs to be provided!" if name_or_index == nil
+    def [](name_or_index, num_as_name = false)
+      raise ArgumentError, 'Name_or_index needs to be provided!' if name_or_index.nil?
 
-      if name_or_index.kind_of?(Integer) and not num_as_name
+      if name_or_index.is_a?(Integer) && !num_as_name
         @children[name_or_index]
       else
-        if num_as_name and not name_or_index.kind_of?(Integer)
-          warn StandardWarning,
-             "Redundant use of the `num_as_name` flag for non-integer node name"
+        if num_as_name && !name_or_index.is_a?(Integer)
+          warn StructuredWarnings::StandardWarning,
+               'Redundant use of the `num_as_name` flag for non-integer node name'
         end
         @children_hash[name_or_index]
       end
@@ -624,6 +609,7 @@ module Tree
     # The traversal is *depth-first* and from *left-to-right* in pre-ordered
     # sequence.
     #
+    # @param [Object] block
     # @yieldparam node [Tree::TreeNode] Each node.
     #
     # @see #preordered_each
@@ -631,22 +617,22 @@ module Tree
     #
     # @return [Tree::TreeNode] this node, if a block if given
     # @return [Enumerator] an enumerator on this tree, if a block is *not* given
-    def each(&block)             # :yields: node
-
-     return self.to_enum unless block_given?
+    # noinspection RubyUnusedLocalVariable
+    def each # :yields: node
+      return to_enum unless block_given?
 
-      node_stack = [self]   # Start with this node
+      node_stack = [self] # Start with this node
 
       until node_stack.empty?
-        current = node_stack.shift    # Pop the top-most node
-        if current                    # Might be 'nil' (esp. for binary trees)
-          yield current               # and process it
-          # Stack children of the current node at top of the stack
-          node_stack = current.children.concat(node_stack)
-        end
+        current = node_stack.shift # Pop the top-most node
+        next unless current # Might be 'nil' (esp. for binary trees)
+
+        yield current # and process it
+        # Stack children of the current node at top of the stack
+        node_stack = current.children.concat(node_stack)
       end
 
-      return self if block_given?
+      self if block_given?
     end
 
     # Traverses the (sub)tree rooted at this node in pre-ordered sequence.
@@ -659,48 +645,51 @@ module Tree
     #
     # @return [Tree::TreeNode] this node, if a block if given
     # @return [Enumerator] an enumerator on this tree, if a block is *not* given
-    def preordered_each(&block)  # :yields: node
+    def preordered_each(&block) # :yields: node
       each(&block)
     end
 
     # Traverses the (sub)tree rooted at this node in post-ordered sequence.
     #
+    # @param [Object] block
     # @yieldparam node [Tree::TreeNode] Each node.
     #
     # @see #preordered_each
     # @see #breadth_each
     # @return [Tree::TreeNode] this node, if a block if given
     # @return [Enumerator] an enumerator on this tree, if a block is *not* given
-    def postordered_each(&block)
-      return self.to_enum(:postordered_each) unless block_given?
+    # noinspection RubyUnusedLocalVariable
+    def postordered_each
+      return to_enum(:postordered_each) unless block_given?
 
       # Using a marked node in order to skip adding the children of nodes that
       # have already been visited. This allows the stack depth to be controlled,
       # and also allows stateful backtracking.
-      markednode = Struct.new(:node, :visited)
-      node_stack = [markednode.new(self, false)] # Start with self
+      marked_node = Struct.new(:node, :visited)
+      node_stack = [marked_node.new(self, false)] # Start with self
 
       until node_stack.empty?
         peek_node = node_stack[0]
-        if peek_node.node.has_children? and not peek_node.visited
+        if peek_node.node.has_children? && !peek_node.visited
           peek_node.visited = true
           # Add the children to the stack. Use the marking structure.
           marked_children =
-            peek_node.node.children.map {|node| markednode.new(node, false)}
+            peek_node.node.children.map { |node| marked_node.new(node, false) }
           node_stack = marked_children.concat(node_stack)
           next
         else
-          yield node_stack.shift.node           # Pop and yield the current node
+          yield node_stack.shift.node # Pop and yield the current node
         end
       end
 
-      return self if block_given?
+      self if block_given?
     end
 
     # Performs breadth-first traversal of the (sub)tree rooted at this node. The
     # traversal at a given level is from *left-to-right*. this node itself is
     # the first node to be traversed.
     #
+    # @param [Object] block
     # @yieldparam node [Tree::TreeNode] Each node.
     #
     # @see #preordered_each
@@ -708,10 +697,11 @@ module Tree
     #
     # @return [Tree::TreeNode] this node, if a block if given
     # @return [Enumerator] an enumerator on this tree, if a block is *not* given
-    def breadth_each(&block)
-      return self.to_enum(:breadth_each) unless block_given?
+    # noinspection RubyUnusedLocalVariable
+    def breadth_each
+      return to_enum(:breadth_each) unless block_given?
 
-      node_queue = [self]       # Create a queue with self as the initial entry
+      node_queue = [self] # Create a queue with self as the initial entry
 
       # Use a queue to do breadth traversal
       until node_queue.empty?
@@ -721,7 +711,7 @@ module Tree
         node_to_traverse.children { |child| node_queue.push child }
       end
 
-      return self if block_given?
+      self if block_given?
     end
 
     # An array of all the immediate children of this node. The child
@@ -736,12 +726,12 @@ module Tree
     #
     # @return [Array<Tree::TreeNode>] An array of the child nodes, if no block
     #                                 is given.
-    def children
+    def children(&block)
       if block_given?
-        @children.each {|child| yield child}
-        return self
+        @children.each(&block)
+        self
       else
-        return @children.clone
+        @children.clone
       end
     end
 
@@ -751,6 +741,7 @@ module Tree
     # May yield this node as well if this is a leaf node.
     # Leaf traversal is *depth-first* and *left-to-right*.
     #
+    # @param [Object] block
     # @yieldparam node [Tree::TreeNode] Each leaf node.
     #
     # @see #each
@@ -758,12 +749,35 @@ module Tree
     #
     # @return [Tree::TreeNode] this node, if a block if given
     # @return [Array<Tree::TreeNode>] An array of the leaf nodes
-    def each_leaf &block
+    # noinspection RubyUnusedLocalVariable
+    def each_leaf
       if block_given?
-        self.each { |node| yield(node) if node.is_leaf? }
-        return self
+        each { |node| yield(node) if node.is_leaf? }
+        self
       else
-        self.select { |node| node.is_leaf?}
+        self.select { |node| node.is_leaf? }
+      end
+    end
+
+    # Yields every level of the (sub)tree rooted at this node to the
+    # specified block.
+    #
+    # Will yield this node as well since it is considered the first level.
+    #
+    # @yieldparam level [Array<Tree::TreeNode>] All nodes in the level
+    #
+    # @return [Tree::TreeNode] this node, if a block if given
+    # @return [Enumerator] an enumerator on this tree, if a block is *not* given
+    def each_level
+      if block_given?
+        level = [self]
+        until level.empty?
+          yield level
+          level = level.map(&:children).flatten
+        end
+        self
+      else
+        each
       end
     end
 
@@ -776,7 +790,7 @@ module Tree
     #
     # @return [Tree::TreeNode] The first child, or +nil+ if none is present.
     def first_child
-      children.first
+      @children.first
     end
 
     # Last child of this node.
@@ -784,7 +798,7 @@ module Tree
     #
     # @return [Tree::TreeNode] The last child, or +nil+ if none is present.
     def last_child
-      children.last
+      @children.last
     end
 
     # @!group Navigating the Sibling Nodes
@@ -858,12 +872,14 @@ module Tree
     def siblings
       if block_given?
         parent.children.each { |sibling| yield sibling if sibling != self }
-        return self
+        self
       else
         return [] if is_root?
+
         siblings = []
-        parent.children {|my_sibling|
-                         siblings << my_sibling if my_sibling != self}
+        parent.children do |my_sibling|
+          siblings << my_sibling if my_sibling != self
+        end
         siblings
       end
     end
@@ -892,8 +908,8 @@ module Tree
     def next_sibling
       return nil if is_root?
 
-      myidx = parent.children.index(self)
-      parent.children.at(myidx + 1) if myidx
+      idx = parent.children.index(self)
+      parent.children.at(idx + 1) if idx
     end
 
     # Previous sibling of this node.
@@ -909,23 +925,25 @@ module Tree
     def previous_sibling
       return nil if is_root?
 
-      myidx = parent.children.index(self)
-      parent.children.at(myidx - 1) if myidx && myidx > 0
+      idx = parent.children.index(self)
+      parent.children.at(idx - 1) if idx && idx > 0
     end
 
     # @!endgroup
 
-    # Provides a comparision operation for the nodes.
+    # Provides a comparison operation for the nodes.
     #
-    # Comparision is based on the natural ordering of the node name objects.
+    # Comparison is based on the natural ordering of the node name objects.
     #
     # @param [Tree::TreeNode] other The other node to compare against.
     #
     # @return [Integer] +1 if this node is a 'successor', 0 if equal and -1 if
-    #                   this node is a 'predecessor'.
+    #                   this node is a 'predecessor'. Returns 'nil' if the other
+    #                   object is not a 'Tree::TreeNode'.
     def <=>(other)
-      return +1 if other == nil
-      self.name <=> other.name
+      return nil if other.nil? || other.class != Tree::TreeNode
+
+      name <=> other.name
     end
 
     # Pretty prints the (sub)tree rooted at this node.
@@ -934,9 +952,10 @@ module Tree
     # @param [Integer] max_depth optional maximum depth at which the printing
     #                            with stop.
     # @param [Proc] block optional block to use for rendering
-    def print_tree(level = 0, max_depth = nil,
+    def print_tree(level = node_depth, max_depth = nil,
                    block = lambda { |node, prefix|
-                     puts "#{prefix} #{node.name}" })
+                             puts "#{prefix} #{node.name}"
+                           })
       prefix = ''
 
       if is_root?
@@ -954,10 +973,11 @@ module Tree
       # Exit if the max level is defined, and reached.
       return unless max_depth.nil? || level < max_depth
 
-      children { |child|
-        child.print_tree(level + 1,
-                         max_depth, block) if child } # Child might be 'nil'
+      # Child might be 'nil'
+      children do |child|
+        child&.print_tree(level + 1,
+                          max_depth, block)
+      end
     end
-
   end
 end