cascading-configuration-hash 1.1.3 → 1.1.4

data/README.md

@@ -1,343 +1,64 @@
 # Cascading Configuration #
 
-http://rubygems.org/gems/cascading-configuration-hash
+http://rubygems.org/gems/cascading-configuration
 
 # Description #
 
-Adds methods for cascading configuration hashes. Support package for cascading-configuration.
+Adds methods for cascading configurations.
 
 # Summary #
 
-## :attr_configuration_hash ##
-
-:attr_configuration_hash provides inheritable configuration that cascades downward. 
-
-Configuration inheritance can cascade through modules, classes, and instances.
-
-:attr_configuration_hash defines a single attribute accessor that composes the set of configuration values appropriate to the ancestor level being queried (merging downward from most distant ancestor to self). An internal cache is kept, and any configuration updates that occur to higher-level ancestors cascade immediately downward.
-
-# Install #
-
-* sudo gem install cascading-configuration-hash
-
-# Usage #
-
-## First Module ##
-
-1. Define initial configuration in a module.
-
-A class works just as well, but we can't use a module in the same chain if we start with a class.
-
-* Include module to enable attr_configuration_hash.
-
-```ruby
-
-  module CascadingConfiguration::MockModule
-	include CascadingConfiguration::Hash
-  end
-
-```
-
-* Declare attr_configuration_hash.
-
-```ruby
-
-  module CascadingConfiguration::MockModule
-    attr_configuration_hash :some_hash_configuration
-  end
-
-```
-
-* Set initial value.
-
-```ruby
-
-  module CascadingConfiguration::MockModule
-    self.some_hash_configuration = { :some_value => :some_value }
-  end
-
-```
-
-* Verify initial configuration value
-
-```ruby
-
-  module CascadingConfiguration::MockModule
-    # => some_hash_configuration.should == { :some_value => :some_value }
-  end
-
-```
-
-## Including Module 1 ##
-
-2. Include initial module in another module.
-
-Including the module that has included a CascadingConfiguration module is the same as including a CascadingConfiguration module.
-
-```ruby
-
-  module CascadingConfiguration::MockModule2
-    include CascadingConfiguration::MockModule
-  end
-
-```
-
-* Verify inherited value
+Cascading configuration methods for single settings, arrays, hashes.
 
-```ruby
-
-  module CascadingConfiguration::MockModule2
-    # => some_hash_configuration.should == { :some_value => :some_value }
-  end
-
-```
-
-* Override inherited value
-
-```ruby
-
-  module CascadingConfiguration::MockModule2
-    self.some_hash_configuration = { :module_value => :some_value }
-  end
-
-```
-
-* Verify local override value
-
-```ruby
-
-  module CascadingConfiguration::MockModule2
-    # => some_hash_configuration.should == { :module_value => :some_value }
-  end
-
-```
-
-## Including Module 2 ##
-
-3. Include second module in another module.
-
-```ruby
-
-  module CascadingConfiguration::MockModule3
-    include CascadingConfiguration::MockModule2
-  end
-
-```
+## :attr_configuration ##
 
