ruleby 0.1 → 0.2

data/lib/core/engine.rb

@@ -73,6 +73,17 @@ module Ruleby
     attr_accessor:pattern   
     attr_reader:action, :name
     
+    
+    def when(&block)
+      wb = WhenBuilder.new
+      yield wb
+      @pattern = wb.pattern
+    end
+    
+    def then(&block)
+      @action = Core::Action.new(&block)  
+    end
+    
     def when=(pattern)
       @pattern = pattern
     end
@@ -128,7 +139,11 @@ module Ruleby
       @facts = Array.new
     end
     
-    attr_reader :facts
+    def each_fact
+      @facts.each do |f|
+        yield(f)
+      end
+    end
     
     def assert_fact(fact)
       raise 'The fact asserted cannot be nil!' unless fact.object
@@ -156,12 +171,27 @@ module Ruleby
   end
 
   class Engine        
-    def initialize()
+    def initialize(wm=WorkingMemory.new)
       @root = nil
-      @working_memory = WorkingMemory.new
+      @working_memory = wm
       @conflict_resolver = RulebyConflictResolver.new
     end
-  
+    #assert fact
+    def assert(object,&block)
+      fact_helper(object,:plus,&block)
+    end
+    #retract fact
+    def retract(object,&block)
+      fact_helper(object,:minus,&block)
+    end
+    #modify fact
+    #  retract 
+    #  assert
+    def modify(object,&block)
+      retract(object,&block)
+      assert(object,&block)
+    end
+    
     def assert_fact(fact)
       wm_fact = @working_memory.assert_fact fact      
       @root.assert_fact wm_fact if @root != nil
@@ -173,8 +203,8 @@ module Ruleby
     end
     
     def match(agenda=@root.match, used_agenda=[], activation_counter=0)
-      agenda = @conflict_resolver.resolve agenda
-      if(agenda && agenda.length > 0)               
+      while (agenda.length > 0)
+        agenda = @conflict_resolver.resolve agenda            
         activation = agenda.pop   
         used_agenda.push activation     
         activation.fire self
@@ -197,15 +227,23 @@ module Ruleby
           end
         end        
         agenda.delete_if {|a| new_agenda.index(a) == nil}
-        
-        match(agenda, used_agenda, activation_counter+1)
+                
+        activation_counter = activation_counter+1
       end
     end
     
     def print
       @working_memory.print
       @root.print
-    end    
+    end 
+    
+    private 
+    def fact_helper(object, sign=:plus, &block)
+      f = Core::Fact.new object, sign
+      yield f if block_given?
+      assert_fact f
+      f
+    end   
   end  
 end
 end

data/lib/core/nodes.rb

@@ -1,100 +1,19 @@
 module Ruleby
   module Core 
-  
-  # This acts as a base class for all Nodes that wrap a pattern and
-  # output to one or more other Nodes.
-  class Node
-  
-    def initialize(pattern)
-      # the pattern that this node wraps
-      @pattern = pattern
-      
-      # The nodes that this node outputs to (ones that are below it in the 
-      # network).  Currently, there will only be a single value in each list
-      # but in the future, out network will be optimize to remove repeated
-      # nodes.  Thus each node can output to multiple nodes.
-      @out_nodes = []     
-    end    
-        
-    attr_reader :pattern
-    attr_reader :out_nodes    
-    
-    # This method is called when a new MatchResult is added to the system.  It
-    # propagates the new MR by invoking the assert method on all nodes that are
-    # below this Node in the network.
-    def propagate_assert(match_result, fact)
-      @out_nodes.each do |out_node|       
-        out_node.assert(self, match_result, fact)
-      end
-    end
-    
-    # This method is called when an existing MatchResult is remvoed from the 
-    # system.  It propagates the removal by invoking the retract method on all
-    # nodes that are below this Node in the network.
-    def propagate_retract(fact)
-      @out_nodes.each do |out_node|        
-        out_node.retract(self, fact)
-      end
-    end
-    
-    # This method is used to progagate a new MatchResult.  The difference 
-    # in this method is that it propagates MatchResults that were 
-    # generated by a NotNode
-    def propagate_assert_neg(neg_match_result, fact)
-      @out_nodes.each do |out_node|        
-        out_node.assert_neg(self, neg_match_result, fact)
-      end
-    end 
-    
-    # This method is used to progagate the removal of a MatchResult.  The 
-    # difference in this method is that it removes MatchResults that were 
-    # generated by a NotNode
-    def propagate_retract_neg(fact)
-      @out_nodes.each do |out_node|        
-        out_node.retract_neg(self, fact)
-      end
-    end 
-    
-    # This method determines if all common tags have equal values.  If any 
-    # values are not equal then the method returns false.
-    def resolve(mr1, mr2)    
-      mr1.variables.each_key do |t1|
-        mr2.variables.each_key do |t2|
-          if t2 == t1 && mr1.fact_hash[t1] != mr2.fact_hash[t2]
-            return false 
-          end
-        end
-      end 
-      return true
-    end
-    
-    # Determines if a given MatchResult is unmatched by the any of the given
-    # NotMatchResults.
-    #   mr - a MatchResult
-    #   nmrs - a list of MatchResults from a NotNode
-    def matches_not?(mr,nmrs)    
-      nmrs.each do |nmr|   
-        return true if resolve(mr,nmr)  
-      end 
-      return false
-    end
-  end
 
   # This class acts as the root-node of the network.  It contains the logic
   # for building the node-network from a set of rules, and updating it
   # according to the working memory
