deep_tree 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 28279e6c4a07b1a3884589b8f9129676c542ed70
+  data.tar.gz: 390b491664e74b1b1c071e66e41a1bb49f7dc169
+SHA512:
+  metadata.gz: 4dc3c17bd5e7655e65f9a3b4e91f6696b1c702398215db52b6aeff98fd230620db98299309aaadc7a584317edad32ef77e2b766f03948c4a158c1b1d167912e1
+  data.tar.gz: 99157c2776fb9b21ffd341986471c4559ec36cdf332d03e4e5df80c65ace140836877dab38b9ed13fd14d76479d35fecdea4b9b4ba276beeba81ff4de4d2bc8d

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in deep_tree.gemspec
+gemspec
+
+group :benchmarks do
+  gem 'hashie'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Patrick Tulskie
+
+MIT License
+
+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,84 @@
+# DeepTree
+
+DeepTree is a simple class that loops through nodes in nested hashes to find a node that you're looking for.  It's built to alleviate this:
+
+    tons_of_hashes['first_node']['second_node']['third_node'] rescue nil
+    
+Not only does this mask other issues in your code, but it is also super slow especially if you're digging through the same tree structure several times in a given app.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'deep_tree'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install deep_tree
+    
+## Usage
+
+There are three ways to use DeepTree depending on your needs.  The first way is to simply use an instance:
+
+    tree = DeepTree.new(tons_of_hashes)
+    tree.get_leaf('first_node', 'second_node', 'third_node')
+    
+Another way to use it is by extending the `Hash` class.
+
+    require 'deep_tree/hash'
+    tons_of_hashes.get_leaf('first_node', 'second_node', 'third_node')
+    
+Many people try not to reopen Ruby's base classes.  If you want this functionality on the `Hash` class then you can load it up.  If you don't then you don't have to.
+
+Finally, you can just use the class method like this:
+
+    DeepTree.get_leaf(tons_of_hashes, 'first_node', 'second_node')
+
+Additionally, `DeepTree::get_leaf` supports evaluating a block if the result is `nil`.
+
+    DeepTree.get_leaf(tons_of_hashes, 'first_node', 'second_node') do
+      logger.info('That leaf couldn't be found.')
+      nil
+    end
+    
+Both the instance and hash extension all use `DeepTree::get_leaf` so they support passing a block as well.
+
+## A Caveat
+
+All nodes except for the final leaf must be hashes in order for this to work.  DeepTree will return nil for anything else.
+
+## Benchmarks
+
+These test were run on a MacBook Pro Retina 2.7ghz w/ 16 GB RAM.  Each test was run 200k times.  Benchmark files are in the benchmarks directory.
+
+    Good Path
+                           user     system      total        real
+    DeepTree::get_leaf  0.260000   0.110000   0.370000 (  0.375624)
+    Hash#get_leaf       0.500000   0.130000   0.630000 (  0.622437)
+    DeepTree#get_leaf   0.600000   0.030000   0.630000 (  0.630710)
+    Hash[] w/ rescue    0.080000   0.010000   0.090000 (  0.094365)
+    Hashie::Mash        4.390000   0.240000   4.630000 (  4.617386)
+
+    Bad Path
+                           user     system      total        real
+    DeepTree::get_leaf  0.210000   0.120000   0.330000 (  0.328618)
+    Hash#get_leaf       0.530000   0.150000   0.680000 (  0.679037)
+    DeepTree#get_leaf   0.620000   0.030000   0.650000 (  0.646792)
+    Hash[] w/ rescue    0.510000   0.050000   0.560000 (  0.567455)
+    Hashie::Mash        6.260000   0.400000   6.660000 (  6.744009)
+    
+So, in the case where the whole path is good, simply chaining together hash calls is the clear winner (but if that was always the case, you wouldn't be here right now).  In the event that the path is broken somewhere along the line, DeepTree's solution is at least 2x faster for this extremely contrived example.  Benchmarks are in the benchmarks directory for your viewing pleasure.
+
+I recently added Hashie::Mash to the mix here since everyone I showed this to told me that I should try Hashie::Mash.  I have had lots of performance and memory issues with Hashie::Mash in the past and as of the latest version (2.0.5) it doesn't seem to be any better.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.pattern = "spec/*_spec.rb"
+end

data/benchmarks/bad_path.rb

@@ -0,0 +1,22 @@
+require_relative 'benchmark_helper'
+
+bad_path = %w(three_level nope nada)
+
+puts "Bad Path"
+Benchmark.bm do |x|
+  x.report('DeepTree::get_leaf') do
+    $iterations.times { DeepTree.get_leaf($hash, *bad_path) }
+  end
+  x.report('Hash#get_leaf     ') do
+    $iterations.times { $hash.get_leaf($hash, *bad_path) }
+  end
+  x.report('DeepTree#get_leaf ') do
+    $iterations.times { tree = DeepTree.new($hash); tree.get_leaf($hash, *bad_path) }
+  end
+  x.report('Hash[] w/ rescue  ') do
+    $iterations.times { $hash['three_level']['nope']['nada'] rescue nil }
+  end
+  x.report('Hashie::Mash      ') do
+    $iterations.times { Hashie::Mash.new($hash).three_level!.nope!.nada }
+  end
+end

data/benchmarks/benchmark_helper.rb

@@ -0,0 +1,20 @@
+require 'rubygems'
+require 'bundler'
+require 'benchmark'
+require_relative '../lib/deep_tree'
+require_relative '../lib/deep_tree/hash'
+
+Bundler.require :benchmarks
+
+$iterations = 200_000
+
+$hash = {
+  'one_level'   => 'SUCCESS',
+  'three_level' => {
+    'level_two' => {
+      'level_one' => 'HOORAY'
+    }
+  }
+}
+
+GC.disable

data/benchmarks/good_path.rb

@@ -0,0 +1,22 @@
+require_relative 'benchmark_helper'
+
+good_path = %w(three_level level_two level_one)
+
+puts "Good Path"
+Benchmark.bm do |x|
+  x.report('DeepTree::get_leaf') do
+    $iterations.times { DeepTree.get_leaf($hash, *good_path) }
+  end
+  x.report('Hash#get_leaf     ') do
+    $iterations.times { $hash.get_leaf($hash, *good_path) }
+  end
+  x.report('DeepTree#get_leaf ') do
+    $iterations.times { tree = DeepTree.new($hash); tree.get_leaf($hash, *good_path) }
+  end
+  x.report('Hash[] w/ rescue  ') do
+    $iterations.times { $hash['three_level']['level_two']['level_one'] rescue nil }
+  end
+  x.report('Hashie::Mash      ') do
+    $iterations.times { Hashie::Mash.new($hash).three_level.level_two.level_one }
+  end
+end

data/deep_tree.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'deep_tree/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "deep_tree"
+  gem.version       = DeepTree::VERSION
+  gem.authors       = ["Patrick Tulskie"]
+  gem.email         = ["patricktulskie@gmail.com"]
+  gem.description   = %q{DeepTree simplifies fetching deeply nested nodes in Ruby hashes.}
+  gem.summary       = %q{Aids with finding deeply nested nodes in Ruby hashes.}
+  gem.homepage      = "https://github.com/patricktulskie/deep_tree"
+  gem.licenses      = %w(MIT)
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  
+  gem.add_development_dependency('minitest')
+end

data/lib/deep_tree.rb

@@ -0,0 +1 @@
+require_relative 'deep_tree/deep_tree'

data/lib/deep_tree/deep_tree.rb

@@ -0,0 +1,41 @@
+class DeepTree
+  
+  Error            = Class.new(StandardError)
+  InvalidTreeError = Class.new(Error)
+  
+  attr_accessor :tree
+  
+  def self.get_leaf(parent, *args)
+    args.each_with_index do |key, index|
+      result = case
+      when index == (args.length - 1)
+        return parent[key].nil? && block_given? ? yield : parent[key]
+      when parent[key].is_a?(Hash)
+        parent = parent[key]
+      else
+        return block_given? ? yield : nil
+      end
+    end
+  end
+  
+  def initialize(tree)
+    if tree.kind_of?(Hash)
+      self.tree = tree
+    else
+      raise InvalidTreeError, "Expected a kind of Hash but got an instance of #{tree.class}"
+    end
+  end
+  
+  def get_leaf(*args)
+    if block_given?
+      DeepTree.get_leaf(tree, *args) { yield }
+    else
+      DeepTree.get_leaf(tree, *args)
+    end
+  end
+  
+  def method_missing(*args)
+    self.tree(args)
+  end
+  
+end

data/lib/deep_tree/hash.rb

@@ -0,0 +1,11 @@
+class Hash
+  
+  def get_leaf(*args)
+    if block_given?
+      DeepTree.get_leaf(self, *args) { yield }
+    else
+      DeepTree.get_leaf(self, *args)
+    end
+  end
+  
+end

data/lib/deep_tree/version.rb

@@ -0,0 +1,3 @@
+class DeepTree
+  VERSION = "0.0.1"
+end

data/spec/deep_tree_spec.rb

@@ -0,0 +1,60 @@
+require_relative "spec_helper"
+
+describe DeepTree do
+  
+  before do
+    @result_data = {
+      'one_level'   => 'SUCCESS',
+      'three_level' => {
+        'level_two' => {
+          'level_one' => 'HOORAY'
+        }
+      }
+    }
+  end
+  
+  describe :class do
+    
+    it "raises an exception for invalid inputs" do
+      proc { DeepTree.new(Array.new) }.must_raise(DeepTree::InvalidTreeError)
+    end
+    
+    it "gets a leaf node" do
+      DeepTree.get_leaf(@result_data, 'three_level', 'level_two', 'level_one').must_equal 'HOORAY'
+    end
+    
+  end
+  
+  describe :instance do
+    
+    before(:each) do
+      @deep_tree = DeepTree.new(@result_data)
+    end
+  
+    it "gets a single level's node" do
+      @deep_tree.get_leaf('one_level').must_equal 'SUCCESS'
+    end
+  
+    it "gets a deeply nested node" do
+      @deep_tree.get_leaf('three_level', 'level_two', 'level_one').must_equal 'HOORAY'
+    end
+  
+    it "responds with nil for a shallow missing node" do
+      @deep_tree.get_leaf('missing').must_be_nil
+    end
+  
+    it "responds with nil for a deep missing node" do
+      @deep_tree.get_leaf('three_level', 'level_two', 'missing').must_be_nil
+    end
+  
+    it "responds with nil when it encounters a non-hash in the path" do
+      @deep_tree.get_leaf('three_level', 'level_two', 'level_one', 'level_zero').must_be_nil
+    end
+  
+    it "evaluates a block instead of returning nil if a block is given" do
+      @deep_tree.get_leaf('nope') { 'potato' }.must_equal 'potato'
+    end
+    
+  end
+  
+end

data/spec/hash_spec.rb

@@ -0,0 +1,48 @@
+require_relative "spec_helper"
+
+describe Hash do
+  
+  describe :instance do
+    
+    before(:each) do
+      @result_data = {
+        'one_level'   => 'SUCCESS',
+        'three_level' => {
+          'level_two' => {
+            'level_one' => 'HOORAY'
+          }
+        }
+      }
+    end
+  
+    it "responds to get_leaf" do
+      @result_data.respond_to?(:get_leaf).must_equal true
+    end
+  
+    it "gets a single level's node" do
+      @result_data.get_leaf('one_level').must_equal 'SUCCESS'
+    end
+  
+    it "gets a deeply nested node" do
+      @result_data.get_leaf('three_level', 'level_two', 'level_one').must_equal 'HOORAY'
+    end
+  
+    it "responds with nil for a shallow missing node" do
+      @result_data.get_leaf('missing').must_be_nil
+    end
+  
+    it "responds with nil for a deep missing node" do
+      @result_data.get_leaf('three_level', 'level_two', 'missing').must_be_nil
+    end
+  
+    it "responds with nil when it encounters a non-hash in the path" do
+      @result_data.get_leaf('three_level', 'level_two', 'level_one', 'level_zero').must_be_nil
+    end
+  
+    it "evaluates a block instead of returning nil if a block is given" do
+      @result_data.get_leaf('nope') { 'potato' }.must_equal 'potato'
+    end
+    
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'minitest/spec'
+require 'minitest/autorun'
+require_relative '../lib/deep_tree'
+require_relative '../lib/deep_tree/hash'

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: deep_tree
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Patrick Tulskie
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-12-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: DeepTree simplifies fetching deeply nested nodes in Ruby hashes.
+email:
+- patricktulskie@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- benchmarks/bad_path.rb
+- benchmarks/benchmark_helper.rb
+- benchmarks/good_path.rb
+- deep_tree.gemspec
+- lib/deep_tree.rb
+- lib/deep_tree/deep_tree.rb
+- lib/deep_tree/hash.rb
+- lib/deep_tree/version.rb
+- spec/deep_tree_spec.rb
+- spec/hash_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/patricktulskie/deep_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.0.3
+signing_key: 
+specification_version: 4
+summary: Aids with finding deeply nested nodes in Ruby hashes.
+test_files:
+- spec/deep_tree_spec.rb
+- spec/hash_spec.rb
+- spec/spec_helper.rb