-* Verify inherited value
-
-```ruby
-
-  module CascadingConfiguration::MockModule3
-    # => some_array_configuration.should == { :module_value => :some_value }
-  end
-
-```
-
-## Top Class ##
-
-4. Include third module in a class.
-
-```ruby
-
-  class CascadingConfiguration::MockClass
-    include CascadingConfiguration::MockModule3
-  end
-
-```
-
-* Verify inherited value
-
-```ruby
-
-  class CascadingConfiguration::MockClass
-    # => some_hash_configuration.should == { :module_value => :some_value }
-  end
-
-```
-
-* Override inherited value
-
-```ruby
-
-  class CascadingConfiguration::MockClass
-    self.some_hash_configuration = { :another_value => :some_value }
-  end
+:attr_configuration provides inheritable configuration that cascades downward. 
 
-```
-
-* Verify local override value
-
-```ruby
-
-  class CascadingConfiguration::MockClass
-    # => some_hash_configuration.should == { :another_value => :some_value }
-  end
-
-```
-
-## Instance of Top Class ##
-
-5. Instantiate class.
-
-```ruby
-
-  object_instance_one = CascadingConfiguration::MockClass.new
-
-```
-
-* Verify inherited value
-
-```ruby
-
-  # => object_instance_one.some_hash_configuration.should == { :another_value => :some_value }
-
-```
-
-* Override inherited value
-
-```ruby
-
-  object_instance_one.some_hash_configuration = { :yet_another_value => :some_value }
-
-```
-
-* Verify local override value
-
-```ruby
-
-  # => object_instance_one.some_hash_configuration.should == { :yet_another_value => :some_value }
-  # => CascadingConfiguration::MockClass.some_hash_configuration.should == { :another_value => :some_value }
-  # => CascadingConfiguration::MockModule.some_hash_configuration.should == { :some_value => :some_value }
-
-```
-
-# First Inheriting Class #
-
-6. Inheriting class.
-
-Inheriting class should not get any settings from instance of superclass.
-
-* Verify inherited value
-
-```ruby
-
-  class CascadingConfiguration::MockClassSub1 < CascadingConfiguration::MockClass
-    # => some_hash_configuration.should == { :another_value => :some_value }
-  end
-
-```
-
-* Override inherited value
-
-```ruby
-
-  class CascadingConfiguration::MockClassSub1 < CascadingConfiguration::MockClass
-    self.some_hash_configuration = { :a_value_not_yet_used => :some_value }
-  end
-
-```
-
-* Verify local override value
-
-```ruby
-
-  class CascadingConfiguration::MockClassSub1 < CascadingConfiguration::MockClass
-    # => some_hash_configuration.should == { :a_value_not_yet_used => :some_value }
-    # => CascadingConfiguration::MockClass.some_hash_configuration.should == { :another_value => :some_value }
-    # => CascadingConfiguration::MockModule.some_hash_configuration.should == { :some_value => :some_value }
-  end
-
-```
-
-## Instance of First Inheriting Class ##
-
-7. Instantiate first inheriting class.
-
-```ruby
-
-  object_instance_two = CascadingConfiguration::MockClassSub1.new
-
-```
+Configuration inheritance can cascade through modules, classes, and instances.
 
-* Verify inherited value
+:attr_configuration defines a single attribute accessor that searches upward for the first ancestor defining the configuration. 
 
-```ruby
+## :attr_configuration_array ##
 
-  # => object_instance_two.some_hash_configuration.should == { :a_value_not_yet_used => :some_value }
-  # => object_instance_one.some_hash_configuration.should == { :yet_another_value => :some_value }
-  # => CascadingConfiguration::MockClass.some_hash_configuration.should == { :another_value => :some_value }
-  # => CascadingConfiguration::MockModule.some_hash_configuration.should == { :some_value => :some_value }
+:attr_configuration_array provides inheritable configuration that cascades downward. 
 
-```
+Configuration inheritance can cascade through modules, classes, and instances.
 
-## Second Inheriting Class ##
+:attr_configuration_array defines a single attribute accessor that composes the set of configuration values appropriate to the ancestor level being queried (merging downward from most distant ancestor to self). An internal cache is kept, and any configuration updates that occur to higher-level ancestors cascade immediately downward.
 
-8. Second inheriting class.
+The array maintained by :attr_configuration_array is kept ordered and unique.
 
-* Verify inherited value
+## :attr_configuration_hash ##
 
-```ruby
+:attr_configuration_hash provides inheritable configuration that cascades downward. 
 
-  class CascadingConfiguration::MockClassSub2 < CascadingConfiguration::MockClassSub1
-    # => some_hash_configuration.should == { :a_value_not_yet_used => :some_value }
-  end
+Configuration inheritance can cascade through modules, classes, and instances.
 
-```
+:attr_configuration_hash defines a single attribute accessor that composes the set of configuration values appropriate to the ancestor level being queried (merging downward from most distant ancestor to self). An internal cache is kept, and any configuration updates that occur to higher-level ancestors cascade immediately downward.
 
-* Override inherited value
+# Install #
 
-```ruby
+* sudo gem install cascading-configuration
 
-  class CascadingConfiguration::MockClassSub2 < CascadingConfiguration::MockClassSub1
-    self.some_hash_configuration = { :another_value_not_yet_used => :some_value }
-  end
+# Usage #
 
-```
+Including CascadingConfiguration includes:
 
