rooted_tree 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 70e0e394dca29c945f79679ac2ade085f9210412
-  data.tar.gz: d8e06827ee6b284d2cc39140229125b5f0232428
+  metadata.gz: dfa5843433eb9461adb4ab0e2698e0429d994263
+  data.tar.gz: ef4f2f8a52ee1aa796e435cb767ab96dc7b563b7
 SHA512:
-  metadata.gz: 2b63502165e12f8d0ff158f07c2d2c010485f85f227ffbe05b1f73cc541907601c8a642816e568b8575a6cb7f7b2f4b41d901e5ffafe926a34b855077ea1764b
-  data.tar.gz: 29c29640e1f5e18812f994a76646e91e15b7e0bc5df125056707901e197a97455d5442cb6e19ff758221fc361663646d50a69b9d64331db5a836e51136c96346
+  metadata.gz: cd771695cade59e40219f65827246e54534158e3d5612e8555c829b4293dafb01f2a60805cb2c36af6a8a80c1c70f5b96f7c2a616cb8af02cb568acb23e68f9e
+  data.tar.gz: d29de94468510ee7f2a52c2658a08e6ee8a8973d61cc1f3c6cc819f8f3751768d99fcaaae0315bc49ffe76dbcfe4b1a1e1ff41c138c798399ba0543e9f856252

data/README.md

@@ -1,6 +1,6 @@
 # RootedTree
 
