cascading-configuration-array 1.0.0 → 1.1.0

data/README.md

@@ -0,0 +1,369 @@
+# Cascading Configuration #
+
+http://rubygems.org/gems/cascading-configuration-array
+
+# Description #
+
+Adds methods for cascading configuration arrays. Support package for cascading-configuration.
+
+# Summary #
+
+## :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.
+
+# Install #
+
+* sudo gem install cascading-configuration-array
+
+# 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_array.
+
+```ruby
+
+  module CascadingConfiguration::MockModule
+	include CascadingConfiguration::Array
+  end
+
+```
+
+* Declare attr_configuration_array.
+
+```ruby
+
+  module CascadingConfiguration::MockModule
+    attr_configuration_array :some_array_configuration
+  end
+
+```
+
+* Set initial value.
+
+```ruby
+
+  module CascadingConfiguration::MockModule
+    self.some_array_configuration = [ :some_value ]
+  end
+
+```
+
+* Verify initial configuration value
+
+```ruby
+
+  module CascadingConfiguration::MockModule
+
+    # => some_array_configuration.should == [ :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
+
+```ruby
+
+  module CascadingConfiguration::MockModule2
+    # => some_array_configuration.should == [ :some_value ]
+  end
+
+```
+
+* Override inherited value
+
+```ruby
+
+  module CascadingConfiguration::MockModule2
+    self.some_array_configuration = [ :module_value ]
+  end
+
+```
+
+* Verify local override value
+
+```ruby
+
+  module CascadingConfiguration::MockModule2
+    # => some_array_configuration.should == [ :module_value ]
+  end
+
+```
+
+## Including Module 2 ##
+
+3. Include second module in another module.
+
+```ruby
+
+  module CascadingConfiguration::MockModule3
+    include CascadingConfiguration::MockModule2
+  end
+
+```
+
+* Verify inherited value
+
+```ruby
+
+  module CascadingConfiguration::MockModule3
+    # => some_array_configuration.should == [ :module_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_array_configuration.should == [ :module_value ]
+  end
+
+```
+
+* Override inherited value
+
+```ruby
+
+  class CascadingConfiguration::MockClass
+    self.some_array_configuration = [ :another_value ]
+  end
+
+```
+
+* Verify local override value
+
+```ruby
+
+  class CascadingConfiguration::MockClass
+    # => some_array_configuration.should == [ :another_value ]
+  end
+
+```
+
+## Instance of Top Class ##
+
+5. Instantiate class.
+
+```ruby
+
+  object_instance_one = CascadingConfiguration::MockClass.new
+
+```
+
+* Verify inherited value
+
+```ruby
+
+  # => object_instance_one.some_array_configuration.should == [ :another_value ]
+
+```
+
+* Override inherited value
+
+```ruby
+
+  object_instance_one.some_array_configuration = [ :yet_another_value ]
+
+```
+
+* Verify local override value
+
+```ruby
+
+  # => 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 #
+
+6. Inheriting class.
+
+Inheriting class should not get any settings from instance of superclass.
+
+* Verify inherited value
+
+```ruby
+
+  class CascadingConfiguration::MockClassSub1 < CascadingConfiguration::MockClass
+    # => some_array_configuration.should == [ :another_value ]
+  end
+
+```
+
+* Override inherited value
+
+```ruby
+
+  class CascadingConfiguration::MockClassSub1 < CascadingConfiguration::MockClass
+    self.some_array_configuration = [ :a_value_not_yet_used ]
+  end
+
+```
+
+* Verify local override value
+
+```ruby
+
+  class CascadingConfiguration::MockClassSub1 < CascadingConfiguration::MockClass
+    # => 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 ##
+
+7. Instantiate first inheriting class.
+
+```ruby
+
+  object_instance_two = CascadingConfiguration::MockClassSub1.new
+
+```
+
+* Verify inherited value
+
+```ruby
+
+  # => 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 ##
+
+8. Second inheriting class.
+
+* Verify inherited value
+
+```ruby
+
+  class CascadingConfiguration::MockClassSub2 < CascadingConfiguration::MockClassSub1
+    # => some_array_configuration.should == [ :a_value_not_yet_used ]
+  end
+
+```
+
+* Override inherited value
+
+```ruby
+
+  class CascadingConfiguration::MockClassSub2 < CascadingConfiguration::MockClassSub1
+    self.some_array_configuration = [ :another_value_not_yet_used ]
+  end
+
+```
+
+* Verify local override value
+
+```ruby
+
+  class CascadingConfiguration::MockClassSub2 < CascadingConfiguration::MockClassSub1
+    # => some_array_configuration.should == [ :another_value_not_yet_used ]
+  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_array_configuration.should == [ :another_value_not_yet_used ]
+
+```
+
+* Override inherited value
+
+```ruby
+
+  object_instance_three.some_array_configuration = [ :one_more_unused_value ]
+
+```
+
+* Verify local override value
+
+```ruby
+
+  # => object_instance_three.some_array_configuration.should == [ :one_more_unused_value ]
+
+```
+
+# License #
+
+  (The MIT License)
+
+  Copyright (c) 2011 Asher
+
+  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.rdoc

