parallel_ancestry 1.0.0 → 1.0.1

data/{CHANGELOG.rdoc → CHANGELOG.md}

@@ -1,32 +1,32 @@
 
-== 6/10/2012
+## 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
+## 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
+## 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
+## 6/15/2012 ##
 
 Added unique-array for children and parents, which means now :include? etc. use hash lookup internally.
 
-== 6/18/2012
+## 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
+## 6/19/2012 ##
 
 Changed include/extend hooks to prepend.
 
-== 7/06/2012
+## 7/06/2012 ##
 
 Renamed to parallel_ancestry.

data/lib/namespaces.rb

@@ -0,0 +1,3 @@
+
+module ::ParallelAncestry  
+end

data/lib/parallel_ancestry.rb

@@ -2,23 +2,363 @@
 require 'module/cluster'
 require 'array/unique'
 
+# namespaces that have to be declared ahead of time for proper load order
+require_relative './namespaces'
+
+# source file requires
+require_relative './requires.rb'
+
 module ::ParallelAncestry
+
+  InstanceAncestryStruct = ::Struct.new( :children, :parents )
+
+  extend ::Module::Cluster
   
-end
+  # Initialize any module extended with self for inheritance hooks
+  cluster( :parallel_ancestry ).after_extend( :module ) do |ancestors_module|    
+    ancestors_module.module_eval do
+      @ancestors_hash = { }
+    end
+  end
+  
+  # Initialize any subclass of module including self for inheritance hooks
+  cluster( :parallel_ancestry ).after_include( :class ) do |class_instance|
+    if class_instance < ::Module
+      class_instance.module_eval do
+        include( ::ParallelAncestry::ModuleSubclassInheritance )
+      end
+    end
+  end
+  
+  extend self
+  
+  ##############
+  #  children  #
+  ##############
+  
+  # Return a list of children for provided object.
+  # @param [Object] instance Object instance.
+  # @return [Array<Object>] An array containing references to children.
+  def children( instance )
+    
+    return ancestor_struct( instance ).children ||= ::Array::Unique.new( self )
 
-basepath = 'parallel_ancestry/parallel_ancestry'
+  end
 
-files = [
+  #############
+  #  parents  #
+  #############
   
-  'inheritance',
-  'inheritance/module_subclass_inheritance',
+  # Return a list of parents for provided object.
+  # @param [Object] instance Object instance.
+  # @return [Array<Object>] An array containing references to immediate parents for any configuration.
+  def parents( instance )
+    
+    return ancestor_struct( instance ).parents ||= ::Array::Unique.new( self )
 
-  'module_subclass_inheritance'
+  end
+
+  ##################
+  #  has_parents?  #
+  ##################
+  
+  # Return whether provided object has parents.
+  # @param [Object] instance Object instance.
+  # @return [true, false] true or false.
+  def has_parents?( instance )
     
-]
+    return ! parents( instance ).empty?
 
-files.each do |this_file|
-  require_relative( File.join( basepath, this_file ) + '.rb' )
-end
+  end
+
+  ###################
+  #  has_children?  #
+  ###################
+  
+  # Return whether provided object has children.
+  # @param [Object] instance Object instance.
+  # @return [true, false] true or false.
+  def has_children?( instance )
+    
+    return ! children( instance ).empty?
+
+  end
+
+  ###############################
+  #  register_child_for_parent  #
+  ###############################
+  
+  # Register instance as child of another instance.
+  # @param [Object] child Child instance.
+  # @param [Object] parent Parent instance.
+  # @return [Array<Object>] An array containing references to children.
+  def register_child_for_parent( child, parent )
+
+    parents_of_child = parents( child )
+    children_of_parent = children( parent )
 