-  class RootNode       
-    
+  class RootNode          
     def initialize(working_memory)
       @working_memory = working_memory
-      
-      # we need to use our own data structure (NodeNetworkArray) for the most 
-      # efficient indexing of nodes.  Also, it creates some mappings that will 
-      # be used later on to avoid repeatedly iterating over lists. 
-      @object_nodes = NodeNetworkArray.new   
-      
-      @join_nodes = Array.new        
-      @terminal_nodes = Array.new  
+
+      # TODO once node sharing is implemented, @type_nodes will be a 
+      # Class=>TypeNode Hash.
+      @type_nodes = [] 
+      @atom_nodes = [] 
+      @join_nodes = []
+      @terminal_nodes = []
     end
   
     # This method is invoked when a new rule is added to the system.  The
@@ -102,8 +21,7 @@ module Ruleby
     def assert_rule(rule)
       pattern = rule.pattern       
       terminal_node = TerminalNode.new rule          
-      node = build_network(pattern, terminal_node)         
-      terminal_node.parent_node = node # only used to print the network      
+      build_network(pattern, terminal_node)             
       @terminal_nodes.push terminal_node
     end
     
@@ -117,140 +35,147 @@ module Ruleby
     #  is above (i.e. it outputs to) the given node.
     def build_network(pattern, out_node, side=nil) 
       if (pattern.kind_of?(ObjectPattern))            
-        return create_object_node(pattern, out_node, side) 
+        atom_node = create_atom_nodes(pattern, out_node, side) 
+        #out_node.parent_nodes.push atom_node # only used to print network
+        return atom_node
       else  
         join_node = create_join_node(pattern, out_node, side)  
         build_network(pattern.left_pattern, join_node, :left)
         build_network(pattern.right_pattern, join_node, :right) 
+        out_node.parent_nodes.push join_node # only used to print network
         return join_node 
       end
     end
     private:build_network
           
-    # Creates an ObjectNode, puts it at the top of the network, and stores
-    # the node below it into its memory. It also checks the working memory to 
-    # see if its conditions are satisfied by the exisiting facts.    
-    #  pattern - the ObjectPattern that the created node wraps
-    #  out_node - the Node that this pattern is directly above in the network
-    #  side - if the out_node is a JoinNode, this marks the side of the new node
-    def create_object_node(pattern, out_node, side) 
-      obj_node = nil
-      if (pattern.kind_of?(NotPattern))
-        obj_node = NotNode.new(pattern)
-      else
-        obj_node = ObjectNode.new(pattern)    
-      end
+    # This method is used to create the atom nodes that make up the given 
+    # pattern's network.  It returns the node that is at the top of the network
+    # for the pattern.
+    #   pattern - the Pattern that the created node wraps
+    #   out_node - the Node that this pattern is directly above in thw network
+    #   side - if the out_node is a JoinNode, this marks the side of the new node
+    def create_atom_nodes(pattern, out_node, side)       
+      type_node = create_type_node(pattern.atoms[0])
       
-      if side==:left
-        out_node.left_input = obj_node
-      elsif side==:right
-        out_node.right_input = obj_node
-      end
+      parent_node = type_node
+      for i in (1..(pattern.atoms.size-1))
+        node = nil
+        if pattern.atoms[i].kind_of?(SelfReferenceAtom)
+          node = create_self_reference_node(pattern.atoms[i])
+        elsif pattern.atoms[i].kind_of?(ReferenceAtom)
+          node = create_reference_node(pattern.atoms[i])
+          out_node.ref_nodes.push node
+        else
+          node = create_property_node(pattern.atoms[i])
+        end
+        parent_node.out_nodes.push node
+        node.parent_nodes.push parent_node
+        parent_node = node
+      end    
+      out_node.parent_nodes.push parent_node
       
-      # TODO fix this opmtimization so it works 
-      #index = @object_nodes.has_node(obj_node)
-      #if (index == nil)
-        @object_nodes.add(obj_node)
-      #else
-        #obj_node = @object_nodes[obj_node.pattern.head,index]
-        # TODO maybe create and push new "alias" node where the @tags 
-        # do not have to be the same, but the patterns are the same
-      #end
-
-      obj_node.out_nodes.push out_node      
-      compare_node_to_wm(obj_node)      
-      return obj_node     
+      if out_node.kind_of?(JoinNode)
+        adapter_node = create_adapter_node(side)
+        parent_node.out_nodes.push adapter_node
+        parent_node = adapter_node
+      end   
+      
+      parent_node.out_nodes.push out_node            
+      compare_to_wm(type_node)       
+      return type_node     
     end
-    private:create_object_node
+    private:create_atom_nodes
         
     # Creates a JoinNode, puts it at the middle of the network, and stores
     # the node below it into its memory. 
-    #  pattern - the Pattern that the created node wraps
-    #  out_node - the Node that this pattern is directly above in thw network
-    #  side - if the out_node is a JoinNode, this marks the side of the new node
-    def create_join_node(pattern, out_node, side)
-      join_node = JoinNode.new(pattern)
-      
-      if side==:left
-        out_node.left_input = join_node
-      elsif side==:right
-        out_node.right_input = join_node
+    #   pattern - the Pattern that the created node wraps
+    #   out_node - the Node that this pattern is directly above in thw network
+    #   side - if the out_node is a JoinNode, this marks the side of the new node
+    def create_join_node(pattern, out_node, side)      
+      join_node = nil
+      if (pattern.left_pattern.kind_of?(NotPattern))  
+        raise 'NotPatterns at the being of a rule are not yet supported'
+      elsif (pattern.right_pattern.kind_of?(NotPattern))  
+        join_node = NotNode.new 
+      else
+        join_node = JoinNode.new    
       end
       
-      # TODO opmtimization the join_nodes list (just like object_nodes)
-      @join_nodes.push(join_node)
-
-      join_node.out_nodes.push out_node      
+      @join_nodes.push(join_node)      
+      parent_node = join_node
+      if out_node.kind_of?(JoinNode)
+        adapter_node = create_adapter_node(side)
+        parent_node.out_nodes.push adapter_node
+        parent_node = adapter_node
+      end         
+      parent_node.out_nodes.push out_node      
       return join_node      
     end
     private:create_join_node
+    
+    def create_type_node(atom)
+      node = TypeNode.new atom
+      @type_nodes.push node
+      return node
+    end
+    private:create_type_node
+    
+    def create_property_node(atom)
+      node = PropertyNode.new atom
+      @atom_nodes.push node
+      return node
+    end
+    private:create_property_node
+    
+    def create_self_reference_node(atom)      
+      node = SelfReferenceNode.new atom
+      @atom_nodes.push node
+      return node
+    end
+    private:create_self_reference_node
+    
+    def create_reference_node(atom)      
+      node = ReferenceNode.new atom
+      @atom_nodes.push node
+      return node
+    end
+    private:create_reference_node
+    
+    def create_adapter_node(side)
+      if side == :left
+        return LeftAdapterNode.new
+      else
+        return RightAdapterNode.new
+      end
+    end
+    private:create_adapter_node
         
     # When a new fact is added to working memory, or an existing one is removed
     # this method is called.  It finds any nodes that depend on it, and updates
     # them accordingly.
     def assert_fact(fact) 
-      @object_nodes.each fact.object.class do |object_node| 
-        altered = false
+      # TODO implement node sharing.  Instead of iterating over the @type_nodes
+      # list, we will just get the one that matches the type of this fact
+      @type_nodes.each do |node| 
         if fact.token == :plus
-          altered = object_node.assert fact 
+          node.assert(MatchContext.new(fact))
         else
-          altered = object_node.retract fact 
-        end
-        
-        # BUG this may cause there to be multiple MatchResults for the same 
-        # fact. It will be as if there were 2 of the same fact in working 
-        # memory.  Right now it is okay because we are removing duplicate 
-        # MatchResults.  But this means we cannot have duplicate facts in 
-        # working memory. The following WILL need to be addressed at 
-        # some point.  
-        # 
-        # QUESTION a possible solution would be to pass an 'is_new' parameter to
-        # the refresh_node method.  This param could represent that we are 
-        # refreshing (as opposed to calling it from assert_rule - which would
-        # be the first time).  
-        if altered
-          check_references(object_node)
+          node.retract fact 
         end
-      end      
-    end
-    
-    def check_references(object_node)
-      object_node.referenced_by.each do |ref_node|
-        # HACK this is a very costly operation because we will have to iterate
-        # over ALL facts in working memory to see if ANY nodes were affected
-        # by the fact asserted/retracted here.  So patterns using ReferenceAtoms 
-        # become very expensive.
-        altered = compare_node_to_wm(ref_node)
-         
-        # call this method recursively until we reach a node that is not 
-        # referenced by any other nodes
-        if altered
-          check_references(ref_node)
-        end
-      end
+      end   
     end
     
-    # This method is used to update each ObjectNode in the given list based on 
+    # This method is used to update each TypeAtomNode based on 
     # the facts in working memory.  It can be a costly operation because it 
-    # iterates over EVERY fact in working memory.  It should be used only when 
-    # needed.
-    def compare_node_to_wm(obj_node)
-      altered = false
-      facts = @working_memory.facts      
-      if (facts.empty? && obj_node.kind_of?(NotNode))
-        # HACK its kind of lame to have to do this here, maybe the NotNode 
-        # should have this value by default
-        obj_node.assert_input_true
-      else 
-        # check working memory to see if this node is satisfied by any fact(s)              
-        facts.each do |fact| 
-          inner_altered = obj_node.assert fact
-          altered = true if inner_altered
-        end
+    # iterates over EVERY fact in working memory.  It should only be used when a
+    # new rule is added.
+    def compare_to_wm(type_node)              
+      @working_memory.each_fact do |fact| 
+        type_node.assert MatchContext.new(fact)
       end
-      return altered
     end
-
+    private:compare_to_wm
+  
     # When invoked, this method returns a list of all Action|MatchContext pairs 
     # as Activations.  The list is generated when facts and rules are asserted, 
     # so no comparisions are done here (i.e. no Backward Chaining).  
