mini_kraken 0.1.09 → 0.2.00

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10a0607b5621effb10eab26d64ff7f52228f93e9c7907b91488613c1d72469aa
-  data.tar.gz: 9b43c9b0d729f2c7944be72f6599decae48d977ea0be5257a365111508473ef9
+  metadata.gz: 4bbfe3d58d4c7271a5c8a54486a743c51d6fddcb3b068095cad44cacad575c83
+  data.tar.gz: 012b412a95752592b5be70859e00d94b379e2c4c564d37d932a300a03cbc9716
 SHA512:
-  metadata.gz: 32c14d82b93ddf21d2b369745b1e556faf1736b53fd7f1782809370777e059c498e1d8347806dc2135aab3bedf429c8d2b93b5f9be4b9b361f86926edb1be20f
-  data.tar.gz: 9b82b3afd53af4da54042f8a8852367250bc8225c1229b31486b4e8223ca533d55f3dcc6250c4de4c03d0d84b77a5e5cf737a6c151f734d7a08334ac442fa330
+  metadata.gz: 952d93b01de392c7168e7cfb4a3cc911e4d1b53be11a4a10d67012bb4ab4a8f69aa42f41bf13a756f89a6d09eb775a5594174d73334c57c2230039b7991e89fd
+  data.tar.gz: a60adbd5da627495badab63de355336f131a5e599c40226931366a7c1b4a349b2542ccb55cf30ef8e60990341c1f5d8547804b1552fbbbc504bd1bed40a36d9e

data/CHANGELOG.md

@@ -1,3 +1,59 @@
+## [0.2.00] - 2020-07-12
+- First release of DSL (Domain Specific Language)
+- Fix defect for fused variables that remain fresh
+
+### NEW
+- Mix-in module `Glue::DSL` hosting methods for implementing the DSL.
+- Method `ConsCell#to_s` uses the Lisp convention for representing lists.
+
+### CHANGED
+- File `README.md` Added a couple of examples of DSL use.
+- Method `AnyValue#==` can compare with symbols with format '_' + integer literal (e.g. :_0).
+
+## [0.1.13] - 2020-07-01
+- Cover all frames from Chapter One of "Reasoned Scheme" book.
+- Fix defect for fused variables that remain fresh
+
+### CHANGED
+- Method `Variable#quote` now takes into account of cases when variables are fused.
+- Method `Vocabulary#names_fused`  now copes with cases where no variable with given name can be found.
+
+## [0.1.12] - 2020-06-29
+- Supports `conde`, that is, a relation that can take an arbitrary number of arguments.
+- Cover all frames but one from Chapter One of "Reasoned Scheme" book.
+
+### New
+- Class `Conde` a relation that succeeds for each of its successful arguments.
+
+### CHANGED
+- Method `Goal#validated_actuals` add into account polyadic relations (= relations with arbitrary number of arguments)
+
+## [0.1.11] - 2020-06-25
+- Supports `defrel`, that is, the capability to define new relations by combining other relations.
+- Covers frames from "The Reasoned Scheme" book up to frame [1:87]
+
+### New
+- Class `BaseArg` a generalization of goal or goal template argument.
+- Class `DefRelation` A specialization of `Relation` class aimed for user-defined relation.
+- Class `FormalArg` to represent goal template argument(s).
+- Class `FormalRef` an allusion to a formal argument in a goal template.
+- Class `GoalTemplate` a representation of a goal parametrized with formal arguments.
+- Class `KBoolean` a MiniKraken representation of a boolean value.
+
+### CHANGED
+- File `README.md` minor change: added more TODO's.
+
+## [0.1.10] - 2020-06-13
+- Supports frames from "The Reasoned Scheme" book up to frame [1:81]
+
+### New
+- Factory methods `Outcome#failure`, `Outcome#success`
+- Method `Vocabulary#inspect`
+- File `outcome_spec.rb`
+
+### FIXED
+- `Conj2#conjunction` vocabulary wasn't cleared when outcome2 was nil.
+
 ## [0.1.09] - 2020-06-06
 - Supports frames from "The Reasoned Scheme" book up to frame [1:76]
 

