ruleby 0.2 → 0.3

data/examples/test_self_reference.rb

@@ -1,6 +1,18 @@
+# This file is part of the Ruleby project (http://ruleby.org)
+#
+# This application is free software; you can redistribute it and/or
+# modify it under the terms of the Ruby license defined in the
+# LICENSE.txt file.
+# 
+# Copyright (c) 2007 Joe Kutner and Matt Smith. All rights reserved.
+#
+# * Authors: Joe Kutner, Matt Smith
+#
+
 $LOAD_PATH << File.join(File.dirname(__FILE__), '../lib/')
 require 'ruleby'
-require 'rulebook'
+
+include Ruleby
 
 class Message
   def initialize(status,message)
@@ -12,22 +24,52 @@ class Message
 end
 
 class SelfRefRulebook < Rulebook
-  def rules
-    rule 'HelloWorld' do |r|
+  def rules    
+    rule :LeTigreTest,
+      'For each Message as :m where #message as :x #&& #status == #:x' do |r,v|
+        puts 'Success'
+    end
+    
+    rule :LeTigreTest,
+      [Message, :m, {m.message => :x}, m.status == b(:x)] do |r,v|
+        puts 'Success'
+    end
+    
+    rule :BlueSteelTest do |r|
       r.when do |has|
-        has.m2 Message
-        has.m2.message :x
-        has.m2.status = :x, :%
+        has.m Message
+        has.m.message :x
+        has.m.status = :x, :%
       end
-      r.then = action do |e,vars|
+      r.then do |e,vars|
         puts 'Success'
       end
     end     
+    
+    # NOTE references the self class binding is not allowed yet
+    
+#    rule 'LeTigreTest',
+#      'exists? Message as :m where #status == #:m.message' do |r,v|
+#        puts 'Success'
+#    end
+
+#    rule 'LeTigreTest',
+#      [Message, :m, m.status(:m, &c{|s,m| s == m.message})] do |r,v|
+#        puts 'Success'
+#    end
+
+#    rule :BlueSteelTest do |r|
+#      r.when do |has|
+#        has.m Message
+#        has.m.status :m do |s,m| s == m.message end
+#      end
+#      r.then do |e,vars|
+#        puts 'Success'
+#      end
+#    end     
   end
 end
 
-include Ruleby
-
 engine :engine do |e|
   SelfRefRulebook.new(e).rules
   e.assert Message.new(:HELLO, :HELLO)

data/lib/core/atoms.rb

@@ -1,27 +1,46 @@
+# This file is part of the Ruleby project (http://ruleby.org)
+#
+# This application is free software; you can redistribute it and/or
+# modify it under the terms of the Ruby license defined in the
+# LICENSE.txt file.
+# 
+# Copyright (c) 2007 Joe Kutner and Matt Smith. All rights reserved.
+#
+# * Authors: Joe Kutner
+#
+
 #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)
+  class Atom     
+    attr_reader:name
+    attr_reader:tag
+    attr_reader:proc
+    attr_reader:clazz
+    
+    def initialize(tag, name, clazz, &block)
       @tag = tag
       @name = name
+      @clazz = clazz
       @proc = Proc.new(&block) if block_given?
-    end
+      
+      # QUESTION we should probably change the '@clazz' variable to be called
+      # something else.  Like '@deftemplate' maybe?
+      
+      # QUESTION we should probably change the '@name' variable to be called
+      # something else.  Like '@method' maybe?
+    end    
     
-    attr_reader :name
-    attr_reader :tag
-    attr_reader :proc
+    def to_s
+      return "#{self.class}, tag=#{@tag}, name=#{@name}, class=#{@clazz}"
+    end
   end
   
   # This kind of atom is used to match just a single, hard coded value.  
   # For example:
   # 
-  #   a.name do |n| n == 'John' end
+  #   a.name = 'John' 
   # 
   # So there are no references to other atoms.
   class PropertyAtom < Atom    
@@ -30,11 +49,7 @@ module Ruleby
     end   
     
     def shareable?(atom)
-      return atom && @name == atom.name && @proc == atom.proc 
-    end
-    
-    def to_s
-      return 'tag='+@tag.to_s + '[' + matches.join(',') + ']'
+      return atom && @name == atom.name && @clazz = atom.clazz && @proc == atom.proc 
     end
   end
   
@@ -43,126 +58,48 @@ module Ruleby
   #   p.has Person 
   # 
   # It is only used at the start of a pattern.
-  class TypeAtom < PropertyAtom
-
+  class TypeAtom < Atom
+    def initialize(tag, clazz)      
+      super tag, :class, clazz do |t| t == clazz end
+    end
+    
+    def shareable?(atom)
+      return atom && @clazz = atom.clazz
+    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
+  #   a.name = :your_name, :%
   #   
   # The expression for this atom depends on some other atom.  
-  class ReferenceAtom < Atom
-  
-    def initialize(tag, name, vars, &block) 
-      super(tag, name, &block)
+  class ReferenceAtom < Atom  
+    attr_reader :vars
+    
+    def initialize(tag, name, vars, clazz, &block) 
+      super(tag, name, clazz, &block)
       @vars = vars # list of referenced variable names
-    end
+    end    
     
-    attr_reader :vars
+    def shareable?(atom)
+      false
+    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(',') + ']'
+      return super + ", vars=#{vars.join(',')}"
     end
   end
   
   # This is an atom that references another atom that is in the same pattern.
+  # Note that in a SelfReferenceAtom, the 'vars' argument must be a list of the
+  # *methods* that this atom references (not the variable names)!
   class SelfReferenceAtom < ReferenceAtom