@@ -258,7 +183,7 @@ module Ruleby
       agenda = Array.new
       @terminal_nodes.each do |node|
         if (node.satisfied?)
-          agenda.concat node.activations.values.values
+          agenda.concat node.activations.values
         end
       end
       return agenda
@@ -267,418 +192,432 @@ module Ruleby
     def print
       puts 'NETWORK:'
       @terminal_nodes.each do |node|
-        node.print('  ')
+        node.print(' ')
+      end
+    end
+  end
+  
+  # Any node in the network that needs to be printed extends this class.  It
+  # provides handles to the nodes above it in network.  These are not used for
+  # matching (i.e. no backward-chaining).
+  class Printable
+    def initialize
+      # this only used for printing the network, not for matching
+      @parent_nodes = [] 
+    end
+    attr_reader:parent_nodes   
+    def print(tab)
+      puts tab + to_s
+      @parent_nodes.each do |out_node|
+        out_node.print('  '+tab)
       end
     end
   end
   
-  # This class represents a one-input node.  It essenatially acts as a wrapper 
-  # for an ObjectPattern, and provides the logic for matching facts.
-  class ObjectNode < Node
-    def initialize(pattern)
+  # Base Node class used by all nodes in the network that do some kind 
+  # of matching.
+  class Node < Printable    
+  
+    # This method determines if all common tags have equal values.  If any 
+    # values are not equal then the method returns false.
+    def resolve(mr1, mr2)    
+      mr1.variables.each_key do |t1|
+        mr2.variables.each_key do |t2|
+          if t2 == t1 && mr1.fact_hash[t1] != mr2.fact_hash[t2]
+            return false 
+          end
+        end
+      end 
+      return true
+    end
+  end
+  
+  # This is the base class for all nodes in the network that output to some 
+  # other node (i.e. they are not at the bottom). It contains methods for 
+  # propagating match results.
+  class ParentNode < Node
+    def initialize
       super
-      
-      # a list of Nodes that reference this node.  This will be used so that we
-      # can update them if this node get some new matches (or loses matches).
-      @referenced_by = []      
-      
-      # The atoms need a handle to this node.
-      @pattern.atoms.each { |a| a.parent = self }    
-      
-      # In this hash, the key is a fact.id, and each value is a list of 
-      # MatchResults.  Each MR is from a node that this node references.
-      @ref_results_hash = {}
-      
-      # In this hash, the key is a fact.id, and each value is a single 
-      # MatchResult.  The MRs represent the match for each fact.
-      @obj_results_hash = {}
-    end   
-     
-    attr:referenced_by,true
+      @out_nodes = []    
+    end
+    attr_reader:out_nodes
     
-    def satisfied?
-      return !@obj_results_hash.empty?
+    def assert(context)
+      propagate_assert(context)
     end
     
-    def obj_results
-      return @obj_results_hash.values
+    def retract(fact)
+      propagate_retract(fact)
     end
     
-    def ref_results(tag)
-      list = []
-      @ref_results_hash.each_value do |ref_result|
-        list.concat ref_result[tag] if ref_result[tag] != ref_result.default
+    def propagate_assert(context)
+      @out_nodes.each do |out_node|
+        out_node.assert(context)
       end
-      return list
-    end
-    
-    # This method initiates the matching of this pattern to the given fact
-    # (specificily to the object it wraps).  If the pattern matches the object
-    # then one or more MatchResults will be created and added to the system.
-    #   returns:boolean - true if this node was altered by the assertion
-    def assert(fact)
-      obj_result = MatchResult.new
-      ref_results = {}
-      results = [MatchResult.new] 
-            
-      @pattern.atoms.each do |atom|
-        r = atom.match? fact
-        if r.empty? || !r[0].is_match
-          return false
-        else      
-          # Build the MatchResult that will be added to each atom
-          # after we have gone through all atoms.  We must wait 
-          # till after we check all atoms because we only add it
-          # if ALL atoms have a match for this object. 
-          obj_result[atom.tag] = r[0][atom.tag]
-          obj_result.is_match = r[0].is_match
-          obj_result.fact_hash = obj_result.fact_hash.update r[0].fact_hash 
-          obj_result.recency = obj_result.recency | r[0].recency
-          
-          ref_results[atom.tag] = [] 
-          results = build_results results, ref_results, r, atom
-        end     
-        ref_results[atom.tag].each do |ref_result|
-          # update each ReferenceAtom's MatchResult with the core result for this fact
-          ref_result.update obj_result 
-        end      
+    end
+    
+    def propagate_retract(fact)
+      @out_nodes.each do |out_node|
+        out_node.retract(fact)
       end