-[![Gem Version](https://badge.fury.io/rb/richtext.png)](http://badge.fury.io/rb/rooted_tree)
+[![Gem Version](https://badge.fury.io/rb/rooted_tree.png)](http://badge.fury.io/rb/rooted_tree)
 [![Build Status](https://travis-ci.org/seblindberg/ruby-rooted_tree.svg?branch=master)](https://travis-ci.org/seblindberg/ruby-rooted_tree)
 [![Coverage Status](https://coveralls.io/repos/github/seblindberg/ruby-rooted_tree/badge.svg?branch=master)](https://coveralls.io/github/seblindberg/ruby-rooted_tree?branch=master)
 [![Inline docs](http://inch-ci.org/github/seblindberg/ruby-rooted_tree.svg?branch=master)](http://inch-ci.org/github/seblindberg/ruby-rooted_tree)

data/lib/rooted_tree/node.rb

@@ -61,16 +61,12 @@ module RootedTree
       super
     end
 
-    # Leaf?
-    #
-    # A node is a leaf if it has no children.
+    # Returns true if this node is a leaf. A leaf is a node with no children.
 
     def leaf?
       @degree == 0
     end
 
-    # Internal?
-    #
     # Returns true if the node is internal, which is equivalent to it having
     # children.
 
@@ -78,17 +74,13 @@ module RootedTree
       !leaf?
     end
 
-    # Root?
-    #
-    # Returns true if node has no parent.
+    # Returns true if the node has no parent.
 
     def root?
       @parent.nil?
     end
 
-    # Root
-    #
-    # Returns the root of the tree.
+    # Returns the root of the tree structure that the node is part of.
 
     def root
       return self if root?
@@ -98,24 +90,18 @@ module RootedTree
       node
     end
 
-    # First?
-    #
     # Returns true if this node is the first of its siblings.
 
     def first?
       @prev.nil?
     end
 
-    # Last?
-    #
     # Returns true if this node is the last of its siblings.
 
     def last?
       @next.nil?
     end
 
-    # Depth
-    #
     # Returns the depth of the node within the tree
 
     def depth
@@ -124,8 +110,6 @@ module RootedTree
 
     alias level depth
 
-    # Max Depth
-    #
     # Returns the maximum node depth under this node.
 
     def max_depth(offset = depth)
@@ -134,36 +118,34 @@ module RootedTree
       children.map { |c| c.max_depth offset + 1 }.max
     end
 
-    # Max Degree
-    #
     # Returns the highest child count of the nodes in the subtree.
 
     def max_degree
       children.map(&:degree).push(degree).max
     end
 
-    # Size
-    #
     # Calculate the size in vertecies of the subtree.
+    #
+    # Returns the number of nodes under this node, including self.
 
     def size
       children.reduce(1) { |a, e| a + e.size }
     end
 
-    # Next
-    #
     # Access the next sibling. Raises a StopIteration if this node is the last
     # one.
+    #
+    # Returns the previous sibling node.
 
     def next
       raise StopIteration if last?
       @next
     end
 
-    # Prev(ious)
-    #
     # Access the previous sibling. Raises a StopIteration if this node is the
     # first one.
+    #
+    # Returns the previous sibling node.
 
     def prev
       raise StopIteration if first?
@@ -172,19 +154,19 @@ module RootedTree
 
     alias previous prev
 
-    # Parent
-    #
     # Access the parent node. Raises a StopIteration if this node is the
     # root.
+    #
+    # Returns the parent node.
 
     def parent
       raise StopIteration if root?
       @parent
     end
 
-    # Append Sibling
-    #
     # Insert a child between this node and the one after it.
+    #
+    # Returns self.
 
     def append_sibling(value = nil)
       raise StructureException, 'Root node can not have siblings' if root?
@@ -203,9 +185,9 @@ module RootedTree
       @next = node
     end
 
-    # Prepend Sibling
-    #
     # Insert a child between this node and the one before it.
+    #
+    # Returns self.
 
     def prepend_sibling(value = nil)
       raise StructureException, 'Root node can not have siblings' if root?
@@ -232,9 +214,9 @@ module RootedTree
       node.parent = self
     end
 
-    # Append Child
-    #
     # Insert a child after the last one.
+    #
+    # Returns self.
 
     def append_child(value = nil)
       if leaf?
@@ -247,9 +229,9 @@ module RootedTree
 
     alias << append_child
 
-    # Prepend Child
-    #
     # Insert a child before the first one.
+    #
+    # Returns self.
 
     def prepend_child(value = nil)
       if leaf?
@@ -259,9 +241,9 @@ module RootedTree
       end
     end
 
-    # Extract
-    #
     # Extracts the node and its subtree from the larger structure.
+    #
+    # Returns self, now made root.
 
     def extract
       return self if root?
@@ -283,9 +265,9 @@ module RootedTree
       self
     end
 
-    # Delete
-    #
     # Removes the node from the tree.
+    #
+    # Returns an array of the children to the deleted node, now made roots.
 
     def delete
       extract.children.map do |child|
@@ -294,12 +276,11 @@ module RootedTree
       end
     end
 
-    # Ancestors
+    # Iterates over the nodes above this in the tree hierarchy and yields them
+    # to a block. If no block is given an enumerator is returned.
     #
     # Returns an enumerator that will iterate over the parents of this node
     # until the root is reached.
-    #
-    # If a block is given it will be yielded to.
 
     def ancestors
       return to_enum(__callee__) unless block_given?
@@ -310,14 +291,14 @@ module RootedTree
       end
     end
 
-    # Children
-    #
-    # Yields to each of the node children. The default order is left-to-right,
-    # but by passing rtl: true the order can be reversed. If a block is not
-    # given an enumerator is returned.
+    # Yields each of the node children. The default order is left-to-right, but
+    # by passing rtl: true the order is reversed. If a block is not given an
+    # enumerator is returned.
     #
     # Note that the block will catch any StopIteration that is raised and
     # terminate early, returning the value of the exception.
+    #
+    # rtl - reverses the iteration order if true.
 
     def children(rtl: false)
       return to_enum(__callee__, rtl: rtl) unless block_given?
@@ -335,9 +316,14 @@ module RootedTree
       end
     end
 
-    # Child
+    # Accessor method for any of the n children under this node. If called
+    # without an argument and the node has anything but exactly one child an
+    # exception will be raised.
     #
-    # Accessor method for any of the n children under this node.
+    # n - the n:th child to be returned. If n is negative the indexing will be
+    #     reversed and the children counted from the last to the first.
+    #
+    # Returns the child at the n:th index.
 
     def child(n = nil)
       if n.nil?
@@ -362,8 +348,6 @@ module RootedTree
       end
     end
 
-    # Each
-    #
     # Yields first to self and then to each child. If a block is not given an
     # enumerator is returned.
 
@@ -373,9 +357,31 @@ module RootedTree
       children { |v| v.each(&block) }
     end
 
-    # Leafs
+    # Converts the tree structure to a nested array of the nodes. Each internal
+    # node is placed at index zero of its own array, followed by an array of its
+    # children. Leaf nodes are not wraped in arrays but inserted directly.
     #
+    # flatten - flattens the array if true.
+    #
+    # Example
+    #
+    #     r
+    #    / \
+    #   a   b  => [r, [[a, [c]], b]]
+    #   |
+    #   c
+    #
+    # Returns a nested array of nodes.
+
+    def to_a flatten: false
+      return super() if flatten
+      return self if leaf?
+      [self, children.map(&:to_a)]
+    end
+
     # Iterates over each of the leafs.
+    #
+    # rtl - if true the iteration order is switched to right to left.
 
     def leafs(rtl: false, &block)
       return to_enum(__callee__, rtl: rtl) unless block_given?
@@ -383,9 +389,10 @@ module RootedTree
       children(rtl: rtl) { |v| v.leafs(rtl: rtl, &block) }
     end
 
-    # Edges
+    # Iterates over each of the edges and yields the parent and the child. If no
+    # block is given an enumerator is returned.
     #
-    # Iterates over each of the edges.
+    # block - an optional block that will be yielded to, if given.
 
     def edges(&block)
       return to_enum(__callee__) unless block_given?
@@ -396,11 +403,13 @@ module RootedTree
       end
     end
 
-    # Add
-    #
     # Add two roots together to create a larger tree. A new common root will be
     # created and returned. Note that if the any of the root nodes are not
     # frozen they will be modified, and as a result seize to be roots.
+    #
+    # other - a Node-like object that responds true to #root?
+    #
+    # Returns a new root with the two nodes as children.
 
     def +(other)
       unless root? && other.root?
@@ -414,53 +423,18 @@ module RootedTree
       ab << a << b
     end
 
-    # Equality
+    # Compare one node (sub)structure with another.
     #
     # Returns true if the two vertecies form identical subtrees
 
     def ==(other)
       return false unless other.is_a? self.class
       return false unless degree == other.degree
+      return false unless value == other.value
 
       children.to_a == other.children.to_a
     end
 
-    # Tree!
-    #
-    # Wraps the entire tree in a Tree object. The operation will freeze the node
-    # structure, making it immutable. If this node is a child the root will be
-    # found and passed to Tree.new.
-
-    def tree!
-      Tree.new root
-    end
-
-    # Tree
-    #
-    # Duplicates the entire tree and calls #tree! on the copy.
-
-    def tree
-      root.dup.tree!
-    end
-
-    # Subtree!
-    #
-    # Extracts this node from the larger tree and wraps it in a Tree object.
-
-    def subtree!
-      Tree.new extract
-    end
-
-    # Subtree
-    #
-    # Duplicates this node and its descendants and wraps them in a Tree object.
-
-    def subtree
-      Tree.new dup
-    end
-
-    # Inspect
-    #
     # Visalizes the tree structure in a style very similar to the cli tool tree.
     # An example of the output can be seen below. Note that the output string
     # contains unicode characters.

data/lib/rooted_tree/tree.rb

@@ -1,32 +1,40 @@
 # frozen_string_literal: true
 
 module RootedTree
-  class Tree
-    attr_reader :root
-
-    def initialize(node)
-      @root = node.root
-      @root.freeze
-    end
-
-    def tree
-      self
-    end
-
-    # Degree
-    #
-    # Returns the maximum degree (number of children) in the tree.
+  module Tree
+    # Returns the maximum degree (highest number of children) in the tree.
 
     def degree
       @degree ||= root.max_degree
     end
 
-    # Depth
-    #
     # Returns the maximum depth of the tree.
 
     def depth
       @depth ||= root.max_depth
     end
+
+    # Iterates over each node in the tree. When given a block it will be yielded
+    # to once for each node. If no block is given an enumerator is returned.
+
+    def each_node(&block)
+      @root.each(&block)
+    end
+
+    # Iterates over each leaf in the tree. When given a block it will be yielded
+    # to once for leaf node. If no block is given an enumerator is returned.
+
+    def each_leaf(&block)
+      @root.leafs(&block)
+    end
+
+    # Iterates over each edge in the tree. An edge is composed of the parent
+    # node and the child, always in that order. When given a block it will be
+    # yielded to once for each node. If no block is given an enumerator is
+    # returned.
+
+    def each_edge(&block)
+      @root.edges(&block)
+    end
   end
 end

data/lib/rooted_tree/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RootedTree
-  VERSION = '0.2.3'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rooted_tree
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Sebastian Lindberg
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-07-27 00:00:00.000000000 Z
+date: 2016-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler