wongi-engine 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c142541d4a9b7743bb902181879415cd71711e28
-  data.tar.gz: 2e3295767ec8e6d9cf0ff7b30eafe5c6b2e3c2d7
+  metadata.gz: 9ef395363d21e3d9fadcc8e6ce974c293b31c189
+  data.tar.gz: 65eb91be6334df92643463f6dee220a3467d3e8a
 SHA512:
-  metadata.gz: c8f67c21c7182067a96b611c57bb25986c814f0cb5822b27744f8d289de2e750ad46fbc2766003912f8c3562f793c1909e5d2b2ed5fe051ac573a7b9486d88e6
-  data.tar.gz: d615dd81a8e8f29417aae2806569278cf6d48ff58c40db352be66de6ccf7fd5de06137a489bba82a24cea64e81ac18a8a9d2d015d2b2d675dd11587b52089f6d
+  metadata.gz: 9b88eb68e39323b45e3b3e6c5ed291f78dc31512096a557f750c5ffa3f840025b31b844b10d4abc2de7b8667809c2f68fff995a366074032c20e7c51833256a8
+  data.tar.gz: eaa26f530def7d9cd1cce40f0169b5e3ecec43d9e097cc02f911ac25ec03d35c3534a49ea631ab411e8ce909917e85d90429879eeda8c0410bcb9bb58ae5594e

data/.hgignore

@@ -0,0 +1,6 @@
+syntax: glob
+*.DS_Store
+Gemfile.lock
+.rspec
+.ruby-version
+

data/.hgtags

@@ -1,6 +1,4 @@
 b1dfd471a2a9e4a57f0e4932ac184faa5d6fa5b5 v0.1.0.alpha1
+cf7d0e690fb65541b19074e132813c79a36d12c5 v0.1.0
 accab6252d5746dafe847935ad55f8500594d0cc v0.1.1
-bcb2b3f279910db9fd7d831bed2eec35ea7f834c v0.1.3
-bcb2b3f279910db9fd7d831bed2eec35ea7f834c v0.1.3
-a9bbf79baec0c02897a43a41dfa0d0c427a05441 v0.1.3
-a1ee475ba255ea50216bb93bac9ff1a32845b8c8 v0.1.4
+0000000000000000000000000000000000000000 v0.1.1

data/.travis.yml

@@ -1,8 +1,21 @@
 language: ruby
 rvm:
-  - 1.9.3
-  - 2.0.0
-  - 2.1.5
-  - 2.2.0
-  - rbx-2.4.1
-  - jruby-19mode
+- 1.9.3
+- 2.0.0
+- 2.1.7
+- 2.2.3
+- rbx-2.4.1
+- rbx-2.5.8
+- jruby-19mode
+sudo: false
+notifications:
+  hipchat:
+    rooms:
+      secure: OwpsmGlIxlSbLUWVZZI+xBErDkFc5XO2vmjs+ddQkNiL1E9N5SG35x75113S6EZ3qhqeNMPFBfZYDqem6jkhNOWsmH3EIH+QT1lWxnosrr0LgyJpvFosvjQaryvqJHVhT5tdBqzaWEYB6ObRLOUt7A5YrbtWHyTScB6ThpXCiR4=
+  webhooks:
+    urls:
+      - secure: Xm+R/3O6iG2sDbfrR8D5Y9AYJkB7DDjLBcKZEn+xaTVjuX/XFLF7p+v9n9v7Qs/v0VtU75pVX4Z++OmNJZJzJKB3Owgb4c1rMOGmctza2JPL+1yovmhpG0/S0hjMkO5g4CsAKKcQoaDXNrubUVHpEchLPP/aCx7/F4twCan9bfc=
+    on_success: always
+    on_failure: always
+    on_start: false
+

data/README.md

@@ -1,467 +1,43 @@
 # Wongi::Engine
 
