ambit 0.9.0

data/examples/queens.rb

@@ -0,0 +1,127 @@
+#!/usr/bin/ruby
+
+require 'rubygems'
+require 'ambit'
+
+# This solution to the N queens problem is inspired by that given
+#
+# Sterling, Leon and Ehud Shapiro, The Art of Prolog, MIT Press, 1994
+#   http://www.amazon.com/Art-Prolog-Second-Programming-Techniques/dp/0262193388
+#
+# but is less elegant, as this is not prolog (and I am not Sterling or Shapiro)
+#
+# we want to place N queens on an NxN chess board.  Since we know no two queens
+# can be in the same row, an array of N integers between 0 and N-1 will do to
+# represent the placement.  Since we know no two queens can be in the same column,
+# each number from 1 .. N will appear once in this array;  this means the solution
+# is a permutation of 1 .. N
+
+# Here is the actual board generator.  Next is the test if a position is safe.  All else
+# in this file is for display or testing.
+$nd = Ambit::Generator.new
+def queens n, board = []
+  if board.size == n
+    board
+  else
+    c = $nd.choose(1..n)
+    $nd.fail! unless safe board, c
+    queens n, board + [c]
+  end
+end
+
+# board is the first M columns of an NxN board, and is valid so far.
+# piece is a proposed piece for the M+1th row of the board.
+# returns true if piece is a valid placement, false otherwise
+def safe board, piece
+  board.each_with_index do |c, r|
+    return false if c == piece  # same column
+    # they're on the same diagonal if the distance in columns == the distance in rows
+    rdist = board.size - r
+    cdist = (piece - c).abs
+    return false if rdist == cdist
+  end
+  true
+end
+
+# Alternator is an infinite enumerables which flipflops between two values
+# We use these to define an odd row and an even row as
+# [" ", ".", " ", ...] and [".", " ", ".", ...], respectively.
+# With these at our disposal, we can break off as many squares as we need to draw
+# an even or odd board row of any size
+class Alternator
+  include Enumerable
+  def initialize first, second
+    @first, @second = first, second
+  end
+
+  def each
+    loop do
+      yield @first
+      yield @second
+    end
+  end
+end
+
+E = Alternator.new " ", "."
+O = Alternator.new ".", " "
+
+# return a blank board of a given size, as an array of N strings of length N
+def empty_board n
+  (1..n).collect do |i|
+    ((i+1).odd? ? O : E).take(n).to_s
+  end
+end
+# board is a board in the above format (array where a[i] is the column
+# number of the queen in row i+1, rows and columns being numbered from 1
+
+# n, if provided, is the size of the full board.  This allows this routine
+# to show a partly-filled board by passing n > board.size, though we don't
+# currently use this.
+def board_to_s board, n = board.size
+  b = empty_board n
+  board.each_with_index do |x, i|
+    b[i][x-1] = 'Q'
+  end
+  b.join "\n"
+end
+
+def show_board board
+  puts board_to_s board
+end
+
+# tests:
+# show_board (1..8).to_a
+# puts ""
+# show_board [1, 3, 5, 7, 2, 4, 6, 8]
+raise "board_to_s failed" unless board_to_s([1,2]) == "Q.\n.Q"
+
+# tests:
+raise "safe failed" if safe([1, 3, 5], 3)
+raise "safe failed" unless safe([1, 3, 5], 2)
+raise "safe failed" if safe([1, 3, 5], 4)
+
+# to run one board
+#show_board queens 8
+
+# to show all valid 8x8 boards:
+args = ARGV.empty? ? ["8"] : ARGV
+args.each do |a|
+  begin
+    n = a.to_i
+
+    # state is not reset when we fail!, so count can be used to track how many times
+    # we returned from `show_board queens n' below
+    count = 0
+    show_board queens n
+    count += 1
+    puts ""
+
+    # force next solution; will throw ChoicesExhausted if none found
+    $nd.fail!
+
+  rescue Ambit::ChoicesExhausted
+    # thrown when we finally run out of possible boards, whether we found any valid
+    # boards or not (since we unconditionally fail! above)
+    puts "#{count} #{n}x#{n} boards found, not accounting for symmetry"
+  end
+end

data/lib/ambit.rb

