ambit 0.9.1 → 0.10

data/History.txt

@@ -1,3 +1,14 @@
+=== 0.10 / 2011-04-26
+
+* Add Ambit::unmark! and Ambit::unmark_all!, which can be used to undo the
+  effects of the Ambit::mark operation -- see "Marking and Cutting" in
+  README for details.
+
+* Add Ambit::trace and Ambit::untrace to turn on or off tracing of Ambit
+  operations to STDERR.  In Ambit test cases, check for the environment
+  variable AMBIT_TRACE, and turn on tracing during execution of tests if it
+  is set.
+
 === 0.9.1 / 2011-04-26
 
 * Minor documentation improvements

data/Manifest.txt

@@ -6,6 +6,7 @@ README.rdoc
 README.txt
 Rakefile
 examples/example.rb
+examples/mapcolor.rb
 examples/queens.rb
 lib/ambit.rb
 test/test_ambit.rb

data/README.rdoc

@@ -165,7 +165,7 @@ we have performed since the choice point we are rewinding to has had side
 effects (other than the choices made), those side effects will not
 themselves be rewound.  While some side effects (setting of variables) could
 theoretically be tracked and undone, this would require very careful
-semantics -- nd other side effects could not be undone by any level of
+semantics -- and other side effects could not be undone by any level of
 complexity added to our language.  If we have printed output to the user,
 for instance, no amount of rewinding will make the user forget what he has
 seen; while we simulate the ability to see the future and to change the
@@ -176,9 +176,7 @@ This can sometimes cause confusion.  This code, for instance:
     a = Ambit::choose([1, 2, 3])
     puts a
     Ambit::fail! unless a.even?
-
 prints
-
     1
     2
 
@@ -260,15 +258,15 @@ If we failed because the first letter was incorrect, we would continue trying
 every possible value for the second, third and fourth letters -- even though none of
 them could be correct.  We need a way to rewind to an earlier choice point.
 
-To work around this, Ambit provides a method, Ambit::cut! which "locks in" a
-set of past choices, preventing them from being revisited later:
+To allow this, Ambit provides a method, Ambit::cut! which "locks in" a set
+of past choices, preventing them from being revisited later:
 
     a = Ambit::choose('a'..'z')
     Ambit::mark
     b = Ambit::choose('a'..'z')
     c = Ambit::choose('a'..'z')
     d = Ambit::choose('a'..'z')
-    if !good_first_letter(a, b, c, d)
+    unless good_first_letter(a, b, c, d)
       Ambit::cut! 
       Ambit::fail!
     end   
@@ -285,6 +283,23 @@ since the last call to Ambit::mark -- in this case, we are saying that we
 know these choices are good, so if we (later) fail, we want to rewind out of
 the whole current branch of computation.
 
