cascading-configuration-array 1.0.0

data/README.rdoc

@@ -0,0 +1,138 @@
+== 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:
+
+  (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/lib/cascading-configuration-array.rb

@@ -0,0 +1,33 @@
+
+require 'cascading-configuration-variable'
+#require_relative '../../variable/lib/cascading-configuration-variable.rb'
+
+module CascadingConfiguration
+  class CascadingCompositeArray < Array
+    module Instance
+    end
+  end
+  class ConfigurationArray < Array
+  end
+  module ConfigurationSettingsArray
+    module Accessors
+    end
+    module ClassInstance
+    end
+    module ObjectInstance
+    end
+    module ModuleInstance
+    end
+  end
+end
+
+require_relative 'cascading-configuration-array/CascadingConfiguration/CascadingCompositeArray.rb'
+require_relative 'cascading-configuration-array/CascadingConfiguration/_private_/CascadingCompositeArray.rb'
+require_relative 'cascading-configuration-array/CascadingConfiguration/CascadingCompositeArray/Instance.rb'
+require_relative 'cascading-configuration-array/CascadingConfiguration/CascadingCompositeArray/_private_/Instance.rb'
+require_relative 'cascading-configuration-array/CascadingConfiguration/ConfigurationArray.rb'
+require_relative 'cascading-configuration-array/CascadingConfiguration/_private_/ConfigurationArray.rb'
+require_relative 'cascading-configuration-array/CascadingConfiguration/ConfigurationSettingsArray.rb'
+require_relative 'cascading-configuration-array/CascadingConfiguration/ConfigurationSettingsArray/Accessors.rb'
+require_relative 'cascading-configuration-array/CascadingConfiguration/ConfigurationSettingsArray/ClassInstance.rb'
+require_relative 'cascading-configuration-array/CascadingConfiguration/ConfigurationSettingsArray/ModuleInstance.rb'

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

@@ -0,0 +1,215 @@
+
+class CascadingConfiguration::CascadingCompositeArray < Array
+
+  attr_accessor  :working_instance, :local_cascading_array
+
+  ################
+  #  initialize  #
+  ################
+  
+  def initialize( cascading_name, working_instance )
+    @cascading_name     = cascading_name
+    @cascading_variable = working_instance.cascading_variable_name( @cascading_name )
+    @working_instance   = working_instance
+    # if first ancestor can have a composite array, register self with it in case it gets updated in the future
+    if ( first_ancestor = @working_instance.first_ancestor ).respond_to?( :composite_array_for_cascading_configuration )
+      @parent_composite_array = first_ancestor.composite_array_for_cascading_configuration( @cascading_name )
+      @parent_composite_array.register_child_composite_array( self )
+    end
+    # get local cascading array (not included in parent composite)
+    @local_cascading_array = ::CascadingConfiguration::ConfigurationArray.new
+    # we may later have our own child composites
+    @child_composite_arrays = Array.new
+    # initialize self status for parent and local
+    update_self_as_cascading_composite
+  end
+
+  ####################################
+  #  register_child_composite_array  #
+  ####################################
+
+  def register_child_composite_array( child_composite_array )
+    @child_composite_arrays.push( child_composite_array )
+    return self
+  end
+
+  ######################################
+  #  unregister_child_composite_array  #
+  ######################################
+
+  def unregister_child_composite_array( child_composite_array )
+    @child_composite_arrays.delete( child_composite_array )
+    return self
+  end
+
+  #########
+  #  []=  #
+  #########
+
+  def []=( index, element )
+    # we sort internally, so index is irrelevant
+    # no reason to differentiate from push
+    push( element )
+  end
+
+  ########
+  #  <<  #
+  ########
+  
+  def <<( *elements )
+    # no reason to differentiate from push
+    push( *elements )
+  end
+  
+  #######
+  #  +  #
+  #######
+
+  def +( *arrays )
+    # no reason to differentiate from push
+    arrays.each do |this_array|
+      push( *this_array )
+    end
+    return self
+  end
+
+  ############
+  #  concat  #
+  ############
+  
+  def concat( *arrays )
+    arrays.each do |this_array|
+      push( *this_array )
+    end
+  end
+  
+  ##########
+  #  push  #
+  ##########
+  
+  alias_method :super_push, :push
+  def push( *elements )
+
+    # we are a composite array
+    # that means we have to set the value for our class
+    @local_cascading_array.push( *elements )
+        
+    update_adding_composite_elements( *elements )
+    
+    return self
+
+  end
+  
+  #######
+  #  -  #
+  #######
+  
+  def -( *arrays )
+    
+    arrays.each do |this_array|
+      delete( *this_array )
+    end
+    
+    return self
+    
+  end
+
+  ############
+  #  delete  #
+  ############
+  
+  alias_method :super_delete, :delete
+  def delete( *elements )
+  
+    @local_cascading_array.delete( *elements )
+
+    update_removing_composite_elements( *elements )
+    
+    return self
+    
+  end
+
+  #########
+  #  pop  #
+  #########
+  
+  def pop
+
+    element = super
+
+    @local_cascading_array.delete( element )
+
+    update_removing_composite_elements( element )
+    
+    return element
+
+  end
+
+  ###########
+  #  shift  #
+  ###########
+  
+  def shift
+
+    element = super
+
+    @local_cascading_array.delete( element )
+
+    update_removing_composite_elements( element )
+
+    return element
+    
+  end
+
+  ############
+  #  slice!  #
+  ############
+  
+  def slice!( *args )
+
+    elements = super
+
+    @local_cascading_array.delete( *elements )
+
+    update_removing_composite_elements( *elements )
+    
+    return elements
+    
+  end
+  
+  ###########
+  #  clear  #
+  ###########
+  
+  alias_method :super_clear, :clear
+  def clear
+
+    # add all existing values to exclude array
+    @local_cascading_array.delete( *self )
+
+    update_removing_composite_elements( *self )
+
+    return self
+    
+  end
+
+  #############
+  #  freeze!  #
+  #############
+
+  # freezes configuration and prevents ancestors from changing this configuration in the future
+  def freeze!
+    
+    # move current configuration into local configuration
+    @local_cascading_array.clear
+    @local_cascading_array.exclude_array.clear
+    @local_cascading_array.push( *self )
+    
+    # unregister with parent composite so we don't get future updates from it
+    @parent_composite_array.unregister_child_composite_array( self ) if @parent_composite_array
+    
+    return self
+    
+  end
+    
+end

data/lib/cascading-configuration-array/CascadingConfiguration/CascadingCompositeArray/Instance.rb

@@ -0,0 +1,37 @@
+
+module CascadingConfiguration::CascadingCompositeArray::Instance
+
+  ###################
+  #  self.included  #
+  ###################
+
+  def self.included( class_or_module )
+    module_self = self
+    class_or_module.instance_eval do
+      extend module_self
+    end
+  end
+
+  #################################################
+  #  composite_array_for_cascading_configuration  #
+  #################################################
+
+  def composite_array_for_cascading_configuration( cascading_name )
+    
+    # initialize composite array if necessary or acquire it from object
+    composite_array_variable = composite_array_variable_name( cascading_name )
+
+    composite_array = nil
+
+    if instance_variable_defined?( composite_array_variable )
+      composite_array = instance_variable_get( composite_array_variable )
+    else
+      composite_array = ::CascadingConfiguration::CascadingCompositeArray.new( cascading_name, self )
+      instance_variable_set( composite_array_variable, composite_array )
+    end
+
+    return composite_array
+    
+  end
+
+end

data/lib/cascading-configuration-array/CascadingConfiguration/CascadingCompositeArray/_private_/Instance.rb

@@ -0,0 +1,16 @@
+
+module CascadingConfiguration::CascadingCompositeArray::Instance
+
+  ###########################################################################################################
+      private ###############################################################################################
+  ###########################################################################################################
+  
+  ###################################
+  #  composite_array_variable_name  #
+  ###################################
+  
+  def composite_array_variable_name( configuration_name )
+    return ( cascading_variable_name( configuration_name ).to_s + '__' + 'composite_array' ).to_sym
+  end
+  
+end

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

@@ -0,0 +1,166 @@
+
+class CascadingConfiguration::ConfigurationArray < Array
+
+  attr_accessor  :exclude_array
+  
+  ################
+  #  initialize  #
+  ################
+
+  def initialize()
+    @exclude_array = Array.new
+  end
+
+  #########
+  #  []=  #
+  #########
+
+  def []=( index, element )
+    # we sort internally, so index is irrelevant
+    # no reason to differentiate from push
+    push( element )
+  end
+
+  ########
+  #  <<  #
+  ########
+  
+  def <<( *elements )
+    # no reason to differentiate from push
+    push( *elements )
+  end
+  
+  #######
+  #  +  #
+  #######
+
+  def +( *element_arrays )
+    element_arrays.each do |this_element_array|
+      push( *this_element_array )
+    end
+    return self
+  end
+
+  ##########
+  #  push  #
+  ##########
+  
+  def push( *elements )
+    
+    # add elements to configuration array
+    super
+
+    # sort and uniq self
+    sort!.uniq!
+    
+    # make sure we don't still have any elements noted as excluded at this level
+    remove_from_exclude_array( *elements )
+
+    return self
+    
+  end
+  
+  ############
+  #  concat  #
+  ############
+  
+  def concat( *arrays )
+
+    arrays.each do |this_array|
+      push( *this_array )
+    end
+
+    return self
+
+  end
+  
+  #######
+  #  -  #
+  #######
+  
+  def -( *arrays )
+
+    arrays.each do |this_array|
+      delete( *this_array )
+    end
+
+    return self
+  
+  end
+
+  ############
+  #  delete  #
+  ############
+  
+  def delete( *elements )
+
+    elements.each do |this_element|
+      super( this_element )
+    end
+    # add subtracted elements to exclude array
+    add_to_exclude_array( *elements )
+
+    return self
+  
+  end
+
+  #########
+  #  pop  #
+  #########
+  
+  def pop
+    
+    element = super
+    
+    # add popped element to exclude array
+    add_to_exclude_array( element )
+    
+    return element
+  
+  end
+
+  ###########
+  #  shift  #
+  ###########
+  
+  def shift
+
+    element = super
+
+    # add shifted element to exclude array
+    add_to_exclude_array( element )
+
+    return element
+
+  end
+
+  ############
+  #  slice!  #
+  ############
+  
+  def slice!( *args )
+
+    elements = super
+
+    # add sliced elements to exclude array
+    delete( *elements )
+
+    return elements
+
+  end
+  
+  ###########
+  #  clear  #
+  ###########
+  
+  def clear
+
+    # add all existing values to exclude array
+    delete( *self )
+
+    # clear existing values
+    super
+
+  end
+  
+end