@@ -0,0 +1,101 @@
+# This gem allows choose/fail (amb) style non-deterministic programming in
+# Ruby
+#
+# Author::    Jim Wise  (mailto:jwise@draga.com)
+# Copyright:: Copyright (c) 2011 Jim Wise
+# License::   2-clause BSD-Style (see LICENSE[link:files/LICENSE.html])
+
+module Ambit
+
+  VERSION = '0.9.0'
+
+  # 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.
+  class ChoicesExhausted < StandardError
+  end
+
+  class Generator
+    # Allocate a new private Generator.  Usually not needed -- use Ambit::choose et al, instead.
+    #
+    # See "Private Generators" in the README for details
+    def initialize
+      @paths = []
+    end
+
+    # Clear all outstanding choices registered with this generator.
+    #
+    # Returns the generator to the state it was in before all choices were
+    # made.  Does not rewind execution.
+    def clear!
+      @paths = []
+    end
+
+    # Given an enumerator, begin a generate-and-test process.
+    #
+    # Returns with the first member of the enumerator.  A later call to #fail!
+    # on the same generator will backtrack and try the next value in the
+    # enumerator, continuing from the point of this #choose as if that value
+    # had been chosen originally.
+    #
+    # Multiple calls to #choose will nest, so that backtracking forms
+    # a tree-like execution path
+    #
+    # calling #choose with no argument or an empty iterator 
+    # is equivalent to calling #fail!
+    def choose choices = []
+      ch = choices.clone          # clone it in case it's modified by the caller
+      ch.each do |choice|
+        callcc do |cc|
+          @paths.unshift cc
+          return choice
+        end
+      end
+      self.fail!                  # if we get here, we've exhausted the choices
+    end
+
+    alias amb choose
+
+    # Indicate that the current combination of choices has failed, and roll execution back
+    # to the last #choose, continuing with the next choice.
+    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
+      cc.call
+    end
+
+    def assert cond
+      fail! unless cond
+    end
+
+    alias require assert
+
+    # Begin a mark/cut pair to commit to one branch of the current #choose operation.
+    #
+    # See "Marking and Cutting" in README for details
+    def mark 
+      @paths.unshift Proc.new {self.fail!}
+    end
+
+    # Commit to all choices since the last #mark! operation.
+    #
+    # See "Marking and Cutting" in README for details
+    def cut!
+      return if @paths.empty?
+      # rewind paths back to the last mark
+      @paths = @paths.drop_while {|x| x.instance_of? Continuation}
+      # drop up to one mark
+      @paths = @paths.drop(1) unless @paths.empty?
+    end
+  end
+
+  # forward method invocations on this module to the default Generator.
+  def Ambit::method_missing(sym, *args, &block) # :nodoc:
+    Ambit::Default_Generator.send(sym, *args, &block)
+  end
+
+  # The default generator used by Ambit.choose, Ambit.fail!, et al.
+  # should not be used directly.
+  Default_Generator = Generator.new
+
+end

data/test/test_ambit.rb

@@ -0,0 +1,68 @@
+require "test/unit"
+require "ambit"
+
+class TestAmbit < Test::Unit::TestCase
+
+  def test_simple_default
+    x = Ambit::choose([1, 2])
+    Ambit::require x.even?
+    assert(x == 2)
+    Ambit::clear!
+  end
+
+  def test_simple_private
+    nd = Ambit::Generator.new
+    x = nd.choose([1, 2])
+    nd.require x.even?
+    assert(x == 2)
+  end
+
+  def test_nested_default
+    a = Ambit::choose(0..5)
+    b = Ambit::choose(0..5)
+    Ambit::fail! unless a + b == 7
+    assert(a+b == 7)
+    Ambit::clear!
+  end
+
+  def test_nested_private
+    nd = Ambit::Generator.new
+    a = nd.choose(0..5)
+    b = nd.choose(0..5)
+    nd.fail! unless a + b == 7
+    assert(a+b == 7)
+    nd.clear!
+  end
+
+  def test_toplevel_fail
+    assert_raise Ambit::ChoicesExhausted do
+      Ambit::fail!
+    end
+  end
+
+  def test_clear
+    Ambit::choose(0..10)
+    Ambit::choose(0..1)
+    Ambit::clear!
+    assert_raise Ambit::ChoicesExhausted do
+      Ambit::fail!
+    end
+  end
+
+  def test_mark_cut
+    nd = Ambit::Generator.new
+    i = 0;
+    a = nd.choose(1..3)
+    nd.mark
+    b = nd.choose([1, 2, 3])
+    c = nd.choose([1, 2, 3])
+    i+=1
+    if b == 2 && c == 2
+      nd.cut!
+    end
+    nd.fail!
+  rescue Ambit::ChoicesExhausted
+    assert(i==15)
+  end
+  
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification 
+name: ambit
+version: !ruby/object:Gem::Version 
+  hash: 59
+  prerelease: 
+  segments: 
+  - 0
+  - 9
+  - 0
+  version: 0.9.0
+platform: ruby
+authors: 
+- Jim Wise
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-26 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 35
+        segments: 
+        - 2
+        - 9
+        - 4
+        version: 2.9.4
+  type: :development
+  version_requirements: *id001
+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], Chapter, 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.  :-)
+email: 
+- jwise@draga.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- LICENSE.txt
+- Manifest.txt
+- README.txt
+files: 
+- .autotest
+- History.txt
+- LICENSE.txt
+- Manifest.txt
+- README.rdoc
+- README.txt
+- Rakefile
+- examples/example.rb
+- examples/queens.rb
+- lib/ambit.rb
+- test/test_ambit.rb
+- .gemtest
+homepage: https://github.com/jimwise/ruby/tree/master/ambit
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: ambit
+rubygems_version: 1.7.2
+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], Chapter, or Section 4.3 of <em>SICP</em>[2]
+test_files: 
+- test/test_ambit.rb