rubylog 2.0pre1 → 2.0.0

data/README.rdoc

@@ -3,38 +3,52 @@
 Rubylog is a Prolog-like DSL for Ruby. The language is inspired by {Jamis
 Buck}[http://weblog.jamisbuck.org/2006/10/28/prolog-in-ruby], and the
 implementation is based on {Yield Prolog}[http://yieldprolog.sourceforge.net/],
-with lots of sintactic and semantic additions.
+with lots of sintactic and semantic candy.
 
 See the {wiki}[https://github.com/cie/rubylog/wiki] for online documentation.
 
 == Getting started
 
+=== Installing
+
+Currently, Rubylog only works with Ruby 1.9.2. 
+
 First, install the gem
 
   $ gem install rubylog
 
 or, if you use +bundler+, add this line to your +Gemfile+:
 
-  gem 'rubylog', '~>2.0pre1'
+  gem 'rubylog', '~>2.0'
+
 
+=== The context
+
+Secondly, you need a Rubylog context. The simplest you can do is to extend Rubylog::Context into the main object.
+
+  require 'rubylog'
+  extend Rubylog::Context
 
+Another option is to use Kernel#rubylog:
 
-First, you need a Rubylog context. The simplest you can do is to extend Rubylog::Context into the main object.
 
   require 'rubylog'
   extend Rubylog::Context
 
+  rubylog do
+    # your code here
+  end
+
 
-=== Data types
+== Data types
 
-Rubylog is similar to Prolog, but there are quite a few differences. In Rubylog,
-you can use any Ruby object as data.
+Rubylog is similar to Prolog, but there are quite a few differences.
 
 Rubylog variables are (undefined) constant names:
 
   A, B, ANYTHING
 
-A variables whose name starts with +ANY...+ (case-insensitive) is a don't-care
+A variable can be bound or unbound, and it contains a Ruby object when bound. A variable whose name starts with +ANY...+ (case-insensitive) is a don't-care
 variable (like +_+ in Prolog).
 
 Lists are just Ruby arrays:
@@ -45,72 +59,74 @@ They can have splats:
 
   [1, 2, *T]
 
-Which would be <tt>[1,2|T]</tt> in Prolog, however, in Rubylog, splats are not limited
-to the end.
+Which would be <tt>[1,2|T]</tt> in Prolog. However, in Rubylog, splats are not limited
+to the end:
 
-=== Predicates
-As in prolog, predicates are the buinding blocks of your program. However, the arguments are in a different order than they are in prolog:
+  [1, *X, 5]
+  [*A, *B]
 
-  predicate_for String, ".likes()"
-  'John'.likes!('beer')
+Currently you cannot use hashes as terms.
 
-which would be <tt>likes('John','beer').</tt> in prolog. In Rubylog, predicates must be declared. The string indicating the predicate syntax is <tt>".likes()"</tt>. The format is <tt>:asdf .asdf .asdf() .asdf(,) .asdf(,,)</tt> for predicates with 0,1,2,3,4 arguments.
+== Predicates
+As in prolog, predicates are the building blocks of your program. However, the arguments are in a different order than they are in prolog:
 
-You can assert a rule with the +if+ method:
+  'John'.likes('beer')
 
-  predicate_for String, ".drinks() .has()"
-  X.drinks(Y).if X.has(Y).and X.likes(Y)        
+which would be <tt>likes('John','beer')</tt> in prolog. As you can see, the first argument comes first, then the functor, and then the further arguments.  
 
-This would be +drinks(X,Y) :- has(X,Y), likes(X,Y)+ in Prolog.
+In Rubylog, predicates must be declared with +predicate_for+:
 
-You can assert facts with <tt>if(:true)</tt>, or, as a shorthand you can use the bang
-syntax:
+  predicate_for String, ".likes()"
+  
+You have to specify the class of the possible first arguments (+String+ in this case), this is called the subject class. This could also be an array of classes. The string indicating the predicate syntax is <tt>".likes()"</tt>. The format is <tt>.asdf .asdf() .asdf(,) .asdf(,,)</tt> for predicates with 1,2,3 and 4 arguments. You can add descriptions in the indicator string e.g. <tt>"Person.likes(Drink)"</tt> means the same as <tt>".likes()"</tt>.
 
-  'John'.likes! 'milk'                         
+Declaring a predicate with arguments gives you three methods on the subject class:
 
-Bang assertions return their first argument (which is <tt>'John'</tt> in this case), so they can be chained:
+  predicate_for String, ".likes()"
+  'John'.likes('beer')    # returns a structure object representing this logical statement
+  'John'.likes!('beer')   # asserts that this statement as a fact
+  'John'.likes?('beer')   # tells if this statement is true (in this case, returns true)
 
-  'John'.likes!('beer').has!('beer')
+=== Nullary predicates
 
-You can also use +unless+:
+Nullary predicates are symbols, and they have to be declared with +predicate+:
 
-  predicate_for String, ".good .bad"
-  A.good.unless A.bad              
+  predicate ":asdf"
+  :asdf
 
-Nullary predicates are symbols, similar to Prolog:
 
-  'John'.drinks('beer').if :false.and(:cut!).or(:true)
+== Asserting clauses
 
+As in Prolog, there are two types of program clauses: facts and rules.
+You can assert facts with the bang syntax:
 
+  predicate_for String, ".likes()"
+  'John'.likes! 'milk'                         
 
-=== Built-in predicates
+This would be <tt>likes('John','beer').</tt> in Prolog. Bang assertions return their first argument (which is <tt>'John'</tt> in this case), so they can be chained:
 
-Some built-in predicates and their Prolog equivalents:
+  'John'.likes!('beer').has!('beer')
 
-  Rubylog  Prolog
-  -------  ------ 
-  :true     true
-  :fail     fail
-  .and()    ,
-  .or()     ;
-  :false    \+
-  .is()     =
-  .is_not() =/=
-  .in()     member
-  :cut!     !
+You can assert rules with the +if+ method:
+
+  predicate_for String, ".likes() .drinks() .has()"
+  
+  X.drinks(Y).if X.has(Y).and X.likes(Y)        
 
-There are some new ones:
+This would be <tt>drinks(X,Y) :- has(X,Y), likes(X,Y).</tt> in Prolog.
 
-  not_in, all, any, one, none, iff
 
-You can see reference of these in <tt>lib/rubylog/builtins/logic.rb</tt> and <tt>lib/rubylog/builtins/term.rb</tt>
+You can also use +unless+:
+
+  predicate_for String, ".good .bad"
+  A.good.unless A.bad              
+
 
 
-See the documentation in <tt>lib/rubylog/builtins/</tt>
 
-=== Unification
+== Unification
 
-In Rubylog, unification works quite the same in Prolog, with the +is+ functor.
+In Rubylog, unification works like in Prolog, but with the +is+ functor.
 
   A.is(B)
 
@@ -121,25 +137,36 @@ Using arrays, you can benefit the splats:
 
 The +in+ predicate unifies the first argument with any member of the collection:
 
-  4.in([1,2,3,4])
+  4.in([1,2,3,4])             # member(4,[1,2,3,4]) in prolog
+
+== Guards
 
-You can use guards:
+You can use guards. These are constant expressions that restrict the unification of variables. There are several types of guards:
 
-  A[String].in(["asdf",5,nil]).each { p A }   # outputs "asdf"
-  A[/x/].in(["asdf","xyz"]).each { p A }      # outputs "xyz"
-  A[thats < 5].in([4,5,6]).each { p A }       # outputs 4
+  A[String].in(["asdf",5,nil]).each { p A }     # outputs "asdf"
+  A[/x/].in(["asdf","xyz"]).each { p A }        # outputs "xyz"
+  A[length: 3].in(["abc","abcd"]).each { p A }  # outputs "abc"
+  A[thats < 5].in([4,5,6]).each { p A }         # outputs 4
+  A[thats.length + 1 == 5].in(["abc","abcd"]).each { p A }    # outputs "abcd"
 
-=== Moving between Ruby and Rubylog
-==== Running a query
++thats+ can receive any number of messages chained, and this will be applied to the value that would be bound to the variable. 
+You can add various guards to a variable. +thats\_not+ is the negation of +thats+.
 
-If you want to run a query, you have many different syntaxes:
+  A[Integer, thats%2 == 0].even!
+
+This is an experimental feature. Currently, you cannot use variables in guards, only constant values.
+
+
+== Moving between Ruby and Rubylog
+=== Running a query
+
+If you want to run a query, you have three different syntaxes:
 
-  prove ('John'.drinks 'beer')  # => true
   true? ('John'.drinks 'beer')  # => true
   ('John'.drinks 'beer').true?  # => true
   'John'.drinks? 'beer'         # => true
 
-==== Enumerations
+=== Finding solutions
 
 +Structure+ implements +Enumerable+, and yields the solutions. Within the
 enumeration block, you can access the values of your variables.
@@ -149,7 +176,9 @@ enumeration block, you can access the values of your variables.
   ('John'.drinks X).map{X}          # => ['beer']
   ('John'.drinks X).count           # => 1
 
-==== Procs as predicates
+You can also use +solve+, which is equivalent with +each+.
+
+=== Procs as predicates
 
 You can invoke Ruby codes in Rubylog rules with a proc:
 
@@ -161,75 +190,107 @@ or in most cases you can use just a block:
 
 The predicate succeeds if the block returns a true value.
 
-==== Procs as functions
+=== Procs as functions
 
 +is+ and +in+ can take a proc or block argument, which they execute and take its return value:
 
   X.good.if X.is { 'BEER'.downcase }
   X.good.if X.in { get_good_drinks() }
 
-==== The two modes of Rubylog
+=== Variables in blocks
 
-Rubylog has two modes, DSL and native. DSL code is executed only once
-at compile time, and is used for describing the Rubylog program. Native code is
-executed runtime. Any block passed to Rubylog structures native code.
+When you use blocks or procs as predicates or functions, or when you use enumeration methods with blocks, you can access values of variables by their name in the blocks (if they are bound).
 
-  ('John'.drinks X).and { X != 'beer'}.each { p X }
-  ^^^^^^^^^^^^^^^^^^^^^^              ^^^^^^          dsl mode
-                         ^^^^^^^^^^^^        ^^^^^    native mode
 
-In dsl mode, variables are +Rubylog::Variable+ objects. In native mode,
-variables are substituted with their respecitve value (or +nil+ if they are not
-bound).
+  'John'.likes(Y).if { Y =~ /ale/ }
+  'John'.likes(Y).if Y.is { Y =~ /ale/ }
+  'John'.likes(Y).each { p Y }
+
+If your variable is unbound, you will get the variable object.
+
+  X.is(Y).each { p X.class }   # outputs 'Rubylog::Variable'
 
-All built-in rubylog predicates are clean logical programming predicates witout
-a side-effect. If you want some side-effects, you always go into native mode.
 
-=== Rubylog as a test suite
+== Rspec integration
 
-You can write simple tests using the +check+ method:
+Rubylog can integrate with RSpec. This enables you to use variables and predicates in specs.
 
-  theory do
-    check :true.or :false
-    check A.is(3).and A.in [1,2,3]
-    check { 5+5 == 10 }
+  require "rspec/rubylog"
+
+  describe "numbers", rubylog: true do
+    specify do
+      A.is(5).map{A}.should == [5]
+    end
   end
 
-You sould put this file in <tt>"./logic/something\_logic.rb"</tt>. Then you can run it
-with 
+There is an assertion method called +check+ that receives a predicate as an argument and raises an exception if it fails.
 
-  rubylog logic/something_logic.rb
+  check 5.is(5)
 
-Or you can run all files in <tt>logic/**/*\_logic.rb</tt> with
+== Built-in predicates
 
-  rubylog
+Some built-in predicates and their Prolog equivalents:
 
-=== Other built-in libraries
+  Rubylog  Prolog
+  -------  ------ 
+  :true     true
+  :fail     fail
+  .and()    ,
+  .or()     ;
+  .false    \+
+  .is()     =
+  .is_not() =/=
+  .in()     member
+  :cut!     !
 
-==== File system
+There are some new ones which do not exist in prolog. 
 
-You can make some queries on the file system:
+* <tt>.not\_in()</tt> is the negation of <tt>.in()</tt>.
 
-  require "rubylog/builtins/file_system"
 
-  theory do
-    check "README".filename_in "."
+=== Quantifiers
 
-    X.dirname_in(".").each { puts X }
-  end
+<tt>.all(), .any(), .one(), .none()</tt> are prediates that are analogous to their equivalents in <tt>Enumerable</tt>. They prove their first argument, and for each solution try to prove their second argument. If the second argument succeeds for all / any / exactly one / none of the solutions of the first argument, they succeed. Some examples:
 
+  predicate_for Integer, ".even"
+  X.even.if { X%2 == 0 } 
+  check X.in([2,4]).all(X.even)
+  check X.in([1,2,4]).any(X.even)
+  check X.in([1,2,3]).one(X.even)
+  check X.in([1,3]).none(X.even)
 
-==== Reflection
+There is another similar predicate <tt>A.iff(B)</tt>, that succeeds if for all solutions of A, B is true, and vice versa. For example,
 
-You can make some metaprogramming with Rubylog
+  check X.in([2,4]).iff(X.in(1..4).and X.even)
 
+These predicates also have a prefix form, which can be used to create more naturally sounding program lines:
+
+  check all X.in([2,4]), X.even
+  check any X.in([1,2,4]), X.even
+  check one X.in([1,2,3]), X.even
+  check none X.in([1,3]), X.even
+  check iff X.in([2,4]), X.in(1..4).and(X.even)
+
+There is another quantifier, which only has a prefix form <tt>every(A, B)</tt>. This works similarly to <tt>.all()</tt>, but for each solution of A, creates a copy of B and chains them together with <tt>.and()</tt>. It can be useful for work with assumptions, see below. This is an experimental feature, and still contains bugs.
+
+=== File system
+
+You can make some queries on the file system:
 
-  require "rubylog/builtins/reflection"
+  check "README".filename_in "."
+  check "./README".file_in "."
 
-  theory do
-    functor_for String, :likes
+  X.dirname_in(".").each { puts X }
 
-    check "John".likes("Jane").structure(:likes, ["John", "Jane"])
+
+=== Reflection
+
+You can make some metaprogramming with Rubylog
+
+
+    predicate_for String, ".likes()"
+
+    check "John".likes("Jane").structure(Pred, :likes, ["John", "Jane"])
 
     "John".likes(X).if X.likes("John")
     "Jane".likes!("John")
@@ -241,12 +302,50 @@ You can make some metaprogramming with Rubylog
 
   end
 
+=== Arithmetics
+
+  check 5.sum_of(2,3)
+  check 5.product_of(1,5)
+
+These work as expected if you provide any two of the three paramters. For example,
+
+  10.sum_of(6,A).solve { p A }  # outputs 4
+
+  A.in(1..21).and(21.product_of(A,B)).each do
+    p [A,B]
+  end # outputs pairs of divisors
+
+=== Assumptions
+
+An assumption is an assertion that gets erased at backtracking. There are several possibilites for assuming clauses.
+
+  A.assumed              # assumes A as a fact
+  A.assumed_if(B)        # assumes A.if(B)
+  A.assumed_unless(B)    # assumes A.unless(B)
+  A.rejected             # assumes A.if(:cut!.and :fail) to the beginning of the rule list
+  A.rejected_if(B)       # assumes A.if(B.and :cut!.and :fail) to the beginning of the rule list
+  A.rejected_unless(B)   # assumes A.if(B.false.and :cut!.and :fail) to the beginning of the rule list
+  A.revoked              # temporarily removes a rule which holds for A
+
+These are experimental features.
+
+== Troubleshooting
+
+You can turn on tracing with
+
+  Rubylog.trace
+
+Or, you can trace a specific code block with
+
+  Rubylog.trace do
+    ...
+  end
+
+
 == Contributing
 
 === To the language
 
-* Post your own examples to the {wiki}[https://github.com/cie/rubylog/wiki/Examples].
-* Improve others' examples.
 * If you have a suggestion for the language, submit an issue.
 
 === Reporting bugs or requesting features

data/RELEASE_NOTES.rdoc

@@ -6,11 +6,10 @@
 
 == Version 2.0.0 (to be released)
 * Backwards incompatibilities
-  * <tt>Rubylog.theory</tt> is removed. Use <tt>Kernel#Rubylog</tt>.
+  * <tt>Rubylog.theory</tt> renamed to <tt>Kernel#rubylog</tt>.
   * <tt>file\_in</tt> includes directories and yields relative paths.
     <tt>dir\_in</tt> also yields relative paths.
-  * <tt>trace</tt> has became <tt>Rubylog.trace</tt>. If you use
-    <tt>Kernel#Rubylog</tt>, it does not matter.
+  * <tt>trace</tt> has became <tt>Rubylog.trace</tt>.
   * <tt>Theory</tt> has changed to <tt>Context</tt> and it became a module. 
   * No more inclusion of theories (contexts).
   * Predicates do not have reference in the theory (context), they are only referenced from the
@@ -26,7 +25,7 @@
   * No more real prefix functors, n-ary prefix functors are n\+1-ary functors with the context object as the first argument. Use <tt>predicate\_for Rubylog::Context, "..."</tt>.
   * <tt>Rubylog::DefaultBuiltins</tt> is replaced by <tt>Rubylog</tt>
   * <tt>Theory#prove</tt> was removed. Use <tt>Context#true?</tt>
-  * <tt>Rubylog::Callable<tt> renamed to <tt>Rubylog::Clause</tt>
+  * <tt>Rubylog::Callable<tt> renamed to <tt>Rubylog::Goal</tt>
   * <tt>discontiguous</tt> is removed. No more discontiguity checks.
   * <tt>implicit</tt> is removed. No implicit mode anymore.
   * <tt>Theory#clear</tt> is replaced by <tt>Context#initialize\_context</tt>.

data/VERSION

@@ -1 +1 @@
-2.0pre1
+2.0.0

data/examples/mice.rb

@@ -53,11 +53,11 @@ class CupSet
   CS.has_neighbors.if [C,D].in{CS[0..-2].zip(CS[1..-1] || [])}.and C.has_mouse.and D.has_mouse
 
   # A predicate definitely solves a set if there is no ambiguity
-  predicate_for Rubylog::Clause, %w(.definitely_solves())
+  predicate_for Rubylog::Goal, %w(.definitely_solves())
   T.definitely_solves(CS).if T.any(CS.has_neighbors).and(T.any(CS.has_neighbors.false)).false
 
   # A trial consist of peeking some cups
-  predicate_for Rubylog::Clause, %w(.trial_for())
+  predicate_for Rubylog::Goal, %w(.trial_for())
   T.trial_for(CS).if T.is{C.in(CS).map{C.peeked.or :true}.inject(:true,&:and)}.and T
 
   # A set is easy if can be definitely solved by a trial that has not seen all

data/examples/tracing.rb

@@ -6,9 +6,9 @@ extend Rubylog::Context
 solve S.is("Hello #{X}!").and X.is("no Trace") do puts S end
 
 # tracing with on/off
-Rubylog.trace!
+Rubylog.trace
 solve S.is("Hello #{X}!").and X.is("Trace") do puts S end
-Rubylog.trace!(false)
+Rubylog.trace(false)
 
 # no trace again
 solve S.is("Hello #{X}!").and X.is("no Trace again") do puts S end

data/lib/rubylog/builtins/ensure.rb

@@ -1,6 +1,6 @@
 rubylog do
   
-  class << primitives_for ::Rubylog::Clause
+  class << primitives_for [::Rubylog::Structure, ::Rubylog::Goal]
     # succeeds if A succeeds. At backtracking, solves B
     def ensure a, b
       begin

data/lib/rubylog/builtins/logic.rb

@@ -12,14 +12,14 @@ rubylog do
     # !
     def cut!
       yield
-      throw :cut
+      throw :rubylog_cut
     end
   end
 
 
-  primitives_for_clause = primitives_for [::Rubylog::Clause, ::Rubylog::Structure]
+  primitives_for_goal = primitives_for [::Rubylog::Goal, ::Rubylog::Structure]
 
-  class << primitives_for_clause
+  class << primitives_for_goal
     # Succeeds if both +a+ and +b+ succeeds.
     def and a, b
       a.prove { b.prove { yield } }
@@ -34,7 +34,7 @@ rubylog do
     # Succeeds if +a+ does not succeed.
     def false a
       # catch cuts
-      catch :cut do
+      catch :rubylog_cut do
         a.prove { return }
       end
       yield
@@ -97,44 +97,66 @@ rubylog do
       yield
     end
 
-  end
 
-  # We also implement some of these methods in a prefix style
-  %w(false all iff any one none).each do |fct|
-    # we discard the first argument, which is the context,
-    # because they are the same in  any context
-    primitives_for_context.define_singleton_method fct do |_,*args,&block|
-      primitives_for_clause.send(fct, *args, &block)
-    end
-  end
-
-  class << primitives_for_context
     # finds every solution of a, and for each solution dereferences all
     # variables in b if possible and collects the results. Then joins all b's
     # with .and() and solves the resulted expression.
-    def every _, a, b
-      c = []
-      a.prove do
-        if b.is_a? Proc
+    def every a, b
+
+      # a block that makes a snapshot of b
+      snapshot = nil
+      snapshot = proc do |subterm|
+        case subterm
+        when Proc
           # save copies of actual variables
           vars = a.rubylog_variables.map do |v|
             new_v = Rubylog::Variable.new(v.name)
             new_v.send :bind_to!, v.value if v.bound?
+            new_v
           end
 
           # store them in a closure
-          b_resolved = proc do
-            b.call_with_rubylog_variables vars
+          proc do
+            subterm.call_with_rubylog_variables vars
           end
-        else
+        when Rubylog::Variable
           # dereference actual variables
-          b_resolved = b.rubylog_deep_dereference 
+          if subterm.bound?
+            subterm.rubylog_dereference.rubylog_clone(&snapshot)
+          else 
+            subterm
+          end
+        else
+          subterm
         end
-        c << b_resolved
+      end 
+
+      # collect resolved b's in an array
+      resolved_bs = []
+      a.prove do
+        resolved_bs << b.rubylog_clone(&snapshot)
       end
-      c.inject(:true){|a,b|a.and b}.solve { yield }
+
+      # chain resolved b's together
+      goal = resolved_bs.empty? ? :true : resolved_bs.inject{|a,b|a.and b}
+
+      # match variables in the resolved b's together with variables in a
+      goal = [a.rubylog_variables, goal].rubylog_match_variables[1]
+
+      # prove b's
+      goal.prove { yield }
     end
   end
 
+  # We also implement some of these methods in a prefix style
+  %w(false all iff any one none every).each do |fct|
+    # we discard the first argument, which is the context,
+    # because they are the same in  any context
+    primitives_for_context.define_singleton_method fct do |_,*args,&block|
+    primitives_for_goal.send(fct, *args, &block)
+    end
+  end
+
+
 end
 

data/lib/rubylog/compound_term.rb

@@ -1,19 +1,27 @@
 module Rubylog::CompoundTerm
+
+  # returns a copy of the term, with variables with the same name meade same
+  # objects. Don't care variables are not matched.
   def rubylog_match_variables 
     vars = []; vars_by_name = {}
+
     rubylog_clone do |subterm|
       case subterm
       when Rubylog::Variable
         var = subterm
 
         if var.dont_care?
+          # duplicate don't care variables
           var.dup
         else
+          # see if a var with that name already exists
           new_var = vars_by_name[var.name]
           if new_var
+            # append guards
             new_var.guards = new_var.guards + var.guards
             new_var
           else
+            # create and add new var
             new_var = var.dup
             vars << new_var
             vars_by_name[var.name] = new_var
@@ -22,7 +30,8 @@ module Rubylog::CompoundTerm
         end
 
       when Rubylog::CompoundTerm
-        subterm.instance_variable_set :"@rubylog_variables", vars
+        # save rubylog variables
+        subterm.rubylog_variables=vars
         subterm
       else
         subterm
@@ -35,7 +44,8 @@ module Rubylog::CompoundTerm
     #self.class.new attr1.rubylog_deep_dereference
   #end
 
-  attr_reader :rubylog_variables
+  attr_accessor :rubylog_variables
+  protected :rubylog_variables=
 
 
   # This is a general deep-copy generating method