mini_kraken 0.2.02 → 0.3.02

data/CHANGELOG.md

@@ -1,3 +1,55 @@
+## [0.3.02] - 2020-12-19
+- `mini_kraken` now implements `conso` relation.
+
+### CHANGED
+- Method `Context#build_solution` old source code (redundant) removed.
+- File `README.md` minor changes.
+
+### FIXED
+- Method `ConsCell#expand` pushed a node in the stack even if it was fully visited.
+
+## [0.3.01] - 2020-12-17
+- Minor: updated Rubocop config file `.rubocop.yml`
+
+### CHANGED
+- Config file `.rubocop.yml` updated to incorporate the cops from Rubocop 1.6.1
+- Several files re-styled to please Rubocop
+- `README.md` Checkbox for `cdro` is now ticked
+
+## [0.3.00] - 2020-12-16
+- Version number bump because this is a vast code rewrite
+
+### CHANGED
+- Most classes have been reworked
+- Relation `Equals` has been renamed to `Unify`
+
+## [0.2.04] - 2020-09-02
+- Intermediate version before vast code rework.
+
+### CHANGED
+- Classes `KBoolean`, `KSymbol`, `KInteger` moved to namespace `Atomic`
+- Classes `ConsCell`, `ConsCellVisitor` moved to namespace `Composite`
+- Class `Variable` renamed to `LogVar`
+- Class `VariableRef` renamed to `LogVarRef`
+
+## [0.2.03] - 2020-09-02
+- The DSL (Domain Specific Language) supports the `caro` relation & passes frames up to 2-8 from Chapter 2.
+
+### NEW
+- Class `ConsCellVisitor`. Its method `df_visitor` builds a Fiber that walks over a ConsCell (list/graph).
+- Method `Outcome#failure?`
+- Method `Outcome#prune!` for removing associations of transient variables.
+- Method `VariableRef#to_s` for providing a text representation of a variable reference
+- Method `Vocabulary#prune` for removing associations of transient variables.
+- Class `FreshEnvFactory` as its name implies, is used to build `FreshEnv` instances.
+
+### CHANGED
+- Method `Outcome#successful?` renamed to `Outcome#success?`
+
+### FIXED
+- Method `Equals#solver_for` now prunes associations of transient variables.
+- Method `Equals#unify_composite_terms` now copes with Conscell vs. VariableRef unification.
+
 ## [0.2.02] - 2020-08-08
 - The DSL (Domain Specific Language) now supports `conde` and passes all examples from Chapter 1.
 

data/README.md

@@ -4,10 +4,9 @@
 [![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__ ?   
-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.   
+A library containing an implementation in Ruby of the [miniKanren](http://minikanren.org/) 
+ language.
+*miniKanren* is a small language for relational (logic) programming as defined in 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.
 
@@ -15,24 +14,25 @@ ISBN: 9780262535519, (2018), MIT Press.
 - Pure Ruby implementation, not a port from another language
 - Object-Oriented design
 - No runtime dependencies
+- Test suite patterned on examples from the reference book.
 
 ### miniKanren Features
-- [X] ==  
+- [X] ( == ) unify
 - [X] run\*  
 - [X] fresh
 - [X] conde
 - [X] conj2  
 - [X] disj2
-- [X] defrel   
+- [X] defrel  
+- [X] caro
+- [X] cdro
+- [X] conso 
 
 ### TODO
 
 - [ ] Occurs check
 
-List-centric relations from Chapter 2
-- [ ] caro  
-- [ ] cdro  
-- [ ] conso  
+Pair-centric relations from Chapter 2 
 - [ ] nullo  
 - [ ] pairo  
 - [ ] singletono  
@@ -65,7 +65,7 @@ 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))
+result = run_star('q', unify(q, :pea))
 puts result # => (:pea)
 ```
 
@@ -79,11 +79,11 @@ and satisfying one or more goals to the `run_star method.
 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)`.
+- meets the goal `unify(q, :pea)`.
 
-The goal `equals(q, :pea)` succeeds because the logical variable `q` is _fresh_ (that is,
+The goal `unify(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`.
+  of the goal `unify`.
 
 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.
@@ -97,11 +97,11 @@ So the above program succeeds and the only found solution is obtained by binding
  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)])
+ result = run_star('q', [unify(q, :pea), unify(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.  
+The program fails to find a solution since it is not possible to satisfy the two `unify` goals simultaneously.  
 In case of failure, the `run_star` returns an empty list represented as `()` in the output.
 
 
@@ -111,7 +111,7 @@ In case of failure, the `run_star` returns an empty list represented as `()` in
 ```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)])