+Finally, Ambit::unmark! can be used to remove the most recent mark (making
+the next Ambit::cut! operation cut back to an earlier mark (or commit to all
+choices if no other mark exists), and the Ambit::unmark_all! operation can
+be used to remove all current marks, making the next Ambit::cut! operation
+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.
+
+Trace output is written to STDERR.  Trace output can be disabled by
+specifying a trace level of 0, or by calling Ambit::untrace.
+
 ==== Private Generators
 
 In addition to using methods of the Ambit module directly, another option is
@@ -308,6 +323,11 @@ Ambit::Generator#clear! is provided for the same reason as Ambit::clear!,
 but it is often clearer to use a new Ambit::Generator object for each
 unrelated set of nondeterministic computations.
 
+As with other module-level operations, Ambit::trace and Ambit::untrace do
+not turn on or off tracing for private generators -- the generator's own
+Ambit::Generator#trace and Ambit::Generator#untrace must be used to enable
+tracing of a private generator's operation.
+
 ==== Compatibility
 
 For historical reasons, Ambit::amb and Ambit::Generator#amb are provided as

data/README.txt

@@ -165,7 +165,7 @@ we have performed since the choice point we are rewinding to has had side
 effects (other than the choices made), those side effects will not
 themselves be rewound.  While some side effects (setting of variables) could
 theoretically be tracked and undone, this would require very careful
-semantics -- nd other side effects could not be undone by any level of
+semantics -- and other side effects could not be undone by any level of
 complexity added to our language.  If we have printed output to the user,
 for instance, no amount of rewinding will make the user forget what he has
 seen; while we simulate the ability to see the future and to change the
@@ -176,9 +176,7 @@ This can sometimes cause confusion.  This code, for instance:
     a = Ambit::choose([1, 2, 3])
     puts a
     Ambit::fail! unless a.even?
-
 prints
-
     1
     2
 
@@ -260,15 +258,15 @@ If we failed because the first letter was incorrect, we would continue trying
 every possible value for the second, third and fourth letters -- even though none of
 them could be correct.  We need a way to rewind to an earlier choice point.
 
-To work around this, Ambit provides a method, Ambit::cut! which "locks in" a
-set of past choices, preventing them from being revisited later:
+To allow this, Ambit provides a method, Ambit::cut! which "locks in" a set
+of past choices, preventing them from being revisited later:
 
     a = Ambit::choose('a'..'z')
     Ambit::mark
     b = Ambit::choose('a'..'z')
     c = Ambit::choose('a'..'z')
     d = Ambit::choose('a'..'z')
-    if !good_first_letter(a, b, c, d)
+    unless good_first_letter(a, b, c, d)
       Ambit::cut! 
       Ambit::fail!
     end   
@@ -285,6 +283,23 @@ since the last call to Ambit::mark -- in this case, we are saying that we
 know these choices are good, so if we (later) fail, we want to rewind out of
 the whole current branch of computation.
 
+Finally, Ambit::unmark! can be used to remove the most recent mark (making
+the next Ambit::cut! operation cut back to an earlier mark (or commit to all
+choices if no other mark exists), and the Ambit::unmark_all! operation can
+be used to remove all current marks, making the next Ambit::cut! operation
+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.
+
+Trace output is written to STDERR.  Trace output can be disabled by
+specifying a trace level of 0, or by calling Ambit::untrace.
+
 ==== Private Generators
 
 In addition to using methods of the Ambit module directly, another option is
@@ -308,6 +323,11 @@ Ambit::Generator#clear! is provided for the same reason as Ambit::clear!,
 but it is often clearer to use a new Ambit::Generator object for each
 unrelated set of nondeterministic computations.
 
+As with other module-level operations, Ambit::trace and Ambit::untrace do
+not turn on or off tracing for private generators -- the generator's own
+Ambit::Generator#trace and Ambit::Generator#untrace must be used to enable
+tracing of a private generator's operation.
+
 ==== Compatibility
 
 For historical reasons, Ambit::amb and Ambit::Generator#amb are provided as

data/examples/mapcolor.rb

@@ -0,0 +1,129 @@
+#!/usr/bin/ruby
+
+require 'rubygems'
+require 'ambit'
+
+# yes, I know, no monaco, luxembourg, or andorra
+WesternEurope = {
+  :portugal => [:spain],
+  :spain => [:france, :portugal, :andorra],
+  :france => [:spain, :belgium, :germany, :switzerland, :italy, :luxembourg, :andorra],
+  :belgium => [:france, :netherlands, :germany, :luxembourg],
+  :netherlands => [:belgium, :germany],
+  :germany => [:france, :belgium, :netherlands, :switzerland, :denmark, :austria, :luxembourg],
+  :denmark => [:germany],
+  :switzerland => [:france, :germany, :austria, :italy],
+  :italy => [:france, :switzerland, :austria],
+  :austria => [:germany, :switzerland, :italy],
+  :luxembourg => [:france, :belgium, :germany],
+  :andorra => [:spain, :france],
+}
+
+ThreeByThree = {
+  :a => [:b, :d],
+  :b => [:a, :c, :e],
+  :c => [:b, :f],
+  :d => [:a, :e, :g],
+  :e => [:b, :d, :f, :h],
+  :f => [:c, :e, :i],
+  :g => [:d, :h],
+  :h => [:e, :g, :i],
+  :i => [:f, :h],
+}
+
+# from http://spicerack.sr.unh.edu/~student/tutorial/fourColor/FourColor.html
+Example = {
+  :inner => [:ne, :se, :sw, :nw],
+  :ne => [:inner, :se, :nw, :outer],
+  :se => [:inner, :ne, :sw, :outer],
+  :sw => [:inner, :se, :nw, :outer],
+  :nw => [:inner, :ne, :sw, :outer],
+  :outer => [:ne, :se, :sw, :nw],
+}
+
+# Example which forces more than one level of backtrack:
+# |         |
+# +-------+ |
+# |a|b|c|d| |
+# +-------+ |
+# |  e    | |
+# +-------+ |
+# | f |  g  |
+
+BackTrack = {
+  :a => [:b, :e, :g],
+  :b => [:a, :c, :e, :g],
+  :c => [:b, :d, :e, :g],
+  :d => [:c, :e, :g],
+  :e => [:a, :b, :c, :d, :f, :g],
+  :f => [:e, :g],
+  :g => [:a, :b, :c, :d, :e, :f],
+}
+Colors = [:red, :yellow, :blue, :green]
+
+# when called as colorize2(map), we start from the beginning colorizing that
+# map.  when recursively called as colorize2(map, countries, colorized),
+# countries are the countries left to colorize, and colorized are the
+# assignments made so far.
+
+def colorize map, countries=map.keys, colorized={}
+  country=countries.first
+  return colorized if country.nil?
+
+  color = Ambit.choose Colors
+  #puts "considering #{color} for #{country}"
+  map[country].each {|n| Ambit.assert colorized[n] != color}
+
+  colorized_new = colorized.clone # fake a functional view of hash
+  colorized_new[country] = color
+  colorize map, countries.drop(1), colorized_new
+end
+
+# an alternative version, using iteration instead of recursion
+def colorize_iterating  map
+  # map from country to its color
+  colorized = {}
+  map.each do |country, neighbors|
+    local_colorized = colorized.clone # fake a functional view of colorized
+    color = Ambit.choose Colors
+    #puts "considering #{color} for #{country}"
+    neighbors.each {|n| Ambit.assert colorized[n] != color}
+    local_colorized[country] = color
+    colorized = local_colorized
+  end
+  colorized
+end
+
+
+# a deterministic check, for comparison purposes
+def check map, colorized
+  map.each do |country, neighbors|
+    color = colorized[country]
+    neighbors.each do |neighbor|
+      if colorized[neighbor] == color
+        raise "country #{country} and neighbor #{neighbor} have the same color!"
+      end
+    end
+  end
+end
+
+def test_map map
+  colorized = colorize map
+  check map, colorized
+
+  colorized.each do |country, color|
+    puts "#{country} => #{color}"
+  end
+end
+
+puts "Simple example:"
+test_map Example
+puts ""
+puts "Complex example:"
+test_map BackTrack
+puts ""
+puts "Three-by-three grid:"
+test_map ThreeByThree
+puts ""
+puts "Western Europe:"
+test_map WesternEurope

data/lib/ambit.rb

@@ -7,7 +7,7 @@
 
 module Ambit
 
-  VERSION = '0.9.1'
+  VERSION = '0.10'
 
   # 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.
@@ -20,6 +20,24 @@ module Ambit
     # See "Private Generators" in the README for details
     def initialize
       @paths = []
+      @trace = 0
+    end
+
+    # Turn on tracing (to standard error) of Ambit operations
+    #
+    # The optional level argument sets the verbosity -- if not passed, each
+    # call to this method increases verbosity
+    def trace lvl=false
+      if lvl
+        @trace = lvl
+      else 
+        @trace = @trace + 1
+      end
+    end
+
+    # Turn off tracing (to standard error) of Ambit operations
+    def untrace
+      @trace = 0
     end
 
     # Clear all outstanding choices registered with this generator.
@@ -46,7 +64,9 @@ module Ambit
       ch = choices.clone          # clone it in case it's modified by the caller
       ch.each do |choice|
         callcc do |cc|
+          STDERR.print "choosing from " + choices.inspect + ": " if @trace > 0
           @paths.unshift cc
+          STDERR.puts choice.inspect if @trace > 0
           return choice
         end
       end
@@ -60,10 +80,12 @@ module Ambit
     def fail!
       raise ChoicesExhausted.new if @paths.empty?
       cc = @paths.shift
-      # if it quacks (or can be called) like a duck, call it -- it's either a Proc from #mark or a Continuation from #choose
+      # if it quacks (or can be called) like a duck, call it -- it's either a Proc
+      # from #mark or a Continuation from #choose
       cc.call
     end
 
+    # Fail unless a condition holds.
     def assert cond
       fail! unless cond
     end
@@ -77,10 +99,30 @@ module Ambit
       @paths.unshift Proc.new {self.fail!}
     end
 
-    # Commit to all choices since the last #mark! operation.
+    # Remove the most recent mark
+    #
+    # See "Marking and Cutting" in README for details
+    def unmark!
+      STDERR.puts "unmark!" if @trace > 0
+      return if @paths.empty?
+      n = @paths.rindex {|x| x.instance_of? Proc}
+      n and @paths.delete_at(n)
+    end
+
+    # Remove all marks
+    #
+    # See "Marking and Cutting" in README for details
+    def unmark_all!
+      STDERR.puts "unmark_all!" if @trace > 0
+      return if @paths.empty?
+      @paths = @paths.reject {|x| x.instance_of? Proc}
+    end
+
+    # Commit to all choices since the last #mark operation.
     #
     # See "Marking and Cutting" in README for details
     def cut!
+      STDERR.puts "cut!" if @trace > 0
       return if @paths.empty?
       # rewind paths back to the last mark
       @paths = @paths.drop_while {|x| x.instance_of? Continuation}

data/test/test_ambit.rb

@@ -1,6 +1,9 @@
 require "test/unit"
 require "ambit"
 
+Ambit::trace if ENV['AMBIT_TRACE']
+
+
 class TestAmbit < Test::Unit::TestCase
 
   def test_simple_default
@@ -64,5 +67,28 @@ class TestAmbit < Test::Unit::TestCase
   rescue Ambit::ChoicesExhausted
     assert(i==15)
   end
-  
+
+  def test_unmark_all
+    a = Ambit::choose(1..3)
+    Ambit::mark
+    b = Ambit::choose(1..3)
+    Ambit::unmark_all!
+    # if we hadn't unmarked here, a cut would leave us choices
+    Ambit::cut!
+    assert_raise Ambit::ChoicesExhausted do
+      Ambit::fail!
+    end
+  end
+
+  def test_unmark
+    a = Ambit::choose(1..3)
+    Ambit::mark
+    Ambit::unmark!
+    # if we hadn't unmarked here, a cut would leave us choices
+    Ambit::cut!
+    assert_raise Ambit::ChoicesExhausted do
+      Ambit::fail!
+    end
+  end
+
 end

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: ambit
 version: !ruby/object:Gem::Version 
-  hash: 57
+  hash: 31
   prerelease: 
   segments: 
   - 0
-  - 9
-  - 1
-  version: 0.9.1
+  - 10
+  version: "0.10"
 platform: ruby
 authors: 
 - Jim Wise
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-26 00:00:00 Z
+date: 2011-09-22 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: hoe
@@ -23,14 +22,13 @@ dependencies:
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
-        hash: 35
+        hash: 27
         segments: 
         - 2
-        - 9
-        - 4
-        version: 2.9.4
+        - 12
+        version: "2.12"
   type: :development
   version_requirements: *id001
 description: |-
@@ -61,6 +59,7 @@ files:
 - README.txt
 - Rakefile
 - examples/example.rb
+- examples/mapcolor.rb
 - examples/queens.rb
 - lib/ambit.rb
 - test/test_ambit.rb
@@ -95,7 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: ambit
-rubygems_version: 1.7.2
+rubygems_version: 1.8.5
 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]