lab42_nhash 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 083d1e07c143e83a9743bc203ab0386c0ca3d13d
-  data.tar.gz: 0c1017bc1a32a9ed99c26d2e83047e76b3a1dd11
+  metadata.gz: dfa964b499cd8f9c9fb458f0082eacf0f990cfac
+  data.tar.gz: f5c06457ecdd6652fd05a33e768791192993a37d
 SHA512:
-  metadata.gz: 01108baa232347e7688bdc2c163f3e7c1e9870bd3156f5e8ead4497b594ba5803b1995c35d2e64847619c9a73578f5d6f414ca1ff478216cd85670077b6ae96c
-  data.tar.gz: acb2707844115bc986d0682a4aad72a181c8a2ffd001d0e84bf0797f9bbb6956c4def3bd8cd209b14c750adc616947f2deeb940f685beeaf66a2192f5a8f09af
+  metadata.gz: aacab0eb78da5bbeb5b945624e0c2fa058634ba87731dee6803cae4caf27c9e9d21f8910b18a75579528a167d556417b1caeb25bdcea512ca31fd3e614d3f779
+  data.tar.gz: 7aa8904790917d875576b024692427ea49fe3b252096aca527b3c25f101d8afb7a035822262f9a41533cc6d4c402ef68eeefa9afecd893d92f3a86f8c9e8d52d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lab42_nhash (0.1.0)
+    lab42_nhash (0.1.1)
       forwarder2 (~> 0.2)
       ruby_parser (~> 3.6)
 

data/README.md

@@ -2,10 +2,18 @@
 
 A nested hash view with dotted deep access à la I18n.t of Rails and with optional string interpolation. Typically YML loaded Hashes are used.
 
+## What is it good for?
 
-## Get Access (combined keys with dot notation)
+I developped `NHash` to scratch an itch that developped when creating presentations of hierarchical data with different aspects. E.g. different languages
+and different versions.
+
+For that I wanted to combine the _data_ and define strategies what to do when compound keys were not found. Typically _data_ will be quite a big `Hash`
+instance coming from _Yaml_ files, a _Json_ webservice, or a document oriented database like _MongoDB_.
+
+But let us start slowly:
+
+## Most Basic Example
 
-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,
@@ -29,8 +37,48 @@ or _subhashes_:
 ```
 
 
+Please see the [QED](http://rubyworks.github.io/qed/) demos [here](https://github.com/RobertDober/lab42_nested_hash/blob/master/demo) for detailed explainations and specifications of the implemented features:
+
+
 ### Indifferent Access
 
-### Prefix and Suffix Stacks
+Symbol and String Keys are treated the same.
+
+### Affixes
+
+Prefixes and Suffixes can be predefined and used when a compound key starts and/or ends with a `.`.
+
+### Lookup Chains
+
+Taking advantage of the Affixes features an affixed access can look in more than one affix. E.g. to fall back
+to English as the default translation language.
+
+### Fallbacks
+
+A more general concept of what to do if an access fails (raises a `KeyError`).
+
+### Interpolation
+
+If values have `ERB` syntax templates as values, the special `get!` access can be used to interpolate them
+in various contexts, the `NHash` instance's binding being the default.
+
+### Compound Values
+
+Subhashes and subarrays maintain important context information, e.g. for _Interpolation_.
+
+### Hierarchies
+
+If all else fails... 
+We can check in other `NHash` instances. They are organised as a _Depth First Search Tree_.
+
+This feature is particularly interesting for complex document composition out of a hierarchical data
+source tree (e.g. a set of yaml files, different for each new version/variation of the result).
+
+### Factories
+
+The `NHash` constructor takes a `Hash` instance (defaulting to `{}` ) as param. This implies that
+much boiler blate code has to be written in order to bring in other data sources, as e.g. Yaml files.
+
+The factories help to avoid this.
 
-## Fallbacks
+There are even helpers to create an `NHash` hierarchy from data sources.

data/demo/100-hierarchies.md

@@ -20,7 +20,7 @@ Here is an example:
     root.add_hierarchies one, two, three
 ```
 
-This constructed a tree like the following (denoting `:never_found` with a `*`)
+This constructed a tree like the following (denoting `:never_found` by a `*`)
 
 
 ```
@@ -125,4 +125,5 @@ from its root, e.g. affix chains or fallbacks.
   end
 ```
 
+
 ### Interpolation Context

data/demo/120-factories.md