@@ -1,118 +1,34 @@
 == Cascading Configuration
 
-http://rubygems.org/gems/cascading-configuration-array
-
-== DESCRIPTION:
-
-Adds methods for cascading configuration arrays. Support package for cascading-configuration.
-
-== SUMMARY:
-  
-  * :attr_configuration_array
-
-== INSTALL:
-
-  * sudo gem install cascading-configuration-array
-
-== EXAMPLE:
-
-  #############################################################################
-  ######################## attr_configuration_array ###########################
-  #############################################################################
-
-  ##################
-  #  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 ]
-
-  #############################################################################
-
-== LICENSE:
+http://rubygems.org/gems/cascading-configuration
+
+== Description
+
+Adds methods for cascading configurations.
+
+== Summary
+
+Cascading configuration methods for single settings, arrays, hashes.
+
+== :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.
+
+== Install
+
+* sudo gem install cascading-configuration
+
+== Usage
+
+See supporting package README markdown files (README.md) for examples.
+
+== License
 
   (The MIT License)
 

data/lib/cascading-configuration-array/CascadingConfiguration/Array/Accessors.rb

@@ -0,0 +1,54 @@
+
+module CascadingConfiguration::Array::Accessors
+
+	extend  CascadingConfiguration::InternalModuleStub
+
+	###################
+	#  self.extended  #
+	###################
+	
+	def self.extended( class_or_module )
+		class_or_module.instance_eval do
+      # accessor support in module to permit method overriding with super
+			unless const_defined?( :AccessorSupportModule )
+				accessor_support_module = Module.new { extend  CascadingConfiguration::InternalModuleStub }
+				const_set( :AccessorSupportModule, accessor_support_module )
+				include class_or_module::AccessorSupportModule
+				extend  class_or_module::AccessorSupportModule
+			end
+		end
+	end
+
+  ###################################
+  #  define_cascading_array_setter  #
+  ###################################
+  
+  def define_cascading_array_setter( configuration_name )
+    configuration_setter_name = ( configuration_name.to_s + '=' ).to_sym
+    self::AccessorSupportModule.module_eval do 
+	    define_method( configuration_setter_name ) do |array|
+	      composite_array = composite_array_for_cascading_configuration( configuration_name )
+	      # we want the array to supplant existing config
+	      # clear the array (excludes everything explicitly)
+	      composite_array.clear
+	      # push array elements (removes anything excluded from exclude)
+	      composite_array.push( *array )
+	      return composite_array
+	    end
+    end
+  end
+
+  ###################################
+  #  define_cascading_array_getter  #
+  ###################################
+  
+  def define_cascading_array_getter( configuration_name )
+    configuration_getter_name = configuration_name
+    self::AccessorSupportModule.module_eval do 
+	    define_method( configuration_getter_name ) do
+	      return composite_array_for_cascading_configuration( configuration_name )
+	    end
+    end
+  end
+
+end

data/lib/cascading-configuration-array/CascadingConfiguration/{ConfigurationSettingsArray → Array}/ClassInstance.rb

@@ -1,5 +1,7 @@
 
-module CascadingConfiguration::ConfigurationSettingsArray::ClassInstance
+module CascadingConfiguration::Array::ClassInstance
+
+	extend  CascadingConfiguration::InternalModuleStub
 
   ##############################
   #  attr_configuration_array  #
@@ -8,9 +10,9 @@ module CascadingConfiguration::ConfigurationSettingsArray::ClassInstance
   def attr_configuration_array( *property_names )
     property_names.each do |this_property_name|
       # define configuration setter
