wongi-engine 0.0.1 → 0.0.2

data/README.md

@@ -26,14 +26,16 @@ Now let's add some facts to the system.
 
 ### Facts
 
-All knowledge in Wongi::Engine is represented as 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.
+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:
 
-	engine << [ "Alice", "friend", "Bob" ]
-	engine << [ "Alice", "age", 35 ]
+```ruby
+engine << [ "Alice", "friend", "Bob" ]
+engine << [ "Alice", "age", 35 ]
+```
 
 What can we do with this information?
 
@@ -41,9 +43,11 @@ What can we do with this information?
 
 Suppose we want to list all we know about Alice. You could, for instance, do:
 
-	engine.each "Alice", :_, :_ do |item|
-		puts "Alice's #{item.predicate} is #{item.object}"
-	end
+```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.
 
@@ -53,19 +57,23 @@ In a similar way, you can use `select` to get an array of matching facts and `fi
 
 It's not very interesting to use the engine like that, though. Rule engines are supposed to be declarative. Let's try this:
 
-	friends = engine.rule "friends" do
-		forall {
-			has :PersonA, "friend", :PersonB
-		}
-	end
+```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 `"friends"`.
 
 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:
 
-	friends.tokens.each do |token|
-		puts "%s and %s are friends" % [ token[ :PersonA ], token[ :PersonB ] ]
-	end
+```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.
 
@@ -77,16 +85,18 @@ Once a variable is bound, it can be used to match further facts within a rule. L
 
 and another rule:
 	
-	remote = engine.rule "remote friends" do
-		forall {
-			has :PersonA, "friend", :PersonB
-			has :PersonB, "friend", :PersonC
-		}
-	end
+```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
+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"]`.)
 
@@ -94,17 +104,19 @@ and another rule:
 
 Taking the SQL metaphor further, you can use the engine to do fancy searches:
 
