amb 0.0.2

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1
+
+ * Initial setup

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2010 Jean-Denis Vauguet
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+This gem is a compilation of several implementations of the **ambiguous function/operator** pattern, useful for constraint programming. Each implementation comes with its own copyright notice and authors, so be sure to check the CREDITS file!
+
+Ever wanted to:
+
+* write straightforward parsers?
+* solve crosswords and sudokus or the n-queens problem?
+* design an equation-solver or a modelizer?
+* understand how logic programming languages (Prolog…) work?
+
+Them amb may be of interest to you.
+
+## Synopsis
+
+*You may want to jump straight to the Examples section if formal stuff annoys you.*
+
+Ambiguous functions were [defined in John McCarty's 1963 paper](http://www-formal.stanford.edu/jmc/basis1/node7.html) *A basis for a mathematical theory of computation*. They allow for writing nondeterministic programs which contain various alternatives for the program flow.
+
+Typically, the programmer would specify a limited number of alternatives (eg. different values for a variable), so that the program must later choose between them at runtime to find which one(s) are valid predicates to solve the issue at stake. The "issue" is often formalized as a constraint or a set of constraints referencing the variables some alternatives have been provided for. The evaluation may result in the discovery of dead ends, in which case it must "switch" to a previous branching point and start over with a different alternative.
+
+To discover which alternatives groups are valid, a check/discard/switch strategy must be enforced by the program. Most often it will make use of a ambiguous operator, `amb()` which implements this strategy. The most basic version of `amb` would be `amb(x,y)`, which returns, *in an unpredictible way*, either x or y when both are defined, or if only one is defined, whichever is defined. If none is defined, it will terminate the program and complain no solution can be found given these alternatives and constraint(s). Using some recursivity, `amb()` may be used to define arbitrary, complex ambiguous functions. It is quite difficult to implement a good `amb()` operator matching that formal definition. A simpler (yet functional) version has the operator return its first defined argument, then pass over the next defined one in case of a dead-end.
+
+The most common strategy used for implementing `amb()`'s logic (check/discard) is backtracking, which is "a general algorithm for finding all (or some) solutions to some computational problem, that incrementally builds candidates to the solutions, and abandons each partial candidate *c* ("backtracks") as soon as it determines that *c* cannot possibly be completed to a valid solution". It almost always relies on some sort of continuations. It may be turned into backjumping for more efficiency, depending on the problem at stake. Another strategy is reinforcement learning or constraint learning, as used in some AI systems. This library implements simple backtracking only.
+
+More details on all of this under the `doc/`` folder (*pending*).
+
+## Examples
+
+``` ruby
+# Amb is a module
+A = Class.new { include Amb }.new
+
+x = A.choose(1,2,3,4) # register each alternative as a backtrack point
+y = A.choose(1,2,3,4) # same for y, so we have 16 backtracking branches
+
+puts "examining x = #{x}, y = #{y}"
+
+# assertions will backtrack if a dead-end is discovered
+A.assert x + y == 5
+A.assert x - y == 1
+#A.assert x == 2    # if this line is uncommented, then no solution can be found
+                    # and the program raises a Amb::ExhaustedError
+
+puts "> solution: x = #{x}, y = #{y}"
+```
+
+will produce:
+
+``` ruby
+examining x = 1, y = 1
+examining x = 1, y = 2
+examining x = 1, y = 3
+examining x = 1, y = 4
+examining x = 2, y = 1
+examining x = 2, y = 2
+examining x = 2, y = 3
+examining x = 2, y = 4
+examining x = 3, y = 1
+examining x = 3, y = 2
+solution: x = 3, y = 2
+```
+This illustrates the incremental, backtracking pattern. Many more examples under the `examples/` directory.
+
+## Installation
+
+    gem install amb
+
+## Usage
+
+## TODO
+
+## See also
+
+* the `doc/` and `examples/` directories.
+* Continuations and fibers concepts.

data/lib/amb.rb

@@ -0,0 +1,2 @@
+require './lib/amb/amb'
+require './lib/amb/amb_operator'

data/lib/amb/amb.rb

@@ -0,0 +1,160 @@
+# Copyright 2006 by Jim Weirich <jim@weirichhouse.org>. All rights reserved.
+# Permission is granted for use, modification and distribution as
+# long as the above copyright notice is included.
+# Modified by Jean-Denis Vauguet <jd@vauguet.fr> for Amb gem release.
+
+# Amb is an ambiguous choice maker. You can ask an Amb object to
+# select from a discrete list of choices, and then specify a set of
+# constraints on those choices. After the constraints have been
+# specified, you are guaranteed that the choices made earlier by amb
+# will obey the constraints.
+#
+# For example, consider the following code:
+#
+#   amb = Class.new { include Amb }.new
+#   x = amb.choose(1,2,3,4)
+#
+# At this point, amb may have chosen any of the four numbers (1
+# through 4) to be assigned to x. But, now we can assert some
+# conditions:
+#
+#   amb.assert (x % 2) == 0
+#
+# This asserts that x must be even, so we know that the choice made by
+# amb will be either 2 or 4. Next we assert:
+#
+#   amb.assert x >= 3
+#
+# This further constrains our choice to 4.
+#
+#   puts x    # prints '4'
+#
+# Amb works by saving a contination at each choice point and
+# backtracking to previousl choices if the contraints are not
+# satisfied. In actual terms, the choice reconsidered and all the
+# code following the choice is re-run after failed assertion.
+#
+# You can print out all the solutions by printing the solution and
+# then explicitly failing to force another choice. For example:
+#
+#   amb = Class.new { include Amb }.new
+#   x = Amb.choose(*(1..10))
+#   y = Amb.choose(*(1..10))
+#   amb.assert x + y == 15
+#
+#   puts "x = #{x}, y = #{y}"
+#
+#   amb.failure
+#
+# The above code will print all the solutions to the equation x + y ==
+# 15 where x and y are integers between 1 and 10.
+#
+# The Amb class has two convience functions, solve and solve_all for
+# encapsulating the use of Amb.
+#
+# This example finds the first solution to a set of constraints:
+#
+#   Amb.solve do |amb|
+#     x = amb.choose(1,2,3,4)
+#     amb.assert (x % 2) == 0
+#     puts x
+#   end
+#
+# This example finds all the solutions to a set of constraints:
+#
+#   Amb.solve_all do |amb|
+#     x = amb.choose(1,2,3,4)
+#     amb.assert (x % 2) == 0
+#     puts x
+#   end
+#
+module Amb
+  require 'continuation'
+
+  class ExhaustedError < RuntimeError; end
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  # Memoize and return the alternatives continuations.
+  #
+  # @return [Array<Proc, Continuation>]
+  #
+  def back_amb
+    @__back_amb ||= [Proc.new { fail ExhaustedError, "amb tree exhausted" }]
+  end
+
+  # Make a choice amoung a set of discrete values.
+  #
+  # @param choices
+  #
+  def choose(*choices)
+    choices.each do |choice|
+      callcc do |fk|
+        back_amb << fk
+        return choice
+      end
+    end
+    failure
+  end
+
+  # Unconditional failure of a constraint, causing the last choice to be
+  # retried. This is equivalent to saying `assert(false)`.
+  #
+  def failure
+    back_amb.pop.call
+  end
+
+  # Assert the given condition is true. If the condition is false,
+  # cause a failure and retry the last choice. One may specify the condition
+  # either as an argument or as a block. If a block is provided, it will be
+  # passed the arguments, whereas without a block, the first argument will
+  # be used as the condition.
+  #
+  # @param cond
+  # @yield
+  #
+  def assert(*args)
+    cond = block_given? ? yield(*args) : args.first
+    failure unless cond
+  end
+
+  # Report the given failure message.  This is called by solve in the event
+  # that no solutions are found, and by +solve_all+ when no more solutions
+  # are to be found.  Report will simply display the message to standard
+  # output, but you may override this method in a derived class if you need
+  # different behavior.
+  #
+  # @param [#to_s] failure_message
+  #
+  def report(failure_message)
+    puts failure_message
+  end
+
+  module ClassMethods
+    # Class convenience method to search for the first solution to the
+    # constraints.
+    #
+    def solve(failure_message="No Solution")
+      amb = self.new
+      yield(amb)
+    rescue Amb::ExhaustedError => ex
+      amb.report(failure_message)
+    end
+
+    # Class convenience method to search for all the solutions to the
+    # constraints.
+    #
+    def solve_all(failure_message="No More Solutions")
+      amb = self.new
+      yield(amb)
+      amb.failure
+    rescue Amb::ExhaustedError => ex
+      amb.report(failure_message)
+    end
+  end
+
+  extend self
+  extend self::ClassMethods
+end

data/lib/amb/amb_operator.rb

@@ -0,0 +1,68 @@
+# By Eric Kidd.
+# See http://www.randomhacks.net/articles/2005/10/11/amb-operator.
+module Amb
+  # Use the ambiguous computation pattern as a stand-alone operator.
+  module Operator
+    require 'continuation'
+
+    # A list of places we can "rewind" to if we encounter amb with no arguments.
+    $backtrack_points = []
+
+    # Rewind to our most recent backtrack point.
+    #
+    def backtrack
+      if $backtrack_points.empty?
+        raise "Can't backtrack"
+      else
+        $backtrack_points.pop.call
+      end
+    end
+
+    # Recursive implementation of the amb operator, as defined by McCarty[63].
+    #
+    # When choices are provided as arguments, it will save a backtracking save
+    # point for each and wait for being resumed. Resuming (starting the
+    # check/discard process) is triggered by calling amb without any arguments.
+    # It is expected you'll attach a conditionnal stating the constraint.
+    #
+    # @param choices a set of alternatives
+    # @example
+    #
+    #    # amb will (appear to) choose values
+    #    # for x and y that prevent future trouble.
+    #    x = amb 1, 2, 3
+    #    y = amb 4, 5, 6
+    #
+    #    # Ooops! If x*y isn't 8, amb would
+    #    # get angry.  You wouldn't like
+    #    # amb when it's angry.
+    #    amb if x*y != 8
+    #
+    #    # Sure enough, x is 2 and y is 4.
+    #    puts "x = #{x}, y = #{y}"
+    #
+    def amb *choices
+      # Fail if we have no arguments.
+      backtrack if choices.empty?
+
+      callcc do |cc|
+        # cc contains the "current continuation". When called, it will make the
+        # program rewind to the end of this block.
+        $backtrack_points << cc
+
+        # Return our first argument.
+        return choices[0]
+      end
+
+      # We only get here if we backtrack by resuming the stored value of cc.
+      # We call amb recursively with the arguments we didn't use.
+      amb(*choices[1...choices.length])
+    end
+
+    # Backtracking beyond a call to cut is strictly forbidden.
+    #
+    def cut
+      $backtrack_points = []
+    end
+  end
+end

data/lib/amb/version.rb

@@ -0,0 +1,6 @@
+module Amb
+  MAJOR = 0
+  MINOR = 0
+  PATCH = 2
+  VERSION = [MAJOR, MINOR, PATCH].join('.')
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: amb
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Jean-Denis Vauguet <jd@vauguet.fr>
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-08-28 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: amb
+  requirement: &73260010 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *73260010
+description: This gem is a compilation of several implementations of the ambiguous
+  function/operator, useful for constraint programming.
+email: jd@vauguet.fr
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/amb.rb
+- lib/amb/amb_operator.rb
+- lib/amb/amb.rb
+- lib/amb/version.rb
+- MIT-LICENSE
+- README.md
+- CHANGELOG.md
+homepage: http://www.github.com/chikamichi/amb
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: McCarty's ambiguous function/operator implementations
+test_files: []