amb 0.0.3 → 0.0.5

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 0.0.5
+
+ * fixed issue with load paths when used as a gem
+
+## 0.0.4
+
+## 0.0.3
+
+ * mostly bug fixes
+
+## 0.0.2
+
+ * mostly new features
+
 ## 0.0.1
 
  * Initial setup

data/README.md

@@ -19,7 +19,7 @@ Typically, the programmer would specify a limited number of alternatives (eg. di
 
 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.
 
-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.
+Thus the most common strategy used for implementing `amb()`'s logic (check/discard) is chronological backtracking. It is kind of a brute-force, linear approach, which always relies on some sort of continuations (`call/cc`). A continuation is like a savepoint, representing "what's left to run" at a given time. Recording as much continuations as alternatives enables `amb` to test "the rest of the program" multiple times until a valid solution is found. This rather dumb algorithm may be tweaked into a (not so) smarter backjumping algorithm for more efficiency, depending on the nature of the problem at stake. Another strategy is reinforcement learning (aka. constraint learning), as used in some AI systems. Most of the time it's really hard. This library implements simple backtracking only.
 
 More details on all of this under the `doc/` folder (*pending*).
 
@@ -58,13 +58,15 @@ examining x = 3, y = 1
 examining x = 3, y = 2
 solution: x = 3, y = 2
 ```
-This illustrates the incremental, backtracking pattern leading to the first valid solution. 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. You may run them with the `-d` flag to output information about the solving process.
 
 ## Installation
 
     gem install amb
 
-## Usage
+## Step by step
 
 Here's a raw use-case, presenting the required *steps*. For concrete examples, see the `examples/` directory.
 
@@ -82,15 +84,33 @@ end
 amb = Ambiguous.new
 ```
 
-Then define your alternatives using `#choose` (aliased as `#choices` or `#alternatives`). It may take arbitrary code (values, proc…).
+Then, define your alternatives using `#choose` (aliased as `#choices` or `#alternatives`). It may take arbitrary code (values, proc…). Don't forget to assign it to a variable, otherwise it is just useless alternatives. Most of the time, several alternatives set will be defined.
 
 ``` ruby
-amb.choose()
+x = amb.choose(1, 2, lambda { some code})
+y = amb.choose(:some, :more, :alternatives)
 ```
 
+Then, state at least one constraint which, hopefully, references your alternatives. If more than one constraint is expressed, all of them will be considered in the problem solving.
+
+``` ruby
+amb.assert(x != y)
+amb.assert heavy_logical_computation_on(x, y)
+```
+
+And so on. Once again, for real use-cases, see the `examples/` directory.
+
 ## TODO
 
+* more examples!
+* more specs!
+* spec out `choose` depending on a previous `choose`
+* implements a version of amb matching the original definition (returns one of its argument at random) => keep track of backtracking paths
+* implements a trampoline version (continuation-passing style)
+* memoization/reset?
+* a different selection algo? (BFS, smarter one)
+
 ## See also
 
-* the `doc/` and `examples/` directories.
+* `doc/` and `examples/` directories.
 * Continuations and fibers concepts.

data/lib/amb.rb

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

data/lib/amb/amb.rb

@@ -98,6 +98,8 @@ module Amb
     end
     failure
   end
+  alias :choices :choose
+  alias :alternatives :choose
 
   # Unconditional failure of a constraint, causing the last choice to be
   # retried. This is equivalent to saying `assert(false)`.
@@ -106,6 +108,10 @@ module Amb
   # @TODO it'd be better not to have to
   #
   def failure
+    if $DEBUG
+      @__num_of_tries ||= 1
+      @__num_of_tries += 1
+    end
     back_amb.pop.call
   end
 
@@ -135,25 +141,33 @@ module Amb
     puts failure_message
   end
 
+  def branches_count
+    @__num_of_tries
+  end
+
   module ClassMethods
     # 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
+      puts
+      puts "#{amb.branches_count} branches explored." if $DEBUG
       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")
+    def solve_all(failure_message = "No more solutions.")
       amb = self.new
       yield(amb)
       amb.failure
     rescue Amb::ExhaustedError => ex
+      puts
+      puts "#{amb.branches_count} branches explored." if $DEBUG
       amb.report(failure_message)
     end
   end

data/lib/amb/version.rb

@@ -1,6 +1,6 @@
 module Amb
   MAJOR = 0
   MINOR = 0
-  PATCH = 3
+  PATCH = 5
   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.3
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-08-28 00:00:00.000000000Z
+date: 2011-09-04 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: amb
-  requirement: &82652280 !ruby/object:Gem::Requirement
+  requirement: &75631670 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *82652280
+  version_requirements: *75631670
 description: This gem is a compilation of several implementations of the ambiguous
   function/operator, useful for constraint programming.
 email: jd@vauguet.fr
@@ -56,7 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.6
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: McCarty's ambiguous function/operator implementations