data/README.md

@@ -4,24 +4,39 @@
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](https://github.com/famished-tiger/mini_kraken/blob/master/LICENSE.txt)
 
 ### What is __mini_kraken__ ?   
-An implemention of the [miniKanren](http://minikanren.org/) relational programming language in Ruby.
+A library containing an implementation of the [miniKanren](http://minikanren.org/)   
+relational programming language in Ruby.
 *miniKanren* is a small language for relational (logic) programming.  
-Based on the reference implementation, in Scheme from the "The Reasoned Schemer" book.  
+Based on the reference implementation, in Scheme from the "The Reasoned Schemer" book.   
 Daniel P. Friedman, William E. Byrd, Oleg Kiselyov, and Jason Hemann: "The Reasoned Schemer", Second Edition,
 ISBN: 9780262535519, (2018), MIT Press.
 
 ### Features
+- Pure Ruby implementation, not a port from another language
+- Object-Oriented design
+- No runtime dependencies
+
+### miniKanren Features
 - [X] ==  
 - [X] run\*  
-- [X] fresh 
+- [X] fresh
+- [X] conde
 - [X] conj2  
-- [X] disj2  
+- [X] disj2
+- [X] defrel   
 
 ### TODO
-- [ ] defrel 
-- [ ] conde  
+
 - [ ] Occurs check
 
+List-centric relations from Chapter 2
+- [ ] caro
+- [ ] cdro
+- [ ] conso
+- [ ] nullo
+- [ ] pairo
+- [ ] singletono
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -38,9 +53,82 @@ Or install it yourself as:
 
     $ gem install mini_kraken
 
-## Usage
+## Examples
+
+The following __MiniKraken__ examples use its DSL (Domain Specific Language).
+
+### Example 1
+Let's first begin with a rather simplistic example.   
+
+```ruby
+require 'mini_kraken' # Load MiniKraken library
+
+extend(MiniKraken::Glue::DSL) # Add DSL method to self (object in context)
+
+result = run_star('q', equals(q, :pea))
+puts result # => (:pea)
+```
+
+The two first lines in the above code snippet are pretty standard:  
+- The first line loads the `mini_kraken` library.
+- The second line add the DSL methods to the current object.
+
+The next line constitutes a trivial `miniKanren` program.
+The aim of a `miniKanren` program is to find one or more solutions involving provided variable(s)
+and satisfying one or more goals.
+In our example, the `run_star` method instructs `MiniKraken` to find all solutions,  
+knowing that each successful solution:
+- binds a value to the provided variable `q` and
+- meets the goal `equals(q, :pea)`.
+
+The goal `equals(q, :pea)` succeeds because the logical variable `q` is _fresh_ (that is,
+  not yet bound to a value) and will be bound to the symbol `:pea` as a side effect
+  of the goal `equals`.
+
+So the above program succeeds and the only found solution is obtained by binding
+ the variable `q` to the value :pea. Hence the result of the `puts` method.
+
+### Example 2
+ The next example illustrates the behavior of a failing `miniKanren` program.
+
+ ```ruby
+ require 'mini_kraken' # Load MiniKraken library
+
+ extend(MiniKraken::Glue::DSL) # Add DSL method to self (object in context)
+
+ # Following miniKanren program fails
+ result = run_star('q', [equals(q, :pea), equals(q, :pod)])
+ puts result # => ()
+ ```
+In this example, we learn that `run_star` can take multiple goals placed in an array.
+The program fails to find a solution since it is not possible to satisfy the two `equals` goals simultaneously. In that case, the `run_star` return an empty list represented as `()` in the output.
+
+
+### Example 3
+ The next example shows the use two logical variables.
+
+```ruby
+# In this example and following, one assumes that DSL is loaded as shown in Example 1
+
+result = run_star(['x', 'y'], [equals(:hello, x), equals(y, :world)])
+puts result # => ((:hello :world))
+```
 
-TODO: Write usage instructions here
+This time, `run_star` takes two logical variables -`x` and `y`- and successfully finds the solution `x = :hello, y = :world`.
+
+### Example 4
+ The next example shows the use of `disj2` goals.
+ ```ruby
+ result = run_star(['x', 'y'],
+                   [
+                     disj2(equals(x, :blue), equals(x, :red)),
+                     disj2(equals(y, :sea), equals(:mountain, y))
+                   ])
+ puts result # => ((:blue :sea) (:blue :mountain) (:red :sea) (:red :mountain))
+ ```
+
+ Here, `run_star` takes two logical variables and two `disj2` goals. A `disj2` succeeds if any of its arguments succeeds.
+ This program finds four distinct solutions for x, y pairs.
 
 ## Development
 

data/lib/mini_kraken.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
-require 'mini_kraken/version'
+# This file acts as a jumping-off point for loading dependencies expected
+# for a MiniKraken client.
+
+require_relative './mini_kraken/version'
+require_relative './mini_kraken/glue/dsl'
+
+
+# End of file
 
 module MiniKraken
   class Error < StandardError; end

data/lib/mini_kraken/core/any_value.rb

@@ -12,7 +12,11 @@ module MiniKraken
       end
 
       def ==(other)
-        rank == other.rank
+        if other.is_a?(AnyValue)
+          rank == other.rank
+        elsif other.id2name =~ /_\d+/
+          rank == other.id2name.sub(/_/, '').to_i
+        end
       end
 
       # Use same text representation as in Reasoned Schemer.

data/lib/mini_kraken/core/association_walker.rb

@@ -2,7 +2,7 @@
 
 require 'set'
 require_relative 'atomic_term'
-require_relative 'composite_term'
+require_relative 'cons_cell'
 
 module MiniKraken
   module Core

data/lib/mini_kraken/core/base_arg.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module MiniKraken
+  module Core
+    # Abstract class that is a generalization for goal actual arguments or
+    # for arguments of goal template.
+    class BaseArg
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/core/conde.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require_relative 'conj2'
+require_relative 'duck_fiber'
+require_relative 'fail'
+require_relative 'goal'
+require_relative 'goal_relation'
+require_relative 'outcome'
+
+unless MiniKraken::Core.constants(false).include? :Conde
+  module MiniKraken
+    module Core
+      # A polyadic relation (i.e. it can takes an arbitrary number of argumentt)
+      # that behaves as the disjunction of its arguments.
+      # It succeeds if at least one of its goal arguments succeeds.
+      class Conde < GoalRelation
+        include Singleton
+
+        def initialize
+          super('conde', nil)
+        end
+
+        # A relation is polyadic when it accepts an arbitrary number of arguments.
+        # @return [TrueClass]
+        def polyadic?
+          true
+        end
+
+        # @param actuals [Array<Term>] A two-elements array
+        # @param anEnv [Vocabulary] A vocabulary object
+        # @return [Fiber<Outcome>] A Fiber that yields Outcomes objects
+        def solver_for(actuals, anEnv)
+          args = *validated_args(actuals)
+          Fiber.new { cond(args, anEnv) }
+        end
+
+        # Yields [Outcome, NilClass] result of the disjunction
+        # @param goals [Array<Goal>] Array of goals
+        # @param voc [Vocabulary] A vocabulary object
+        def cond(goals, voc)
+          # require 'debug'
+          success = false
+
+          goals.each do |g|
+            fiber = nil
+
+            case g
+              when Core::Goal
+                fiber = g.attain(voc)
+              when Core::Environment
+                fiber = g.attain(voc)
+              when Array
+                conjunct = conjunction(g)
+                fiber = conjunct.attain(voc)
+              when Core::ConsCell
+                goal_array = to_goal_array(g)
+                conjunct = conjunction(goal_array)
+                fiber = conjunct.attain(voc)
+            end
+            loop do
+              outcome = fiber.resume
+              break unless outcome
+
+              outcome.parent = voc unless outcome.parent
+              if outcome.successful?
+                success = true
+                Fiber.yield outcome
+                outcome.clear
+              end
+            end
+          end
+
+          Fiber.yield Outcome.new(:"#u", voc) unless success
+          Fiber.yield nil
+        end
+
+        private
+
+        def validated_args(actuals)
+          result = []
+
+          actuals.each do |arg|
+            case arg
+              when Core::Goal
+                result << arg
+
+              when Core::Environment
+                result << arg
+
+              when Array
+                result << validated_args(arg)
+
+              else
+                prefix = "#{name} expects goal as argument, found a "
+                raise StandardError, prefix + "'#{arg.class}'"
+            end
+          end
+
+          result
+        end
+
+        def conjunction(goal_array)
+          result = nil
+
+          loop do
+            conjunctions = []
+            goal_array.each_slice(2) do |uno_duo|
+              if uno_duo.size == 2
+                conjunctions << Core::Goal.new(Core::Conj2.instance, uno_duo)
+              else
+                conjunctions << uno_duo[0]
+              end
+            end
+            if conjunctions.size == 1
+              result = conjunctions[0]
+              break
+            end
+            goal_array = conjunctions
+          end
+
+          result
+        end
+
+        def to_goal_array(aCons)
+          array = []
+          curr_node = aCons
+          loop do
+            array << curr_node.car if curr_node.car.kind_of?(Core::Goal)
+            break unless curr_node.cdr
+            break unless curr_node.car.kind_of?(Core::Goal)
+
+            curr_node = curr_node.cdr
+          end
+
+          array
+        end
+      end # class
+
+      Conde.instance.freeze
+    end # module
+  end # module
+end # unless

data/lib/mini_kraken/core/conj2.rb

@@ -31,6 +31,7 @@ unless MiniKraken::Core.constants(false).include? :Conj2
         # @param g2 [Goal] Second goal argument
         # @param voc [Vocabulary] A vocabulary object
         def conjunction(g1, g2, voc)
+          # require 'debug'
           if g1.relation.kind_of?(Fail) || g2.relation.kind_of?(Fail)
             Fiber.yield Outcome.new(:"#u", voc)
           else
@@ -62,7 +63,9 @@ unless MiniKraken::Core.constants(false).include? :Conj2
               else
                 Fiber.yield outcome1
               end
-              voc.clear if outcome1&.successful? && outcome2&.successful?
+              if outcome1.successful? && (outcome2&.successful? || outcome2.nil?)
+                voc.clear
+              end
             end
           end
 

data/lib/mini_kraken/core/cons_cell.rb

@@ -11,7 +11,11 @@ unless MiniKraken::Core.constants(false).include? :ConsCell
 
         def initialize(obj1, obj2 = nil)
           @car = obj1
-          @cdr = obj2
+          if obj2.kind_of?(ConsCell) && obj2.null?
+            @cdr = nil
+          else
+            @cdr = obj2
+          end
         end
 
         def children
@@ -42,9 +46,32 @@ unless MiniKraken::Core.constants(false).include? :ConsCell
           ConsCell.new(new_car, new_cdr)
         end
 
+        # Use the list notation from Lisp as a text representation.
+        def to_s
+          return '()' if null?
+
+          "(#{pair_to_s})"
+        end
+
         def append(another)
           @cdr = another
         end
+
+        protected
+
+        def pair_to_s
+          result = +car.to_s
+          if cdr
+            result << ' '
+            if cdr.kind_of?(ConsCell)
+              result << cdr.pair_to_s
+            else
+              result << ". #{cdr}"
+            end
+          end
+
+          result
+        end
       end # class
 
       # Constant representing the null (empty) list.