-require_relative( basepath + '.rb' )
+    # child order shouldn't be relevant
+    children_of_parent.push( child )
+    
+    # parent order determines who wins conflicts, so we keep youngest first
+    parents_of_child.unshift( parent )
+
+    return self
+
+  end
+
+  ##############
+  #  ancestor  #
+  ##############
+  
+  # Return parent for instance that matches match_ancestor_block.
+  # @param [Object] instance Child instance.
+  # @yield Block used to match parent. The parameter is the parent instance, the return value true
+  #        or false, reflecting whether or not block matched ancestor.
+  # @example
+  #   ::ParallelAncestry.ancestor( some_instance ) do |this_parent|
+  #     if this_parent.matches_arbitrary_condition
+  #       true
+  #     else
+  #       false
+  #     end
+  #   end
+  # @return [Object] A reference to parent matching block condition.
+  def ancestor( instance, & match_ancestor_block )
+    
+    ancestor_instance = nil
+    
+    parents = parents( instance )
+    
+    # If we don't have ancestors explicitly declared for this instance, and if it is not 
+    # a ::Class or ::Module (both are ::Modules) then we have an instance of a class,
+    # so we can use the instance's class
+    if parents.empty? and instance != ::Class
+      
+      instance_class = instance.class
+      if match_ancestor_block.call( instance_class )
+        ancestor_instance = instance.class
+      end
+          
+    else
+
+      parents.each do |this_parent|
+        # we need a way to go from multiple parents to the one that makes up this chain
+        # we use the match_ancestor_block to determine this - it should return true/false
+        if match_ancestor_block.call( this_parent )
+          ancestor_instance = this_parent
+          break
+        end
+      end
+
+    end
+    
+    return ancestor_instance
+    
+  end
+  
+  alias_method :parent, :ancestor
+  
+  ####################
+  #  ancestor_chain  #
+  ####################
+  
+  # Returns ancestor chain defined for provided object.
+  # @param [Object] instance Instance for which ancestors are being looked up.
+  # @yield Block used to match parent. The parameter is the parent instance, the return value true
+  #        or false, reflecting whether or not block matched ancestor.
+  # @example
+  #   ::ParallelAncestry.ancestor( some_instance ) do |this_parent|
+  #     if this_parent.matches_arbitrary_condition
+  #       true
+  #     else
+  #       false
+  #     end
+  #   end
+  # @return [Array<Object>] An array containing references to parents matching block condition.
+  def ancestor_chain( instance, & match_ancestor_block )
+    
+    ancestor_chain = [ this_ancestor = instance ]
+
+    while this_ancestor = ancestor( this_ancestor, & match_ancestor_block )
+      ancestor_chain.push( this_ancestor )
+    end
+    
+    return ancestor_chain
+    
+  end
+
+  ####################
+  #  lowest_parents  #
+  ####################
+  
+  # Returns the lowest parent in each parent tree matching block condition. For simple linear
+  # trees, this is simply the first parent, but more complex trees quickly diverge into multiple
+  # branches, each of which then requires a lowest match.
+  # @param [Object] instance Instance for which parents are being looked up.
+  # @yield Block used to match parent. The parameter is the parent instance, the return value true
+  #        or false, reflecting whether or not block matched ancestor.
+  # @example
+  #   ::ParallelAncestry.lowest_parents( some_instance ) do |this_parent|
+  #     if this_parent.matches_arbitrary_condition
+  #       true
+  #     else
+  #       false
+  #     end
+  #   end
+  # @return [Array<Object>] An array containing references to lowest parent in each parent tree 
+  #   matching block condition.
+  def lowest_parents( instance, & match_ancestor_block )
+
+    # the first super module available for each tree
+
+    lowest_parents_array = [ ]
+
+    parents( instance ).each do |this_parent|
+      
+      # if we match this parent we are done with this branch and can go to the next
+      if match_ancestor_block.call( this_parent )
+
+        lowest_parents_array.push( this_parent )
+
+      # otherwise our branch expands and we have to finish it before the next parent
+      elsif has_parents?( this_parent )
+
+        parents_for_branch = lowest_parents( this_parent, & match_ancestor_block )
+
+        lowest_parents_array.concat( parents_for_branch )
+
+      end
+      
+    end
+
+    return lowest_parents_array
+    
+  end
+
+  ######################
+  #  highest_children  #
+  ######################
+  
+  # Returns the highest parent in each parent tree matching block condition. For simple linear
+  # trees, this is simply the first parent, but more complex trees quickly diverge into multiple
+  # branches, each of which then requires a highest match.
+  # @param [Object] instance Instance for which parents are being looked up.
+  # @yield Block used to match parent. The parameter is the parent instance, the return value true
+  #        or false, reflecting whether or not block matched ancestor.
+  # @example
+  #   ::ParallelAncestry.highest_parents( some_instance ) do |this_parent|
+  #     if this_parent.matches_arbitrary_condition
+  #       true
+  #     else
+  #       false
+  #     end
+  #   end
+  # @return [Array<Object>] An array containing references to highest parent in each parent tree 
+  #   matching block condition.
+  def highest_children( instance, & match_ancestor_block )
+
+    # the first super module available for each tree
+
+    highest_children_array = [ ]
+
+    children( instance ).each do |this_child|
+      
+      # if we match this parent we are done with this branch and can go to the next
+      if match_ancestor_block.call( this_child )
+
+        highest_children_array.push( this_child )
+
+      # otherwise our branch expands and we have to finish it before the next parent
+      elsif has_children?( this_child )
+
+        children_for_branch = highest_children( this_child, & match_ancestor_block )
+
+        highest_children_array.concat( children_for_branch )
+
+      end
+      
+    end
+
+    return highest_children_array
+    
+  end
+  
+  ####################
+  #  match_ancestor  #
+  ####################
+
+  # Returns the first ancestor (determined by ancestor_match_block) for which match_block is true.
+  # @param [Object] instance Instance for which parents are being looked up.
+  # @param [Proc] ancestor_match_block Proc used to match parent. The parameter is the parent 
+  #        instance, the return value true or false, reflecting whether or not block matched 
+  #        ancestor.
+  # @yield Block used to match parent. The parameter is the parent instance, the return value true
+  #        or false, reflecting whether or not block matched.
+  # @example
+  #   ancestor_match_block = ::Proc.new do |this_parent|
+  #     if this_parent.matches_arbitrary_condition
+  #       true
+  #     else
+  #       false
+  #     end
+  #   end
+  #   ::ParallelAncestry.match_ancestor( some_instance, ancestor_match_block ) do |this_parent|
+  #     if this_parent.matches_arbitrary_condition
+  #       true
+  #     else
+  #       false
+  #     end
+  #   end
+  # @return [Object] 
+  def match_ancestor( instance, ancestor_match_block, & match_block )
+
+    matched_ancestor = nil
+    
+    this_ancestor = instance
+
+    if has_parents?( this_ancestor )
+
+      begin
+        if match_block.call( this_ancestor )
+          matched_ancestor = this_ancestor
+          break
+        end
+        break if this_ancestor.equal?( ::Object )
+      end while this_ancestor = ancestor( this_ancestor, & ancestor_match_block )
+
+    elsif match_block.call( this_ancestor )
+
+      matched_ancestor = this_ancestor
+      
+    else
+
+      matched_ancestor = match_ancestor( this_ancestor.class, ancestor_match_block, & match_block )
+      
+    end
+
+    return matched_ancestor
+    
+  end
+  
+  ##################################################################################################
+      private ######################################################################################
+  ##################################################################################################
+
+  #####################
+  #  ancestor_struct  #
+  #####################
+  
+  def ancestor_struct( instance )
+    
+    unless ancestor_struct = @ancestors_hash[ instance.__id__ ]
+      # fill in slots lazily
+      ancestor_struct = ::ParallelAncestry::InstanceAncestryStruct.new
+      @ancestors_hash[ instance.__id__ ] = ancestor_struct
+    end
+    
+    return ancestor_struct
+    
+  end
+
+end

