mini_kraken 0.2.03 → 0.2.04

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ae3703cbb0a7a854af490478227c915d7d9af72715be80cbd4e3c95cb7b2c3f
-  data.tar.gz: 27e04d428e1015f176fbafba7c047a0b12c28e9150161a7a5702190c8dd2e2e9
+  metadata.gz: 96c07c3751d0c46963e19f8e25dc429a77dbd630c22b32018914ccf36f471689
+  data.tar.gz: 26efce2c03a89fd4129c756ce64daa80783cc9bfcebc0358b493076f33ef9434
 SHA512:
-  metadata.gz: bd9cd60953f88610ce3a5009e0cad4099e1896643ad01f1c6616a4c20fb4495a71f5c5ed11efe98873362055bda2ec9d0ba4a1ce972844588cacab528ac5333d
-  data.tar.gz: 1c9d27a9fb7fa014f9789a159aff5309bd9c03ce810e994951373ee550698518683359815c4db43b9d95b00ba889670b824af18c1019af5442f2ca3b42c795ba
+  metadata.gz: 1df0d6a9397a804e35700aaedb1fcc1ae7fb91a4b3b237ffe138be5cc63b51113d1af5a57f5cd216a41217993dce5dc5186d0690ab992d2eab229995321e7dfb
+  data.tar.gz: d5af2983495e31e77e8947bffeca99a9b88b916208cb511a88e3f0e397ec2f105cd60d333d2663b78c4e943edad9e4c76c8aa7eabd07a94a733e9821d63de305

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [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.
 

data/lib/mini_kraken/atomic/all_atomic.rb

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

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

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
-require_relative 'term'
-require_relative 'freshness'
+require_relative '../core/term'
+require_relative '../core/freshness'
 
 module MiniKraken
-  module Core
-    # An atomic term is an elementary Minikraken term that cannot be
-    # decomposed into simpler MiniKraken data value(s).
-    class AtomicTerm < Term
-      # @return [Object] Internal representation of a MiniKraken data value
+  # This module packages the atomic term classes, that is,
+  # the basic MiniKraken datatypes.
+  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()
@@ -23,7 +28,7 @@ module MiniKraken
       # @param _env [Vocabulary]
       # @return [Freshness]
       def freshness(_env)
-        Freshness.new(:ground, self)
+        Core::Freshness.new(:ground, self)
       end
 
       # An atomic term is a ground term: by definition it doesn't contain
@@ -35,19 +40,27 @@ module MiniKraken
       end
 
       # An atomic term is a ground term: by definition it doesn't contain
-      # any fresh variable.
+      # any (fresh) variable.
       # @param _env [Vocabulary]
       # @return [TrueClass]
       def ground?(_env)
         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(_env)
         self
       end
 
       # Data equality testing
+      # @param other [AtomicTerm, #value]
       # @return [Boolean]
       def ==(other)
         if other.respond_to?(:value)
@@ -58,6 +71,7 @@ module MiniKraken
       end
 
       # Type and data equality testing
+      # @param other [AtomicTerm]
       # @return [Boolean]
       def eql?(other)
         (self.class == other.class) && value.eql?(other.value)

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,9 +3,10 @@
 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)

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

@@ -3,10 +3,11 @@
 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
+      # Initialize a MiniKraken symbol with a given Ruby Symbol value.
       # @param aValue [Symbol] Ruby representation of symbol value
       def initialize(aValue)
         super(aValue)
@@ -19,6 +20,7 @@ module MiniKraken
       end
 
       # Returns a string representing the MiniKraken symbol.
+      # @return [String]
       def to_s
         ":#{id2name}"
       end

data/lib/mini_kraken/{core → composite}/composite_term.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
-require_relative 'term'
-require_relative 'freshness'
+require_relative '../core/term'
+require_relative '../core/freshness'
 
 module MiniKraken
-  module Core
+  # 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 < Term
+    class CompositeTerm < Core::Term
       # Abstract method (to override). Return the child terms.
       # @return [Array<Term>]
       def children