-      
-      @ref_results_hash[fact.id] = ref_results
-      @obj_results_hash[fact.id] = obj_result
-               
-      # HACK delete repeated MatchResults.  Instead of doing this
-      # we need to be sure that every MatchResult added is unique (or is
-      # intended to be a duplicate).
-      results.each do |r1|
-        results.delete_if do |r2|
-          r1 == r2 && r1.object_id != r2.object_id
-        end
-      end        
-      
-      results.each do |mr|
-        propagate_assert mr, fact
-      end              
-      return !results.empty? 
-    end
-    
-    # This method is called when a fact is removed from the system.  If the 
-    # patterned contained in the node was matched to the given fact, then we
-    # removed those MatchResults from our local cache, and propagate the change.
-    #   returns:boolean - true if this node was altered by the retraction
-    def retract(fact)           
-      @ref_results_hash.delete(fact.id)
-      result = @obj_results_hash.delete(fact.id) 
-      if result != @obj_results_hash.default
-        propagate_retract fact
-        return true
+    end
+  end
+  
+  # This is a base class for all single input nodes that match facts based on
+  # some properties.  It is essentially a wrapper for an Atom.
+  class AtomNode < ParentNode
+    def initialize(atom)
+      super()
+      @atom = atom 
+    end
+    attr_reader:atom
+    
+    def retract(fact)
+      # These nodes do not have a memory, so there is no need to do anything
+      # when a fact is retracted.  Just pass it on to the two-input nodes.
+      propagate_retract(fact)
+    end
+  end
+  
+  # This node class is used to match the type of a fact.
+  class TypeNode < AtomNode
+    def assert(context)
+      mr = match(context.fact)
+      if mr.is_match    
+        context.match.update mr
+        propagate_assert(context)
       end
-      return false
-    end
-    
-    # This internal method is used to build the result set for matching fact-
-    # pattern combination.
-    def build_results(results, ref_results, r, atom)
-      inner_results = []       
-      r.each do |each_r|         
-        # Update each MatchResult already in the list with this MatchResult
-        # if the two resolve.  Then add the result to the list for this atom.
-        results.each do |result|
-          if resolve(result, each_r)
-            ref_results[atom.tag].push each_r
-            mr = result.dup
-            mr.update(each_r)   
-            inner_results.push mr 
-          end 
-        end                
-      end              
-      return inner_results
-    end
-    private:build_results
-    
-    def ==(node)
-      if (node.kind_of?(ObjectNode))
-        return @pattern == node.pattern 
+    end
+    
+    def match(fact)
+      mr = MatchResult.new
+      val = fact.object.send("#{@atom.name}")
+      if @atom.proc.call(val)
+        mr.is_match = true
+        mr.recency.push fact.recency
+        mr.fact_hash[@atom.tag] = fact.id
+        mr[@atom.tag] = fact.object 
+      end
+      return mr
+    end
+    private:match
+  end
+  
+  # This node class is used for matching properties of a fact.
+  class PropertyNode < AtomNode
+    def assert(context)
+      mr = match(context.fact)
+      if mr.is_match
+        # TODO for node sharing will we have to update multiple matches
+        context.match.update mr
+        propagate_assert(context)
       end
     end
     
-    def print(tab)
-      puts tab + to_s + " (#{satisfied?}) #{@pattern} -> #{@out_nodes}"
+    def match(fact)
+      mr = MatchResult.new
+      val = fact.object.send("#{@atom.name}")
+      if @atom.proc.call(val)
+        mr.is_match = true
+        mr.fact_hash[@atom.tag] = fact.id
+        mr.recency.push fact.recency
+        mr[@atom.tag] = val 
+      end
+      return mr
     end
+    private:match
   end
   
-  # This class represents a one-input node.  It essenatially acts as a wrapper 
-  # for an NotPattern, and provides the logic for matching facts.  This class
-  # is similar to ObjectNode (and in fact extends it), but some of the matching
-  # logic is different.  This is because when this matches facts that need to 
-  # not exist in working memory.
-  class NotNode < ObjectNode
-    def satisfied?
-      return true # there is always something not there...
+  # This node class is used to match properties of one with the properties
+  # of any other already matched fact.  It differs from the other AtomNodes 
+  # because it does not perform any inline matching.  The match method is only
+  # invoked by the two input node.
+  class ReferenceNode < AtomNode    
+    def match(left_context,right_fact)
+      val = right_fact.object.send("#{@atom.name}")  
+      args = [val]            
+      # TODO for node sharing we will have to compare against multiple matches
+      match = left_context.match.dup     
+      @atom.vars.each do |var|
+        args.push match.variables[var]   
+      end       
+      if @atom.proc.call(*args) 
+        m = MatchResult.new(match.variables.clone, true, match.fact_hash.clone, match.recency)
+        m.recency.push right_fact.recency
+        m.fact_hash[@atom.tag] = right_fact.id
+        m.variables[@atom.tag] = val 
+        return m
+      end
+      return MatchResult.new
     end  
-    
-    # This method initiates the matching of this pattern to the given fact
-    # (really to the object it wraps).  If the pattern matches the object
-    # then one or more MatchResults will be created and added to the system.
-    #   returns:boolean - false because no nodes can reference a NotNode
-    def assert(fact)
-      ref_results = {}
-      results = [MatchResult.new] 
-            
-      @pattern.atoms.each do |atom|
-        r = atom.match? fact
-        if r.empty? || !r[0].is_match
-          # QUESTION do we need to add this for every unmatched fact?
-          propagate_assert MatchResult.new({},true), fact
-          return false
-        else                  
-          ref_results[atom.tag] = [] 
-          results = build_results results, ref_results, r, atom
-        end          
+  end
+  
+  # This node class is used to match properties of a fact with other properties
+  # of itself.  Unlike ReferenceAtom it does perform inline matching. 
+  class SelfReferenceNode < ReferenceNode    
+    def assert(context)
+      mr = match(context, context.fact)
+      if mr.is_match
+        context.match.update mr
+        propagate_assert(context)
       end