data/lib/requires.rb

@@ -0,0 +1,15 @@
+
+basepath = 'parallel_ancestry'
+
+files = [
+  
+  'inheritance',
+  'inheritance/module_subclass_inheritance',
+
+  'module_subclass_inheritance'
+    
+]
+
+files.each do |this_file|
+  require_relative( File.join( basepath, this_file ) + '.rb' )
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parallel_ancestry
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -58,16 +58,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/parallel_ancestry/parallel_ancestry/inheritance/module_subclass_inheritance.rb
-- lib/parallel_ancestry/parallel_ancestry/inheritance.rb
-- lib/parallel_ancestry/parallel_ancestry/module_subclass_inheritance.rb
-- lib/parallel_ancestry/parallel_ancestry.rb
+- lib/namespaces.rb
+- lib/parallel_ancestry/inheritance/module_subclass_inheritance.rb
+- lib/parallel_ancestry/inheritance.rb
+- lib/parallel_ancestry/module_subclass_inheritance.rb
 - lib/parallel_ancestry.rb
+- lib/requires.rb
 - spec/parallel_ancestry/inheritance_spec.rb
 - spec/parallel_ancestry_spec.rb
 - README.md
-- README.rdoc
-- CHANGELOG.rdoc
+- CHANGELOG.md
 homepage: http://rubygems.org/gems/parallel_ancestry
 licenses: []
 post_install_message: 