-      define_configuration_array_setter( this_property_name )
+      define_cascading_array_setter( this_property_name )
       # define configuration getter
-      define_configuration_array_getter( this_property_name )
+      define_cascading_array_getter( this_property_name )
     end
   end
 

data/lib/cascading-configuration-array/CascadingConfiguration/{ConfigurationSettingsArray → Array}/ModuleInstance.rb

@@ -1,19 +1,22 @@
 
-module CascadingConfiguration::ConfigurationSettingsArray::ModuleInstance
+module CascadingConfiguration::Array::ModuleInstance
   
+	extend  CascadingConfiguration::InternalModuleStub
+
   ##############
   #  included  #
   ##############
   
   def included( class_or_module )
-    self_module = self
+		super if method_defined?( :super )
+    module_self = self
     class_or_module.instance_eval do
-      include CascadingConfiguration::ConfigurationSettingsArray
+      include CascadingConfiguration::Array
       # when we extend a module (which has happened if we got here)
       # then we need to make sure when the module we are extending is included
       # * CascadingConfiguration is included
       # * the module we extended is used to extend the class/module that included
-      extend  self_module
+      extend  module_self
     end
   end
   

data/lib/cascading-configuration-array/CascadingConfiguration/Array.rb

@@ -0,0 +1,33 @@
+
+module CascadingConfiguration::Array
+  
+	extend  CascadingConfiguration::InternalModuleStub
+
+  ###################
+  #  self.included  #
+  ###################
+
+  def self.included( class_or_module )
+		module_self = self
+    class_or_module.instance_eval do
+      include CascadingConfiguration::Variable
+      extend  module_self
+      extend  CascadingConfiguration::Array::Accessors
+      extend  CascadingConfiguration::Array::ClassInstance
+      include CascadingConfiguration::CompositingArray::Instance
+			# module support
+			unless is_a?( Class )
+        extend CascadingConfiguration::Array::ModuleInstance
+      end
+    end
+  end
+
+  #########################
+  #  ancestors_to_Object  #
+  #########################
+
+  def ancestors_to_Object
+    return ancestors_to_class_or_module_interpolating_module_branches( Object, CascadingConfiguration::Array::ModuleInstance )
+  end
+
+end

data/lib/cascading-configuration-array/CascadingConfiguration/{CascadingCompositeArray → CompositingArray}/Instance.rb

@@ -1,5 +1,7 @@
 
-module CascadingConfiguration::CascadingCompositeArray::Instance
+module CascadingConfiguration::CompositingArray::Instance
+
+	extend  CascadingConfiguration::InternalModuleStub
 
   ###################
   #  self.included  #
@@ -26,7 +28,7 @@ module CascadingConfiguration::CascadingCompositeArray::Instance
     if instance_variable_defined?( composite_array_variable )
       composite_array = instance_variable_get( composite_array_variable )
     else
-      composite_array = ::CascadingConfiguration::CascadingCompositeArray.new( cascading_name, self )
+      composite_array = ::CascadingConfiguration::CompositingArray.new( cascading_name, self )
       instance_variable_set( composite_array_variable, composite_array )
     end
 

data/lib/cascading-configuration-array/CascadingConfiguration/{CascadingCompositeArray → CompositingArray}/_private_/Instance.rb

@@ -1,5 +1,5 @@
 
-module CascadingConfiguration::CascadingCompositeArray::Instance
+module CascadingConfiguration::CompositingArray::Instance
 
   ###########################################################################################################
       private ###############################################################################################

data/lib/cascading-configuration-array/CascadingConfiguration/{CascadingCompositeArray.rb → CompositingArray.rb}

@@ -1,5 +1,5 @@
 
-class CascadingConfiguration::CascadingCompositeArray < Array
+class CascadingConfiguration::CompositingArray < Array
 
   attr_accessor  :working_instance, :local_cascading_array
 
@@ -17,9 +17,9 @@ class CascadingConfiguration::CascadingCompositeArray < Array
       @parent_composite_array.register_child_composite_array( self )
     end
     # get local cascading array (not included in parent composite)
-    @local_cascading_array = ::CascadingConfiguration::ConfigurationArray.new
+    @local_cascading_array = ::CascadingConfiguration::LocalConfigurationArray.new
     # we may later have our own child composites
-    @child_composite_arrays = Array.new
+    @child_composite_arrays = ::Array.new
     # initialize self status for parent and local
     update_self_as_cascading_composite
   end