lab42_ihash 0.0.1.beta

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 340ee6217f0f1fabdcc7d5af631fe6c40982b6e9
+  data.tar.gz: ec83fb030f1ae017e193525fcedae4c8e335606b
+SHA512:
+  metadata.gz: 90f46bf55fb52af4d0d6deda21421d66e2f530c2f27869a8f2348eb48160387f35ce15fb1af1f83e9e529af76258013836367eb98aebf23ac9d711c150fee9fd
+  data.tar.gz: 1f67e0a1699424b0e0e45a21fe740cadb0e0db02e5cc94420c7ca7562cc0ad10ec90417468fe82c678120f66888286a54d441e92805ac021bf5769b09a7b8176

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,49 @@
+PATH
+  remote: .
+  specs:
+    lab42_intellihash (0.0.1)
+      forwarder2 (~> 0.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ae (1.8.2)
+      ansi
+    ansi (1.4.3)
+    brass (1.2.1)
+    coderay (1.1.0)
+    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-nav (0.2.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)
+    slop (3.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ae (~> 1.8)
+  bundler (~> 1.6)
+  lab42_intellihash!
+  pry (~> 0.9)
+  pry-nav (~> 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,35 @@
+# lab42_ihash
+
+A Hash with Business Logic ( call it intelligent ).
+
+Actually it is a view layer over a Hash like object, which needs to obey the simple protocol
+
+`Hash#fetch`.
+
+
+The services `IHash` provides are of the number of four:
+
+* Default values per key.
+* Validation via _Constraints_.
+* Business Logic or Lookup Logic.
+* Caching of Computed Values.
+
+
+## Installation
+
+```sh
+    gem install lab42_ihash --pre
+```
+
+## Usage
+
+```ruby
+    require 'lab42/ihash'
+
+    IHash = Lab42::IHash
+```
+
+
+## Manual (QED Driven)
+
+Details are explained in the [QED](https://github.com/rubyworks/qed) demos [here](https://github.com/RobertDober/lab42_intellihash/tree/master/demo)

data/demo/000-introduction.md

@@ -0,0 +1,109 @@
+# IHash QED
+
+## Introduction
+
+An `IHash` is an object that lets us define an _intelligent_ way to access a Hash like object.
+
+
+The services `IHash` provides are of the number of four:
+
+* Default values per key.
+* Validation via _Constraints_.
+* Business Logic or Lookup Logic.
+* Caching of Computed Values.
+
+## Defaults
+
+
+### Predefined
+
+The simplest meaningful example could look like the following:
+
+```ruby
+    ihash = IHash.new a: 1, b: 2
+
+    ihash.get( :a ).assert == 1
+    ihash.get( :b ).assert == 2
+    ihash.set_values a: 42
+    ihash.get( :a ).assert == 42
+    # Defaults are not changed:
+    ihash.get( :b ).assert == 2
+```
+
+Alternatively the `set_defaults` method can be used:
+
+```ruby
+    ihash.set_defaults a: 1, c: 2
+    # values are not touched
+    ihash.get( :a ).assert == 42
+    # new default values are in place
+    ihash.get( :c ).assert == 2
+    # But the old defaults have been lost
+    KeyError.assert.raised? do
+      ihash.get :b
+    end
+```
+
+### Defaults provided via a parameter
+
+```ruby
+    ihash = IHash.new a: 1
+
+    ihash.get( :a ).assert == 1
+    ihash.get( :a, 42 ).assert == 42
+
+    # However values override the default of course
+    ihash.set_values a: 2
+    ihash.get( :a, 42 ).assert == 2
+    
+```
+
+
+### Computed Defaults
+
+They are the main reason for caching, but as defaults provided
+via parameters override cached values, we will need an alternative
+calculation mechanisme for business logic, which we will discuss
+later on.
+
+For know all we need to know to understand the following example
+is that `Proc` instances as default values will be evaluated
+in the `IHash` instance's context.
+
+```ruby
+    rectangle = IHash.new \
+      height: ->{ get( :surface ) / get( :width ) },
+      width: ->{ get( :surface ) / get( :height ) },
+      surface: ->{ get( :width ) * get( :height ) }
+
+    # Obviously we need some data here. The following code
+    # will consume the whole stack before crashing.
+    # Later on we will see how to avoid this by means
+    # of defaults and constraints, and hopefully a later version
+    # of IHash will detect the mutual infinite recursion.
+
+    #   rectangle.get :surface
+
+    # So let us provide some data
+    rectangle.set_values width: 20, height: 30
+    rectangle.get( :surface ).assert == 600
+```
+
+Now it would be nice if we could avoid the potential stack overflow
+by means of defaults.
+And, as promised, we can:
+
+```ruby
+    
+    rectangle = IHash.new \
+      height: ->{ get( :surface, 600 ) / get( :width, 20 ) },
+      width: ->{ get( :surface, 600 ) / get( :height ) },
+      surface: ->{ get( :width ) * get( :height ) }
+
+    # These defaults shall be sufficent
+    rectangle.get( :surface ).assert == 600
+    # and they are.
+
+```
+
+To see how to do this with constraints, please refer to the [constraints demo](https://github.com/RobertDober/lab42_intellihash/blob/master/demo/050-constraints.md)

data/demo/050-constraints.md

@@ -0,0 +1,70 @@
+# IHash QED
+
+## Constraints
+
+Constraints are evaluated whenever the values of an `IHash` instance are set via the `set_values` method.
+
+The result of this evaluation is stored for later validation. 
+
+Let us dive into a simple example:
+
+```ruby
+    ihash = IHash.new
+      .set_constraints( 
+        a: ->(eventual_value_for_a){ eventual_value_for_a == 42 } )
+      .set_values a: 43
+
+    ihash.valid?.assert == false
+    ihash.errors.empty?.assert == false
+    ihash.errors.first.assert =~ /value error for key :a and value 43/
+
+    ihash.set_values a: 42
+    ihash.valid?.assert == true
+    ihash.errors.empty?.assert == true
+    
+```
+
+In order to implement an early failure policy you need to raise exceptions yourself.
+
+```ruby
+    ArgumentError.assert.raised? do
+      ihash =
+        IHash.new
+          .set_constraints\
+            a: ->(value){ value == 42 or raise ArgumentError }
+
+      ihash.set_values a: 41
+    end
+```
+
+Maybe a `set_constraints!` method doing something like that for you can be
+implemented later on.
+
+Oh and I am so glad you asked, before setting values, constraints are not enforced and
+the instance is therefore valid in all cases:
+
+```ruby
+    ihash = IHash.new( a: nil ).set_constraints a: ->{ raise ArgumentError }
+
+    ihash.valid?.assert == true
+
+    ArgumentError.assert.raised? do
+      ihash.set_values b: nil
+    end
+    ihash.valid?.assert == false
+    ihash.errors.first.assert == 'constraint for key :a raised an error ArgumentError'
+```
+
+And this works for calculated values too, of course:
+
+```ruby
+    ihash = IHash
+      .new( a: ->{ - get( :b ) } )
+      .set_constraints( a: ->(val){ val > 0 } )
+      .set_values b: 42
+
+    ihash.valid?.assert == false
+    
+```
+
+

data/demo/080-business-logic.md

@@ -0,0 +1,12 @@
+# IHash QED
+
+## Business Logic
+
+_Not implemented_
+
+For the time being the defaults semantics serve all YHS' needs. But he believes
+that more complex computations, recursion detection, a seperate cache that
+would override default parameters and other subtle differences might come forth
+one day.
+
+

data/demo/100-caching.md

@@ -0,0 +1,77 @@
+# IHash QED
+
+## Caching
+
+Will only occur when lookup values or default values are accessed.
+
+Actually `#cache` is exposed as an attribute, but manipulate it not (or at your
+own risk).
+
+```ruby
+    ihash = IHash.new \
+      a: ->{ 42 }, 
+      b: 42
+
+    # The cache is empty
+    ihash.cache.assert.empty?
+
+    # Let us access :b
+    ihash.get :b
+    # The cache is not empty any more
+    ihash.cache.refute.empty?
+    # It has been filled with :b only
+    ihash.cache.assert.has_key? :b
+    ihash.cache.refute.has_key? :a
+    # And now we add :a
+    ihash.get :a
+    ihash.cache.assert.has_key? :b
+    ihash.cache.assert.has_key? :a
+    
+```
+
+### Setting values invalidates the cache
+
+```ruby
+    ihash.set_values b: 56
+
+    # Cache is empty again
+    ihash.cache.assert.empty?
+    # Values come before the cache, but don't do that
+    ihash.cache[ :b ] = 22
+    ihash.get( :b ).assert == 56
+    # We did not even break anything
+    ihash.get( :a ).assert == 42
+    ihash.cache.assert.has_key? :a
+
+```
+
+### Value access does not populate the cache
+
+```ruby
+    ihash.set_values b: 29
+
+    ihash.cache.assert.empty?
+    ihash.get( :b ).assert == 29
+    ihash.cache.assert.empty?
+```
+
+
+### Setting defaults invalidates the cache too
+
+```ruby
+    ihash.get :a
+    ihash.cache.keys.assert == [:a]
+    ihash.set_defaults
+    # The following is not very wise, maybe setting values, defaults
+    # or constraints will reset the instance.
+    # Not sure: ihash.get( :b ).assert == 29
+    ihash.cache.assert.empty?
+
+```
+
+
+This behavior might change with minor version updates as it is not very
+intuitive.
+
+Now that we are aware how caching and default values work let us go further with constraints
+

data/demo/applique/require_ae.rb

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

data/demo/applique/require_ihash.rb

@@ -0,0 +1,4 @@
+LIBRARY_PATH = File.expand_path '../../lib'
+
+require 'lab42/ihash'
+IHash = Lab42::IHash

data/lab42_ihash.gemspec

@@ -0,0 +1,37 @@
+
+base = File.dirname __FILE__
+$:.unshift File.join( base, 'lib' )
+
+require 'lab42/ihash/version'
+
+Gem::Specification.new do | spec |
+  spec.name        = 'lab42_ihash'
+  spec.version     = Lab42::IHash::VERSION
+  spec.authors     = ['Robert Dober']
+  spec.email       = %w{ robert.dober@gmail.com }
+  spec.description = %{A Hash with Business Logic (call it intelligent).}
+  spec.summary     = %{A view over Hash like objects (needs to implement #fetch only).
+Allowing to specify defaults, constraints and business logic. Implements caching for computed values.}
+  spec.homepage    = %{https://github.com/RobertDober/lab42_ihash}
+  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_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'rspec', '~> 2.14'
+  spec.add_development_dependency 'pry', '~> 0.9'
+  spec.add_development_dependency 'pry-nav', '~> 0.2'
+  spec.add_development_dependency 'ae', '~> 1.8'
+  spec.add_development_dependency 'qed', '~> 2.9'
+  
+end

data/lib/lab42/ihash/version.rb

@@ -0,0 +1,5 @@
+module Lab42
+  class IHash
+    VERSION = '0.0.1.beta'
+  end # class IHash
+end # module Lab42

data/lib/lab42/ihash.rb

@@ -0,0 +1,89 @@
+module Lab42
+  class IHash
+    attr_reader :cache, :constraints, :defaults, :errors, :values
+
+    def get key, *default
+      values.fetch key do 
+        lookup( key, *default )
+      end
+    end
+
+    def set_constraints(**constraints)
+      @constraints << constraints
+      self
+    end
+
+    def set_defaults(**defaults)
+      invalidate_cache_and_errors
+      @defaults = defaults
+      self
+    end
+
+    def set_values a_hashy={}
+      invalidate_cache_and_errors
+      
+      @values = a_hashy.dup rescue a_hashy
+      validate_constraints
+      self
+    end
+
+    def valid?; errors.empty? end
+
+    private
+    def evaluate val_or_proc
+      return evaluate_proc val_or_proc if Proc===val_or_proc
+      val_or_proc
+    end
+
+    def evaluate_proc a_proc
+      a_proc.arity == 1 ? instance_eval( &a_proc ) : instance_exec( &a_proc )
+    end
+
+    def initialize(**defaults)
+      set_defaults(**defaults)
+
+      @cache       = {}
+      @values      = {}
+
+      @constraints = []
+      @errors      = []
+    end
+
+    def invalidate_cache_and_errors
+      @cache  = {}
+      @errors = []
+    end
+
+    # Precondition: key not in values and key not in cache
+    # This explains the default value provided priority, we reason:
+    # An explicit default value in a get shall override the predefined defaults
+    # **But** that means that later caching will change the behavior of get not
+    # my preferred programming style. This might change in the future. (E.g.
+    # default comes before cache lookup).
+    def lookup key, *default
+      return default.first unless default.empty?
+      cache.fetch key do
+        raise KeyError, "#{key} not found in values, defaults or logic" unless defaults.has_key? key
+        cache[ key ] = evaluate( defaults[key] )
+      end
+    end
+
+    def validate_constraints
+      constraints.each do | constraint |
+        constraint.each do | k, c |
+          v = get k
+          if c.arity == 1
+            c.(v) || errors << "value error for key #{k.inspect} and value #{v.inspect}"
+          else
+            begin
+              instance_exec(&c) || errors << "value error for key #{k.inspect} and value #{v.inspect}"
+            rescue StandardError => e
+              errors << "constraint for key #{k.inspect} raised an error #{e}"
+              raise
+            end
+          end
+        end
+      end
+    end
+  end # class IHash
+end # module Lab42

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: lab42_ihash
+version: !ruby/object:Gem::Version
+  version: 0.0.1.beta
+platform: ruby
+authors:
+- Robert Dober
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: pry-nav
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: ae
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: qed
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.9'
+description: A Hash with Business Logic (call it intelligent).
+email:
+- robert.dober@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- demo/000-introduction.md
+- demo/050-constraints.md
+- demo/080-business-logic.md
+- demo/100-caching.md
+- demo/applique/require_ae.rb
+- demo/applique/require_ihash.rb
+- lab42_ihash.gemspec
+- lib/lab42/ihash.rb
+- lib/lab42/ihash/version.rb
+homepage: https://github.com/RobertDober/lab42_ihash
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 2.2.2
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: 'A view over Hash like objects (needs to implement #fetch only). Allowing
+  to specify defaults, constraints and business logic. Implements caching for computed
+  values.'
+test_files:
+- demo/000-introduction.md
+- demo/050-constraints.md
+- demo/080-business-logic.md
+- demo/100-caching.md
+- demo/applique/require_ae.rb
+- demo/applique/require_ihash.rb