data/README.rdoc

@@ -1,125 +0,0 @@
-== 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.rb

@@ -1,355 +0,0 @@
-
-module ::ParallelAncestry
-
-  InstanceAncestryStruct = ::Struct.new( :children, :parents )
-
-  extend ::Module::Cluster
-  
-  # Initialize any module extended with self for inheritance hooks
-  cluster( :parallel_ancestry ).after_extend( :module ) do |ancestors_module|    
-    ancestors_module.module_eval do
-      @ancestors_hash = { }
-    end
-  end
-  
-  # Initialize any subclass of module including self for inheritance hooks
-  cluster( :parallel_ancestry ).after_include( :class ) do |class_instance|
-    if class_instance < ::Module
-      class_instance.module_eval do
-        include( ::ParallelAncestry::ModuleSubclassInheritance )
-      end
-    end
-  end
-  
-  extend self
-  
-  ##############
-  #  children  #
-  ##############
-  
-  # Return a list of children for provided object.
-  # @param [Object] instance Object instance.
-  # @return [Array<Object>] An array containing references to children.
-  def children( instance )
-    
-    return ancestor_struct( instance ).children ||= ::Array::Unique.new( self )
-
-  end
-
-  #############
-  #  parents  #
-  #############
-  
-  # Return a list of parents for provided object.
-  # @param [Object] instance Object instance.
-  # @return [Array<Object>] An array containing references to immediate parents for any configuration.
-  def parents( instance )
-    
-    return ancestor_struct( instance ).parents ||= ::Array::Unique.new( self )
-
-  end
-
-  ##################
-  #  has_parents?  #
-  ##################
-  
-  # Return whether provided object has parents.
-  # @param [Object] instance Object instance.
-  # @return [true, false] true or false.
-  def has_parents?( instance )
-    
-    return ! parents( instance ).empty?
-
-  end
-
-  ###################
-  #  has_children?  #
-  ###################
-  
-  # Return whether provided object has children.
-  # @param [Object] instance Object instance.
-  # @return [true, false] true or false.
-  def has_children?( instance )
-    
-    return ! children( instance ).empty?
-
-  end
-
-  ###############################
-  #  register_child_for_parent  #
-  ###############################
-  
-  # Register instance as child of another instance.
-  # @param [Object] child Child instance.
-  # @param [Object] parent Parent instance.
-  # @return [Array<Object>] An array containing references to children.
-  def register_child_for_parent( child, parent )
-
-    parents_of_child = parents( child )
-    children_of_parent = children( parent )
-
-    # child order shouldn't be relevant
-    children_of_parent.push( child )
-    
-    # parent order determines who wins conflicts, so we keep youngest first
-    parents_of_child.unshift( parent )
-
-    return self
-
-  end
-
-  ##############
-  #  ancestor  #
-  ##############
-  
-  # Return parent for instance that matches match_ancestor_block.
-  # @param [Object] instance Child instance.
-  # @yield Block used to match parent. The parameter is the parent instance, the return value true
-  #        or false, reflecting whether or not block matched ancestor.
-  # @example
-  #   ::ParallelAncestry.ancestor( some_instance ) do |this_parent|
-  #     if this_parent.matches_arbitrary_condition
-  #       true
-  #     else
-  #       false
-  #     end
-  #   end
-  # @return [Object] A reference to parent matching block condition.
-  def ancestor( instance, & match_ancestor_block )
-    
-    ancestor_instance = nil
-    
-    parents = parents( instance )
-    
-    # If we don't have ancestors explicitly declared for this instance, and if it is not 
-    # a ::Class or ::Module (both are ::Modules) then we have an instance of a class,
-    # so we can use the instance's class
-    if parents.empty? and instance != ::Class
-      
-      instance_class = instance.class
-      if match_ancestor_block.call( instance_class )
-        ancestor_instance = instance.class
-      end
-          
-    else
-
-      parents.each do |this_parent|
-        # we need a way to go from multiple parents to the one that makes up this chain
-        # we use the match_ancestor_block to determine this - it should return true/false
-        if match_ancestor_block.call( this_parent )
-          ancestor_instance = this_parent
-          break
-        end
-      end
-
-    end
-    
-    return ancestor_instance
-    
-  end
-  
-  alias_method :parent, :ancestor
-  
-  ####################
-  #  ancestor_chain  #
-  ####################
-  
-  # Returns ancestor chain defined for provided object.
-  # @param [Object] instance Instance for which ancestors are being looked up.
-  # @yield Block used to match parent. The parameter is the parent instance, the return value true
-  #        or false, reflecting whether or not block matched ancestor.
-  # @example
-  #   ::ParallelAncestry.ancestor( some_instance ) do |this_parent|
-  #     if this_parent.matches_arbitrary_condition
-  #       true
-  #     else
-  #       false
-  #     end
-  #   end
-  # @return [Array<Object>] An array containing references to parents matching block condition.
-  def ancestor_chain( instance, & match_ancestor_block )
-    
-    ancestor_chain = [ this_ancestor = instance ]
-
-    while this_ancestor = ancestor( this_ancestor, & match_ancestor_block )
-      ancestor_chain.push( this_ancestor )
-    end
-    
-    return ancestor_chain
-    
-  end
-
-  ####################
-  #  lowest_parents  #
-  ####################
-  
-  # Returns the lowest parent in each parent tree matching block condition. For simple linear
-  # trees, this is simply the first parent, but more complex trees quickly diverge into multiple
-  # branches, each of which then requires a lowest match.
-  # @param [Object] instance Instance for which parents are being looked up.
-  # @yield Block used to match parent. The parameter is the parent instance, the return value true
-  #        or false, reflecting whether or not block matched ancestor.
-  # @example
-  #   ::ParallelAncestry.lowest_parents( some_instance ) do |this_parent|
-  #     if this_parent.matches_arbitrary_condition
-  #       true
-  #     else
-  #       false
-  #     end
-  #   end
-  # @return [Array<Object>] An array containing references to lowest parent in each parent tree 
-  #   matching block condition.
-  def lowest_parents( instance, & match_ancestor_block )
-
-    # the first super module available for each tree
-
-    lowest_parents_array = [ ]
-
-    parents( instance ).each do |this_parent|
-      
-      # if we match this parent we are done with this branch and can go to the next
-      if match_ancestor_block.call( this_parent )
-
-        lowest_parents_array.push( this_parent )
-
-      # otherwise our branch expands and we have to finish it before the next parent
-      elsif has_parents?( this_parent )
-
-        parents_for_branch = lowest_parents( this_parent, & match_ancestor_block )
-
-        lowest_parents_array.concat( parents_for_branch )
-
-      end
-      
-    end
-
-    return lowest_parents_array
-    
-  end
-
-  ######################
-  #  highest_children  #
-  ######################
-  
-  # Returns the highest parent in each parent tree matching block condition. For simple linear
-  # trees, this is simply the first parent, but more complex trees quickly diverge into multiple
-  # branches, each of which then requires a highest match.
-  # @param [Object] instance Instance for which parents are being looked up.
-  # @yield Block used to match parent. The parameter is the parent instance, the return value true
-  #        or false, reflecting whether or not block matched ancestor.
-  # @example
-  #   ::ParallelAncestry.highest_parents( some_instance ) do |this_parent|
-  #     if this_parent.matches_arbitrary_condition
-  #       true
-  #     else
-  #       false
-  #     end
-  #   end
-  # @return [Array<Object>] An array containing references to highest parent in each parent tree 
-  #   matching block condition.
-  def highest_children( instance, & match_ancestor_block )
-
-    # the first super module available for each tree
-
-    highest_children_array = [ ]
-
-    children( instance ).each do |this_child|
-      
-      # if we match this parent we are done with this branch and can go to the next
-      if match_ancestor_block.call( this_child )
-
-        highest_children_array.push( this_child )
-
-      # otherwise our branch expands and we have to finish it before the next parent
-      elsif has_children?( this_child )
-
-        children_for_branch = highest_children( this_child, & match_ancestor_block )
-
-        highest_children_array.concat( children_for_branch )
-
-      end
-      
-    end
-
-    return highest_children_array
-    
-  end
-  
-  ####################
-  #  match_ancestor  #
-  ####################
-
-  # Returns the first ancestor (determined by ancestor_match_block) for which match_block is true.
-  # @param [Object] instance Instance for which parents are being looked up.
-  # @param [Proc] ancestor_match_block Proc used to match parent. The parameter is the parent 
-  #        instance, the return value true or false, reflecting whether or not block matched 
-  #        ancestor.
-  # @yield Block used to match parent. The parameter is the parent instance, the return value true
-  #        or false, reflecting whether or not block matched.
-  # @example
-  #   ancestor_match_block = ::Proc.new do |this_parent|
-  #     if this_parent.matches_arbitrary_condition
-  #       true
-  #     else
-  #       false
-  #     end
-  #   end
-  #   ::ParallelAncestry.match_ancestor( some_instance, ancestor_match_block ) do |this_parent|
-  #     if this_parent.matches_arbitrary_condition
-  #       true
-  #     else
-  #       false
-  #     end
-  #   end
-  # @return [Object] 
-  def match_ancestor( instance, ancestor_match_block, & match_block )
-
-    matched_ancestor = nil
-    
-    this_ancestor = instance
-
-    if has_parents?( this_ancestor )
-
-      begin
-        if match_block.call( this_ancestor )
-          matched_ancestor = this_ancestor
-          break
-        end
-        break if this_ancestor.equal?( ::Object )
-      end while this_ancestor = ancestor( this_ancestor, & ancestor_match_block )
-
-    elsif match_block.call( this_ancestor )
-
-      matched_ancestor = this_ancestor
-      
-    else
-
-      matched_ancestor = match_ancestor( this_ancestor.class, ancestor_match_block, & match_block )
-      
-    end
-
-    return matched_ancestor
-    
-  end
-  
-  ##################################################################################################
-      private ######################################################################################
-  ##################################################################################################
-
-  #####################
-  #  ancestor_struct  #
-  #####################
-  
-  def ancestor_struct( instance )
-    
-    unless ancestor_struct = @ancestors_hash[ instance.__id__ ]
-      # fill in slots lazily
-      ancestor_struct = ::ParallelAncestry::InstanceAncestryStruct.new
-      @ancestors_hash[ instance.__id__ ] = ancestor_struct
-    end
-    
-    return ancestor_struct
-    
-  end
-
-end