-This library contains a rule engine written in Ruby. It's based on the [Rete algorithm](http://en.wikipedia.org/wiki/Rete_algorithm) and uses a DSL to express rules in a readable way.
+[![Join the chat at https://gitter.im/ulfurinn/wongi-engine](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/ulfurinn/wongi-engine?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 [![Build Status](https://travis-ci.org/ulfurinn/wongi-engine.svg?branch=master)](https://travis-ci.org/ulfurinn/wongi-engine) (MRI 1.9.3, 2.0, 2.1, 2.2, Rubinius, JRuby)
 
-## Word of caution
-
-This is complex and fragile machinery, and there may be subtle bugs that are only revealed with nontrivial usage. Be conservative with upgrades, test your rules extensively, and please report any behaviour that is not consistent with your expectations.
-
-## Tutorial
-
-To begin, say
-
-	engine = Wongi::Engine.create
-
-Now let's add some facts to the system.
-
-### Facts
-
-All knowledge in Wongi::Engine is represented by triples of { subject, predicate, object }. Predicates usually stand for subjects' properties, and objects for values of those properties. More complex types can always be decomposed into such triples.
-
-Triples can contain any Ruby object that defines the `==` comparison in a meaningful way, but some symbols have special meaning, as we will see.
-
-Try this:
-
-```ruby
-engine << [ "Alice", "friend", "Bob" ]
-engine << [ "Alice", "age", 35 ]
-```
-
-To remove facts, say:
-
-```ruby
-engine.retract [ "Alice", "age", 35 ]
-```
-
-What can we do with this information?
-
-### Simple iteration
-
-Suppose we want to list all we know about Alice. You could, for instance, do:
-
-```ruby
-engine.each "Alice", :_, :_ do |item|
-	puts "Alice's #{item.predicate} is #{item.object}"
-end
-```
-
-`each` takes three arguments for every field of a triple and tries to match the resulting template against the known facts. `:_` is the special value that matches anything. This kind of pattern matching plays a large role in Wongi::Engine; more on that later.
-
-In a similar way, you can use `select` to get an array of matching facts and `find` to get the first matching one. Both methods take three arguments.
-
-### Simple rules
-
-It's not very interesting to use the engine like that, though. Rule engines are supposed to be declarative. Let's try this:
-
-```ruby
-friends = engine.rule "friends" do
-	forall {
-		has :PersonA, "friend", :PersonB
-	}
-end
-```
-
-Here's your first taste of the engine's DSL. A rule, generally speaking, consists of a number of conditions the dataset needs to meet; those are defined in the `forall` section (also spelled `for_all`, if you prefer that). `has` (or `fact`) specifies that there needs to be a fact that matches the given pattern; in this case, one with the predicate `"friend"`.
-
-When a pattern contains a symbol that starts with an uppercase letter, it introduces a variable which will be bound to an actual triple field. Their values can be retrieved from the result set:
-
-```ruby
-friends.tokens.each do |token|
-	puts "%s and %s are friends" % [ token[ :PersonA ], token[ :PersonB ] ]
-end
-```
-
-A **token** represents all facts that passed the rule's conditions. If you think of the dataset as of a long SQL table being joined with itself, then a token is like a row in the resulting table.
-
-If you don't care about a specific field's value, you can use the all-matcher `:_` in its place so as not to introduce unnecessary variables.
-
-Once a variable is bound, it can be used to match further facts within a rule. Let's add another friendship:
-
-```ruby
-engine << [ "Bob", "friend", "Claire" ]
-```
-
-and another rule:
-	
-```ruby
-remote = engine.rule "remote friends" do
-	forall {
-		has :PersonA, "friend", :PersonB
-		has :PersonB, "friend", :PersonC
-	}
-end
-
-remote.tokens.each do |token|
-	puts "%s and %s are friends through %s" % [ token[ :PersonA ], token[ :PersonC ], token[ :PersonB ] ]
-end
-```
-
-(`engine.rule` returns the created **production node** - an object that accumulates the rule's result set. You don't have to carry it around if you don't want to - it is always possible to retrieve it later as `engine.productions["remote friends"]`.)
-
-### Stored queries
-
-Taking the SQL metaphor further, you can use the engine to do fancy searches:
-
-```ruby
-q = engine.query "friends" do
-	search_on :Name
-	forall {
-		has :Name, "friend", :Friend
-	}
-end
-
-engine.execute "friends", { Name: "Alice" }
-q.tokens.each do |token|
-	... # you know the drill
-end
-```
-
-Not that this is a particularly fancy search, but you get the idea.
-
-Queries work the same way as normal rules, but they come with some variables already bound by the time matching starts.
-
-You can also retrieve the query's production node from `engine.results["friends"]` (they are intentionally kept separate from regular productions).
-
-### Taking an action
-
-There's more to rules than passive accumulation:
-
-```ruby
-engine.rule "self-printer" do
-	forall {
-		has :PersonA, "friend", :PersonB
-	}
-	make {
-		action { |token|
-			puts "%s and %s are friends" % [ token[ :PersonA ], token[ :PersonB ] ]
-		}
-	}
-end
-```
-
-The `make` section (also spelled `do!`, if you find it more agreeable English, because `do` is a keyword in Ruby) lists everything that happens when a rule's conditions are fully matched (we say "the production node is **activated**"). Wongi::Engine provides only a small amount of built-in actions, but you can define your own ones, and the simplest one is just `action` with a block. The block will be executed in the engine's context.
-
-### More facts!
-
-Note how our facts define relations that always go from subject to object - they form a directed graph. In a perfect world, friendships go both ways, but to specify this in our model, we need to have two facts for each couple. Instead of duplicating everything by hand, let's automate that:
-
-```ruby
-engine.rule "symmetric predicate" do
-	forall {
-		has :Predicate, "symmetric", true
-		has :X, :Predicate, :Y
-	}
-	make {
-		gen :Y, :Predicate, :X
-	}
-end
-
-engine << ["friend", "symmetric", true]
-```
-
-If you still have the "self-printer" rule installed, you will see some new friendships pop up immediately!
-
-The built-in `gen` action creates new facts, taking either fixed values or variables as arguments. (It will complain if you provide a variable that isn't bound by the time it's activated.) Here, it takes all relations we've defined to be [symmetric](http://en.wikipedia.org/wiki/Symmetric_relation), finds all couples in those sorts of relations and turns them around.
-
-### Matchers
-
-It wouldn't be very useful if `has` were the only sort of condition that could be used. Here are some more:
-
-#### `neg subject, predicate, object`
-
-Passes if the specified template does *not* match anything in the dataset. Alias: `missing`.
-
-#### `maybe subject, predicate, object`
-
-Passes whether or not the template matches anything. It's only useful if it introduces a new variable; you can think of `LEFT JOIN`. Alias: `optional`.
-
-#### `none { ... }`
-
-The `none` block contains other matchers and passes if that *entire subchain* returns an empty set. In other words, it corresponds to an expression `not ( a and b and ... )`.
-
-#### `any { option { ... } ... }`
-
-The `any` block contains several `option` blocks, each of them containing other matchers. It passes if any of the `option` subchains matches. It's a shame that disjunction has to be so much more verbose than conjunction, but life is cruel.
-
-#### `same x, y`
-
-Passes if the arguments are equal. Alias: `eq`, `equal`.
-
-#### `diff x, y`
-
-Passes if the arguments are not equal. Alias: `ne`.
-
-#### `less x, y`, `greater x, y`
-
-Should be obvious by now.
-
-#### `assuming rule_name`
-
-This is a shortcut for extending a common base rule with additional matchers. `rule_name` must already be installed on the same engine instance. `assuming` must be the first clause in the extending rule.
-
-```ruby
-engine << rule( :base ) {
-  forall {
-    has :x, :y, :Z
-  }
-}
-
-engine << rule {
-  forall {
-    assuming :base
-    has :Z, :u, :W
-  }
-}
-```
-
-#### `assert { |token| ... }`, `assert var1, var2, ... do |val1, val2, ... | ... end`
-
-Passes if the block evaluates to `true`. Having no arguments passes the entire token as an argument, listing some variables passes only their values.
-
-#### `assign variable do |token| ... end`
-
-Not a *matcher*, strictly speaking, because it always passes. What it does instead is introduce a new variable bound to the block's return value.
+[Feature annoucements](https://github.com/ulfurinn/wongi-engine/issues?q=is%3Aopen+is%3Aissue+label%3Aannoucement)
 
-### Feedback loop prevention
+[Open discussions](https://github.com/ulfurinn/wongi-engine/issues?q=is%3Aopen+is%3Aissue+label%3Adiscussion)
 
-Consider the following rule:
-
-```ruby
-engine.rule "default value" do
-	forall {
-		neg :car, :colour, :_
-	}
-	make {
-		gen :car, :colour, "black"
-	}
-end
-```
-
-The intent here is to provide a default value for an attribute; however, how will it actually execute?
-
-1. The fact is missing, activate the rule, generate the fact.
-2. The fact is present, invalidate the rule, retract the generated fact.
-3. The fact is missing...
-
-...and so on until you get a stack overflow. In situations like this the engine will try to do the pragmatic thing and detect the loop, stopping after step 1. If you want to keep the "pure" behaviour, give the `unsafe: true` option to the `neg` rule and try to do the same thing with helper facts.
-
-**Note**: this is a specific use case; it is still perfectly possible to construct more elaborate infinite cascades involving several rules that will not be caught.
-
-### Timeline
-
-Wongi::Engine has a limited concept of timed facts: time is discrete and only extends into the past. Matchers that accept a triple specification (`has`, `neg` and `maybe`) can also accept a `time` option, an integer <= 0, which will make them look at a past state of the system. "0" means the current state and is the default value, "-1" means the one just before the current, and so on.
-
-To create past states, say:
-
-```ruby
-engine.snapshot!
-```
-
-This will shift all facts one step into the past. The new current state will be a copy of the last one. You can only insert new facts into the current state, "retroactive" facts are not allowed.
-
-### Time-aware matchers
-
-The following matchers are nothing but syntactic sugar for a combination of primitives.
-
-#### `asserted subject, predicate, object`
-
-Short for:
-	
-```ruby
-has subject, predicate, object, time: 0
-neg subject, predicate, object, time: -1
-```
-
-That is, it passes if the fact was missing in the previous state but exists in the current one. Alias: `added`.
-
-#### `retracted subject, predicate, object`
-
-Short for:
-
-```ruby
-has subject, predicate, object, time: -1
-neg subject, predicate, object, time: 0
-```
-
-The reverse of `asserted`. Alias: `removed`.
-
-#### `kept subject, predicate, object`
-
-Short for:
-
-```ruby
-has subject, predicate, object, time: -1
-has subject, predicate, object, time: 0
-```
-
-Alias: `still_has`.
-
-#### `kept_missing subject, predicate, object`
-
-Short for:
-
-```ruby
-neg subject, predicate, object, time: -1
-neg subject, predicate, object, time: 0
-```
-
-Since neg rules cannot introduce new variables, neither can this one.
-
-Alias: `still_missing`.
-
-### Other built-in actions
-
-#### `collect variable, collector_name`
-
-If you use this action, `engine.collection( collector_name )` will provide a `uniq`'ed array of all values `variable` has been bound to. It's a bit shorter than iterating over the tokens by hand.
-
-#### `error message`, `error { |hash_of_variable_assignments| ... }`
-
-Useful when you want to detect contradictory facts. `engine.errors` will give an array of all error messages produced when this action is activated. If you use the block form, the block needs to return a message.
-
-#### `trace options`
-
-The debugging action that will print a message every time it's activated. Possible options are:
-
-* `values` (boolean = false): whether to print variable assignments as well
-* `io` (IO = $stdout): which IO object to use
-* `generation` (boolean = false): whether this rule's `gen` action should print messages too. `trace` must come before any `gen` actions in this case.
-* `tracer`, `tracer_class`: a custom tracer that must respond to `trace` and accept a hash argument. Hash contents will vary depending on the action being traced.
-
-### Custom actions
-
-We've seen one way to specify custom actions: using `action` with a block. Another way to use it is to say:
-
-```ruby
-action class, ... do
-	...
-end
-```
-
-Any additional arguments or blocks will be given to `initialize`, and the class must define an `execute` method taking a token. Passing any object with an `execute` method also works.
-
-If your action class inherits from `Wongi::Engine::Action`, you'll have the following (more or less useful) attributes:
-
-* `rete`: the engine instance
-* `rule`: the rule object that is using this action
-* `name`: the extension clause used to define this action (read more under [DSL extensions](#dsl-extensions))
-* `production`: the production node
-
-If you can't or don't want to inherit, you can define the accessors yourself. Having just the ones you need is fine.
-
-### Organising rules
-
-Using `engine.rule` and `engine.query` is fine if you want to experiment, but to make rules and queries more manageable, you will probably want to keep them separate from the engine instance. One way to do that is to just say:
-
-```ruby
-my_rule = rule "name" do
-	...
-end
-
-engine << my_rule
-```
-
-For even more convenience, why not group rules together:
-
-```ruby
-my_ruleset = ruleset {
-	rule "rule 1" do
-		...
-	end
-	rule "rule 2" do
-		...
-	end
-}
-
-engine << my_ruleset
-```
-
-Again, you don't need to hold on to object references if you don't want to:
-
-```ruby
-ruleset "my set" do
-	...
-end
-
-engine << Wongi::Engine::Ruleset[ "my set" ]
-```
-
-### DSL extensions
-
-This is a more advanced method of customising. In general, DSL extensions have the form:
-
-```ruby
-dsl {
-	section [ :forall | :make ]
-	clause :my_action
-	[ action | accept | body ] ...
-}
-```
-
-which is then used in a rule like this:
-
-```ruby
-make {
-	my_action ...
-}
-```
-
-DSL extensions are globally visible to all engine instances.
-
-Let's have a look at the three ways to define a clause's implementation.
-
-#### `body { |...| ... }`
-
-This simply allows you to group several other actions or matchers. It is perhaps the only way you have to extend the `forall` section, as any non-trivial matchers will require special support from the engine itself.
-
-#### `action class`, `action do |token| ... end`
-
-This works almost exactly like using the `action` action directly in a rule, but gives it a more meaningful alias. Arguments to `initialize`, however, are taken from the action's invocation in `make`, not the definition.
-
-A useful pattern is having specialised named collectors, defined like this:
+This library contains a rule engine written in Ruby. It's based on the [Rete algorithm](http://en.wikipedia.org/wiki/Rete_algorithm) and uses a DSL to express rules in a readable way.
 
-```ruby
-dsl {
-	section :make
-	clause :my_collection
-	action Wongi::Engine::SimpleCollector.collector
-}
-```
+## Word of caution
 
-installed like this:
+This is complex and fragile machinery, and there may be subtle bugs that are only revealed with nontrivial usage. Be conservative with upgrades, test your rules extensively, and please report any behaviour that is not consistent with your expectations.
 
-```ruby
-rule('collecting') {
-	...
-	make {
-		my_collection :X
-	}
-}
-```
+## How to use this thing?
 
-and accessed like this:
+[The tutorial](http://ulfurinn.github.io/wongi-engine/) should get you started nicely.
 
-```ruby
-collection = engine.collection :my_collection
-```
+## Acknowledgements
 
-#### `accept class`
+The Rete implementation in this library largely follows the outline presented in [\[Doorenbos, 1995\]](http://reports-archive.adm.cs.cmu.edu/anon/1995/CMU-CS-95-113.pdf).
 
-Most library users probably won't need this, but it's here for completion. Acceptors represent an intermediate state. They allow you to have some shared data that you customize for a given engine instance. The class needs to respond to `import_into( engine_instance )` and return something usable as an action, or to be usable as an action itself.
+## Changelog
 
-The class also gets arguments to `initialize` from the action's invocation.
+### 0.2.0
 
-## Acknowledgements
+* refactored compilation code
+* [data overlays](https://github.com/ulfurinn/wongi-engine/issues/45)
+* DSL methods are removed from `Object` and are available by including `Wongi::Engine::DSL` instead
 
-The Rete implementation in this library largely follows the outline presented in [\[Doorenbos, 1995\]](http://reports-archive.adm.cs.cmu.edu/anon/1995/CMU-CS-95-113.pdf).
+### 0.1.4
 
-## Changelog
+* fixed a bug in evaluation of `assign` nodes
 
 ### 0.1.0
 
 * massively rewritten rule activation; this simplifies development and debugging and opens the road for useful features such as fully reversible custom actions
+* **treat this as a major upgrade and test thoroughly**
 
 ### 0.0.17
 

data/examples/ex02.rb

@@ -1,4 +1,5 @@
 include Wongi::Engine
+include Wongi::Engine::DSL
 
 ds = Network.new
 
@@ -26,11 +27,11 @@ ds << WME.new( "Alice", "friend", "Bob" )
 puts "Asserted facts:"
 
 puts "Should print 3 facts:"
-puts ds.wmes
+puts ds.wmes.to_a
 
 
 ds.retract WME.new( "Alice", "friend", "Bob" )
 
 puts "Should print 1 fact:"
-puts ds.wmes
+puts ds.wmes.to_a
 

data/examples/graphviz.rb

@@ -1,6 +1,7 @@
 require 'wongi-engine'
 
 include Wongi::Engine
+include Wongi::Engine::DSL
 
 ds = Network.new
 ds << rule('demo') {

data/lib/wongi-engine/alpha_memory.rb

@@ -13,8 +13,7 @@ module Wongi::Engine
     end
 
     def activate wme
-      @wmes << wme
-      wme.alphas << self
+      wme.overlay.add_wme(wme, self)
       # TODO: it used to activate before adding to the list. mandated by the original thesis. investigate. it appears to create duplicate tokens - needs a remedy in collecting nodes
       betas.each do |beta|
         beta.alpha_activate wme
@@ -22,7 +21,7 @@ module Wongi::Engine
     end
 
     def deactivate wme
-      @wmes.delete wme
+      wme.overlay.remove_wme(wme, self)
       betas.each do |beta|
         beta.alpha_deactivate wme
       end
@@ -35,17 +34,23 @@ module Wongi::Engine
     end
 
     def inspect
-      "<Alpha #{__id__} template=#{template} wmes=#{@wmes}>"
+      "<Alpha #{__id__} template=#{template}>"
     end
 
     def to_s
       inspect
     end
 
+    def size
+      wmes.count
+    end
+
     def wmes
       Enumerator.new do |y|
-        @wmes.dup.each do |wme|
-          y << wme unless wme.deleted?
+        rete.overlays.each do |overlay|
+          overlay.raw_wmes(self).dup.each do |wme|
+            y << wme
+          end
         end
       end
     end

data/lib/wongi-engine/beta/assignment_node.rb

@@ -1,20 +1,5 @@
 module Wongi::Engine
 
-  class Assignment
-
-    def initialize variable, &body
-      @variable, @body = variable, body
-    end
-
-    def compile context
-      context.node = context.node.beta_memory.assignment_node( @variable, @body )
-      context.node.context = context
-      context.earlier << self
-      context
-    end
-
-  end
-
   class AssignmentNode < BetaNode
 
     def initialize parent, variable, body