module-cluster 1.0.3 → 1.1.0

data/README.md

@@ -8,7 +8,17 @@ Adds methods for defining module clusters using #included and #extended.
 
 # Summary #
 
-Provides :define_module_included, :define_module_extended, and :define_module_cluster.
+Provides:
+
+* :define_module_included
+* :define_module_extended
+* :define_module_cluster
+* :define_module_included_cascades
+* :define_module_extended_cascades
+* :define_module_cluster_cascades
+* :define_module_included_cascades_to_class
+* :define_module_extended_cascades_to_class
+* :define_module_cluster_cascades_to_class
 
 # Install #
 
@@ -24,6 +34,16 @@ module SomeModule
 end
 ```
 
+## The Basic Idea ##
+
+We use blocks to define cascading module includes/extends. This automates calls to super (so we don't forget) and puts self.included/self.extended support into a module so that local overriding is still possible.
+
+The block provides arrays to hold includes/extends. If two arrays [ includes, extends ] are returned by the block, they will be used. Otherwise the arrays passed in by parameters will be used. This means, due to how Ruby handles references, that *if you set one of the parameter arrays to a new array you have to return both arrays* or your changes won't be added.
+
+Calls to define_module_... functions are cumulative, permitting multiple calls (whether subsequently or otherwise). This is particularly useful for configuring including/extending modules from the included/extended module (and so on - nested blocks permit this sort of determination indefinitely).
+
+## define_module_included ##
+
 To cause modules to be included when this module is included:
 
 ```ruby
@@ -44,7 +64,9 @@ module SomeModule
 end
 ```
 
-or when this module is extended
+## define_module_extended ##
+
+To cause modules to be included when this module is extended:
 
 ```ruby
 module SomeModule
@@ -54,7 +76,7 @@ module SomeModule
 end
 ```
 
-or
+or extended when this module is extended:
 
 ```ruby
 module SomeModule
@@ -64,7 +86,9 @@ module SomeModule
 end
 ```
 
-or when this module is either included or extended:
+## define_module_cluster ##
+
+To cause modules to be included when this module is included or extended:
 
 ```ruby
 module SomeModule
@@ -74,7 +98,7 @@ module SomeModule
 end
 ```
 
-or
+or extended when this module is included or extended:
 
 ```ruby
 module SomeModule