+result = run_star(['x', 'y'], [unify(:hello, x), unify(y, :world)])
 puts result # => ((:hello :world))
 ```
 
@@ -122,8 +122,8 @@ This time, `run_star` takes two logical variables -`x` and `y`- and successfully
  ```ruby
  result = run_star(['x', 'y'],
                    [
-                     disj2(equals(x, :blue), equals(x, :red)),
-                     disj2(equals(y, :sea), equals(:mountain, y))
+                     disj2(unify(x, :blue), unify(x, :red)),
+                     disj2(unify(y, :sea), unify(:mountain, y))
                    ])
  puts result # => ((:blue :sea) (:blue :mountain) (:red :sea) (:red :mountain))
  ```

data/lib/mini_kraken.rb

@@ -12,4 +12,3 @@ module MiniKraken
 end
 
 # End of file
-

data/lib/mini_kraken/atomic/all_atomic.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'k_boolean'
+require_relative 'k_string'
+require_relative 'k_symbol'

data/lib/mini_kraken/atomic/atomic_term.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative '../core/term'
+# require_relative '../core/freshness'
+
+module MiniKraken
+  # This module packages the atomic term classes, that is,
+  # the basic datatypes that cannot be decomposed
+  # in MiniKraken into simpler, smaller data values.
+  module Atomic
+    # An atomic term is an elementary MiniKraken term, a data value
+    # that cannot be decomposed into simpler MiniKraken term(s).
+    # Typically, an atomic term encapsulates a Ruby primitive data object.
+    # MiniKraken treats atomic terms as immutable objects.
+    class AtomicTerm < Core::Term
+      # @return [Object] Internal representation of a MiniKraken data value.
+      attr_reader :value
+
+      # Initialize an atomic term with the given data object.
+      # @param aValue [Object] Ruby representation of MiniKraken data value
+      def initialize(aValue)
+        super()
+        @value = aValue
+        @value.freeze
+      end
+
+      # An atomic term, by definition is bound to a definite value.
+      # @param _ctx [Context]
+      # @return [FalseClass]
+      def unbound?(_ctx)
+        false
+      end
+
+      # An atomic term has a definite value, therefore it is not floating.
+      # @param _ctx [Context]
+      # @return [FalseClass]
+      def floating?(_ctx)
+        false
+      end
+
+      # An atomic term is a pinned term: by definition, it has a definite
+      # value.
+      # @param _ctx [Context]
+      # @return [TrueClass]
+      def pinned?(_ctx)
+        true
+      end
+
+      # Return a String representation of the atomic term
+      # @return [String]
+      def to_s
+        value.to_s
+      end
+
+      # Treat this object as a data value.
+      # @return [AtomicTerm]
+      def quote(_ctx)
+        self
+      end
+
+      # Data equality testing
+      # @param other [AtomicTerm, #value]
+      # @return [Boolean]
+      def ==(other)
+        if other.respond_to?(:value)
+          value == other.value
+        else
+          value == other
+        end
+      end
+
+      # Type and data equality testing
+      # @param other [AtomicTerm]
+      # @return [Boolean]
+      def eql?(other)
+        (self.class == other.class) && value.eql?(other.value)
+      end
+
+      # Return the list of variable (i_names) that this term depends on.
+      # For atomic terms, there is no such dependencies.
+      # @param _ctx [Core::Context]
+      # @return [Set] an empty set
+      def dependencies(_ctx)
+        Set.new
+      end
+
+      # Make a copy of self with all the variable reference being
+      # replaced by the corresponding value in the Hash.
+      # @param _substitutions [Hash {String => Term}]
+      # @return [Term]
+      def dup_cond(_substitutions)
+        dup
+      end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/atomic/k_boolean.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'atomic_term'
+
+module MiniKraken
+  module Atomic
+    # A specialized atomic term that implements a boolean (true/false) value
+    # in MiniKraken.
+    class KBoolean < AtomicTerm
+      # Initialize a MiniKraken boolean with a given data value.
+      # @example
+      #   # Initialize with a Ruby boolean
+      #   truthy = KBoolean.new(true)
+      #   falsey = KBoolean.new(false)
+      #   # Initialize with a String inspired from canonical miniKanren
+      #   truthy = KBoolean.new('#t')   # In Scheme #t means true
+      #   falsey = KBoolean.new('#f')   # In Scheme #f means false
+      #   # Initialize with a Symbol inspired from canonical miniKanren
+      #   truthy = KBoolean.new(:"#t")   # In Scheme #t means true
+      #   falsey = KBoolean.new(:"#f")   # In Scheme #f means false
+      # @param aValue [Boolean, String, Symbol] Ruby representation of boolean value.
+      def initialize(aValue)
+        super(validated_value(aValue))
+      end
+
+      private
+
+      def validated_value(aValue)
+        case aValue
+          when true, false
+            aValue
+          when :"#t", '#t'
+            true
+          when :"#f", '#f'
+            false
+          else
+            raise StandardError, "Invalid boolean literal '#{aValue}'"
+        end
+      end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/{core → atomic}/k_integer.rb

@@ -3,14 +3,11 @@
 require_relative 'atomic_term'
 
 module MiniKraken
-  module Core
+  module Atomic
     # A specialized atomic term that represents an integer value.
     # in MiniKraken
+    # @note As MiniKraken doesn't support integer values yet, this class is WIP.
     class KInteger < AtomicTerm
-      # @param aValue [Integer] Ruby representation of integer value
-      def initialize(aValue)
-        super(aValue)
-      end
     end # class
   end # module
 end # module

data/lib/mini_kraken/atomic/k_string.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'atomic_term'
+
+module MiniKraken
+  module Atomic
+    # A specialized atomic term that represents a string value
+    # in MiniKraken.
+    class KString < AtomicTerm
+      # Returns a string representing the MiniKraken symbol.
+      # @return [String]
+      def to_s
+        value
+      end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/{core → atomic}/k_symbol.rb

@@ -3,15 +3,10 @@
 require_relative 'atomic_term'
 
 module MiniKraken
-  module Core
-    # A specialized atomic term that represents a symbolic value.
-    # in MiniKraken
+  module Atomic
+    # A specialized atomic term that represents a symbolic value
+    # in MiniKraken.
     class KSymbol < AtomicTerm
-      # @param aValue [Symbol] Ruby representation of symbol value
-      def initialize(aValue)
-        super(aValue)
-      end
-
       # Returns the name or string corresponding to value.
       # @return [String]
       def id2name
@@ -19,6 +14,7 @@ module MiniKraken
       end
 
       # Returns a string representing the MiniKraken symbol.
+      # @return [String]
       def to_s
         ":#{id2name}"
       end

data/lib/mini_kraken/composite/all_composite.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'list'
+require_relative 'cons_cell_visitor'

data/lib/mini_kraken/composite/composite_term.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../core/term'
+
+module MiniKraken
+  # This module packages the composite term classes.
+  # These hold one or more MiniKanren objects.
+  module Composite
+    # An composite term is an Minikraken term that can be
+    # decomposed into simpler MiniKraken data value(s).
+    class CompositeTerm < Core::Term
+      # Abstract method (to override). Return the child terms.
+      # @return [Array<Term>]
+      def children
+        raise NotImplementedError, 'This method must re-defined in subclass(es).'
+      end
+
+=begin
+      # @param env [Environment]
+      # @return [Boolean]
+      def fresh?(env)
+        env.fresh_value?(self)
+      end
+=end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/composite/cons_cell.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require_relative 'composite_term'
+require_relative 'cons_cell_visitor'
+
+module MiniKraken
+  module Composite
+    # In Lisp dialects, a cons cell (or a pair) is a data structure with two
+    # fields named car and cdr (for historical reasons).
+    # Cons cells are the key ingredient for building lists in Lisp.
+    # A cons cell can be depicted as a box with two parts, car and cdr each
+    # containing a reference to another object.
+    #   +-----------+
+    #   | car | cdr |
+    #   +--|-----|--+
+    #      |     |
+    #      V     V
+    #     obj1  obj2
+    #
+    # The list (1 2 3) can be constructed as follows:
+    #   +-----------+
+    #   | car | cdr |
+    #   +--|-----|--+
+    #      |     |
+    #      V     V
+    #      1  +-----------+
+    #         | car | cdr |
+    #         +--|-----|--+
+    #            |     |
+    #            V     V
+    #            2  +-----------+
+    #               | car | cdr |
+    #               +--|-----|--+
+    #                  |     |
+    #                  V     V
+    #                  3    nil
+    class ConsCell < CompositeTerm
+      # The first slot in a ConsCell
+      # @return [Term]
+      attr_reader :car
+
+      # The second slot in a ConsCell
+      # @return [Term]
+      attr_reader :cdr
+
+      # Construct a new conscell whose car and cdr are obj1 and obj2.
+      # In Scheme, a list is terminated by a null list.
+      # In MiniKraken, a list is terminated by a Ruby nil.
+      # Therefore, when setting the cdr to the null list, the implementation
+      # will silently replace the null list by a nil.
+      # @param obj1 [Term, NilClass]
+      # @param obj2 [Term, NilClass]
+      def initialize(obj1, obj2 = nil)
+        super()
+        @car = obj1
+        if obj2.kind_of?(ConsCell) && obj2.null?
+          @cdr = nil
+        else
+          @cdr = obj2
+        end
+      end
+
+      # Specialized constructor for null list.
+      # @return [ConsCell] Null list
+      def self.null
+        new(nil, nil)
+      end
+
+      def children
+        [car, cdr]
+      end
+
+      # Return true if it is an empty list, otherwise false.
+      # A list is empty, when both car and cdr fields are nil.
+      # @return [Boolean]
+      def null?
+        car.nil? && cdr.nil?
+      end
+
+      # Is the receiver an unbound variable?
+      # By definition, a composite isn't a variable.
+      # @param _ctx [Core::Context]
+      # @return [FalseClass]
+      def unbound?(_ctx)
+        false
+      end
+
+      # Does the composite have a variable that is itself floating?
+      # @return [Boolean]
+      def floating?(ctx)
+        !pinned?(ctx)
+      end
+
+      # Does the composite have a definite value?
+      # @return [Boolean]
+      def pinned?(ctx)
+        @pinned_car ||= car.nil? || car.pinned?(ctx)
+        @pinned_cdr ||= cdr.nil? || cdr.pinned?(ctx)
+
+        @pinned_car && @pinned_cdr
+      end
+
+      # Return true if car and cdr fields have the same values as the other
+      # ConsCell.
+      # @param other [ConsCell]
+      # @return [Boolean]
+      def ==(other)
+        return false unless other.respond_to?(:car)
+
+        (car == other.car) && (cdr == other.cdr)
+      end
+
+      # Test for type and data value equality.
+      # @param other [ConsCell]
+      # @return [Boolean]
+      def eql?(other)
+        (self.class == other.class) && car.eql?(other.car) && cdr.eql?(other.cdr)
+      end
+
+      # Return a data object that is a copy of the ConsCell
+      # @param anEnv [Core::Environment]
+      # @return [ConsCell]
+      def quote(anEnv)
+        return self if null?
+
+        new_car = car.nil? ? nil : car.quote(anEnv)
+        new_cdr = cdr.nil? ? nil : cdr.quote(anEnv)
+        ConsCell.new(new_car, new_cdr)
+      end
+
+      # Use the list notation from Lisp as a text representation.
+      # @return [String]
+      def to_s
+        return '()' if null?
+
+        "(#{pair_to_s})"
+      end
+
+      # Return the list of variable (i_names) that this term depends on.
+      # For a variable reference, it will return the i_names of its variable
+      # @param ctx [Core::Context]
+      # @return [Set<String>] A set of i_names
+      def dependencies(ctx)
+        deps = []
+        visitor = ConsCellVisitor.df_visitor(self)
+        skip_children = false
+        loop do
+          side, cell = visitor.resume(skip_children)
+          if cell.kind_of?(Core::LogVarRef)
+            deps << ctx.lookup(cell.name).i_name
+            skip_children = true
+          else
+            skip_children = false
+          end
+          break if side == :stop
+        end
+
+        Set.new(deps)
+      end
+
+      # @param ctx [Core::Context]
+      # @param theSubstitutions [Hash{String => Association}]
+      def expand(ctx, theSubstitutions)
+        head = curr_cell = nil
+        path = []
+
+        visitor = ConsCellVisitor.df_visitor(self) # Breadth-first!
+        skip_children = false
+
+        loop do
+          side, cell = visitor.resume(skip_children)
+          # next if cell == self
+          break if side == :stop
+
+          case cell
+            when ConsCell
+              new_cell = ConsCell.null
+              if curr_cell
+                curr_cell.set!(side, new_cell)
+                path.push(curr_cell) unless side == :cdr
+              end
+              curr_cell = new_cell
+              head ||= new_cell
+
+            when Core::LogVarRef
+              # Is this robust?
+              if cell.i_name
+                i_name = cell.i_name
+              else
+                i_name = ctx.symbol_table.lookup(cell.name).i_name
+              end
+              expanded = ctx.expand_value_of(i_name, theSubstitutions)
+              curr_cell.set!(side, expanded)
+              curr_cell = path.pop if side == :cdr
+
+            else
+              curr_cell.set!(side, cell)
+              curr_cell = path.pop if side == :cdr
+          end
+        end
+
+        head
+      end
+
+
+      # @param ctx [Core::Context]
+      # @param theSubstitutions [Hash{String => Association}]
+
+
+      # File 'lib/mini_kraken/atomic/atomic_term.rb', line 91
+      # Make a copy of self with all the variable reference being replaced
+      # by the corresponding value in the Hash.
+      # @param substitutions [Hash {String => Term}]
+      # @return [ConsCell]
+      def dup_cond(substitutions)
+        head = curr_cell = nil
+        path = []
+
+        visitor = ConsCellVisitor.df_visitor(self) # Breadth-first!
+        skip_children = false
+
+        loop do
+          side, cell = visitor.resume(skip_children)
+          # next if cell == self
+          break if side == :stop
+
+          if cell.kind_of?(ConsCell)
+            new_cell = ConsCell.null
+            if curr_cell
+              curr_cell.set!(side, new_cell)
+              path.push(curr_cell)
+            end
+            curr_cell = new_cell
+            head ||= new_cell
+
+          else
+            duplicate = cell.nil? ? nil : cell.dup_cond(substitutions)
+            curr_cell.set!(side, duplicate)
+            curr_cell = path.pop if side == :cdr
+          end
+        end
+
+        head
+      end
+
+      # Set one element of the pair
+      # @param member [Symbol]
+      # @param element [Term]
+      def set!(member, element)
+        case member
+          when :car
+            set_car!(element)
+          when :cdr
+            @pinned_cdr = nil
+            @cdr = element
+          else
+            raise StandardError, "Undefined cons cell member #{member}"
+          end
+      end
+
+      # Change the car of ConsCell to 'element'.
+      # Analogue of set-car! procedure in Scheme.
+      # @param element [Term]
+      def set_car!(element)
+        @pinned_car = nil # To force re-evaluation
+        @car = element
+      end
+
+      # Change the cdr of ConsCell to 'element'.
+      # Analogue of set-cdr! procedure in Scheme.
+      # @param element [Term]
+      def set_cdr!(element)
+        @pinned_cdr = nil # To force re-evaluation
+        @cdr = (element.kind_of?(ConsCell) && element.null?) ? nil : element
+      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 set to a null (empty) list.
+    NullList = ConsCell.null.freeze
+  end # module
+end # module