amb 0.0.2 → 0.0.3

data/README.md

@@ -17,11 +17,11 @@ Ambiguous functions were [defined in John McCarty's 1963 paper](http://www-forma
 
 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.
+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. [Quoting Dorai Sitaram](http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme-Z-H-16.html#node_chap_14), "`amb` takes zero or more expressions, and makes a nondeterministic (or "ambiguous") choice among them, preferring those choices that cause the program to converge meaningfully". 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; if only one is defined, whichever is defined; and terminate the program if none is defined. 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 though (for unpredictability is not what computers enjoys doing). 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, in a depth-first selection algorithm. It *is* dumb yet it works as expected.
 
-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.
+Thus the most common strategy used for implementing `amb()`'s logic (check/discard) is chronological backtracking. It almost always relies on some sort of continuations (`call/cc`) and a search algorithm (say, depth-first). The algorithm may be tweaked into a smarter backjumping for more efficiency, depending on the problem at stake. Another strategy is reinforcement learning (aka. constraint learning), as is used in some AI systems. This library implements simple backtracking only though.
 
-More details on all of this under the `doc/`` folder (*pending*).
+More details on all of this under the `doc/` folder (*pending*).
 
 ## Examples
 
@@ -58,7 +58,7 @@ 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.
+This illustrates the incremental, backtracking pattern leading to the first valid solution. Many more examples under the `examples/` directory.
 
 ## Installation
 
@@ -66,6 +66,28 @@ This illustrates the incremental, backtracking pattern. Many more examples under
 
 ## Usage
 
+Here's a raw use-case, presenting the required *steps*. For concrete examples, see the `examples/` directory.
+
+First, require the lib:
+
+``` ruby
+require 'amb'
+
+# one may either use the Amb module (Amb.choose…) or create a proxy class.
+class Ambiguous
+  include Amb
+  # opportunity to log & the like here
+end
+
+amb = Ambiguous.new
+```
+
+Then define your alternatives using `#choose` (aliased as `#choices` or `#alternatives`). It may take arbitrary code (values, proc…).
+
+``` ruby
+amb.choose()
+```
+
 ## TODO
 
 ## See also

data/lib/amb/amb.rb

@@ -77,7 +77,7 @@ module Amb
     base.extend(ClassMethods)
   end
 
-  # Memoize and return the alternatives continuations.
+  # Memoize and return the alternatives associated continuations.
   #
   # @return [Array<Proc, Continuation>]
   #
@@ -102,6 +102,9 @@ module Amb
   # Unconditional failure of a constraint, causing the last choice to be
   # retried. This is equivalent to saying `assert(false)`.
   #
+  # Use to force a search for another solution (see examples).
+  # @TODO it'd be better not to have to
+  #
   def failure
     back_amb.pop.call
   end
@@ -136,7 +139,7 @@ module Amb
     # Class convenience method to search for the first solution to the
     # constraints.
     #
-    def solve(failure_message="No Solution")
+    def solve(failure_message = "No Solution")
       amb = self.new
       yield(amb)
     rescue Amb::ExhaustedError => ex
@@ -146,7 +149,7 @@ module Amb
     # Class convenience method to search for all the solutions to the
     # constraints.
     #
-    def solve_all(failure_message="No More Solutions")
+    def solve_all(failure_message = "No More Solutions")
       amb = self.new
       yield(amb)
       amb.failure

data/lib/amb/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amb
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2011-08-28 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: amb
-  requirement: &73260010 !ruby/object:Gem::Requirement
+  requirement: &82652280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *73260010
+  version_requirements: *82652280
 description: This gem is a compilation of several implementations of the ambiguous
   function/operator, useful for constraint programming.
 email: jd@vauguet.fr