-      
-      @ref_results_hash[fact.id] = ref_results
-               
-      # HACK delete repeated MatchResults.  Instead of doing this
-      # we need to be sure that every MatchResult added is unique.
-      results.each do |r1|
-        results.delete_if do |r2|
-          r1 == r2 && r1.object_id != r2.object_id
-        end
-      end    
-        
-      results.each do |mr|    
-        # TODO we need to extend the atoms so that NotNodes's results don't 
-        # have the variables that we are removing below        
-        mr.keys.each do |key|
-          delete = true
-          @pattern.atoms.each do |a|
-            if (a.kind_of?(ReferenceAtom) && a.vars.index(key) != nil)
-              delete = false
-            end
-          end
-          mr.delete key if delete
-        end
-        
-        propagate_assert_neg mr, fact                
-      end      
-      return false # nothing can reference a NotNode... easy 
-    end
-    
-    # This method is called when a fact is removed from the system.  If the 
-    # patterned contained in the node was matched to the given fact, then we
-    # removed those MatchResults from our local cache, and propagate the change.
-    #   returns:boolean - always false because no other nodes will ever care
-    def retract(fact)      
-      unless @ref_results_hash.delete(fact.id) == @ref_results_hash.default
-        propagate_retract_neg fact
+    end
+  end
+  
+  # This class is used to plug nodes into the left input of a two-input JoinNode
+  class LeftAdapterNode < ParentNode
+    def propagate_assert(context)
+      @out_nodes.each do |out_node|
+        out_node.assert_left(context)
       end
-      return false # nothing can reference a NotNode... easy  
-    end 
-    
-    # This method forces the node to be true (regardless of the facts in 
-    # working memory).  This is need when the working memory is empty.
-    def assert_input_true
-      propagate_assert MatchResult.new({},true), nil
     end
     
-    def print(tab)
-      puts tab + to_s + " (#{satisfied?}) #{@pattern} -> #{@out_nodes}"
+    def propagate_retract(fact)
+      @out_nodes.each do |out_node|
+        out_node.retract_left(fact)
+      end
     end
   end
-      
-  # This class represents a two-input node.  It acts as a wrapper for a 
-  # composite pattern, and keeps a memory of whether or not the left and 
-  # right values have been satisfied.  
-  class JoinNode < Node
   
-    # the 'pattern' parameter denotes the boolean operator that this class
-    # will use to compute if this join_node has been satisfied.
-    def initialize(pattern)    
-      super pattern      
-      @left_memory = MatchContext.new
-      @right_memory = MatchContext.new          
-      @local_memory = MatchContext.new
-      @not_memory = MatchContext.new     
-      @left_input = nil
-      @right_input = nil       
-    end    
-        
-    attr :left_input, true
-    attr :right_input, true  
-    attr :local_memory, true
-    
-    def satisfied?
-      return @local_memory.satisfied?
-    end
-    
-    def assert(in_node, mr, fact)
-      left = []; right = []
-      if (in_node.object_id == @left_input.object_id)      
-        return if @left_memory.contains?(mr)
-        @left_memory.add mr.fact_ids, mr
-        left = [mr]
-        right = @right_memory.match_results
-      elsif (in_node.object_id == @right_input.object_id)
-        return if @right_memory.contains?(mr)
-        @right_memory.add mr.fact_ids, mr
-        left = @left_memory.match_results
-        right = [mr]
-      else
-        return
-      end 
-      list = filter_match_results(left, right) 
-      list.each do |new_mr|
-        # QUESTION can we just do this inside of filter_match_results?
-        @local_memory.add new_mr.fact_ids, new_mr
-        propagate_assert new_mr, fact
-      end  
-    end
-    
-    def retract(in_node, fact)
-      if in_node.object_id == @left_input.object_id    
-        @left_memory.remove fact.id 
-      elsif in_node.object_id == @right_input.object_id
-        @right_memory.remove fact.id   
-      else
-        return
+  # This class is used to plug nodes into the right input of a two-input JoinNode
+  class RightAdapterNode < ParentNode
+    def propagate_assert(context)
+      @out_nodes.each do |out_node|
+        out_node.assert_right(context)
       end
-      @local_memory.remove fact.id
-      propagate_retract fact 
     end
+  
+    def propagate_retract(fact)
+      @out_nodes.each do |out_node|
+        out_node.retract_right(fact)
+      end
+    end
+  end
+  
+  # This class is a two-input node that is used to create a cross-product of the
+  # two network branches above it.  It keeps a memory of the left and right 
+  # inputs and compares new facts to each.
+  class JoinNode < ParentNode
+    def initialize
+      super
+      @left_memory = {}
+      @right_memory = {} 
+      @ref_nodes = []
+    end
+    attr:ref_nodes,true
     