data/lib/mini_kraken/composite/cons_cell.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative 'composite_term'
+
+module MiniKraken
+  module Composite
+    # In Lisp dialects, a cons cell (or a pair) is a data structure with two
+    # fields called the car and cdr fields (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.
+      # @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
+
+      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
+
+      # 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
+
+      # Change the cdr of ConsCell to 'another'.
+      # Analogue of set-cdr! procedure in Scheme.
+      # @param another [Term]
+      def set_cdr!(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.
+    NullList = ConsCell.new(nil, nil).freeze
+  end # module
+end # module

data/lib/mini_kraken/{core → composite}/cons_cell_visitor.rb

@@ -4,7 +4,7 @@ require 'set'
 require_relative 'cons_cell'
 
 module MiniKraken
-  module Core
+  module Composite
     # Factory class.
     # Purpose: to create an enumerator specialized in the visit of cons cells.
     class ConsCellVisitor

data/lib/mini_kraken/core/association_walker.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 require 'set'
-require_relative 'atomic_term'
-require_relative 'cons_cell'
+require_relative '../atomic/atomic_term'
+require_relative '../composite/cons_cell'
 
 module MiniKraken
   module Core
@@ -26,7 +26,7 @@ module MiniKraken
         # Treat easy cases first...
         return nil if assocs.empty?
 
-        assoc_atomic = assocs.find { |assc| assc.value.kind_of?(AtomicTerm) }
+        assoc_atomic = assocs.find { |assc| assc.value.kind_of?(Atomic::AtomicTerm) }
         return assoc_atomic.value if assoc_atomic
 
         result = nil
@@ -45,17 +45,17 @@ module MiniKraken
       end
 
       def walk_value(aTerm, anEnv)
-        return aTerm if aTerm.kind_of?(AtomicTerm) || aTerm.kind_of?(AnyValue)
+        return aTerm if aTerm.kind_of?(Atomic::AtomicTerm) || aTerm.kind_of?(AnyValue)
 
         result = nil
 
-        if aTerm.kind_of?(CompositeTerm)
+        if aTerm.kind_of?(Composite::CompositeTerm)
           children = aTerm.children.compact
           walk_results = children.map do |child|
             walk_value(child, anEnv)
           end
           result = aTerm unless walk_results.any?(&:nil?)
-        else # VariableRef or Variable
+        else # LogVarRef or Variable
           name = aTerm.respond_to?(:name) ? aTerm.name : aTerm.var_name
           result = find_ground(name, anEnv)
         end
@@ -74,9 +74,9 @@ module MiniKraken
         # require 'debug'
         result = nil
 
-        if aTerm.kind_of?(AtomicTerm)
+        if aTerm.kind_of?(Atomic::AtomicTerm)
           result = Freshness.new(:ground, aTerm)
-        elsif aTerm.kind_of?(CompositeTerm)
+        elsif aTerm.kind_of?(Composite::CompositeTerm)
           children = aTerm.children.compact
           walk_results = children.map { |chd| determine_freshness(chd, anEnv) }
 
@@ -89,7 +89,7 @@ module MiniKraken
             degree = :bound
           end
           result = Freshness.new(degree, aTerm)
-        else # VariableRef or Variable
+        else # LogVarRef or Variable
           name = aTerm.respond_to?(:name) ? aTerm.name : aTerm.var_name
           assocs = anEnv[name]
           if assocs.empty?
@@ -103,7 +103,7 @@ module MiniKraken
       end
 
       def freshness_associated(assocs, anEnv)
-        assoc_atomic = assocs.find { |assc| assc.value.kind_of?(AtomicTerm) }
+        assoc_atomic = assocs.find { |assc| assc.value.kind_of?(Atomic::AtomicTerm) }
         return Freshness.new(:ground, assoc_atomic.value) if assoc_atomic
 
         raw_results = assocs.map do |assc|
@@ -133,11 +133,11 @@ module MiniKraken
         # require 'debug'
         result = nil
 
-        if aTerm.kind_of?(AtomicTerm)
+        if aTerm.kind_of?(Atomic::AtomicTerm)
           result = aTerm.quote(anEnv)
-        elsif aTerm.kind_of?(ConsCell)
+        elsif aTerm.kind_of?(Composite::ConsCell)
           result = aTerm.quote(anEnv)
-        else # VariableRef or Variable
+        else # LogVarRef or Variable
           name = aTerm.respond_to?(:name) ? aTerm.name : aTerm.var_name
           assocs = anEnv[name]
           if assocs.empty?
@@ -151,7 +151,7 @@ module MiniKraken
       end
 
       def quote_associated(assocs, anEnv)
-        assoc_atomic = assocs.find { |assc| assc.value.kind_of?(AtomicTerm) }
+        assoc_atomic = assocs.find { |assc| assc.value.kind_of?(Atomic::AtomicTerm) }
         return assoc_atomic.value if assoc_atomic
 
         raw_results = assocs.map do |assc|

data/lib/mini_kraken/core/binary_relation.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'relation'
-require_relative 'composite_term'
+require_relative '../composite/composite_term'
 
 module MiniKraken
   module Core
@@ -25,26 +25,26 @@ module MiniKraken
       # |arg1                | arg2               | arg2.ground? || Commute |
       # | isa? Atomic        | isa? Atomic        | dont_care    || Yes     |
       # | isa? Atomic        | isa? CompositeTerm | dont_care    || Yes     |
-      # | isa? Atomic        | isa? VariableRef   | dont_care    || Yes     |
+      # | isa? Atomic        | isa? LogVarRef   | dont_care    || Yes     |
       # | isa? CompositeTerm | isa? Atomic        | true         || No      |
       # | isa? CompositeTerm | isa? CompositeTerm | false        || Yes     |
       # | isa? CompositeTerm | isa? CompositeTerm | true         || No      |
-      # | isa? CompositeTerm | isa? VariableRef   | dont_care    || Yes     |
-      # | isa? VariableRef   | isa? Atomic        | dont_care    || No      |
-      # | isa? VariableRef   | isa? CompositeTerm | dont_care    || No      |
-      # | isa? VariableRef   | isa? VariableRef   | false        || Yes     |
-      # | isa? VariableRef   | isa? VariableRef   | true         || No      |
+      # | isa? CompositeTerm | isa? LogVarRef   | dont_care    || Yes     |
+      # | isa? LogVarRef   | isa? Atomic        | dont_care    || No      |
+      # | isa? LogVarRef   | isa? CompositeTerm | dont_care    || No      |
+      # | isa? LogVarRef   | isa? LogVarRef   | false        || Yes     |
+      # | isa? LogVarRef   | isa? LogVarRef   | true         || No      |
       def commute_cond(arg1, arg2, env)
         commuting = true
-        arg2_is_var_ref = arg2.kind_of?(VariableRef)
+        arg2_is_var_ref = arg2.kind_of?(LogVarRef)
 
-        if arg1.kind_of?(CompositeTerm)
+        if arg1.kind_of?(Composite::CompositeTerm)
           if arg2_is_var_ref
             commuting = true
           else
             commuting = !arg2.ground?(env)
           end
-        elsif arg1.kind_of?(VariableRef)
+        elsif arg1.kind_of?(LogVarRef)
           if arg2_is_var_ref
             commuting = !arg2.ground?(env)
           else