parallel_ancestry 1.0.0

data/CHANGELOG.rdoc

@@ -0,0 +1,32 @@
+
+== 6/10/2012
+
+Initial release abstracted to be entirely independent from cascading-configuration.
+Replaces cascading-configuration-inheritance and cascading-configuration-ancestors without any cascading-configuration dependencies.
+
+== 6/11/2012
+
+Added YARD docs.
+Shortened :initialize_base_instance_for_include and :initialize_base_instance_for_extend parameters to remove reference to self, since self is already present as block receiver.
+
+== 6/12/2012
+
+Renamed :match_ancestor_searching_upward to :match_ancestor because ancestors are always found by searching upward.
+Fixes for ancestor lookup when arriving at Class.
+
+== 6/15/2012
+
+Added unique-array for children and parents, which means now :include? etc. use hash lookup internally.
+
+== 6/18/2012
+
+Added is_extending parameter (default = false) to :initialize_inheriting_instance.
+Fix for subclass inheritance passing subclass instance (self) rather than class instance.
+
+== 6/19/2012
+
+Changed include/extend hooks to prepend.
+
+== 7/06/2012
+
+Renamed to parallel_ancestry.

data/README.md

@@ -0,0 +1,137 @@
+# Parallel Ancestry #
+
+http://rubygems.org/gems/parallel_ancestry
+
+# Summary #
+
+Provides parallel implementations of inheritance hierarchies. This is useful both for tracking the existing inheritance tree and for creating trees that function independently of inheritance models determined internal to Ruby.
+
+# Description #
+
+Create and track parallel inheritance hierarchies.
+
+Hook parallel hierarchies (by including a module) to automatically update/register ancestry at include and extend, or update/register only manually. 
+
+Manual registration permits definitions of ancestry across, for example, instances of the same type or instances of entirely different types. 
+
+Implementation is provided by simple child/parent trees with an block to choose which parent. This permits a simple multiple inheritance model very similar to how Ruby handles modules. Conflicts for multiple inheritance are resolved by the parent most recently named for the block match.
+
+Used heavily by CascadingConfiguration gem (cascading-configuration) as well as by forthcoming Persistence and Magnets gems (persistence and magnets).
+
+# Install #
+
+* sudo gem install parallel_ancestry
+
+# Usage #
+
+Two modules are provided by Parallel Ancestry:
+
+1. ::ParallelAncestry, which provides parallel inheritance.
+2. ::ParallelAncestry::Inheritance, which provides cascading inheritance hooks.
+
+## ::ParallelAncestry ##
+
+::ParallelAncestry provides parallel inheritance registration and lookup. This is useful for tracking arbitrary trees of ancestry relations (determined by manual registration), and can be combined with ::ParallelAncestry::Inheritance for automatic registration in correspondence with Ruby's inheritance relations.
+
+3 ways to use:
+
+1. ::ParallelAncestry provides a singleton implementation for parallel inheritance.
+2. Extend any module with ::ParallelAncestry to enable module as singleton implementation for parallel inheritance.
+3. Include ::ParallelAncestry in subclass of ::Module to enable instances of ::Module subclass as individual implementations for parallel inheritance.
+
+Parallel ancestry instances support registration and lookup of arbitrarily declared ancestor relationships:
+
+* children( instance )
+* parents( instance )
+* has_parents?( instance )
+* has_children?( instance )
+* register_child_for_parent( child, parent )
+* ancestor( instance, & match_ancestor_block )
+* ancestor_chain( instance, & match_ancestor_block )
+* lowest_parents( instance, & match_ancestor_block )
+* highest_children( instance, & match_ancestor_block )
+* match_ancestor( instance, ancestor_match_block, & match_block )
+
+match_block is always a proc or lambda that will be passed the next ancestor as the single parameter and is expected to return true or false whether or not the ancestor matches the condition.
+
+```ruby
+match_block = ::Proc.new do |this_ancestor|
+
+  if this_ancestor.matches_arbitrary_condition
+    true
+  else
+    false
+  end
+
+end
+```
+
+## ::ParallelAncestry::Inheritance ##
+
+::ParallelAncestry::Inheritance provides hooks for Ruby inheritance events.
+
+2 ways to use:
+
+1. Extend any module with ::ParallelAncestry::Inheritance to enable hooks in module singleton.
+2. Include ::ParallelAncestry::Inheritance in subclass of ::Module to enable instance of ::Module subclass wit hooks.
+
+Hooks provided:
+
+* Initialization
+
+```ruby
+def initialize_inheritance!
+  ... [ your hook ] ...
+end
+```
+
+* First include:
+
+```ruby
+def initialize_base_instance_for_include
+  ... [ your hook ] ...
+end
+```
+
+
+* First extend:
+
+```ruby
+def initialize_base_instance_for_extend
+  ... [ your hook ] ...
+end
+```
+
+* Subsequent includes:
+
+
+```ruby
+def initialize_inheriting_instance
+  ... [ your hook ] ...
+end
+```
+
+# License #
+
+  (The MIT License)
+
+  Copyright (c) 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