-    def assert_neg(in_node, nmr, fact)
-      return if @not_memory.contains?(nmr)
-      @not_memory.add nmr.fact_ids, nmr
-      @local_memory.delete_if do |mr| 
-        matches_not?(mr,[nmr])    
+    def retract_left(fact)
+      @left_memory.delete(fact.id)
+      propagate_retract(fact)
+    end
+    
+    def retract_right(fact)
+      @right_memory.delete(fact.id)
+      propagate_retract(fact)
+    end
+  
+    def assert_left(context)
+      add_to_left_memory(context)
+      @right_memory.values.each do |right_context|
+        mr = match_ref_nodes(context,right_context)      
+        if (mr.is_match)
+          # TODO for node sharing we will have to update multiple matches
+          new_context = MatchContext.new context.fact, mr  
+          propagate_assert(new_context)
+        end
       end
-      propagate_assert_neg nmr, fact
     end
     
-    def retract_neg(in_node, fact)
-      result = @not_memory.remove fact.id
-      return if result == @not_memory.default
-      
-      # TODO keep a cache of MatchResults that were left out because of
-      # certain not_match_results.  Hash these by the fact.id of those NMRs.
-      list = filter_match_results(@left_memory.match_results, @right_memory.match_results)
-      list.each do |mr|
-        unless @local_memory.contains?(mr)
-          @local_memory.push mr
-          propogate_assert mr, nil
-        end       
-      end     
-      propagate_retract_neg fact
-    end
-    
-    def ==(node)
-      if (node.kind_of?(JoinNode))
-        return @pattern == node.pattern 
+    def assert_right(context)
+      @right_memory[context.fact.id] = context
+      @left_memory.values.flatten.each do |left_context|
+        mr = match_ref_nodes(left_context,context)      
+        if (mr.is_match)
+          # TODO for node sharing we will have to update multiple matches
+          new_context = MatchContext.new context.fact, mr              
+          propagate_assert(new_context)
+        end
       end
     end
     
-    def print(tab)
-      puts tab + "JoinNode:#{satisfied?}(#{@left_memory},#{@right_memory})(#{@not_memory}) -> #{@out_nodes}"
-      @left_input.print(tab + '  ')
-      @right_input.print(tab + '  ')
-    end
-    
-    # This method filters the match results that are given by the left and
-    # right patterns.  It does this by merging the two. It needs to be 
-    # refactored, and probably moved into the Pattern that this JoinNode wraps
-    # (so we can take a different approach for OrPatterns in the future).    
-    def filter_match_results(left, right)       
-      mc = []    
-      left.each do |left_mr|     
-        right.each do |right_mr|            
-          if right_mr.keys.empty?             
-            # HACK we're doing this because we have an empty MatchResult
-            # from a NotNode. 
-            # QUESTION do we need to account for these on the left too?
-            mc.push left_mr.dup unless matches_not?(left_mr,@not_memory.match_results) 
-          else 
-            if resolve left_mr, right_mr                                             
-              mr = left_mr.dup.update(right_mr.dup)       
-              mr.fact_hash.update left_mr.fact_hash
-              mr.fact_hash.update right_mr.fact_hash                  
-              mc.push mr unless matches_not?(mr,@not_memory.match_results)                 
-              # TODO cache the mr's that fail the test above, and add them in
-              # if the fact that generated that not_match_result is retracted?
-            end
+    def match_ref_nodes(left_context,right_context)
+      mr = right_context.match.dup
+      if @ref_nodes.empty?
+        return left_context.match.dup.update(mr)
+      else
+        # TODO for node sharing we will have to have a list of matches
+        @ref_nodes.each do |ref_node|
+          ref_mr = ref_node.match(left_context, right_context.fact)
+          if ref_mr.is_match
+            mr.update ref_mr
+          else
+            return MatchResult.new
           end
         end
-      end   
-      return mc
-    end    
-    private:filter_match_results
-  end
-  
-  # This class represents a final node in the network.  It has no outputs.  It
-  # is responsible for creating, and maintaining the list of activations for the
-  # node network.
-  class TerminalNode < Node
-  
-    def initialize(rule)
-      super(nil)
-      @rule = rule      
-      @activations = DoubleHash.new  
-      @parent_node = nil  #only used for printing the network
+        return mr
+      end
     end
+    private:match_ref_nodes
     
-    attr_reader :rule  
-    attr :parent_node, true 
-    attr_reader :activations
+    def add_to_left_memory(context)
+      lm = @left_memory[context.fact.id]
+      lm = [] unless lm      
+      lm.push context
+      @left_memory[context.fact.id] = lm      
+      # QUESTION for a little while we were having trouble with duplicate contexts
+      # being added to the left_memory.  Double check that this is not happening
+    end
     
-    def assert(in_node,mr,fact)
-      if verify_by_tags(mr, @rule.pattern.atom_tags)
-        @activations.add mr.fact_ids, Activation.new(@rule.action, mr)
+    def propagate_retract_resolve(match)
+      @out_nodes.each do |o|
+        o.retract_resolve(match)
       end
     end
     
-    def retract(in_node,fact)
-      @activations.remove(fact.id)
+    def retract_resolve(match)
+      # in this method we retract an existing match from memory if it resolves
+      # with the match given.  It would probably be better to check if it 
+      # resolves with a list of facts.  But the system is not set up for
+      # that yet.
+      @left_memory.each do |fact_id,contexts|
+        value.delete_if do |left_context|          
+          resolve(left_context.match, match)
+        end        
+      end
     end
     
