ruleby 0.1

data/lib/core/atoms.rb

@@ -0,0 +1,226 @@
+#tokens
+module Ruleby
+  module Core
+  
+  # TODO eventually we want to refactor some of the match? and
+  # match_result logic out of these classes and into an AtomNode
+  # class.  This will allow the Atoms to simply contain some attrs
+  
+  class Atom
+    def initialize(tag, name, &block)
+      @tag = tag
+      @name = name
+      @proc = Proc.new(&block) if block_given?
+      @parent = nil # TODO move to AtomNode
+    end
+    
+    attr :parent, true
+    attr_reader :name
+    attr_reader :tag
+    attr_reader :proc
+
+  end
+  
+  # This kind of atom is used to match just a single, hard coded value.  
+  # For example:
+  # 
+  #   a.name do |n| n == 'John' end
+  # 
+  # So there are no references to other atoms.
+  class PropertyAtom < Atom
+    
+    def match?(fact)
+      mr = MatchResult.new
+      temp = fact.object.send("#{@name}")
+      if @proc.call(temp)
+        mr.is_match = true
+        mr.fact_hash[@tag] = fact.id
+        mr.recency.push fact.recency
+        mr[@tag] = temp
+      end
+      return [mr]
+    end
+
+    def matches
+      @parent.obj_results
+    end
+    
+    def ==(atom)      
+      return atom != nil && @tag == atom.tag && @name == atom.name && @proc == atom.proc 
+    end   
+    
+    def to_s
+      return 'tag='+@tag.to_s + '[' + matches.join(',') + ']'
+    end
+  end
+  
+  # This kind of atom is used to match a class type.  For example:
+  # 
+  #   p.has Person 
+  # 
+  # It is only used at the start of a pattern.
+  class TypeAtom < PropertyAtom
+    def match?(fact)
+      mr = MatchResult.new
+      temp = fact.object.send("#{@name}")
+      if @proc.call(temp)
+        mr.is_match = true
+        mr.recency.push fact.recency
+        mr.fact_hash[@tag] = fact.id
+        mr[@tag] = fact.object 
+      end
+      return [mr]
+    end
+  end
+  
+  # This kind of atom is used for matching a value that is a variable.
+  # For example:
+  # 
+  #   a.name references => :your_name do |n,yn| n == yn end
+  #   
+  # The expression for this atom depends on some other atom.  
+  class ReferenceAtom < Atom
+  
+    def initialize(tag, name, vars, &block) 
+      super(tag, name, &block)
+      @vars = vars # list of referenced variable names
+      @var_atoms = Hash.new # will be set when rule is asserted
+    end
+    
+    attr_reader :vars
+    attr :var_atoms, true
+    
+    def match?(fact)
+      local_matches = Array.new      
+      val = fact.object.send("#{@name}")     
+      @vars.each do |v|  
+        # TODO we don't really need to iterate over all the @var_atoms, just
+        # the one that is at the top of the reference chain (i.e. the one that
+        # has references to all of this atoms other references.
+        @var_atoms[v].matches.each do |match| 
+          args = [val]                 
+          args.push match.variables[v]     
+          i = 0; while i < @vars.length
+            if match.key? @vars[i]
+              args.push match.variables[@vars[i]]                
+              i+=1
+            else
+              i = @vars.length + 1
+            end
+          end
+          break if i > @vars.length 
+          if @proc.call(args)   
+            m = MatchResult.new(match.variables.clone, true, match.fact_hash.clone, match.recency)
+            m.recency.push fact.recency
+            m.fact_hash[@tag] = fact.id
+            m.variables[@tag] = val            
+            local_matches.push(m)
+          end
+        end
+      end      
+      return local_matches.uniq
+    end   
+    
+    def matches
+      return @parent.ref_results(@tag)
+    end
+    
+    def ==(atom)      
+      return atom.kind_of?(ReferenceAtom) && @proc == atom.proc && @tag == atom.tag && @vars == atom.vars
+    end
+    
+    def to_s
+      return 'tag='+@tag.to_s + '[' + matches.join(',') + ']'
+    end
+  end
+  
+  class MatchResult  
+  
+    # TODO this class needs to be cleaned up for that we don't have a bunch of
+    # properties.  Instead, maybe it sould have a list of facts.
+    def initialize(variables=Hash.new,is_match=false,fact_hash={},recency=[])
+      @variables = variables      
+      
+      # a list of recencies of the facts that this matchresult depends on.
+      @recency = recency
+      
+      # notes where this match result is from a NotPattern or ObjectPattern
+      # TODO this isn't really needed anymore.  how can we get rid of it?
+      @is_match = is_match 
+      
+      # a hash of fact.ids that each tag corresponds to
+      # QUESTION what is better: this or the @backward_hash in MatchContext?
+      # Right now these two are somewhat redundate.
+      @fact_hash = fact_hash 
+    end
+    def []=(sym, object)
+      @variables[sym] = object
+    end
+    def [](sym)
+       return @variables[sym]
+    end
+    def fact_ids
+      return fact_hash.values.uniq
+    end
+    attr :variables, true
+    attr :is_match, true
+    attr :fact_hash, true
+    attr :resolved, true
+    attr :recency, true
+    def ==(match)           
+      return match != nil && @variables == match.variables && @is_match == match.is_match && @fact_hash == match.fact_hash
+    end
+    
+    def key?(m)
+      return @variables.key?(m)
+    end
+    
+    def keys
+      return @variables.keys
+    end
+    
+    def update(mr)
+      @recency = @recency | mr.recency
+      @is_match = mr.is_match
+      @variables = @variables.update mr.variables      
+      
+      # QUESTION why the heck is does this statement work instead of the 
+      # commented one below it??
+      @fact_hash = mr.fact_hash.update @fact_hash
+      #@fact_hash = @fact_hash.update mr.fact_hash      
+      
+      return self
+    end
+    
+    def dup     
+      dup_mr = MatchResult.new
+      dup_mr.recency = @recency.clone
+      dup_mr.is_match = @is_match
+      dup_mr.variables = @variables.clone
+      dup_mr.fact_hash = @fact_hash.clone       
+      return dup_mr
+    end
+    
+    def clear
+      @variables = {}
+      @fact_hash = {}
+      @recency = []
+    end
+    
+    def delete(tag)
+      @variables.delete(tag)
+      @fact_hash.delete(tag)
+    end
+    
+    def to_s
+      s = '#MatchResult('
+      s = s + 'f)(' unless @is_match
+      s = s + object_id.to_s+')('
+      @variables.each do |key,value|
+        s += "#{key}=#{value}/#{@fact_hash[key]}, "
+      end
+      return s + ")"
+    end
+  end
+end
+end

