rooted_tree 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a23c9e6f541bfd82e32fa1417fefd88b8357e843
+  data.tar.gz: 05ac69ac576ba55e81c05d064d1adaa73380a8e6
+SHA512:
+  metadata.gz: dcffedd7ac50e2220bdd1dd7e6dbc9158bda7144eaa79c60e5a3c39a15375e1e7a7b3e6b77a7d316d48c5c4b8115444e732f6f6659a7b6a304770e12596fc452
+  data.tar.gz: e76035b943dabc64f8455d158f6d0074cbbb3605eb253646045e9538fba115c7321d961c7936e86e2d4bc48b4e6f51ef72d834aae2c332ffd82a22e7e181051f

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.12.5

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rooted_tree.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Sebastian Lindberg
+
+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.md

@@ -0,0 +1,99 @@
+# RootedTree
+
+[![Gem Version](https://badge.fury.io/rb/richtext.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)
+
+A tree is a connected graph with no cycles. There, that is plenty of explanation. Please refer to https://en.wikipedia.org/wiki/Tree_structure for a more in depth description, but if you need one this library probably is not for you.
+
+This gem technically implements a _rooted, ordered tree_, but that name is a mouthful. It is ment to be used as a building block when working with any tree shaped data. For a brief recap of the terminology please see below.
+
+           A     A is the root.
+      ┌────┼──┐  B, C and D are all children of A.
+      B    C  D  E is a descendant of A.
+    ┌─┼─┐ ┌┴┐ │  A is of degree 3 while C is of degree 2.
+    E F G H I J  F is a leaf.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rooted_tree'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rooted_tree
+
+## Usage
+
+Please see the documentation for the complete API.
+
+```ruby
+# Create some nodes
+root = RootedTree::Node.new
+child_a = RootedTree::Node.new
+child_b = RootedTree::Node.new
+
+# Put the two children below the root
+root << child_a << child_b
+
+# Look at the result
+p root # => RootedTree::Node:0x3fd5d54efda0
+       #    ├─╴RootedTree::Node:0x3fd5d54c3ea8
+       #    └─╴RootedTree::Node:0x3fd5d54ba894
+```
+
+The gem is primarily ment to be extended by other classes. The following example builds a tree of the files in the file system and displays it much like the command line tool `tree`.
+
+```ruby
+class FileSystemItem < RootedTree::Node
+  attr_reader :name
+
+  def initialize name
+    super()
+    @name = name
+  end
+
+  def display
+    inspect { |item| item.name }
+  end
+
+  def self.map_to_path path = '.', root: new(path)
+    # Iterate over all of the files in the directory
+    Dir[path + '/*'].each do |entry|
+      # Create a new FileSystemItem for the entry
+      item = new File.basename entry
+      root << item
+      # Continue to map the files and directories under
+      # entry, if it is a directory
+      map_to_path entry, root: item unless File.file? entry
+    end
+
+    root
+  end
+end
+
+puts FileSystemItem.map_to_path('.').display
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rooted_tree.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rooted_tree"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/filesystem_tree.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+require 'rooted_tree'
+
+# FileSystemItem
+#
+# Maps the entries in the file system to `Node` objects via .map_to_path. The
+# Node#inspect method is then exploited in #display to show the resulting tree
+# structure.
+
+class FileSystemItem < RootedTree::Node
+  attr_reader :name
+  
+  def initialize name
+    super()
+    @name = name
+  end
+  
+  def display
+    inspect { |item| item.name }
+  end
+  
+  def self.map_to_path path = '.', root: new(path)
+    # Iterate over all of the files in the directory
+    Dir[path + '/*'].each do |entry|
+      # Create a new FileSystemItem for the entry
+      item = new File.basename entry
+      root << item
+      # Continue to map the files and directories under
+      # entry, if it is a directory
+      map_to_path entry, root: item unless File.file? entry
+    end
+    
+    root
+  end
+end
+
+puts FileSystemItem.map_to_path('.').display

data/lib/rooted_tree.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'rooted_tree/version'
+require 'rooted_tree/node'
+require 'rooted_tree/tree'
+
+module RootedTree
+  class StructureException < StandardError; end
+end

data/lib/rooted_tree/node.rb

@@ -0,0 +1,413 @@
+# frozen_string_literal: true
+
+# Node
+#
+#
+# The following is an example of a rooted tree of height 3.
+#
+#       r         - r, a, b, c, and d are internal vertices
+#    +--+---+     - vertices e, f, g, h, i, and j are leaves
+#    a  b   c     - vertices g, h, and i are siblings
+#   +++ | +-+-+   - node a is an ancestor of j
+#   d e f g h i   - j is a descendant of a
+#   |
+#   j
+#
+# The terminology is mostly referenced from
+# http://www.cs.columbia.edu/~cs4203/files/GT-Lec4.pdf.
+
+module RootedTree
+  class Node
+    attr_accessor :first_child, :last_child
+    attr_writer :next, :prev, :parent
+    protected :next=, :prev=, :parent=, :first_child=, :last_child=
+
+    def initialize
+      @parent = nil
+      @next = nil
+      @prev = nil
+      @first_child = nil
+      @last_child = nil
+    end
+
+    def initialize_copy(*)
+      duped_children = children.map { |v| v.dup.tap { |w| w.parent = self } }
+      duped_children.each_cons(2) { |a, b| a.next, b.prev = b, a }
+
+      @parent = nil
+      @first_child = duped_children.first
+      @last_child = duped_children.last
+    end
+
+    # Leaf?
+    #
+    # A node is a leaf if it has no children.
+
+    def leaf?
+      @first_child.nil?
+    end
+
+    # Internal?
+    #
+    # Returns true if the node is internal, which is equivalent to it having
+    # children.
+
+    def internal?
+      !leaf?
+    end
+
+    # Root?
+    #
+    # Returns true if node has no parent.
+
+    def root?
+      @parent.nil?
+    end
+
+    # Root
+    #
+    # Returns the root of the tree.
+
+    def root
+      return self if root?
+      
+      node = self
+      loop { node = node.parent }
+      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
+      ancestors.count
+    end
+
+    alias level depth
+
+    # Degree
+    #
+    # Returns the number of children of the node.
+
+    def degree
+      children.count
+    end
+    
+    alias arity degree
+
+    # Size
+    #
+    # Calculate the size in vertecies of the subtree.
+
+    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.
+
+    def next
+      raise StopIteration if last?
+      @next
+    end
+
+    # Prev(ious)
+    #
+    # Access the previous sibling. Raises a StopIteration if this node is the
+    # first one.
+
+    def prev
+      raise StopIteration if first?
+      @prev
+    end
+
+    alias previous prev
+
+    # Parent
+    #
+    # Access the parent node. Raises a StopIteration if this node is the
+    # root.
+
+    def parent
+      raise StopIteration if root?
+      @parent
+    end
+
+    # Append Sibling
+    #
+    # Insert a child between this node and the one after it.
+
+    def append_sibling(node)
+      raise StructureException, 'Root node can not have siblings' if root?
+
+      node.next = @next
+      node.prev = self
+      node.parent = @parent
+      if @next
+        @next.prev = node
+      else
+        @parent.last_child = node
+      end
+      @next = node
+    end
+
+    # Prepend Sibling
+    #
+    # Insert a child between this node and the one before it.
+
+    def prepend_sibling(node)
+      raise StructureException, 'Root node can not have siblings' if root?
+
+      node.next = self
+      node.prev = @prev
+      node.parent = @parent
+      if @prev
+        @prev.next = node
+      else
+        @parent.first_child = node
+      end
+      @prev = node
+    end
+
+    # Append Child
+    #
+    # Insert a child after the last one.
+
+    def append_child(child)
+      if leaf?
+        @first_child = @last_child = child
+        child.next = child.prev = nil
+        child.parent = self
+      else
+        @last_child.append_sibling child
+      end
+      self
+    end
+
+    # Prepend Child
+    #
+    # Insert a child before the first one.
+
+    def prepend_child(child)
+      if leaf?
+        @first_child = @last_child = child
+        child.next = child.prev = nil
+        child.parent = self
+      else
+        @first_child.prepend_sibling child
+      end
+    end
+
+    alias << append_child
+
+    # Extract
+    #
+    # Extracts the node and its subtree from the larger structure.
+
+    def extract
+      return self if root?
+
+      if last?
+        parent.last_child = @prev
+      else
+        @next.prev = @prev
+      end
+
+      if first?
+        parent.first_child = @next
+      else
+        @prev.next = @next
+      end
+
+      @prev = @next = @parent = nil
+      self
+    end
+
+    # Delete
+    #
+    # Removes the node from the tree.
+
+    def delete
+      extract.children.map do |child|
+        child.parent = nil
+        child
+      end
+    end
+
+    # Ancestors
+    #
+    # 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?
+      node = self
+      loop do
+        node = node.parent
+        yield node
+      end
+    end
+
+    # Children
+    #
+    # Returns an enumerator that will iterate over 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 given it will be yielded to.
+
+    def children(rtl: false)
+      return to_enum(__callee__, rtl: rtl) unless block_given?
+      return if leaf?
+
+      child, advance = if rtl
+                         [@last_child, :prev]
+                       else
+                         [@first_child, :next]
+                       end
+
+      loop do
+        yield child
+        child = child.send advance
+      end
+    end
+
+    # Each
+    #
+    #
+
+    def each(&block)
+      return to_enum(__callee__) unless block_given?
+      yield self
+      children { |v| v.each(&block) }
+    end
+
+    # Leafs
+    #
+    # Iterates over each of the leafs.
+
+    def leafs(rtl: false, &block)
+      return to_enum(__callee__, rtl: rtl) unless block_given?
+      return yield self if leaf?
+      children(rtl: rtl) { |v| v.leafs(rtl: rtl, &block) }
+    end
+
+    # Edges
+    #
+    # Iterates over each of the edges.
+
+    def edges(&block)
+      return to_enum(__callee__) unless block_given?
+
+      children do |v|
+        yield self, v
+        v.edges(&block)
+      end
+    end
+
+    # Add
+    #
+    # Add two roots together to create a larger tree. A new common root will be
+    # created and returned.
+
+    def +(other)
+      unless root? && other.root?
+        raise StructureException, 'Only roots can be added'
+      end
+
+      root = self.class.new
+      root << self << other
+    end
+
+    # Equality
+    #
+    # Returns true if the two vertecies form identical subtrees
+
+    def ==(other)
+      return false unless other.is_a? self.class
+      return other.leaf? if leaf?
+
+      children.to_a == other.children.to_a
+    end
+    
+    # Tree
+    #
+    # Wraps the entire tree in a Tree object If this node is a child the root
+    # will be found and passed to Tree.new.
+    
+    def tree
+      Tree.new root
+    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.
+    #
+    #   Node:0x3ffd64c22abc
+    #   |--Node:0x3ffd64c1fd30
+    #   |  |--Node:0x3ffd64c1f86c
+    #   |  +--Node:0x3ffd64c1f63c
+    #   +--Entety:0x3ffd64c1f40c
+    #
+    # By passing `as_array: true` the method will instead return an array
+    # containing each of the output lines. The method also accepts a block
+    # which, if given, will be yielded to once for every node, and the output
+    # will be used as node labels instead of the default identifier.
+
+    def inspect(as_array: false, &block)
+      unless block_given?
+        block = proc { |v| format '%s:0x%0x', v.class.name, v.object_id }
+      end
+
+      res = [block.call(self)]
+
+      children do |child|
+        lines = child.inspect(as_array: true, &block).each
+        res << ((child.last? ? '└─╴' : '├─╴') + lines.next)
+        prep = child.last? ? '   ' : '│  '
+        loop { res << (prep + lines.next) }
+      end
+
+      as_array ? res : res.join("\n")
+    end
+  end
+end

data/lib/rooted_tree/tree.rb

@@ -0,0 +1,20 @@
+module RootedTree
+  class Tree
+    attr_reader :root
+    
+    def initialize(node = Node.new)
+      @root = node.root
+    end
+    
+    # Degree
+    #
+    # Returns the maximum degree (number of children) in the tree.
+    
+    def degree
+      max_degree_node = root.each.max_by do |node|
+        node.degree
+      end
+      max_degree_node.degree
+    end
+  end
+end

data/lib/rooted_tree/version.rb

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

data/rooted_tree.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rooted_tree/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rooted_tree"
+  spec.version       = RootedTree::VERSION
+  spec.authors       = ["Sebastian Lindberg"]
+  spec.email         = ["seb.lindberg@gmail.com"]
+
+  spec.summary       = %q{A basic implementation of a tree data structure.}
+  spec.description   = %q{This gem implements a rooted, ordered tree, with a focus on easy iteration over nodes and access to basic tree prperties.}
+  spec.homepage      = "https://github.com/seblindberg/ruby-rooted_tree"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.12"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "coveralls", "~> 0.8"
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: rooted_tree
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sebastian Lindberg
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-07-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: This gem implements a rooted, ordered tree, with a focus on easy iteration
+  over nodes and access to basic tree prperties.
+email:
+- seb.lindberg@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- examples/filesystem_tree.rb
+- lib/rooted_tree.rb
+- lib/rooted_tree/node.rb
+- lib/rooted_tree/tree.rb
+- lib/rooted_tree/version.rb
+- rooted_tree.gemspec
+homepage: https://github.com/seblindberg/ruby-rooted_tree
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: A basic implementation of a tree data structure.
+test_files: []