@@ -0,0 +1,125 @@
+== Parallel Ancestry
+
+http://rubygems.org/gems/parallel_ancestry
+
+== Summary
+
+Provides parallel implementations of inheritance hierarchies. This is useful both for tracking the existing inheritance tree and for creating trees that function independently of inheritance models determined internal to Ruby.
+
+== Description
+
+Create and track parallel inheritance hierarchies.
+
+Hook parallel hierarchies (by including a module) to automatically update/register ancestry at include and extend, or update/register only manually. 
+
+Manual registration permits definitions of ancestry across, for example, instances of the same type or instances of entirely different types. 
+
+Implementation is provided by simple child/parent trees with an block to choose which parent. This permits a simple multiple inheritance model very similar to how Ruby handles modules. Conflicts for multiple inheritance are resolved by the parent most recently named for the block match.
+
+Used heavily by CascadingConfiguration gem (cascading-configuration) as well as by forthcoming Persistence and Magnets gems (persistence and magnets).
+
+== Install
+
+* sudo gem install parallel_ancestry
+
+== Usage
+
+Two modules are provided by Parallel Ancestry:
+
+1. ::ParallelAncestry, which provides parallel inheritance.
+2. ::ParallelAncestry::Inheritance, which provides cascading inheritance hooks.
+
+==  ::ParallelAncestry
+
+::ParallelAncestry provides parallel inheritance registration and lookup. This is useful for tracking arbitrary trees of ancestry relations (determined by manual registration), and can be combined with ::ParallelAncestry::Inheritance for automatic registration in correspondence with Ruby's inheritance relations.
+
+3 ways to use:
+
+1. ::ParallelAncestry provides a singleton implementation for parallel inheritance.
+2. Extend any module with ::ParallelAncestry to enable module as singleton implementation for parallel inheritance.
+3. Include ::ParallelAncestry in subclass of ::Module to enable instances of ::Module subclass as individual implementations for parallel inheritance.
+
+Parallel ancestry instances support registration and lookup of arbitrarily declared ancestor relationships:
+
+* children( instance )
+* parents( instance )
+* has_parents?( instance )
+* has_children?( instance )
+* register_child_for_parent( child, parent )
+* ancestor( instance, & match_ancestor_block )
+* ancestor_chain( instance, & match_ancestor_block )
+* lowest_parents( instance, & match_ancestor_block )
+* highest_children( instance, & match_ancestor_block )
+* match_ancestor( instance, ancestor_match_block, & match_block )
+
+match_block is always a proc or lambda that will be passed the next ancestor as the single parameter and is expected to return true or false whether or not the ancestor matches the condition.
+
+	match_block = ::Proc.new do |this_ancestor|
+
+	  if this_ancestor.matches_arbitrary_condition
+	    true
+	  else
+	    false
+	  end
+
+	end
+
+==  ::ParallelAncestry::Inheritance
+
+::ParallelAncestry::Inheritance provides hooks for Ruby inheritance events.
+
+2 ways to use:
+
+1. Extend any module with ::ParallelAncestry::Inheritance to enable hooks in module singleton.
+2. Include ::ParallelAncestry::Inheritance in subclass of ::Module to enable instance of ::Module subclass wit hooks.
+
+Hooks provided:
+
+* Initialization
+
+def initialize_inheritance!
+  ... [ your hook ] ...
+end
+
+* First include:
+
+def initialize_base_instance_for_include
+  ... [ your hook ] ...
+end
+
+* First extend:
+
+def initialize_base_instance_for_extend
+  ... [ your hook ] ...
+end
+
+* Subsequent includes:
+
+def initialize_inheriting_instance
+  ... [ your hook ] ...
+end
+
+== License
+
+  (The MIT License)
+
+  Copyright (c) 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/parallel_ancestry/parallel_ancestry/inheritance/module_subclass_inheritance.rb

@@ -0,0 +1,18 @@
+
+module ::ParallelAncestry::Inheritance::ModuleSubclassInheritance
+
+  ################
+  #  initialize  #
+  ################
+  
+  # define with *args so we can be inserted anywhere in inheritance chain
+  def initialize( *args )
+    
+    # call super if defined so we can be inserted anywhere in inheritance chain
+    super if defined?( super )
+    
+    initialize_inheritance_for_module!
+    
+  end
+
+end

