lab42_nhash 0.1.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 02be76a89cdf9ca8717dff56712bff2479224757
+  data.tar.gz: 419240c05de38a8552b5573ac2152b40714fd76c
+SHA512:
+  metadata.gz: b1937b9751c90dd02b23bd092c345d0b2f8844876c16476900487512b9603c5e121b7aed6113070487ac3b948e9cb29c7b8e8053f1f04b213689d5447984ea50
+  data.tar.gz: 188a2fba1f7034068c8d73b4e6847942b05c46bc2b1c56658631f149ffdb7ceef3c392f914cde35264ced0d78f1c5777abe87b39881a6f5718e82a44279df047

data/.gitignore

@@ -0,0 +1,35 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+.tmux

data/.rspec

@@ -0,0 +1,3 @@
+--colour
+--format documentation
+--tag ~js

data/Gemfile

@@ -0,0 +1,4 @@
+# A sample Gemfile
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,61 @@
+PATH
+  remote: .
+  specs:
+    lab42_nhash (0.1.0.pre)
+      forwarder2 (~> 0.2)
+      ruby_parser (~> 3.6)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ae (1.8.2)
+      ansi
+    ansi (1.4.3)
+    brass (1.2.1)
+    coderay (1.1.0)
+    columnize (0.8.9)
+    debugger (1.6.6)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.2.0)
+      debugger-ruby_core_source (~> 1.3.2)
+    debugger-linecache (1.2.0)
+    debugger-ruby_core_source (1.3.4)
+    diff-lcs (1.2.5)
+    facets (2.9.3)
+    forwarder2 (0.2.0)
+    method_source (0.8.2)
+    pry (0.9.12.6)
+      coderay (~> 1.0)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    pry-debugger (0.2.2)
+      debugger (~> 1.3)
+      pry (~> 0.9.10)
+    qed (2.9.1)
+      ansi
+      brass
+      facets (>= 2.8)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.8)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.6)
+    ruby_parser (3.6.0)
+      sexp_processor (~> 4.1)
+    sexp_processor (4.4.3)
+    slop (3.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ae (~> 1.8)
+  bundler (~> 1.6)
+  lab42_nhash!
+  pry (~> 0.9)
+  pry-debugger (~> 0.2)
+  qed (~> 2.9)
+  rspec (~> 2.14)

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Robert Dober
+
+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,36 @@
+# lab42_nested_hash
+
+A nested hash view with dotted deep access à la I18n.t of Rails and with optional string interpolation. Typically YML loaded Hashes are used.
+
+
+## Get Access (combined keys with dot notation)
+
+Please see the [QED](http://rubyworks.github.io/qed/) demos [here](https://github.com/RobertDober/lab42_nested_hash/blob/master/demo/000-basic-examples.md) for detailed explainations and specifications:
+
+```ruby
+    h = { "a" => 1,
+          "b" => { "c" => 2, "d" => true } }
+
+    nh = NHash.new h
+
+```
+
+Then `get` lets us access elements
+
+```ruby
+    nh.get('a').assert == 1
+    nh.get('b.c').assert == 2
+```
+
+or _subhashes_:
+
+```ruby
+    nh.get('b').assert.kind_of? NHash
+```
+
+
+### Indifferent Access
+
+### Prefix and Suffix Stacks
+
+## Fallbacks

data/demo/000-basic-examples.md

@@ -0,0 +1,45 @@
+
+# Lab42::NHash QED 
+
+## Basic Example Dotted Access
+
+
+```ruby
+    h = { "a" => 1,
+          "b" => { "c" => 2, "d" => true } }
+
+    nh = NHash.new h
+
+```
+
+Then `get` lets us access elements
+
+```ruby
+    nh.get('a').assert == 1
+    nh.get('b.c').assert == 2
+```
+
+or _subhashes_:
+
+```ruby
+    nh.get('b').assert.kind_of? NHash
+```
+
+## Non existing keys
+
+`get` raises a KeyError if there is no such key
+
+```ruby
+    KeyError.assert.raised? do
+      nh.get 'c'
+    end
+```
+
+but like `Hash#fetch` a default value or block can remedy at that
+
+```ruby
+    nh.get( 'c', :default ).assert == :default
+    nh.get( 'c' ){ |key| key + key }.assert == 'cc'
+```
+
+

data/demo/010-indifferent-access.md

@@ -0,0 +1,48 @@
+
+# Lab42::NHash QED 
+
+## Indifferent Access
+
+
+```ruby
+    h = { "a" => 1,
+          b: { "c" => 2, d: true } }
+
+    nh = NHash.new h
+
+```
+
+is not available by default
+
+```ruby
+    KeyError.assert.raised? do
+      nh.get 'b.c'
+    end
+```
+
+but it can be enabled
+
+```ruby
+    nia = nh.with_indifferent_access
+    nia.get( 'b.c' ).assert == 2
+```
+
+without affecting the original object
+
+```ruby
+    KeyError.assert.raised? do
+      nh.get 'b.c'
+    end
+```
+
+and of course KeyErrors are still raised in case
+
+```ruby
+    KeyError.assert.raised? do
+      nia.get 'a.b'
+    end
+    KeyError.assert.raised? do
+      nh.get 'a.b'
+    end
+```
+

data/demo/020-afixes.md

@@ -0,0 +1,108 @@
+
+# Lab42::NHash QED 
+
+## Afixed Access
+
+
+### Prefixes
+
+YAML documents are typically quite nested and often
+a common prefix (and less often a common suffix) is
+used in a given context.
+
+```ruby
+    h = { "a" => { 
+            "b" => 
+              { "c" => 'abc',
+                "d" => 'abd' } },
+          "x" => {
+            "b" =>
+              { "c" => 'xbc' } } }
+
+    nh = NHash.new h
+    nh.push_prefix 'a'
+
+```
+
+Now `get` keys that start with a '.' are prefixed with a, let us demonstrate:
+
+```ruby
+    nh.get( '.b.c' ).assert == 'abc'
+```
+
+but not using the '.' as a prefix I can still access with an _absolute_ key path.
+
+```ruby
+    nh.get( 'a.b.c').assert == 'abc'
+```
+
+### Suffixes and Combination of both
+
+```ruby
+    nh.push_suffix 'c'
+    nh.get( 'a.b.' ).assert == 'abc'
+    nh.get( 'x.b.' ).assert == 'xbc'
+
+    nh.get( '.b.' ).assert == 'abc'
+    nh.get( 'x.b.'  ).assert == 'xbc'
+```
+
+
+### The Stack
+
+As the name suggests we can push and pop suffices and prefices
+This is convenient as often the suffix/Prefix correspond to
+a given context in the program.
+
+```ruby
+    nh.push_prefix 'a.b'
+    nh.get('.d').assert == 'abd'
+    2.times{ nh.pop_prefix }
+    KeyError.assert.raised? do
+      nh.get('.d').assert == 'abd'
+    end
+```
+
+### Temporary Stack Modifiaction with the With Pattern
+
+An often more convenient way to push values to the stacks is the `with` pattern that will
+ensure that the stack is popped again at the end of the provided block.
+
+
+```ruby
+    nh.with_prefix 'a' do |x|
+      # self is passed into the block for convenience
+      x.assert == nh
+
+      # fetch is an alias to get
+      x.fetch( '.b.c' ).assert == 'abc'
+    end
+```
+
+Outside the block the stack will have been restored
+
+```ruby
+    KeyError.assert.raised? do
+      nh.fetch '.b.c'
+    end
+```
+
+Works with suffix too
+
+```ruby
+    nh.with_suffix 'd' do
+      nh.get('a.b.').assert == 'abd'
+    end
+```
+
+And as it would be combersome to nest a `with_prefix` and a `with_suffix` there is a convenience method
+`with_afixes` at your disposal:
+
+```ruby
+    nh.with_affixes 'a', 'c' do
+      nh.get('.b.').assert == 'abc'
+    end
+```
+
+
+

data/demo/030-lookup-chains.md

@@ -0,0 +1,137 @@
+# Lab42::NHash QED
+
+## Lookup Chains
+
+These are convenience methods using the more general, but also much more comlicated
+fallback mechanism that is demonstrated [here](https://github.com/RobertDober/lab42_nested_hash/blob/master/demo/060-fallback.md)
+
+### Prefix Chains
+
+This defines a mechanism that will use different prefixes until a prefixed key is found.
+
+```ruby
+    nh = NHash.new(
+      en: { '1' => 'one', '2' => 'two', '3' => 'three' },
+      fr: { '2' => 'deux', '3' => 'trois' },
+      it: { '3' => 'tre' })
+      .with_indifferent_access
+```
+
+Now we can simply define a prefix lookup chain as follows:
+
+```ruby
+    nh.push_prefix_lookup :it, :fr, :en
+    nh.with_prefix :de do
+      get( '.1' ).assert == 'one'
+      get( '.2' ).assert == 'deux'
+      get( '.3' ).assert == 'tre'
+      KeyError.assert.raised? do
+        get( '.4' )
+      end
+    end
+```
+
+### Suffix Chains
+
+are not different of course.
+
+```ruby
+    nh = NHash.new(
+      en: {
+        dog: { one: 'dog', many: 'dogs' },
+        cat: { one: 'cat', many: 'cats' },
+        sheep: { one: 'sheep' }
+      },
+      fr: {
+        dog: { one: 'chien', many: 'chiens' },
+        cat: { one: 'chat' }, # for demonstration purpose we ommit "chats"
+        money: { one: 'argent' }
+      } ).with_indifferent_access
+```
+
+Now we define the suffix chain
+
+```ruby
+    nh.push_suffix_lookup :many, :one
+```
+
+proof that this works
+
+```ruby
+    nh.with_prefix :fr do
+      with_suffix :many do
+        get( '.money.').assert == 'argent'
+      end
+    end
+```
+
+However the suffix chain masks the prefix chain, thus we will not find any bovines here:
+
+```ruby
+    nh.with_prefix :fr do
+      with_suffix :many do
+        KeyError.assert.raised? do
+          get( '.sheep.' )
+        end
+      end
+    end
+```
+
+
+### Combining Chains
+
+In order to make both work together we need to implement a backtracking mechanism (or a
+carthesian product fallback definition). This is done via the `push_affix_lookup` method
+
+First we reset both lookup chains, for the time being there is only one method that accomplishes
+this:
+
+```ruby
+    nh.clear_fallbacks!
+    nh.push_affix_lookup prefixes: %w{fr en}, suffixes: %w{many one}
+```
+
+Now our sleep endorsing animals are found again:
+
+```ruby
+    nh.with_prefix :fr do
+      with_suffix :many do
+        get( '.sheep.' ).assert == 'sheep'
+      end
+    end
+```
+
+This searches for an entry by varying the prefixes first, if you want to vary over the suffixes first
+the named parameter `suffixes_first` can be set to true. Let us prove the difference by giving yet
+another demo.
+
+First we do not set `suffixes_first` and
+
+```ruby
+    nh.with_prefix :fr do
+      with_suffix :many do
+        get( '.cat.' ).assert == 'chat'
+      end
+    end
+```
+
+`'chat'` is found (sorry for the grammatical error).
+
+Now if we inverse the lookup order
+
+```ruby
+    nh.clear_fallbacks!
+    nh.push_affix_lookup prefixes: %w{fr en}, suffixes: %w{many one}, suffixes_first: true
+```
+
+and try again, we will get
+
+```ruby
+    nh.with_prefix :fr do
+      with_suffix :many do
+        get( '.cat.' ).assert == 'cats'
+      end
+    end
+```
+
+

data/demo/060-fallback.md

@@ -0,0 +1,89 @@
+
+# Lab42::NHash QED
+
+## Fallbacks
+
+Fallbacks are registred procedures, on a stack, that are executed in LIFO order.
+They are triggered whenever a `get/fetch` invocation would trigger a `KeyError`.
+
+The special `again` method is available inside the fallback procedure (and inside *only*)
+to reexecute the `get/fetch` invocation that triggered the callback (it might trigger the next fallback
+if applicable)
+
+A simple example would be to define a fallback that searches with a different affix.
+
+```ruby
+    numbers = NHash.new( 
+      en: { '1' => 'one', '2' => 'two', '3' => 'three' },
+      fr: { '1' => 'un',  '2' => 'deux' },
+      it: { '1' => 'uno' } )
+      .with_indifferent_access
+```
+
+It stands to reason that looking for an italian '2' will get us a `KeyError` raised.
+
+```ruby
+    KeyError.assert.raised? do
+      numbers.with_prefix :it do
+        get '.2'
+      end
+    end
+```
+
+We will use _fallbacks_ to implement a lookup strategy. By using `push_fallback` 
+we will have to define them in the reverse execution order, we could also use `unshift_fallback` 
+if that suits your style better.
+
+```ruby
+    # use English as last resort...
+    numbers.push_fallback do |n|
+      n.with_prefix :en do 
+        again
+      end
+    end
+    # But try French first
+    numbers.push_fallback do
+      with_prefix( :fr ){ again }
+    end
+```
+
+Please note the two possible styles, a block with arity one ( or negative arity ) will be called
+with the `NHash` instance as a parameter, all other blocks will be instance_execed with the same
+instance as receiver.
+
+These fallbacks will cause the following assertions to hold
+
+```ruby
+    numbers.get( '.1' ).assert == 'un'
+    numbers.with_prefix :it do
+      get( '.1' ).assert == 'uno'
+      get( '.2' ).assert == 'deux'
+      get( '.3' ).assert == 'three'
+    end
+```
+
+### With Pattern
+
+Now if we can limit the validity of a defined fallback stack to a certain scope, we can use
+`with_fallbacks`  so that we do not need to call  `clear_fallbacks!` explicitely.
+
+
+```ruby
+    numbers.clear_fallbacks!
+    KeyError.assert.raised? do
+      numbers.get('.1')
+    end
+
+    numbers.with_fallback do
+      push_fallback do
+        with_prefix( :fr ){ again }
+      end
+      with_prefix :it do
+        get( '.2' ).assert == 'deux'
+      end
+    end
+    KeyError.assert.raised? do
+      numbers.get('.1')
+    end
+```
+

data/demo/080-interpolation.md

@@ -0,0 +1,37 @@
+# Lab42::NHash QED 
+
+## Interpolation
+
+In order to be able to use string interpolation we can use the alternative
+`get!/fetch!` methods which will expand [ERB](http://www.ruby-doc.org/stdlib-2.1.1/libdoc/erb/rdoc/ERB.html) templates inside
+string values.
+
+
+Here is a short demonstration of that feature:
+
+```ruby
+    nh = NHash.new( 
+      sum: '<%= get("a")+get("b") %>',
+      a: 41,
+      b: 1,
+      result: 'the sum is <%= get! :sum %>'
+    )
+      .with_indifferent_access
+```
+
+`get/fetch` do not do anything 
+
+```ruby
+    nh.get(:result).assert == 'the sum is <%= get! :sum %>'
+```
+
+However `get!/fetch!` are made from a completely different kind.
+
+```ruby
+    nh.get!(:sum).assert == '42'
+    nh.fetch!(:result).assert == 'the sum is 42'
+```
+
+
+
+

data/demo/applique/require_ae.rb

@@ -0,0 +1 @@
+require 'ae'

data/demo/applique/require_nhash.rb

@@ -0,0 +1,3 @@
+LIBRARY_PATH = File.expand_path '../../lib'
+
+require 'lab42/nhash/auto_import'

data/lab42_nhash.gemspec

@@ -0,0 +1,38 @@
+
+base = File.dirname __FILE__
+$:.unshift File.join( base, 'lib' )
+
+require 'lab42/nhash/version'
+
+Gem::Specification.new do | spec |
+  spec.name        = 'lab42_nhash'
+  spec.version     = Lab42::NHash::VERSION
+  spec.authors     = ['Robert Dober']
+  spec.email       = %w{ robert.dober@gmail.com }
+  spec.description = %{A Nested Hash with dotted access à la I18n in Rails}
+  spec.summary     = %{A nested hash view with dotted deep access à la I18n.t of Rails and with optional string interpolation.
+Typically YML loaded Hashes are used.}
+  spec.homepage    = %{https://github.com/RobertDober/lab42_nested_hash}
+  spec.license     = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.test_files    = spec.files.grep(%r{\Atest|\Aspec|\Afeatures|\Ademo/})
+  spec.require_paths = %w{lib}
+
+  # spec.post_install_message = %q{ }
+
+
+  spec.required_ruby_version = '>= 2.0.0'
+  spec.required_rubygems_version = '>= 2.2.2'
+
+  spec.add_dependency 'forwarder2', '~> 0.2'
+  spec.add_dependency 'ruby_parser', '~> 3.6'
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'rspec', '~> 2.14'
+  spec.add_development_dependency 'pry', '~> 0.9'
+  spec.add_development_dependency 'pry-debugger', '~> 0.2'
+  spec.add_development_dependency 'ae', '~> 1.8'
+  spec.add_development_dependency 'qed', '~> 2.9'
+  
+end