@@ -0,0 +1,70 @@
+# Lab42::NHash QED
+
+## Factories
+
+The purpose of factories is to bring in common data sources to create a, potentially hierarchic, `NHash` instance.
+
+Let us see what the generic factory method `from_sources` does with `Hash` or `NHash` instances first.
+
+### Creating Hierarchies from Hash alikes
+
+```ruby
+  nh = NHash.new( 'a' => 1, b: 1 )
+  h  = { 'a' => 2, 'b' => 2 }
+
+  hier = NHash.from_sources nh, h
+    
+```
+
+The hierarchy's root node is on the left, and all hierarchies created by `from_sources` are lists, not trees.
+
+Demonstration:
+
+```ruby
+    hier.get( 'a' ).assert == 1
+    hier.get( 'b' ).assert == 2
+```
+
+
+Maybe you noticed that symbolic keys were not found. That is beacause, this time, we did not specify `with_indifferent_access` 
+
+This can be done too, of course (note again that all keys are transformed to strings as usual:
+
+```ruby
+    hier = NHash.from_sources_with_indifferent_access nh, h
+    hier.get( :a ).assert == 1
+    hier.get( :b ).assert == 1
+```
+
+
+### Creating Hierarchies from YAML Files
+
+The same works if the data is inside a Yaml file
+
+```ruby
+    given_a_file named: "one.yml", with: <<-EOF
+      a: 1
+    EOF
+    and_given_a_file named: "two.yml", with: <<-EOF
+      a: 2
+      b: 2
+    EOF
+```
+
+Now if we invoke `from_sources` with strings, denoting these files, these strings will be replaced by an `NHash` instance
+initialized with the `Hash` resulting from YAML loading the content of the file
+Now if we invoke icodefrom_sourceswith strings, denoting these files, these strings will be replaced by an icodeNHashinstance
+initialized with the icodeHashresulting from YAML loading the content of the file
+
+Or in short ;) :
+
+```ruby
+    yaml_hierarchy = NHash.from_sources 'one.yml', 'two.yml'
+
+    yaml_hierarchy.get( :a ).assert == 1
+    yaml_hierarchy.get( :b ).assert == 2
+    KeyError.assert.raised? do
+      yaml_hierarchy.get :c
+    end
+```
+

data/demo/applique/file_mockers.rb

@@ -0,0 +1,26 @@
+
+def given_a_file named: required, with: required
+  @files         ||= {}
+  stub_file unless @orig_readable
+  @files.update named => with
+end
+alias_method :and_given_a_file, :given_a_file
+
+def erase_all_files
+  @files = {}
+  # Is it necessary to remove methods first?
+  File.define_singleton_method :readable?, &@orig_readable
+  File.define_singleton_method :read, &@orig_read
+end
+
+def stub_file
+  @orig_readable = File.method :readable?
+  @orig_read     = File.method :read
+  files = @files
+  File.define_singleton_method :readable? do | fn |
+    !!files[ fn ]
+  end
+  File.define_singleton_method :read do | fn |
+    files[ fn ]
+  end
+end

data/lib/lab42/nhash/class_methods.rb

@@ -1,18 +1,56 @@
 require_relative 'enum'
+
+require 'yaml'
+
 module Lab42
   class NHash
     module ClassMethods
 
+      def from_sources *sources
+        __from_sources__(sources)
+      end
+      
+      def from_sources_with_indifferent_access *sources
+        __from_sources__(sources, indifferent_access: true )
+      end
+
       def from_value value, options={}
         case value
         when Hash
-          Lab42::NHash.new( value ).import_options options
+          new( value ).import_options options
         when Enumerable
           Lab42::NHash::Enum.new value, options
         else
           value
         end
       end
+
+      private
+      def __from_sources__ sources, indifferent_access: false
+        sources = sources.map{ |source|
+          make_nhash_from source, indifferent_access: indifferent_access
+        }
+        result = sources.shift
+        sources.inject result do | r, s |
+          r.add_hierarchy s
+          s
+        end
+        result
+      end
+
+      def make_nhash_from source, indifferent_access: false
+        case source
+        when Hash
+          new source, indifferent_access: indifferent_access
+        when self
+          indifferent_access ? source.dup.with_indifferent_access : source.dup
+        when String
+          raise ArgumentError, "#{source.inspect} needs to designate a readable yaml file" unless File.readable? source
+          new YAML.load( File.read source ), indifferent_access: indifferent_access
+        else
+          raise ArgumentError, "type of value #{source.inspect} is not implemented (yet)"
+        end
+      end
     end # module ClassMethods
     extend ClassMethods
   end # class NHash