@@ -84,7 +108,83 @@ module SomeModule
 end
 ```
 
-If the block returns [ includes, extends ] as arrays, those values will be used; otherwise, the contents of the includes and extends parameters passed to the block will be used.
+## define_module_included_cascades ##
+
+To cause modules to be included or extended when this module is used to include in a class or module.
+
+```ruby
+module SomeModule
+  define_module_included_cascades do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+```
+
+## define_module_extended_cascades ##
+
+To cause modules to be included or extended when this module is used to extend in a class or module:
+
+```ruby
+module SomeModule
+  define_module_extended_cascades do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+```
+
+## define_module_cluster_cascades ##
+
+To cause modules to be included or extended when this module is used to include or extend in a class or module:
+
+```ruby
+module SomeModule
+  define_module_cluster_cascades do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+```
+
+## define_module_included_cascades_to_class ##
+
+To cause modules to be included or extended when this module is used to include in a class (and not a module):
+
+```ruby
+module SomeModule
+  define_module_included_cascades_to_class do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+```
+
+## define_module_extended_cascades_to_class ##
+
+To cause modules to be included or extended when this module is used to extend in a class (and not a module):
+
+```ruby
+module SomeModule
+  define_module_extended_cascades_to_class do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+```
+
+## define_module_cluster_cascades_to_class ##
+
+To cause modules to be included or extended when this module is used to include or extend in a class (and not a module):
+
+```ruby
+module SomeModule
+  define_module_cluster_cascades_to_class do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+```
 
 # License #
 

data/README.rdoc

@@ -0,0 +1,182 @@
+== Module Cluster
+
+http://rubygems.org/gems/module-cluster
+
+== Description
+
+Adds methods for defining module clusters using #included and #extended.
+
+== Summary
+
+Provides:
+* :define_module_included
+* :define_module_extended
+* :define_module_cluster
+* :define_module_included_cascades_to_class
+* :define_module_extended_cascades_to_class
+* :define_module_cluster_cascades_to_class
+
+== Install
+
+* sudo gem install module-cluster
+
+== Usage
+
+Simply:
+
+module SomeModule
+  include ModuleCluster
+end
+
+=== The Basic Idea
+
+We use blocks to define cascading module includes/extends. This automates calls to super (so we don't forget) and puts self.included/self.extended support into a module so that local overriding is still possible.
+
+The block provides arrays with the current set of includes/extends to cascade for the module. If two arrays [ includes, extends ] are returned by the block, they will be used. Otherwise the arrays passed in by parameters will be used. This means, due to how Ruby handles references, that *if you set one of the parameter arrays to a new array you have to return both arrays* or your changes won't be added.
+
+Calls to define_module_... functions are cumulative, permitting multiple calls (whether subsequently or otherwise). This is particularly useful for configuring including/extending modules from the included/extended module (and so on - nested blocks permit this sort of determination indefinitely).
+
+=== define_module_included
+
+To cause modules to be included when this module is included:
+
+module SomeModule
+  define_module_included do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+  end
+end
+
+or extended when this module is included:
+
+module SomeModule
+  define_module_included do |includes, extends|
+    extends.concat [ SomeOtherModule ]
+  end
+end
+
+=== define_module_extended
+
+To cause modules to be included when this module is extended:
+
+module SomeModule
+  define_module_extended do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+  end
+end
+
+or extended when this module is extended:
+
+module SomeModule
+  define_module_extended do |includes, extends|
+    extends.concat [ SomeOtherModule ]
+  end
+end
+
+=== define_module_cluster
+
+To cause modules to be included when this module is included or extended:
+
+module SomeModule
+  define_module_cluster do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+  end
+end
+
+or extended when this module is included or extended:
+
+module SomeModule
+  define_module_cluster do |includes, extends|
+    extends.concat [ SomeOtherModule ]
+  end
+end
+
+=== define_module_included_cascades
+
+To cause modules to be included or extended when this module is used to include in a class or module.
+
+module SomeModule
+  define_module_included_cascades do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+
+=== define_module_extended_cascades
+
+To cause modules to be included or extended when this module is used to extend in a class or module:
+
+module SomeModule
+  define_module_extended_cascades do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+
+=== define_module_cluster_cascades
+
+To cause modules to be included or extended when this module is used to include or extend in a class or module:
+
+module SomeModule
+  define_module_cluster_cascades do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+
+=== define_module_included_cascades_to_class
+
+To cause modules to be included or extended when this module is used to include a class (and not a module):
+
+module SomeModule
+  define_module_included_cascades_to_class do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+
+=== define_module_extended_cascades_to_class
+
+To cause modules to be included or extended when this module is used to extend a class (and not a module):
+
+module SomeModule
+  define_module_extended_cascades_to_class do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+
+=== define_module_cluster_cascades_to_class
+
+To cause modules to be included or extended when this module is used to include or extend a class (and not a module):
+
+module SomeModule
+  define_module_cluster_cascades_to_class do |includes, extends|
+    includes.concat [ SomeOtherModule ]
+    extends.concat [ SomeOtherModule ]
+  end
+end
+
+== 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/module-cluster.rb

@@ -6,8 +6,16 @@ module ModuleCluster
 	end
 end
 
+class Array::ClassOrModule < Array
+end
+class Array::CascadeToClass < Array
+end
+class Array::CascadeToClassOrModule < Array
+end
+
 require_relative 'module-cluster/ModuleCluster.rb'
 require_relative 'module-cluster/_private_/ModuleCluster.rb'
 require_relative 'module-cluster/ModuleCluster/IncludeExtendSupport.rb'
+require_relative 'module-cluster/ModuleCluster/_private_/IncludeExtendSupport.rb'
 require_relative 'module-cluster/ModuleCluster/IncludeSupport.rb'
 require_relative 'module-cluster/ModuleCluster/ExtendSupport.rb'

data/lib/module-cluster/ModuleCluster.rb

@@ -1,26 +1,26 @@
 
 module ModuleCluster
 
-	#############################
+	############################
 	#  define_module_included  #
-	#############################
+	############################
 
-	def define_module_included( & block )
-		inclusion_array, extension_array = yield_for_includes_extends( block )
-		ModuleCluster::IncludeSupport.set_includes_for_class_or_module( self, inclusion_array )
-		ModuleCluster::IncludeSupport.set_extends_for_class_or_module( self, extension_array )
+	def define_module_included( & include_extend_block )
+		inclusion_array, extension_array = yield_for_includes_extends( Array::ClassOrModule.new, Array::ClassOrModule.new, include_extend_block )
+		ModuleCluster::IncludeSupport.add_includes_for_class_or_module( self, inclusion_array )
+		ModuleCluster::IncludeSupport.add_extends_for_class_or_module( self, extension_array )
 		extend ModuleCluster::IncludeSupport
 		return self
 	end
 
-	#############################
+	############################
 	#  define_module_extended  #
-	#############################
+	############################
 	
-	def define_module_extended( & block )
-		inclusion_array, extension_array = yield_for_includes_extends( block )
-		ModuleCluster::ExtendSupport.set_includes_for_class_or_module( self, inclusion_array )
-		ModuleCluster::ExtendSupport.set_extends_for_class_or_module( self, extension_array )
+	def define_module_extended( & include_extend_block )
+		inclusion_array, extension_array = yield_for_includes_extends( Array::ClassOrModule.new, Array::ClassOrModule.new, include_extend_block )
+		ModuleCluster::ExtendSupport.add_includes_for_class_or_module( self, inclusion_array )
+		ModuleCluster::ExtendSupport.add_extends_for_class_or_module( self, extension_array )
 		extend ModuleCluster::ExtendSupport
 		return self
 	end
@@ -35,4 +35,92 @@ module ModuleCluster
 		return self
 	end
 
+	#####################################
+	#  define_module_included_cascades  #
+	#####################################
+
+	def define_module_included_cascades( & include_extend_block )
+		# any time we are included or extended in a module we want to add cascading extends:
+		# * to the module cascading includes
+		# any time we are included in a class we want to add cascading extends
+		# * to the class
+		inclusion_array, extension_array = yield_for_includes_extends( Array::CascadeToClassOrModule.new, Array::CascadeToClassOrModule.new, include_extend_block )
+		ModuleCluster::IncludeSupport.add_cascading_includes_for_class_or_module( self, inclusion_array )
+		ModuleCluster::IncludeSupport.add_cascading_extends_for_class_or_module( self, extension_array )
+		extend ModuleCluster::IncludeSupport
+		return inclusion_array, extension_array
+	end
+	
+	#####################################
+	#  define_module_extended_cascades  #
+	#####################################
+
+	def define_module_extended_cascades( & include_extend_block )
+		# any time we are included or extended in a module we want to add cascading extends:
+		# * to the module cascading extends
+		# any time we are extended in a class we want to add cascading extends
+		# * to the class
+		inclusion_array, extension_array = yield_for_includes_extends( Array::CascadeToClassOrModule.new, Array::CascadeToClassOrModule.new, include_extend_block )
+		ModuleCluster::ExtendSupport.add_cascading_includes_for_class_or_module( self, inclusion_array )
+		ModuleCluster::ExtendSupport.add_cascading_extends_for_class_or_module( self, extension_array )
+		extend ModuleCluster::ExtendSupport
+		return inclusion_array, extension_array
+	end
+	
+	####################################
+	#  define_module_cluster_cascades  #
+	####################################
+
+	def define_module_cluster_cascades( & include_extend_block )
+		include_includes, include_extends = define_module_included_cascades( & include_extend_block )
+		extend_includes, extend_extends = define_module_extended_cascades( & include_extend_block )
+		ModuleCluster::IncludeSupport.set_as_cluster( self, include_includes, include_extends )
+		ModuleCluster::ExtendSupport.set_as_cluster( self, extend_includes, extend_extends )
+		return self
+	end
+
+	##############################################
+	#  define_module_included_cascades_to_class  #
+	##############################################
+
+	def define_module_included_cascades_to_class( & include_extend_block )
+		# any time we are included or extended in a module we want to add cascading extends:
+		# * to the module cascading includes
+		# any time we are included in a class we want to add cascading extends
+		# * to the class
+		inclusion_array, extension_array = yield_for_includes_extends( Array::CascadeToClass.new, Array::CascadeToClass.new, include_extend_block )
+		ModuleCluster::IncludeSupport.add_cascading_includes_for_class( self, inclusion_array )
+		ModuleCluster::IncludeSupport.add_cascading_extends_for_class( self, extension_array )
+		extend ModuleCluster::IncludeSupport
+		return inclusion_array, extension_array
+	end
+	
+	##############################################
+	#  define_module_extended_cascades_to_class  #
+	##############################################
+
+	def define_module_extended_cascades_to_class( & include_extend_block )
+		# any time we are included or extended in a module we want to add cascading extends:
+		# * to the module cascading extends
+		# any time we are extended in a class we want to add cascading extends
+		# * to the class
+		inclusion_array, extension_array = yield_for_includes_extends( Array::CascadeToClass.new, Array::CascadeToClass.new, include_extend_block )
+		ModuleCluster::ExtendSupport.add_cascading_includes_for_class( self, inclusion_array )
+		ModuleCluster::ExtendSupport.add_cascading_extends_for_class( self, extension_array )
+		extend ModuleCluster::ExtendSupport
+		return inclusion_array, extension_array
+	end
+	
+	#############################################
+	#  define_module_cluster_cascades_to_class  #
+	#############################################
+
+	def define_module_cluster_cascades_to_class( & include_extend_block )
+		include_includes, include_extends = define_module_included_cascades_to_class( & include_extend_block )
+		extend_includes, extend_extends = define_module_extended_cascades_to_class( & include_extend_block )
+		ModuleCluster::IncludeSupport.set_as_cluster( self, include_includes, include_extends )
+		ModuleCluster::ExtendSupport.set_as_cluster( self, extend_includes, extend_extends )
+		return self
+	end
+	
 end