data/lib/core/engine.rb

@@ -0,0 +1,211 @@
+#core core
+require 'core/atoms'
+require 'core/patterns'
+require 'core/utils'
+require 'core/nodes'
+
+module Ruleby
+  module Core
+  class Action   
+    def initialize(&block)
+      @name = nil
+      @proc = Proc.new(&block) if block_given?
+      @priority = 0
+    end
+        
+    attr_accessor :priority
+    attr_accessor :name
+    attr_reader :matches
+    
+    def fire(r, match)
+      @proc.call(r, match)        
+    end 
+       
+    def ==(a2)
+      return @name == a2.name
+    end    
+  end   
+ 
+  class Activation    
+    def initialize(action, match)
+      @action = action
+      @match = match
+      @match.recency.sort!
+      @match.recency.reverse!
+      @counter = 0
+    end
+    
+    attr_reader :action, :match
+    attr_accessor :counter
+    
+    def fire(r)
+      @action.fire r, @match
+    end
+    
+    def <=>(a2)          
+      return @counter <=> a2.counter if @counter != a2.counter
+      return @action.priority <=> a2.action.priority if @action.priority != a2.action.priority           
+
+      # NOTE in order for this to work, the array must be reverse sorted
+      i = 0; while @match.recency[i] == a2.match.recency[i] && i < @match.recency.size-1 && i < a2.match.recency.size-1 
+        i += 1
+      end
+      return @match.recency[i] <=> a2.match.recency[i]
+    end
+    
+    def ==(a2)
+      return a2 != nil && @action == a2.action && @match == a2.match
+    end
+    
+    def to_s
+      return "[#{@action.name}-#{object_id}|#{@counter}|#{@action.priority}|#{@match.recency.join(',')}|#{@match.to_s}] "
+    end
+  end
+ 
+  class Rule
+    def initialize(name, pattern=nil, action=nil, priority=0) 
+      @name = name
+      @pattern = pattern
+      @action = action  
+      @priority = priority    
+    end
+
+    attr_accessor:pattern   
+    attr_reader:action, :name
+    
+    def when=(pattern)
+      @pattern = pattern
+    end
+    
+    def then=(action)
+      @action = action
+      @action.name = @name
+      @action.priority = @priority
+    end
+    
+    def priority
+      return @priority
+    end
+    
+    def priority=(p)
+      @priority = p
+      @action.priority = @priority
+    end    
+  end
+  
+  class Fact    
+    def initialize(object, token)
+      @token = token      
+      @object = object
+    end
+   
+    attr :token, true
+    attr :recency, true    
+    attr_reader :object
+    
+    def id
+      return object.object_id
+    end
+    
+    def ==(fact)
+      return fact != nil && fact.id == id
+    end
+    
+    def to_s
+      return "[Fact |#{@recency}|#{@object.to_s}]"
+    end
+  end
+  
+  class RulebyConflictResolver
+    def resolve(agenda) 
+      return agenda.sort
+    end
+  end
+  
+  class WorkingMemory
+    def initialize
+      @recency = 0
+      @facts = Array.new
+    end
+    
+    attr_reader :facts
+    
+    def assert_fact(fact)
+      raise 'The fact asserted cannot be nil!' unless fact.object
+      if (fact.token == :plus)
+        fact.recency = @recency
+        @recency += 1
+        @facts.push fact
+        return fact
+      else #if (fact.token == :minus)  
+        i = @facts.index(fact)
+        raise 'The fact to remove does not exist!' unless i
+        existing_fact = @facts[i]
+        @facts.delete_at(i)
+        existing_fact.token = fact.token
+        return existing_fact
+      end
+    end
+    
+    def print
+      puts 'WORKING MEMORY:'
+      @facts.each do |fact|
+        puts " #{fact.object} - #{fact.id} - #{fact.recency}"
+      end
+    end
+  end
+
+  class Engine        
+    def initialize()
+      @root = nil
+      @working_memory = WorkingMemory.new
+      @conflict_resolver = RulebyConflictResolver.new
+    end
+  
+    def assert_fact(fact)
+      wm_fact = @working_memory.assert_fact fact      
+      @root.assert_fact wm_fact if @root != nil
+    end
+  
+    def assert_rule(rule)      
+      @root = RootNode.new(@working_memory) if @root == nil
+      @root.assert_rule rule
+    end
+    
+    def match(agenda=@root.match, used_agenda=[], activation_counter=0)
+      agenda = @conflict_resolver.resolve agenda
+      if(agenda && agenda.length > 0)               
+        activation = agenda.pop   
+        used_agenda.push activation     
+        activation.fire self
+        
+        new_agenda = @root.match
+        
+        # HACK the following is a workaround.  This problem would best be 
+        # solved by working this into the nodes themselves.         
+        new_agenda.each do |a|
+          used = false
+          used_agenda.each do |used_activation|
+            used = true if used_activation.object_id == a.object_id
+          end
+          
+          # BUG we are comparing against the current agenda, but we may need to 
+          # compare against all activations that have existed...
+          if (agenda.index(a) == nil) && (!used)
+            a.counter = activation_counter+1
+            agenda.push a
+          end
+        end        
+        agenda.delete_if {|a| new_agenda.index(a) == nil}
+        
+        match(agenda, used_agenda, activation_counter+1)
+      end
+    end
+    
+    def print
+      @working_memory.print
+      @root.print
+    end    
+  end  
+end
+end