data/lib/lab42/nhash/hierarchies.rb

@@ -14,7 +14,7 @@ module Lab42
         self
       end
 
-      def get_form_hierarchies keyexpr, keyexc
+      def get_from_hierarchies keyexpr, keyexc
         @hierarchies.each do | h |
           begin
             return h.get keyexpr

data/lib/lab42/nhash/version.rb

@@ -1,5 +1,5 @@
 module Lab42
   class NHash
-    VERSION = '0.1.0'
+    VERSION = '0.1.1'
   end # class NHash
 end # module Lab42

data/lib/lab42/nhash.rb

@@ -18,7 +18,7 @@ module Lab42
     forward :pop_binding, to: :@binding_stack, as: :pop
     forward :push_binding, to: :@binding_stack, as: :push
 
-    attr_reader :hashy, :parent
+    attr_reader :hashy, :hierarchies, :parent
 
     def export_options
       { indifferent_access: @indifferent_access,
@@ -41,7 +41,7 @@ module Lab42
     def fallback_or_hierarchy keyexpr, keyexc
       fallback keyexpr, keyexc
     rescue KeyError => k
-      get_form_hierarchies keyexpr, k
+      get_from_hierarchies keyexpr, k
     end
 
     def import_options options
@@ -57,7 +57,22 @@ module Lab42
       end
     end
 
+
+    def with_indifferent_access! cache={}
+      __recursive_indifferent_access__ self, {}
+    end
     private
+
+    def __recursive_indifferent_access__ for_nhash, cache
+      return if cache[ for_nhash.object_id ]
+
+      for_nhash.with_indifferent_access
+      cache.update for_nhash.object_id => true
+
+      for_nhash.hierarchies.each do | hier |
+        __recursive_indifferent_access__ hier, cache
+      end
+    end
     def complete_keys keys, use_prefix: false, use_suffix: false
       keys =  current_prefix + keys if use_prefix
       keys += current_suffix if use_suffix
@@ -79,18 +94,18 @@ module Lab42
       end
     end
 
-    def initialize hashy={}
+    def initialize hashy={}, options={}
       @hashy  = hashy
-      init_options
+      init_options options
     end
 
-    def init_options
+    def init_options options
       @parent = self
 
-      @indifferent_access       = false
-      @suffix_stack             = []
-      @prefix_stack             = []
-      @binding_stack            = []
+      @indifferent_access       = options.fetch(:indifferent_access, false)
+      @suffix_stack             = options.fetch(:suffix_stack, [])
+      @prefix_stack             = options.fetch(:prefix_stack, [])
+      @binding_stack            = options.fetch(:binding_stack, [])
 
       @fallbacks                = []
       @current_fallback_pointer = 0

data/spec/support/file_mocks.rb

@@ -0,0 +1,15 @@
+
+module FileMocks
+
+  def given_a_file named: required, with: required
+    before do
+      expect( File ).to receive( :readable? ).with( named ).and_return( true ).ordered
+      expect( File ).to receive( :read ).with( named ).and_return( with ).ordered
+    end 
+  end
+  
+end # module FileMocks
+
+RSpec.configure do | c |
+  c.extend FileMocks
+end

data/spec/unit/factories/from_sources_using_hashes_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+describe NHash do 
+  context :factories do 
+    context :with_hashes do
+      let(:h){{ 'a' => 1, 'c' => 1 }}
+      let(:nh){described_class.new( 'a' => 2, 'b' => 2 )}
+      subject do
+        described_class.from_sources( h, nh )
+      end
+
+      it 'is a NHash instance' do
+        expect( subject ).to be_kind_of described_class
+      end
+
+      it 'finds elements in root' do
+        expect( subject.get( 'a' )  ).to eq 1
+      end
+
+      it 'finds element at 2nd level now' do
+        expect( subject.get( 'b' ) ).to eq 2
+      end
+
+      context 'longer chains' do 
+        let(:first){ described_class.new( 'a' => 0) }
+        let(:root){
+          described_class.from_sources first, h, nh
+        }
+
+        it 'finds a at root level' do
+          expect( root.get 'a' ).to eq 0
+        end
+
+        it 'finds c at second level' do
+          expect( root.get 'c' ).to eq 1
+        end
+
+        it 'finds b at last level' do
+          expect( root.get 'b' ).to eq 2
+        end
+
+        it 'does not find d at all' do
+          expect( ->{root.get 'd'} ).to raise_error KeyError
+        end
+        
+      end # context 'longer chains'
+    end # context :with_hashes
+
+  end # context :factories
+end # describe NHash

data/spec/unit/factories/from_sources_using_yaml_files_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+describe NHash do 
+  context :factories do 
+    context  'from yaml files' do
+      
+      given_a_file named: 'one.yml', with: <<-EOF
+        a: 1
+      EOF
+      given_a_file named: 'two.yml', with: <<-EOF
+        a: 2
+        b: 2
+      EOF
+      subject do
+        described_class.from_sources 'one.yml', 'two.yml'
+      end
+
+      it "finds a's value in the first file" do
+        expect( subject.get :a ).to eq 1
+      end
+
+      it "finds b's value in the first file" do
+        expect( subject.get :b ).to eq 2
+      end
+
+      it "does not find c's value anywhere" do
+        expect( ->{ subject.get :c } ).to raise_error KeyError
+      end
+    end # context  'from yaml files'
+  end # context :factories
+end # describe NHash

data/spec/unit/factories/inidfferent_access_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+describe NHash do 
+  
+  context :factories do
+    context 'without indifferent access' do 
+      subject do
+        described_class.from_sources( {a: 1}, {'a' => 2, b: 2} )
+      end
+      it 'finds only the stringy "a"' do
+        expect( subject.get( :a ) ).to eq 2
+      end
+      it 'and string "b" is not found at all' do
+        expect( ->{ subject.get :b } ).to raise_error KeyError
+      end
+    end # context :indifferent_access
+
+    context 'however, with indifferent access' do 
+      subject do
+        described_class.from_sources_with_indifferent_access( {a: 1}, {'a' => 2, b: 2} )
+      end
+      it 'finds also the symbol :a' do
+        expect( subject.get( :a ) ).to eq 1
+      end
+      it 'as well as the symbol :b' do
+        expect( subject.get( :b ) ).to eq 2
+      end
+      
+    end # context 'however, with indifferent access'
+  end # context :factories
+
+end # describe NHash

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lab42_nhash
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Robert Dober
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-23 00:00:00.000000000 Z
+date: 2014-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: forwarder2
@@ -143,6 +143,8 @@ files:
 - demo/080-interpolation.md
 - demo/090-compound-values.md
 - demo/100-hierarchies.md
+- demo/120-factories.md
+- demo/applique/file_mockers.rb
 - demo/applique/require_ae.rb
 - demo/applique/require_nhash.rb
 - lab42_nhash.gemspec
@@ -161,11 +163,15 @@ files:
 - spec/integration/hierarchie_and_lookup_spec.rb
 - spec/regression_spec.rb
 - spec/spec_helper.rb
+- spec/support/file_mocks.rb
 - spec/unit/afixes/affix_spec.rb
 - spec/unit/afixes/prefix_spec.rb
 - spec/unit/afixes/suffix_spec.rb
 - spec/unit/compound/enum_spec.rb
 - spec/unit/compound/nhash_spec.rb
+- spec/unit/factories/from_sources_using_hashes_spec.rb
+- spec/unit/factories/from_sources_using_yaml_files_spec.rb
+- spec/unit/factories/inidfferent_access_spec.rb
 - spec/unit/fallback/fallback_spec.rb
 - spec/unit/hierarchies/base_spec.rb
 - spec/unit/hierarchies/tree_form_spec.rb
@@ -206,16 +212,22 @@ test_files:
 - demo/080-interpolation.md
 - demo/090-compound-values.md
 - demo/100-hierarchies.md
+- demo/120-factories.md
+- demo/applique/file_mockers.rb
 - demo/applique/require_ae.rb
 - demo/applique/require_nhash.rb
 - spec/integration/hierarchie_and_lookup_spec.rb
 - spec/regression_spec.rb
 - spec/spec_helper.rb
+- spec/support/file_mocks.rb
 - spec/unit/afixes/affix_spec.rb
 - spec/unit/afixes/prefix_spec.rb
 - spec/unit/afixes/suffix_spec.rb
 - spec/unit/compound/enum_spec.rb
 - spec/unit/compound/nhash_spec.rb
+- spec/unit/factories/from_sources_using_hashes_spec.rb
+- spec/unit/factories/from_sources_using_yaml_files_spec.rb
+- spec/unit/factories/inidfferent_access_spec.rb
 - spec/unit/fallback/fallback_spec.rb
 - spec/unit/hierarchies/base_spec.rb
 - spec/unit/hierarchies/tree_form_spec.rb