data/lib/parallel_ancestry/parallel_ancestry/inheritance.rb

@@ -0,0 +1,138 @@
+
+module ::ParallelAncestry::Inheritance
+  
+  # Provides hooks for inheritance events:
+  # * Initialization:       :initialize_inheritance!
+  # * First include:        :initialize_base_instance_for_include
+  # * First extend:         :initialize_base_instance_for_extend
+  # * Subsequent includes:  :initialize_inheriting_instance
+  
+  extend ::Module::Cluster
+
+  ##################################################################################################
+  ##################################  Inheritance Initialization  ##################################
+  ##################################################################################################
+
+  # We want to enable any module extended with self or any subclass of Module including self
+
+  # Initialize any module extended with self for inheritance hooks
+  cluster( :parallel_ancestry ).after_extend do |inheritance_module|
+    inheritance_module.initialize_inheritance_for_module!
+  end
+
+  # Initialize any subclass of module including self for inheritance hooks
+  cluster( :parallel_ancestry ).after_include do |class_instance|
+    if class_instance < ::Module
+      class_instance.module_eval do
+        include( ::ParallelAncestry::Inheritance::ModuleSubclassInheritance )
+      end
+    end
+  end
+  
+  ########################################
+  #  initialize_inheritance_for_module!  #
+  ########################################
+
+  def initialize_inheritance_for_module!
+
+    @initialized_inheritance_for_instance = { }
+    
+    extend ::Module::Cluster
+    
+    # When inheritance module is included in another module:
+    cluster( :parallel_ancestry ).before_include do |base_instance|
+      initialize_base_instance_for_include( base_instance )
+    end
+
+    # When inheritance module is used to extend another module:
+    cluster( :parallel_ancestry ).before_extend do |base_instance|
+      initialize_base_instance_for_extend( base_instance )
+    end
+    
+    return self
+    
+  end
+  
+  ##################################################################################################
+  ##############################  Base Configuration Initialization  ###############################
+  ##################################################################################################
+  
+  ##########################################
+  #  initialize_base_instance_for_include  #
+  ##########################################
+  
+  def initialize_base_instance_for_include( inheriting_instance )
+
+    # Initialize for future inheriting instances.
+    return initialize_inheritance( inheriting_instance )
+    
+  end
+
+  #########################################
+  #  initialize_base_instance_for_extend  #
+  #########################################
+
+  def initialize_base_instance_for_extend( inheriting_instance )
+  
+    # Hook for extended module to redefine - nothing to do.
+    
+    return inheriting_instance
+    
+  end
+
+  ##################################################################################################
+  ###########################  Inheriting Configuration Initialization  ############################
+  ##################################################################################################
+
+  ############################
+  #  initialize_inheritance  #
+  ############################
+  
+  def initialize_inheritance( instance )
+    
+    unless @initialized_inheritance_for_instance[ instance ]
+
+      inheritance_module = self
+
+      if instance.is_a?( ::Class )
+
+        instance.extend( ::Module::Cluster )
+        
+        instance.cluster( :parallel_ancestry ).subclass do |inheriting_subclass|
+          inheritance_module.initialize_inheriting_instance( self, inheriting_subclass, true )
+        end
+
+      else
+
+        instance.extend( ::Module::Cluster )
+
+        instance.cluster( :parallel_ancestry ).before_include do |inheriting_module|
+          inheritance_module.initialize_inheriting_instance( instance, inheriting_module )
+          inheritance_module.initialize_inheritance( inheriting_module )
+        end
+
+        instance.cluster( :parallel_ancestry ).before_extend do |inheriting_module|
+          inheritance_module.initialize_inheriting_instance( instance, inheriting_module, false, true )
+        end
+        
+      end
+
+      @initialized_inheritance_for_instance[ instance ] = true
+    
+    end
+  
+  end
+
+  ####################################
+  #  initialize_inheriting_instance  #
+  ####################################
+
+  def initialize_inheriting_instance( parent_instance, inheriting_instance, for_subclass = false, is_extending = false )
+
+    # Hook for extended module to redefine - nothing to do.
+
+    return inheriting_instance
+    
+  end
+
+end

data/lib/parallel_ancestry/parallel_ancestry/module_subclass_inheritance.rb

@@ -0,0 +1,18 @@
+
+module ::ParallelAncestry::ModuleSubclassInheritance
+
+  ################
+  #  initialize  #
+  ################
+  
+  # define with *args so we can be inserted anywhere in inheritance chain
+  def initialize( *args )
+    
+    # call super if defined so we can be inserted anywhere in inheritance chain
+    super if defined?( super )
+
+    @ancestors_hash = { }
+    
+  end
+
+end