-    def assert_neg(in_node,mr,fact)    
-      @activations.delete_if { |a| matches_not?(a.match,[mr]) }
+    def to_s
+      return "#{self.class}:#{object_id} | #{@left_memory.values} | #{@right_memory}"
+    end
+  end
+  
+  # This node class is used when a rule is looking for a fact that does not 
+  # exist.  It is a two-input node, and thus has some of the properties of the
+  # JoinNode.  NOTE it has not clear how this will work if the NotPattern is
+  # declared as the first pattern in a rule.
+  class NotNode < JoinNode
+    def initialize
+      super
     end
     
-    def retract_neg(in_node,fact) 
-      # we don't need to do anything here, because the nodes above us will
-      # handle the assertion of new MatchResults; hence Activations
+    def retract_left(fact)
+      @left_memory.delete(fact.id)
+      propagate_retract(fact)
     end
     
-    def print(tab)
-      puts tab + 'TerminalNode: ' + satisfied?.to_s + "(#{@activations.values})(#{@match_context})"
-      @parent_node.print(tab + '  ')
-    end
-    
-    # HACK This method is used to ensure that all required atoms have a value
-    # present in this match result. If any are missing, then the match result
-    # is incomplete.  Maybe this should be moved up to be done within the context 
-    # of matching.  Each MatchContext could keep a hash/list of atoms it needs
-    # to be satisfied, and check them off as they are.
-    def verify_by_tags(match, tags)
-      tags.each do |t|           
-        if t.kind_of?(Array)  
-          # for future use by the OrPattern  
-          return false unless verify_by_tags(match, t)
-        else            
-          if t.exists    
-            unless (match.key? t.tag)
-              return false  
+    def retract_right(fact)
+      right_context = @right_memory.delete(fact.id)  
+      unless right_context == @right_memory.default
+        unless @ref_nodes.empty? && !@right_memory.empty?
+          @left_memory.values.each do |left_context|
+            # TODO we should cache the matches on the left that were unmatched 
+            # by a result from a NotPattern.  We could hash them by the right 
+            # match that caused this.  In that we woould not have to re-compare 
+            # the the left and right matches.
+            if match_ref_nodes(left_context,right_context)      
+              propagate_assert(left_context)
             end
+          end   
+        end
+      end
+    end
+  
+    def assert_left(context)    
+      add_to_left_memory(context)      
+      unless @ref_nodes.empty? && @right_memory.empty?
+        propagate = true
+        @right_memory.values.each do |right_context|
+          if match_ref_nodes(context,right_context)     
+            propagate = false
+            break
+          end
+        end
+        propagate_assert(context) if propagate
+      end
+    end
+    
+    def assert_right(context)                    
+      @right_memory[context.fact.id] = context
+      unless @ref_nodes.empty?
+        @left_memory.values.flatten.each do |left_context|
+          if match_ref_nodes(left_context,context)
+            # QUESTION is there a more efficient way to retract here?
+            propagate_retract_resolve(left_context.match)
           end
-        end      
+        end
+      end
+    end
+    
+    # NOTE this returns a boolean, while the other classes return a MatchResult
+    def match_ref_nodes(left_context,right_context)
+      @ref_nodes.each do |ref_node|
+        ref_mr = ref_node.match(left_context, right_context.fact)
+        unless ref_mr.is_match
+          return false
+        end
       end
       return true
     end
-    private:verify_by_tags
+    private:match_ref_nodes
+  end
+  
+  # This class represents the bottom node in the network.  There is a one to one
+  # relation betweek TerminalNodes and Rules.  A terminal node acts as a wrapper
+  # for a rule.  The class is responsible for keeping a memory of the 
+  # activations that have been generated by the network.
+  class TerminalNode < Node
+    def initialize(rule)
+      super()
+      @rule = rule
+      @activations = MultiHash.new  
+    end
+    attr_reader:activations
+  
+    def assert(context)
+      @activations.add context.match.fact_ids, Activation.new(@rule.action, context.match)
+    end
+    
+    def retract(fact)
+      @activations.remove fact.id
+    end
     
     def satisfied?
       return !@activations.values.empty? 
+    end  
+    
+    def to_s
+      return "TerminalNode:#{object_id} | #{@activations.values}"
+    end
+    
+    def retract_resolve(match)
+      # in this method we retract an existing activation from memory if its 
+      # match resolves with the match given.  It would probably be better to 
+      # check if it resolves with a list of facts.  But the system is not set up
+      # for that yet.
+      @activations.delete_if do |activation|
+        resolve(activation.match, match)
+      end
     end    
-  end  
-  end  
+  end
+  
+  class MatchContext
+    def initialize(fact,mr=MatchResult.new)
+      @fact = fact
+      
+      # TODO for node sharing this will be a pattern=>match Hash
+      @match = mr   
+    end
+    attr_reader:fact
+    attr_reader:match
+    
+    def to_s
+      return @match.to_s
+    end
+    
+    def ==(t)
+      return @fact == t.fact && @match == t.match
+    end
+  end
+
+  end
 end