data/lib/core/nodes.rb

@@ -0,0 +1,684 @@
+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       
+    
+    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  
+    end
+  
+    # This method is invoked when a new rule is added to the system.  The
+    # rule is processed and the appropriate nodes are added to the network.
+    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      
+      @terminal_nodes.push terminal_node
+    end
+    
+    # This method builds the network by starting at the bottom and recursively 
+    # working its way to the top.  The recursion goes up the left side of the 
+    # tree first (depth first... but our tree is up-side-down).
+    #  pattern - the pattern to process (Single or Composite)
+    #  out_node - the node that will be below the new node in the network
+    #  side - if the out_node is a JoinNode, this marks the side of the new node
+    #  Returns a new node in the network that wraps the given pattern and 
+    #  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) 
+      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) 
+        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
+      
+      if side==:left
+        out_node.left_input = obj_node
+      elsif side==:right
+        out_node.right_input = obj_node
+      end
+      
+      # 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     
+    end
+    private:create_object_node
+        
+    # 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
+      end
+      
+      # TODO opmtimization the join_nodes list (just like object_nodes)
+      @join_nodes.push(join_node)
+
+      join_node.out_nodes.push out_node      
+      return join_node      
+    end
+    private:create_join_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
+        if fact.token == :plus
+          altered = object_node.assert 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)
+        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
+    
+    # This method is used to update each ObjectNode in the given list 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
+      end
+      return altered
+    end
+
+    # 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).  
+    def match
+      agenda = Array.new
+      @terminal_nodes.each do |node|
+        if (node.satisfied?)
+          agenda.concat node.activations.values.values
+        end
+      end
+      return agenda
+    end
+    
+    def print
+      puts 'NETWORK:'
+      @terminal_nodes.each do |node|
+        node.print('  ')
+      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)
+      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
+    
+    def satisfied?
+      return !@obj_results_hash.empty?
+    end
+    
+    def obj_results
+      return @obj_results_hash.values
+    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
+      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
+      
+      @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
+      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
+    end
+    
+    def print(tab)
+      puts tab + to_s + " (#{satisfied?}) #{@pattern} -> #{@out_nodes}"
+    end
+  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...
+    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
+      
+      @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
+      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}"
+    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
+      end
+      @local_memory.remove fact.id
+      propagate_retract fact 
+    end
+    
+    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])    
+      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 
+      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
+          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
+    end
+    
+    attr_reader :rule  
+    attr :parent_node, true 
+    attr_reader :activations
+    
+    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)
+      end
+    end
+    
+    def retract(in_node,fact)
+      @activations.remove(fact.id)
+    end
+    
+    def assert_neg(in_node,mr,fact)    
+      @activations.delete_if { |a| matches_not?(a.match,[mr]) }
+    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
+    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  
+            end
+          end
+        end      
+      end
+      return true
+    end
+    private:verify_by_tags
+    
+    def satisfied?
+      return !@activations.values.empty? 
+    end    
+  end  
+  end  
+end