-* Verify local override value
+* CascadingConfiguration::Setting
+* CascadingConfiguration::Array
+* CascadingConfiguration::Hash
 
 ```ruby
-
-  class CascadingConfiguration::MockClassSub2 < CascadingConfiguration::MockClassSub1
-    # => some_hash_configuration.should == { :another_value_not_yet_used => :some_value }
+  module AnyModuleOrClass
+    include CascadingConfiguration
   end
-
-```
-
-## Instance of Second Inheriting Class ##
-
-9. Instantiate Second Inheriting Class.
-
-```ruby
-
-  object_instance_three = CascadingConfiguration::MockClassSub2.new
-
-```
-
-* Verify inherited value
-
-```ruby
-
-  # => object_instance_three.some_hash_configuration.should == { :another_value_not_yet_used => :some_value }
-
 ```
 
-* Override inherited value
+See supporting package README files for examples in each case:
 
-```ruby
-
-  object_instance_three.some_hash_configuration = { :one_more_unused_value => :some_value }
-
-```
-
-* Verify local override value
-
-```ruby
-
-  # => object_instance_three.some_hash_configuration.should == { :one_more_unused_value => :some_value }
-
-```
+* attr_configuration
+* attr_configuration_array
+* attr_configuration_hash
 
 # License #
 

data/README.rdoc

@@ -10,6 +10,24 @@ Adds methods for cascading configurations.
 
 Cascading configuration methods for single settings, arrays, hashes.
 
+== :attr_configuration
+
+:attr_configuration provides inheritable configuration that cascades downward. 
+
+Configuration inheritance can cascade through modules, classes, and instances.
+
+:attr_configuration defines a single attribute accessor that searches upward for the first ancestor defining the configuration. 
+
+== :attr_configuration_array
+
+:attr_configuration_array provides inheritable configuration that cascades downward. 
+
+Configuration inheritance can cascade through modules, classes, and instances.
+
+:attr_configuration_array defines a single attribute accessor that composes the set of configuration values appropriate to the ancestor level being queried (merging downward from most distant ancestor to self). An internal cache is kept, and any configuration updates that occur to higher-level ancestors cascade immediately downward.
+
+The array maintained by :attr_configuration_array is kept ordered and unique.
+
 == :attr_configuration_hash
 
 :attr_configuration_hash provides inheritable configuration that cascades downward. 
@@ -24,7 +42,15 @@ Configuration inheritance can cascade through modules, classes, and instances.
 
 == Usage
 
-See supporting package README markdown files (README.md) for examples.
+module AnyModuleOrClass
+  include CascadingConfiguration
+end
+
+For further details, see supporting package README markdown files (README.md) for examples in each case:
+
+* attr_configuration
+* attr_configuration_array
+* attr_configuration_hash
 
 == License
 

data/lib/cascading-configuration/CascadingConfiguration.rb

@@ -0,0 +1,16 @@
+
+module CascadingConfiguration
+  
+  ###################
+  #  self.included  #
+  ###################
+  
+  def self.included( class_or_module )
+    class_or_module.instance_eval do
+      include CascadingConfiguration::Setting
+      include CascadingConfiguration::Array
+      include CascadingConfiguration::Hash
+    end
+  end
+    
+end

data/lib/cascading-configuration.rb

@@ -0,0 +1,15 @@
+
+if $cascading_configuration_development
+	require_relative '../setting/lib/cascading-configuration-setting.rb'
+	require_relative '../settings-array/lib/cascading-configuration-array.rb'
+	require_relative '../settings-hash/lib/cascading-configuration-hash.rb'
+else
+	require 'cascading-configuration-setting'
+	require 'cascading-configuration-array'
+	require 'cascading-configuration-hash'
+end
+
+module CascadingConfiguration
+end
+
+require_relative 'cascading-configuration/CascadingConfiguration.rb'

data/spec/CascadingConfiguration_spec.rb

