inherited-hash 1.0.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in inherited-hash.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (C) 2011 by Ryan Biesemeyer (@yaauie)
+
+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.mdown

@@ -0,0 +1,108 @@
+InheritedHash
+=============
+
+This module lets you specify a hash that is inherited by subclasses and
+instances of any class that it extends.
+
+It's best explained by example:
+
+```ruby
+class Robot
+  extend InheritedHash
+  inherited_hash_accessor :sensor_settings
+
+  sensor_settings= {
+    :temperature  => :kelvin,
+    :distance     => :metric,
+    :pressure     => :atmosphere
+  }
+  # ...
+end
+
+class EuropeanRobot < Robot
+  sensor_settings[:temperature] = :centigrade
+  # ...
+end
+
+class AmericanRobot < Robot
+  sensor_settings = {
+    :tempertaure  => :fahrenheight,
+    :distance     => :imperial
+  }
+  # ...
+end
+
+confused_robot = AmericanRobot.new
+confused_robot.sensor_settings[:distance] = :wednesday
+
+# get the hash for this instance.
+puts confused_robot.sensor_settings
+# => {:distance => :wednesday}
+
+# get the hash built using inheritance.
+# note how the result in our example contains 
+# elements from each layer of inheritance
+puts confused_robot.sensor_settings!
+# => {:distance => :wednesday, :temperature => :fahrenheight, :pressure => :atmosphere}
+
+```
+
+Inheritance
+-----------
+
+Each element in the inheritance chain stores its own `ConnectedHash`,
+accessible directly by calling the name you gave it.
+
+It can also build a composite `Hash` accounting for inheritance with the bang-
+variant (`foo!` for a hash named `foo`) method, which is built by merging its
+own hash with the hash it inherits, following the inheritance chain.
+
+The composite `Hash` is generated every time you request it, so destructive
+methods like `delete` may not work as intended; they will be destructive to
+your current generated object, but will not affect the source or composite
+hashes generated subsequently.
+
+Finding a Definition
+--------------------
+
+Inspection is simple: Call `find_definition_of(key)` on the `ConnectedHash` to
+find the object (instance, class, or module) whose `ConnectedHash` of the same
+name defines the value that is inherited in the composite.
+
+From our example above:
+
+```ruby
+puts confused_robot.sensor_settings.find_definition_of(:distance)
+#=> #<AmericanRobot:0x10e6fdb78 @sensor_settings={:distance=>:wednesday}>
+
+puts confused_robot.sensor_settings.find_definition_of(:tempertaure)
+#=> AmericanRobot
+
+puts confused_robot.sensor_settings.find_definition_of(:humidity).inspect
+#=> nil
+```
+
+Global Availability
+-------------------
+
+To include this module into *all* Modules and Classes, simply: 
+
+```ruby
+require 'inherited-hash/global'
+```
+
+Contributing
+============
+
+* Check out the latest code to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the [issue tracker](https://github.com/yaauie/inherited-hash/issues) and [pull requests](https://github.com/yaauie/inherited-hash/pulls) to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+License
+=======
+
+This project is Copyright (c) 2011 by Ryan Biesemeyer and released under an [MIT-style license](https://github.com/yaauie/inherited-hash/blob/master/LICENSE.txt).

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end

data/inherited-hash.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "inherited-hash/version"
+
+Gem::Specification.new do |s|
+  s.name        = "inherited-hash"
+  s.version     = InheritedHash::VERSION
+  s.authors     = ["Ryan Biesemeyer"]
+  s.email       = ["ryan@yaauie.com"]
+  s.homepage    = "https://github.com/yaauie/inherited-hash"
+  s.summary     = %q{class inheritance with hashes}
+  s.description = %q{a module that allows you to specify hashes that are merged along the inheritance chain}
+
+  s.rubyforge_project = "inherited-hash"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rake'
+end

data/lib/inherited-hash.rb

@@ -0,0 +1,61 @@
+require "inherited-hash/version"
+
+module InheritedHash
+  def inherited_hash_accessor *names
+    names.each do |name|
+      [self,class<<self;self;end].each do |context|
+        context.send(%Q{instance_eval}.to_s) do
+          define_method(name) do
+            storage = %Q{@#{name}}.to_sym
+            unless instance_variable_defined?( storage )
+              instance_variable_set(storage, InheritedHash::ConnectedHash.new.connect(self,name))
+            end
+            instance_variable_get( storage)
+          end
+          define_method(%Q{#{name}!}.to_sym) do
+            send(name).to_hash!
+          end
+          define_method(%Q{#{name}=}.to_sym) do |hsh|
+            raise ArgumentError, 'Only hashes are allowed' unless hsh.is_a? Hash
+            send(name).replace(hsh)
+          end
+        end
+      end
+    end
+  end
+
+  class ConnectedHash < Hash
+    def connect(anchor,name)
+      @anchor, @name = anchor, name
+      self
+    end
+
+    def verify!
+      raise Exception, "#{self.inspect} must be connected!" unless @anchor and @name
+    end
+
+    def to_hash!
+      verify!
+      return @anchor.class.send(%Q{#{@name}!}.to_sym).merge(self.to_hash) unless @anchor.is_a? Module
+      hash = Hash.new
+      @anchor.ancestors.reverse.each do |ancestor|
+        hash.merge!(ancestor.send(@name).to_hash) if ancestor.respond_to?(@name)
+      end
+      hash
+    end
+
+    def to_hash
+      Hash.new(&default_proc).replace(super)
+    end
+
+    def find_definition_of(key)
+      verify!
+      return @anchor if has_key? key
+      return @anchor.class.send(@name).find_definition_of(key) unless @anchor.is_a? Module
+      @anchor.ancestors.reverse.index do |ancestor|
+        next false unless ancestor.respond_to?(@name)
+        return ancestor if ancestor.send(@name).has_key?(key)
+      end
+    end
+  end
+end

data/lib/inherited-hash/global.rb

@@ -0,0 +1,5 @@
+require File.expand_path(File.join(File.dirname(__FILE__),'..','inherited-hash.rb'))
+
+class Module
+  include InheritedHash
+end

data/lib/inherited-hash/version.rb

@@ -0,0 +1,3 @@
+module InheritedHash
+  VERSION = "1.0.0"
+end

data/spec/inherited-hash_spec.rb

@@ -0,0 +1,106 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe 'InheritedHash' do
+  describe '#inherited_hash_accessor' do
+    subject do
+      Class.new do
+        extend InheritedHash
+        inherited_hash_accessor :foo
+      end
+    end
+
+    it 'should create accessor methods in instances' do
+      subject.new.should respond_to :foo
+      subject.new.should respond_to :foo!
+    end
+
+    it 'should create accessor methods in the class' do
+      subject.should respond_to :foo
+      subject.should respond_to :foo!
+    end
+  end
+  context 'an inherited stack' do
+    before :each do
+      @s = Hash.new
+      @s[:root] = Class.new do
+        extend InheritedHash
+        inherited_hash_accessor :foo,:bar
+
+        self.foo={
+          :not_overridden => "don't override me",
+          :existing_key => 'unchanged'
+        }
+      end
+      @s[:leaf1] = Class.new(@s[:root]) do
+        foo[:new_key] = 'brand new'
+        foo[:existing_key] = 'changed'
+      end
+      @s[:leaf2] = Class.new(@s[:root]) do
+      end
+      @s[:leaf2_shoot1] = Class.new(@s[:leaf2]) do
+        foo[:existing_key] = 'changed!'
+      end
+
+      @s
+    end
+
+    context 'in root class' do
+      subject {@s[:root]}
+
+      it 'should be directly accessible' do
+        subject.foo[:existing_key].should == 'unchanged'
+        subject.foo[:not_overridden].should == "don't override me"
+      end
+
+      it 'should not be overridden' do
+        subject.foo[:new_key].should be_nil
+      end
+    end
+
+    context 'in extended class' do
+      subject {@s[:leaf1]}
+
+      it 'should be directly accessible' do
+        subject.foo[:new_key].should == 'brand new'
+        subject.foo[:existing_key].should == 'changed'
+        subject.foo[:not_overridden].should be_nil
+      end
+      it 'should be able to access inheritance' do
+        subject.foo![:new_key].should == 'brand new'
+        subject.foo![:existing_key].should == 'changed'
+        subject.foo![:not_overridden].should == "don't override me"
+      end
+
+      context 'instance' do
+        subject do
+          s = @s[:leaf1].new
+          s.foo = {:another_new_key => 'ooh, shiny'}
+          s
+        end
+        it 'should have access to instance-set key' do
+          subject.foo![:another_new_key].should == 'ooh, shiny'
+        end
+        it 'should have access to keys inherited from class' do
+          subject.foo![:existing_key].should == 'changed'
+        end
+        it 'should have access to keys inherited from root' do
+          subject.foo![:not_overridden].should == "don't override me"
+        end
+        it 'should be able to find the definition in the object' do
+          subject.foo.find_definition_of(:another_new_key).should be subject
+        end
+        it 'should be able to find the definition in the class' do
+          subject.foo.find_definition_of(:new_key).should be subject.class
+          subject.foo.find_definition_of(:existing_key).should be subject.class
+        end
+        it 'should be able to find the definition in the root' do
+          subject.foo.find_definition_of(:not_overridden).should be @s[:root]
+        end
+        it 'should not be able to find a definition that does not exist' do
+          subject.foo.find_definition_of(:not_exist).should be_nil
+        end
+      end
+    end
+
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'inherited-hash/global'

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification 
+name: inherited-hash
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Ryan Biesemeyer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-11-02 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: a module that allows you to specify hashes that are merged along the inheritance chain
+email: 
+- ryan@yaauie.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.mdown
+- Rakefile
+- inherited-hash.gemspec
+- lib/inherited-hash.rb
+- lib/inherited-hash/global.rb
+- lib/inherited-hash/version.rb
+- spec/inherited-hash_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/yaauie/inherited-hash
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: inherited-hash
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: class inheritance with hashes
+test_files: 
+- spec/inherited-hash_spec.rb
+- spec/spec_helper.rb