-	q = engine.query "friends" do
-		search_on :Name
-		forall {
-			has :Name, "friend", :Friend
-		}
-	end
+```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
+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.
 
@@ -116,16 +128,18 @@ You can also retrieve the query's production node from `engine.results["friends"
 
 There's more to rules than passive accumulation:
 
-	engine.rule "self-printer" do
-		forall {
-			has :PersonA, "friend", :PersonB
-		}
-		make {
-			action { |token|
-				puts "%s and %s are friends" % [ token[ :PersonA ], token[ :PersonB ] ]
-			}
+```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
+	}
+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 build-in actions, but you can define define your own ones, and the simplest one is just `action` with a block.
 
@@ -133,17 +147,19 @@ The `make` section (also spelled `do!`, if you find it more agreeable English, b
 
 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 out model, we need to have two facts for each couple. Instead of duplicating everything by hand, let's automate that:
 
-	engine.rule "symmetric predicate" do
-		forall {
-			has :Predicate, "symmetric", true
-			has :X, :Predicate, :Y
-		}
-		make {
-			gen :Y, :Predicate, :X
-		}
-	end
+```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]
+engine << ["friend", "symmetric", true]
+```
 
 If you still have the "self-printer" rule installed, you will see some new friendships pop up immediately!
 
@@ -165,9 +181,9 @@ Passes whether or not the template matches anything. It's only useful if it intr
 
 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 { variant { ... } ... }`
+#### `any { option { ... } ... }`
 
-The `any` block contains several `variant` blocks, each of them containing other matchers. It passes if any of the `variant` subchains matches. It's a shame that disjunction has to be so much more verbose than conjunction, but life is cruel.
+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`
 
@@ -195,8 +211,10 @@ The following matchers are nothing but syntactic sugar for a combination of prim
 
 Short for:
 	
-	neg subject, predicate, object, -1
-	has subject, predicate, object, 0
+```ruby
+neg subject, predicate, object, -1
+has subject, predicate, object, 0
+```
 
 That is, it passes if the fact was missing in the previous state but exists in the current one. Alias: `added`.
 
@@ -204,8 +222,10 @@ That is, it passes if the fact was missing in the previous state but exists in t
 
 Short for:
 
-	has subject, predicate, object, -1
-	neg subject, predicate, object, 0
+```ruby
+has subject, predicate, object, -1
+neg subject, predicate, object, 0
+```
 
 The reverse of `asserted`. Alias: `removed`.
 
@@ -213,8 +233,10 @@ The reverse of `asserted`. Alias: `removed`.
 
 Short for:
 
-	has subject, predicate, object, -1
-	has subject, predicate, object, 0
+```ruby
+has subject, predicate, object, -1
+has subject, predicate, object, 0
+```
 
 Alias: `still_has`.
 
@@ -222,8 +244,10 @@ Alias: `still_has`.
 
 Short for:
 
-	neg subject, predicate, object, -1
-	neg subject, predicate, object, 0
+```ruby
+neg subject, predicate, object, -1
+neg subject, predicate, object, 0
+```
 
 Alias: `still_missing`.
 
@@ -250,9 +274,11 @@ The debugging action that will print a message every time it's activated. Possib
 
 We've seen one way to specify custom actions: using `action` with a block. Another way to use it is to say:
 
-	action class, ... do
-		...
-	end
+```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.
 
@@ -260,7 +286,7 @@ If your action class inherits from `Wongi::Engine::Action`, you'll have the foll
 
 * `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])
+* `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.
@@ -269,48 +295,58 @@ If you can't or don't want to inherit, you can define the accessors yourself. Ha
 
 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:
 
-	my_rule = rule "name" do
-		...
-	end
+```ruby
+my_rule = rule "name" do
+	...
+end
 
-	engine << my_rule
+engine << my_rule
+```
 
 For even more convenience, why not group rules together:
 
-	my_ruleset = ruleset {
-		rule "rule 1" do
-			...
-		end
-		rule "rule 2" do
-			...
-		end
-	}
+```ruby
+my_ruleset = ruleset {
+	rule "rule 1" do
+		...
+	end
+	rule "rule 2" do
+		...
+	end
+}
 
-	engine << my_ruleset
+engine << my_ruleset
+```
 
 Again, you don't need to hold on to object references if you don't want to:
 
-	ruleset "my set" do
-		...
-	end
+```ruby
+ruleset "my set" do
+	...
+end
 
-	engine << Wongi::Engine::Ruleset[ "my set" ]
+engine << Wongi::Engine::Ruleset[ "my set" ]
+```
 
 ### DSL extensions
 
 This is a more advanced method of customising. In general, DSL extensions have the form:
 
-	dsl {
-		section [ :forall | :make ]
-		clause :my_action
-		[ action | accept | body ] ...
-	}
+```ruby
+dsl {
+	section [ :forall | :make ]
+	clause :my_action
+	[ action | accept | body ] ...
+}
+```
 
 which is then used in a rule like this:
 
-	make {
-		my_action ...
-	}
+```ruby
+make {
+	my_action ...
+}
+```
 
 DSL extensions are globally visible to all engine instances.
 
@@ -322,7 +358,34 @@ This simply allows you to group several other actions or matchers. It is perhaps
 
 #### `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 definition.
+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:
+
+```ruby
+dsl {
+	section :make
+	clause :my_collection
+	action Wongi::Engine::SimpleCollector.collector
+}
+```
+
+installed like this:
+
+```ruby
+rule('collecting') {
+	...
+	make {
+		my_collection :X
+	}
+}
+```
+
+and accessed like this:
+
+```ruby
+collection = engine.collection :my_collection
+```
 
 #### `accept class`
 

data/lib/wongi-engine/dsl/any_rule.rb

@@ -10,7 +10,7 @@ module Wongi::Engine
       end
     end
 
-    def variant &block
+    def option &block
       var = VariantRule.new
       var.instance_eval &block
       variants << var

data/lib/wongi-engine/version.rb

@@ -1,5 +1,5 @@
 module Wongi
   module Engine
-    VERSION = "0.0.1"
+    VERSION = "0.0.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wongi-engine
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-13 00:00:00.000000000 Z
+date: 2012-07-16 00:00:00.000000000 Z
 dependencies: []
 description: A rule engine.
 email: