ambit 0.10.1 → 0.11

data/History.txt

@@ -1,4 +1,13 @@
-=== 0.10.1 / 2011-04-26
+=== 0.11 / 2012-10-12
+
+* Additional documentation on side effects and rewinding.
+
+* Fixed Ambit::trace and Ambit::untrace to work as described in the docs.
+  This breaks the (undocumented) ability to turn on tracing
+  generator-by-generator, but buys the ability to trace operation of the
+  anonymous generator used by Ambit::choose.
+
+=== 0.10.1 / 2012-10-10
 
 * Updated repo path -- no functional change.
 

data/README.rdoc

@@ -8,13 +8,8 @@ License::   2-clause BSD-Style (see LICENSE.txt)
 
 == DESCRIPTION:
 
-This is an all-ruby implementation of choose/fail nondeterministic
-programming with branch cut, as described in Chapter 22 of Paul Graham's
-<em>On Lisp</em>[1], or Section 4.3 of <em>SICP</em>[2].
-
-Due to Ruby containing a true call/cc, this is a much straighter port of
-Paul Graham's scheme version of this code than his Common Lisp or my C
-versions are.  :-)
+Ambit is a ruby non-deterministic programming system with backtracking and
+branch cut.
 
 == REQUIREMENTS:
 
@@ -116,7 +111,7 @@ enumerable is returned <em>from the same call to Ambit::choose</em>:
     Ambit::fail! unless a.even?
     puts a
 prints
-	2
+    2
 (and only "2")
 
 <em>This means that computation now proceeds as if that had been the value
@@ -181,21 +176,68 @@ prints
     2
 
 instead of only "2" -- the printing has already been done by the time we
-call Ambit::fail!.
+call Ambit::fail!.  
+
+Likewise, this code:
+
+    x = 1
+    y = Ambit::choose([1, 2, 3])
+    if y == 2
+      puts x
+    else
+      x = 42
+    end
+    Ambit::fail! unless a.even?
+
+prints
+    42
+
+, not +1+, as Ambit does not rewind the setting of 'x' after the first
+return from Ambit::choose.
 
 Such side effects can also be useful, however.  This code:
 
     i = 0
     first = Ambit.choose(1..10)
+    i += 1
     second = Ambit.choose(1..10)
+    i += 1
     third = Ambit.choose(1..10)
     i += 1
     Ambit.fail! unless open_lock(first, second, third)
     puts i
 
-prints out the number of combinations which were tried in total (since +i+
+prints out the number of values which were chosen in total (since +i+
 remains incremented even when we rewind computation).
 
+If we wanted to avoid this type of side effect, one option would be to use a
+function argument to capture this setting, as function calls (and thus the
+value of their arguments and local variables) are rewindable.  This version,
+for instance:
+
+   def try_first
+     i = 0
+     first = Ambit::choose(1..10)
+     try_second(i + 1, first)
+   end
+
+   def try_second i, first
+     second = Ambit::choose(1..10)
+     try_third(i + 1, first, second)
+   end
+
+   def try_third i, first, second
+     third = Ambit::choose(1..10)
+     Ambit.fail! unless open_lock(first, second, third)
+     puts i+1
+   end
+
+   try_first
+
+will always print +3+ -- the number of values tried in the ultimately
+successful series of choices, rather than the number of combinations tried
+over all.
+
 ==== More Than One Answer
 
 Often, more than one combination of choices is interesting to consider -- it
@@ -291,11 +333,11 @@ commit to all choices made so far.
 
 ==== Watching Ambit work
 
-The methods Ambit::trace and Ambit::untrace can be used to enable debug
-tracing of Ambit operations.  Repeated calls to Ambit::trace increase the
-verbosity of trace output (though this has no effect in the current
-version), and a specific trace level (as an integer) may also be passed to
-Ambit::trace as an optional argument.
+The class method Ambit::trace can be used to enable debug tracing of Ambit
+operations.  Repeated calls to Ambit::trace increase the verbosity of trace
+output (though this has no effect in the current version), and a specific
+trace level (as an integer) may also be passed to Generator#trace as an
+optional argument.
 
 Trace output is written to STDERR.  Trace output can be disabled by
 specifying a trace level of 0, or by calling Ambit::untrace.
@@ -413,11 +455,16 @@ a given N.
 
 === References
 
-[1] Graham, Paul, <em>On Lisp</em>, Prentice Hall, 1993. Available online at http://www.paulgraham.com/onlisp.html
+For more information on nondeterministic programming, see
+
+* Abelson, Harold and Gerald Jay Sussman, <em>Structure and Interpretation
+of Computer Programs, 2nd Edition</em>, Section 4.3, MIT Press, 1996.
+Available online at http://mitpress.mit.edu/sicp/
 
-[2] Abelson, Harold and Gerald Jay Sussman, <em>Structure and Interpretation of Computer Programs, 2nd Edition</em>, MIT Press, 1996.  Available online at http://mitpress.mit.edu/sicp/
+* Graham, Paul, <em>On Lisp</em>, Chapter 22, Prentice Hall, 1993. Available
+online at http://www.paulgraham.com/onlisp.html
 
-[3] Sterling, Leon and Ehud Shapiro, <em>The Art of Prolog</em>, MIT Press, 1994
+* Sterling, Leon and Ehud Shapiro, <em>The Art of Prolog</em>, MIT Press, 1994
 
 == LICENSE:
 

data/README.txt

@@ -8,13 +8,8 @@ License::   2-clause BSD-Style (see LICENSE.txt)
 
 == DESCRIPTION:
 
-This is an all-ruby implementation of choose/fail nondeterministic
-programming with branch cut, as described in Chapter 22 of Paul Graham's
-<em>On Lisp</em>[1], or Section 4.3 of <em>SICP</em>[2].
-
-Due to Ruby containing a true call/cc, this is a much straighter port of
-Paul Graham's scheme version of this code than his Common Lisp or my C
-versions are.  :-)
+Ambit is a ruby non-deterministic programming system with backtracking and
+branch cut.
 
 == REQUIREMENTS:
 
@@ -116,7 +111,7 @@ enumerable is returned <em>from the same call to Ambit::choose</em>:
     Ambit::fail! unless a.even?
     puts a
 prints
-	2
+    2
 (and only "2")
 
 <em>This means that computation now proceeds as if that had been the value
@@ -181,21 +176,68 @@ prints
     2
 
 instead of only "2" -- the printing has already been done by the time we
-call Ambit::fail!.
+call Ambit::fail!.  
+
+Likewise, this code:
+
+    x = 1
+    y = Ambit::choose([1, 2, 3])
+    if y == 2
+      puts x
+    else
+      x = 42
+    end
+    Ambit::fail! unless a.even?
+
+prints
+    42
+
+, not +1+, as Ambit does not rewind the setting of 'x' after the first
+return from Ambit::choose.
 
 Such side effects can also be useful, however.  This code:
 
     i = 0
     first = Ambit.choose(1..10)
+    i += 1
     second = Ambit.choose(1..10)
+    i += 1
     third = Ambit.choose(1..10)
     i += 1
     Ambit.fail! unless open_lock(first, second, third)
     puts i
 
-prints out the number of combinations which were tried in total (since +i+
+prints out the number of values which were chosen in total (since +i+
 remains incremented even when we rewind computation).
 
+If we wanted to avoid this type of side effect, one option would be to use a
+function argument to capture this setting, as function calls (and thus the
+value of their arguments and local variables) are rewindable.  This version,
+for instance:
+
+   def try_first
+     i = 0
+     first = Ambit::choose(1..10)
+     try_second(i + 1, first)
+   end
+
+   def try_second i, first
+     second = Ambit::choose(1..10)
+     try_third(i + 1, first, second)
+   end
+
+   def try_third i, first, second
+     third = Ambit::choose(1..10)
+     Ambit.fail! unless open_lock(first, second, third)
+     puts i+1
+   end
+
+   try_first
+
+will always print +3+ -- the number of values tried in the ultimately
+successful series of choices, rather than the number of combinations tried
+over all.
+
 ==== More Than One Answer
 
 Often, more than one combination of choices is interesting to consider -- it
@@ -291,11 +333,11 @@ commit to all choices made so far.
 
 ==== Watching Ambit work
 
-The methods Ambit::trace and Ambit::untrace can be used to enable debug
-tracing of Ambit operations.  Repeated calls to Ambit::trace increase the
-verbosity of trace output (though this has no effect in the current
-version), and a specific trace level (as an integer) may also be passed to
-Ambit::trace as an optional argument.
+The class method Ambit::trace can be used to enable debug tracing of Ambit
+operations.  Repeated calls to Ambit::trace increase the verbosity of trace
+output (though this has no effect in the current version), and a specific
+trace level (as an integer) may also be passed to Generator#trace as an
+optional argument.
 
 Trace output is written to STDERR.  Trace output can be disabled by
 specifying a trace level of 0, or by calling Ambit::untrace.
@@ -413,11 +455,16 @@ a given N.
 
 === References
 
-[1] Graham, Paul, <em>On Lisp</em>, Prentice Hall, 1993. Available online at http://www.paulgraham.com/onlisp.html
+For more information on nondeterministic programming, see
+
+* Abelson, Harold and Gerald Jay Sussman, <em>Structure and Interpretation
+of Computer Programs, 2nd Edition</em>, Section 4.3, MIT Press, 1996.
+Available online at http://mitpress.mit.edu/sicp/
 
-[2] Abelson, Harold and Gerald Jay Sussman, <em>Structure and Interpretation of Computer Programs, 2nd Edition</em>, MIT Press, 1996.  Available online at http://mitpress.mit.edu/sicp/
+* Graham, Paul, <em>On Lisp</em>, Chapter 22, Prentice Hall, 1993. Available
+online at http://www.paulgraham.com/onlisp.html
 
-[3] Sterling, Leon and Ehud Shapiro, <em>The Art of Prolog</em>, MIT Press, 1994
+* Sterling, Leon and Ehud Shapiro, <em>The Art of Prolog</em>, MIT Press, 1994
 
 == LICENSE:
 

data/examples/example.rb

@@ -59,3 +59,46 @@ rescue Ambit::ChoicesExhausted
 end
 
 find_boxes
+
+Ambit::clear!
+
+# Simple combination lock example, used in README
+
+# test if we have the right combination
+def open_lock x, y, z
+  [x, y, z] == [3, 7, 2]
+end
+
+# version with global variable -- counts calls to #choose
+def try_combinations
+  i = 0
+  first = Ambit.choose(1..10)
+  i += 1
+  second = Ambit.choose(1..10)
+  i += 1
+  third = Ambit.choose(1..10)
+  i += 1
+  Ambit.fail! unless open_lock(first, second, third)
+  i
+end
+
+puts try_combinations
+
+def try_first
+  i = 0
+  first = Ambit::choose(1..10)
+  try_second(i + 1, first)
+end
+
+def try_second i, first
+  second = Ambit::choose(1..10)  
+  try_third(i + 1, first, second)
+end
+
+def try_third i, first, second
+  third = Ambit::choose(1..10)
+  Ambit.fail! unless open_lock(first, second, third)
+  i+1
+end
+
+puts try_first

data/lib/ambit.rb

@@ -7,7 +7,7 @@
 
 module Ambit
 
-  VERSION = '0.10.1'
+  VERSION = '0.11'
 
   # A ChoicesExhausted exception is raised if the outermost choose invocation of
   # a Generator has run out of choices, indicating that no (more) solutions are possible.
@@ -15,6 +15,7 @@ module Ambit
   end
 
   class Generator
+    @@trace = 0
     # Allocate a new private Generator.  Usually not needed -- use Ambit::choose et al, instead.
     #
     # See "Private Generators" in the README for details
@@ -25,19 +26,23 @@ module Ambit
 
     # Turn on tracing (to standard error) of Ambit operations
     #
+    # intended for use by Ambit::trace
+    #
     # The optional level argument sets the verbosity -- if not passed, each
     # call to this method increases verbosity
-    def trace lvl=false
+    def self.trace lvl=false
       if lvl
-        @trace = lvl
+        @@trace = lvl
       else 
-        @trace = @trace + 1
+        @@trace = @trace + 1
       end
     end
 
     # Turn off tracing (to standard error) of Ambit operations
-    def untrace
-      @trace = 0
+    #
+    # intended for use by Ambit::untrace
+    def self.untrace
+      @@trace = 0
     end
 
     # Clear all outstanding choices registered with this generator.
@@ -131,8 +136,26 @@ module Ambit
     end
   end
 
+  # Turn on tracing (to standard error) of Ambit operations
+  #
+  # See ``Watching Ambit Work'' in README.rdoc
+  #
+  # The optional level argument sets the verbosity -- if not passed, each
+  # call to this method increases verbosity
+  def self.trace lvl = false
+    Generator::trace lvl
+  end
+
+  # Turn off tracing (to standard error) of Ambit operations
+  #
+  # See ``Watching Ambit Work'' in README.rdoc
+  #
+  def self.untrace
+    Generator::untrace
+  end
+
   # forward method invocations on this module to the default Generator.
-  def Ambit::method_missing(sym, *args, &block) # :nodoc:
+  def self.method_missing(sym, *args, &block) # :nodoc:
     Ambit::Default_Generator.send(sym, *args, &block)
   end
 

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: ambit
 version: !ruby/object:Gem::Version 
-  hash: 53
+  hash: 29
   prerelease: 
   segments: 
   - 0
-  - 10
-  - 1
-  version: 0.10.1
+  - 11
+  version: "0.11"
 platform: ruby
 authors: 
 - Jim Wise
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-10 00:00:00 Z
+date: 2012-01-12 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rdoc
@@ -48,13 +47,8 @@ dependencies:
   type: :development
   version_requirements: *id002
 description: |-
-  This is an all-ruby implementation of choose/fail nondeterministic
-  programming with branch cut, as described in Chapter 22 of Paul Graham's
-  <em>On Lisp</em>[1], or Section 4.3 of <em>SICP</em>[2].
-  
-  Due to Ruby containing a true call/cc, this is a much straighter port of
-  Paul Graham's scheme version of this code than his Common Lisp or my C
-  versions are.  :-)
+  Ambit is a ruby non-deterministic programming system with backtracking and
+  branch cut.
 email: 
 - jwise@draga.com
 executables: []
@@ -113,6 +107,6 @@ rubyforge_project: ambit
 rubygems_version: 1.8.13
 signing_key: 
 specification_version: 3
-summary: This is an all-ruby implementation of choose/fail nondeterministic programming with branch cut, as described in Chapter 22 of Paul Graham's <em>On Lisp</em>[1], or Section 4.3 of <em>SICP</em>[2]
+summary: Ambit is a ruby non-deterministic programming system with backtracking and branch cut.
 test_files: 
 - test/test_ambit.rb