-    
-  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 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

@@ -1,4 +1,14 @@
-#core core
+# This file is part of the Ruleby project (http://ruleby.org)
+#
+# This application is free software; you can redistribute it and/or
+# modify it under the terms of the Ruby license defined in the
+# LICENSE.txt file.
+# 
+# Copyright (c) 2007 Joe Kutner and Matt Smith. All rights reserved.
+#
+# * Authors: Joe Kutner, Matt Smith
+#
+
 require 'core/atoms'
 require 'core/patterns'
 require 'core/utils'
@@ -6,17 +16,20 @@ require 'core/nodes'
 
 module Ruleby
   module Core
-  class Action   
+  
+  # An action is a wrapper for a code block that will be executed if a rule is
+  # satisfied.  
+  class Action    
+    attr_accessor :priority
+    attr_accessor :name
+    attr_reader   :matches
+    
     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 
@@ -26,19 +39,24 @@ module Ruleby
     end    
   end   
  
-  class Activation    
-    def initialize(action, match)
+  # An activation is an action/match pair that is executed if a rule is matched.
+  # It also contains metadata that can be used for conflict resolution if two 
+  # rules are satisfied by the same fact.
+  class Activation      
+    attr_reader   :action, :match
+    attr_accessor :counter, :used
+    
+    def initialize(action, match, counter=0)
       @action = action
       @match = match
       @match.recency.sort!
       @match.recency.reverse!
-      @counter = 0
-    end
-    
-    attr_reader :action, :match
-    attr_accessor :counter
+      @counter = counter
+      @used = false
+    end   
     
     def fire(r)
+      @used = true
       @action.fire r, @match
     end
     
@@ -62,41 +80,16 @@ module Ruleby
     end
   end
  
-  class Rule
+  class Rule  
+    attr_accessor :pattern
+    attr_reader   :action, :name, :priority   
+    
     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(&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
-    
-    def then=(action)
-      @action = action
-      @action.name = @name
-      @action.priority = @priority
-    end
-    
-    def priority
-      return @priority
-    end
     
     def priority=(p)
       @priority = p
@@ -104,16 +97,18 @@ module Ruleby
     end    
   end
   
-  class Fact    
-    def initialize(object, token)
-      @token = token      
-      @object = object
-    end
-   
+  # A fact is an object that is stored in working memory.  The rules in the 
+  # system will either look for the existence or absence of particular facts.
+  class Fact      
     attr :token, true
     attr :recency, true    
     attr_reader :object
     
+    def initialize(object, token)
+      @token = token      
+      @object = object
+    end
+       
     def id
       return object.object_id
     end
@@ -127,12 +122,18 @@ module Ruleby
     end
   end
   
-  class RulebyConflictResolver
+  # A conflict resolver is used to order activations that become active at the 
+  # same time.  The default implementation sorts the agenda based on the 
+  # properties of the activation.
+  class RulebyConflictResolver   
     def resolve(agenda) 
       return agenda.sort
-    end
+    end    
   end
   
+  # The working memory is a container for all the facts in the system.  The
+  # inference engine will compare these facts with the rules to produce some
+  # outcomes.  
   class WorkingMemory
     def initialize
       @recency = 0
@@ -170,65 +171,59 @@ module Ruleby
     end
   end
 
+  # This is the core class of the library.  A new rule engine is create by 
+  # instantiating it.  Each rule engine has one inference engine, one rule set
+  # and one working memory.
   class Engine        
-    def initialize(wm=WorkingMemory.new)
+    def initialize(wm=WorkingMemory.new,cr=RulebyConflictResolver.new)
       @root = nil
       @working_memory = wm
-      @conflict_resolver = RulebyConflictResolver.new
+      @conflict_resolver = cr
+      @wm_altered = false
     end
-    #assert fact
+  
+    # This method id called to add a new fact to working memory
     def assert(object,&block)
+      @wm_altered = true
       fact_helper(object,:plus,&block)
     end
-    #retract fact
+
+    # This method is called to remove an existing fact from working memory
     def retract(object,&block)
+      @wm_altered = true
       fact_helper(object,:minus,&block)
     end
-    #modify fact
-    #  retract 
-    #  assert
+
+    # This method is called to alter an existing fact.  It is essentially a 
+    # retract followed by an 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
-    end
-  
-    def assert_rule(rule)      
+    # This method adds a new rule to the system.
+    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)
-      while (agenda.length > 0)
-        agenda = @conflict_resolver.resolve agenda            
-        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
+    # This method executes the activations that were generated by the rules
+    # that match facts in working memory.
+    def match(agenda=nil, used_agenda=[])      
+      if @root
+        @root.reset_counter
+        agenda = @root.matches unless agenda 
+        while (agenda.length > 0)
+          agenda = @conflict_resolver.resolve agenda            
+          activation = agenda.pop   
+          used_agenda.push activation     
+          activation.fire self       
+          if @wm_altered          
+            agenda = @root.matches(false)    
+            @root.increment_counter
+            @wm_altered = false
           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}
-                
-        activation_counter = activation_counter+1
+        end
       end
     end
     
@@ -238,12 +233,17 @@ module Ruleby
     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   
+      def fact_helper(object, sign=:plus, &block)
+        f = Core::Fact.new object, sign
+        yield f if block_given?
+        assert_fact f
+        f
+      end   
+      
+      def assert_fact(fact)
+        wm_fact = @working_memory.assert_fact fact      
+        @root.assert_fact wm_fact if @root != nil
+      end  
   end  
 end
 end