@@ -0,0 +1,224 @@
+
+require_relative '../lib/cascading-configuration.rb'
+
+describe CascadingConfiguration do
+  
+  ########################
+  #  attr_configuration  #
+  ########################
+  
+  it 'can declare an attribute as a cascading configuration setting' do
+    module CascadingConfiguration::MockModule2
+    end
+
+    # first module
+    module CascadingConfiguration::MockModule
+      include CascadingConfiguration
+      attr_configuration :some_configuration
+      self.some_configuration = :some_value
+      some_configuration.should == :some_value
+    end
+
+    # including module 1
+    module CascadingConfiguration::MockModule2
+      include CascadingConfiguration::MockModule
+      some_configuration.should == :some_value
+      self.some_configuration = :module_value
+      some_configuration.should == :module_value
+    end
+
+    # including module 2
+    module CascadingConfiguration::MockModule3
+      include CascadingConfiguration::MockModule2
+    end
+
+    # top class
+    class CascadingConfiguration::MockClass
+      include CascadingConfiguration::MockModule3
+      some_configuration.should == :module_value
+      self.some_configuration = :another_value
+      some_configuration.should == :another_value
+    end
+
+    # instance of top class
+    object_instance_one = CascadingConfiguration::MockClass.new
+    object_instance_one.some_configuration.should == :another_value
+    object_instance_one.some_configuration = :yet_another_value
+    object_instance_one.some_configuration.should == :yet_another_value
+    CascadingConfiguration::MockClass.some_configuration.should == :another_value
+    CascadingConfiguration::MockModule.some_configuration.should == :some_value
+
+    # first inheriting class
+    class CascadingConfiguration::MockClassSub1 < CascadingConfiguration::MockClass
+      some_configuration.should == :another_value
+      self.some_configuration = :a_value_not_yet_used
+      some_configuration.should == :a_value_not_yet_used
+      CascadingConfiguration::MockClass.some_configuration.should == :another_value
+      CascadingConfiguration::MockModule.some_configuration.should == :some_value
+    end
+
+    # Instance of First Inheriting Class
+    object_instance_two = CascadingConfiguration::MockClassSub1.new
+    object_instance_two.some_configuration.should == :a_value_not_yet_used
+    object_instance_one.some_configuration.should == :yet_another_value
+    CascadingConfiguration::MockClass.some_configuration.should == :another_value
+    CascadingConfiguration::MockModule.some_configuration.should == :some_value
+
+    # Second Inheriting Class
+    class CascadingConfiguration::MockClassSub2 < CascadingConfiguration::MockClassSub1
+      some_configuration.should == :a_value_not_yet_used
+      self.some_configuration = :another_value_not_yet_used
+      some_configuration.should == :another_value_not_yet_used
+    end
+
+    # Instance of Second Inheriting Class
+    object_instance_three = CascadingConfiguration::MockClassSub2.new
+    object_instance_three.some_configuration.should == :another_value_not_yet_used
+    object_instance_three.some_configuration = :one_more_unused_value
+    object_instance_three.some_configuration.should == :one_more_unused_value
+
+  end
+
+  ##############################
+  #  attr_configuration_array  #
+  ##############################
+  
+  it 'can declare an attribute as a cascading configuration array' do
+
+    # first module
+    module CascadingConfiguration::MockModule
+      attr_configuration_array :some_array_configuration
+      self.some_array_configuration = [ :some_value ]
+      some_array_configuration.should == [ :some_value ]
+    end
+
+    # including module 1
+    module CascadingConfiguration::MockModule2
+      some_array_configuration.should == [ :some_value ]
+      self.some_array_configuration = [ :module_value ]
+      some_array_configuration.should == [ :module_value ]
+    end
+
+    # including module 2
+    module CascadingConfiguration::MockModule3
+      some_array_configuration.should == [ :module_value ]
+    end
+
+    # top class
+    class CascadingConfiguration::MockClass
+      some_array_configuration.should == [ :module_value ]
+      self.some_array_configuration = [ :another_value ]
+      some_array_configuration.should == [ :another_value ]
+    end
+
+    # instance of top class
+    object_instance_one = CascadingConfiguration::MockClass.new
+    object_instance_one.some_array_configuration.should == [ :another_value ]
+    object_instance_one.some_array_configuration = [ :yet_another_value ]
+    object_instance_one.some_array_configuration.should == [ :yet_another_value ]
+    CascadingConfiguration::MockClass.some_array_configuration.should == [ :another_value ]
+    CascadingConfiguration::MockModule.some_array_configuration.should == [ :some_value ]
+
+    # first inheriting class
+    class CascadingConfiguration::MockClassSub1 < CascadingConfiguration::MockClass
+      some_array_configuration.should == [ :another_value ]
+      self.some_array_configuration = [ :a_value_not_yet_used ]
+      some_array_configuration.should == [ :a_value_not_yet_used ]
+      CascadingConfiguration::MockClass.some_array_configuration.should == [ :another_value ]
+      CascadingConfiguration::MockModule.some_array_configuration.should == [ :some_value ]
+    end
+
+    # Instance of First Inheriting Class
+    object_instance_two = CascadingConfiguration::MockClassSub1.new
+    object_instance_two.some_array_configuration.should == [ :a_value_not_yet_used ]
+    object_instance_one.some_array_configuration.should == [ :yet_another_value ]
+    CascadingConfiguration::MockClass.some_array_configuration.should == [ :another_value ]
+    CascadingConfiguration::MockModule.some_array_configuration.should == [ :some_value ]
+
+    # Second Inheriting Class
+    class CascadingConfiguration::MockClassSub2 < CascadingConfiguration::MockClassSub1
+      some_array_configuration.should == [ :a_value_not_yet_used ]
+      self.some_array_configuration = [ :another_value_not_yet_used ]
+      some_array_configuration.should == [ :another_value_not_yet_used ]
+    end
+
+    # Instance of Second Inheriting Class
+    object_instance_three = CascadingConfiguration::MockClassSub2.new
+    object_instance_three.some_array_configuration.should == [ :another_value_not_yet_used ]
+    object_instance_three.some_array_configuration = [ :one_more_unused_value ]
+    object_instance_three.some_array_configuration.should == [ :one_more_unused_value ]
+    
+  end
+  
+  #############################
+  #  attr_configuration_hash  #
+  #############################
+  
+  it 'can declare an attribute as a cascading configuration hash' do
+
+    # first module
+    module CascadingConfiguration::MockModule
+      attr_configuration_hash :some_hash_configuration
+      self.some_hash_configuration = { :some_value => :some_value }
+      some_hash_configuration.should == { :some_value => :some_value }
+    end
+
+    # including module 1
+    module CascadingConfiguration::MockModule2
+      some_hash_configuration.should == { :some_value => :some_value }
+      self.some_hash_configuration = { :module_value => :some_value }
+      some_hash_configuration.should == { :module_value => :some_value }
+    end
+
+    # including module 2
+    module CascadingConfiguration::MockModule3
+
+    end
+
+    # top class
+    class CascadingConfiguration::MockClass
+      some_hash_configuration.should == { :module_value => :some_value }
+      self.some_hash_configuration = { :another_value => :some_value }
+      some_hash_configuration.should == { :another_value => :some_value }
+    end
+
+    # instance of top class
+    object_instance_one = CascadingConfiguration::MockClass.new
+    object_instance_one.some_hash_configuration.should == { :another_value => :some_value }
+    object_instance_one.some_hash_configuration = { :yet_another_value => :some_value }
+    object_instance_one.some_hash_configuration.should == { :yet_another_value => :some_value }
+    CascadingConfiguration::MockClass.some_hash_configuration.should == { :another_value => :some_value }
+    CascadingConfiguration::MockModule.some_hash_configuration.should == { :some_value => :some_value }
+
+    # first inheriting class
+    class CascadingConfiguration::MockClassSub1 < CascadingConfiguration::MockClass
+      some_hash_configuration.should == { :another_value => :some_value }
+      self.some_hash_configuration = { :a_value_not_yet_used => :some_value }
+      some_hash_configuration.should == { :a_value_not_yet_used => :some_value }
+      CascadingConfiguration::MockClass.some_hash_configuration.should == { :another_value => :some_value }
+      CascadingConfiguration::MockModule.some_hash_configuration.should == { :some_value => :some_value }
+    end
+
+    # Instance of First Inheriting Class
+    object_instance_two = CascadingConfiguration::MockClassSub1.new
+    object_instance_two.some_hash_configuration.should == { :a_value_not_yet_used => :some_value }
+    object_instance_one.some_hash_configuration.should == { :yet_another_value => :some_value }
+    CascadingConfiguration::MockClass.some_hash_configuration.should == { :another_value => :some_value }
+    CascadingConfiguration::MockModule.some_hash_configuration.should == { :some_value => :some_value }
+
+    # Second Inheriting Class
+    class CascadingConfiguration::MockClassSub2 < CascadingConfiguration::MockClassSub1
+      some_hash_configuration.should == { :a_value_not_yet_used => :some_value }
+      self.some_hash_configuration = { :another_value_not_yet_used => :some_value }
+      some_hash_configuration.should == { :another_value_not_yet_used => :some_value }
+    end
+
+    # Instance of Second Inheriting Class
+    object_instance_three = CascadingConfiguration::MockClassSub2.new
+    object_instance_three.some_hash_configuration.should == { :another_value_not_yet_used => :some_value }
+    object_instance_three.some_hash_configuration = { :one_more_unused_value => :some_value }
+    object_instance_three.some_hash_configuration.should == { :one_more_unused_value => :some_value }
+    
+  end
+  
+end