mini_kraken 0.2.04 → 0.3.00

data/lib/mini_kraken/composite/cons_cell_visitor.rb

@@ -6,50 +6,36 @@ require_relative 'cons_cell'
 module MiniKraken
   module Composite
     # Factory class.
-    # Purpose: to create an enumerator specialized in the visit of cons cells.
+    # Purpose: to create Fiber specialized in the visit of cons cells.
     class ConsCellVisitor
       # Build a depth-first in-order expression tree visitor.
-      # The visitor is implemented as an Enumerator.
-      # The enumerator returns couples of the form: [:car or :cdr or :nil, visitee]
-      # [anExpr] the term to visit.
+      # The visitor is implemented as a Fiber.
+      # The Fiber yields couples of the form: [member, visitee]
+      # where member is one of :car, :cdr
+      # The end of visit is signalled with the couple [:stop, nil]
       # @param aCell [ConsCell]
-      # @return [Fiber]
+      # @return [Fiber] A Fiber that yields couples
       def self.df_visitor(aCell)
         first = aCell	# The visit will start from the provided cons cell
+        # puts "#{__callee__} called with #{aCell.object_id.to_s(16)}"
         visitor = Fiber.new do |skipping|
           # Initialization part: will run once
           visitees = Set.new # Keep track of the conscell already visited
           visit_stack = first.nil? ? [] : [[:car, first]] # The LIFO queue of cells to visit
 
           until visit_stack.empty?	# Traversal part (as a loop)
-            to_swap = false
             side, cell = visit_stack.pop
-            next if visitees.include?(cell)
+            next if visitees.include?(cell) && side == :car
 
-            visitees << cell
+            visitees << cell if cell.kind_of?(ConsCell)
 
             skip_children = Fiber.yield [side, cell]
-            # require 'debug' if skip_children
             next if skip_children || skipping
 
             skipping = false
-            case cell.car
-              when ConsCell
-                visit_stack.push([:car, cell.car])
-                to_swap = true
-              else
-                Fiber.yield [:car, cell.car]
-            end
-
-            case cell.cdr
-              when ConsCell
-                if to_swap
-                  visit_stack.insert(-2, [:cdr, cell.cdr])
-                else
-                  visit_stack.push([:cdr, cell.cdr])
-                end
-              else
-                Fiber.yield [:cdr, cell.cdr]
+            if cell.is_a?(ConsCell)
+              visit_stack.push([:cdr, cell.cdr])
+              visit_stack.push([:car, cell.car])
             end
           end
 
@@ -57,44 +43,6 @@ module MiniKraken
           Fiber.yield [:stop, nil]
         end
 
-=begin
-        visitor = Enumerator.new do |requester|	# requester argument is a Yielder
-          # Initialization part: will run once
-          visitees = Set.new # Keep track of the conscell already visited
-          visit_stack = first.nil? ? [] : [[ :car, first ]] # The LIFO queue of cells to visit
-
-          until visit_stack.empty?	# Traversal part (as a loop)
-            to_swap = false
-            side, cell = visit_stack.pop()
-            next if visitees.include?(cell)
-
-            requester << [side, cell]
-            case cell.car
-              when ConsCell
-                visit_stack.push([:car, cell.car])
-                to_swap = true
-              else
-                requester << [:car, cell.car]
-            end
-
-            case cell.cdr
-              when ConsCell
-                if to_swap
-                  visit_stack.insert(-2, [:cdr, cell.cdr])
-                else
-                  visit_stack.push([:cdr, cell.cdr])
-                end
-              else
-                requester << [:cdr, cell.cdr]
-            end
-
-            visitees << cell
-          end
-
-          # Send stop mark
-          requester << [:stop, nil]
-        end
-=end
         return visitor
       end
     end # class

data/lib/mini_kraken/composite/list.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'cons_cell'
+
+module MiniKraken
+  module Composite
+    # Module that implements convenience methods for manipulating
+    # proper lists represented with ConsCell objects.
+    module List
+      # Factory method for constructing a ConsCell pair.
+      # @param obj1 [Term]
+      # @param obj2 [Term]
+      # @return [Composite::ConsCell]
+      def self.cons(obj1, obj2 = nil)
+        ConsCell.new(obj1, obj2)
+      end
+
+      # Factory method. Build a proper list with elements of given array.
+      # @param arr [Array] Array of elements to put in a new list
+      # @return [Composite::ConsCell] Head nnode (cell) of created list.
+      def self.make_list(arr)
+        return cons(nil, nil) if arr.empty?
+
+        reversed = arr.reverse
+
+        reversed.reduce(nil) do |sub_result, elem|
+          ConsCell.new(elem, sub_result)
+        end
+      end
+    end # module
+  end # module
+end # module

data/lib/mini_kraken/core/all_core.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'context'
+require_relative 'fail'
+require_relative 'goal'
+require_relative 'log_var'
+require_relative 'log_var_ref'
+require_relative 'succeed'

data/lib/mini_kraken/core/any_value.rb

@@ -2,36 +2,60 @@
 
 module MiniKraken
   module Core
+    # When MiniKraken successfully finds a solution but cannot associate
+    # a definite value to one or more logical variable(s), then it is
+    # useful to "assign" such unbound variable a placeholder that stands
+    # for any possible value. Following the practice of the "Reasoned Scheme"
+    # book, we associate a rank number to such a placeholder in order
+    # to distinguish arbitrary values from independent variables.
     class AnyValue
+      # The rank number helps to differentiate independent variables.
+      # @return [Integer]
       attr_reader :rank
 
-      # @param aName [String]
-      # @param anEnv [Vocabulary]
-      def initialize(aName, anEnv, alternate_names = [])
-        @rank = anEnv.get_rank(aName, alternate_names)
+      # @param aRank [Integer] The rank of the variable that must reified.
+      def initialize(aRank)
+        @rank = aRank
       end
 
+      # Compare with another instance.
+      # @param other [AnyValue, Integer, Symbol]
+      # @return [Boolean]
       def ==(other)
         if other.is_a?(AnyValue)
           rank == other.rank
+        elsif other.is_a?(Integer)
+          rank == other
         elsif other.id2name =~ /_\d+/
           rank == other.id2name.sub(/_/, '').to_i
         end
       end
 
-      # Use same text representation as in Reasoned Schemer.
+      # Use same text representation as in "Reasoned Schemer" book.
+      # return [String]
       def to_s
         "_#{rank}"
       end
 
-      def ground?(_env)
+      def pinned?(_ctx)
         false
       end
 
       # @return [AnyValue]
-      def quote(_env)
+      def quote(_ctx)
         self
       end
+
+      private
+
+      def valid_rank(aRank)
+        unless aRank.kind_of?(Integer)
+          msg = "Rank number MUST be an Integer, found a #{aRank.class}"
+          raise StandardError, msg
+        end
+
+        aRank
+      end
     end # class
   end # module
 end # module

data/lib/mini_kraken/core/arity.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module MiniKraken
+  module Core
+    # The arity is the number of arguments a relations or a function can take.
+    Arity = Struct.new(:low, :high) do
+      # Is the arity constrained to a single, unique value?
+      # In other words, are the low and high bound equal?
+      # @return [Boolean] true iff both bounds have same value
+      def unique?
+        low == high
+      end
+
+      # Is the arity set to zero?
+      # @return [Boolean] true if arity is exactly zero
+      def nullary?
+        unique? && low.zero?
+      end
+
+      # Is the arity set to one?
+      # @return [Boolean] true if arity is exactly one
+      def unary?
+        unique? && low == 1
+      end
+
+      # Is the arity set to two?
+      # @return [Boolean] true if arity is exactly two
+      def binary?
+        unique? && low == 2
+      end
+
+      # Can the arity take arbitrary values?
+      # @return [Boolean] true if arity has no fixed high bound
+      def variadic?
+        high == '*'
+      end
+
+      # Does the given argument value fits within the boundary values?
+      # @param aCount [Integer]
+      # @return [Boolean]
+      def match?(aCount)
+        is_matching = aCount >= low
+        is_matching &&= aCount <= high unless variadic?
+
+        is_matching
+      end
+
+      # Equality check
+      # @param other [Arity, Array, Integer]
+      # @return [Boolean] true if 'other' has same boundary values.
+      def ==(other)
+        return true if object_id == other.object_id
+
+        result = false
+
+        case other
+          when Arity
+            result = true if (low == other.low) && (high == other.high)
+          when Array
+            result = true if (low == other.first) && (high == other.last)
+          when Integer
+            result = true if (low == other) && (high == other)
+        end
+
+        result
+      end
+    end # struct
+  end # module
+end # module

data/lib/mini_kraken/core/association.rb

@@ -2,7 +2,7 @@
 
 module MiniKraken
   module Core
-    # A record that a given vairable is associated with a value.
+    # A record that a given variable is associated with a value.
     class Association
       # @return [String] internal name of variable being associated the value.
       attr_accessor :i_name
@@ -10,13 +10,38 @@ module MiniKraken
       # @return [Term] the MiniKraken value associated with the variable
       attr_reader :value
 
-
-      # @param aVariable [Variable, String] A variable or its name.
+      # @param aVariable [Variable, String] A variable or its internal name.
       # @param aValue [Term] value being associated to the variable.
       def initialize(aVariable, aValue)
-        a_name = aVariable.respond_to?(:name) ? aVariable.i_name : aVariable
+        a_name = aVariable.respond_to?(:i_name) ? aVariable.i_name : aVariable
         @i_name = validated_name(a_name)
         @value = aValue
+        @dependencies = nil
+      end
+
+      # Is the associated value floating, that is, it does contain
+      # a variable that is either unbound or floating?
+      # @param ctx [Core::Context]
+      # @return [Boolean]
+      def floating?(ctx)
+        value.floating?(ctx)
+      end
+
+      # Is the associated value pinned, that is, doesn't contain
+      # an unbound or floating variable?
+      # @param ctx [Core::Context]
+      # @return [Boolean]
+      def pinned?(ctx)
+        @pinned ||= value.pinned?(ctx)
+        @pinned
+      end
+
+      # @return [Array<String>] The i_names of direct dependent variables
+      def dependencies(ctx)
+        @dependencies ||= value.dependencies(ctx)
+        raise StandardError unless @dependencies.kind_of?(Set) || @dependencies.kind_of?(NilClass)
+
+        @dependencies
       end
 
       private

data/lib/mini_kraken/core/association_copy.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'association'
+
+module MiniKraken
+  module Core
+    # A specialized association that bind a variable to a value from another
+    # association.
+    class AssociationCopy < Association
+      # @return [String] internal name of variable being associated the value.
+      attr_accessor :i_name
+
+      # @return [Association] the association from which the value is shared.
+      attr_reader :source
+
+      # @param aVariable [Variable, String] A variable or its internal name.
+      # @param anAssoc [Association] an association that shares its value.
+      def initialize(aVariable, anAssoc)
+        super(aVariable, nil)
+        @source = anAssoc
+      end
+
+      # Is the associated value floating, that is, it does contain
+      # a variable that is either unbound or floating?
+      # @param ctx [Core::Context]
+      # @return [Boolean]
+      def floating?(ctx)
+        source.floating?(ctx)
+      end
+
+      # Is the associated value pinned, that is, doesn't contain
+      # an unbound or floating variable?
+      # @param ctx [Core::Context]
+      # @return [Boolean]
+      def pinned?(ctx)
+        source.pinned?(ctx)
+      end
+
+      # @return [Term] the MiniKraken value associated with the variable
+      def value
+        source.value
+      end
+
+      # @return [Array<String>] The i_names of direct dependent variables
+      def dependencies(ctx)
+         source.dependencies(ctx)
+      end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/core/base_term.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MiniKraken
+  # The namespace for the classes that central in the implementation of MiniKraken.
+  # By 'central', one means that there a dependency between the remaining classes
+  # and the classes in this module.
+  module Core
+    # Abstract class that is a generalization for goal actual arguments or
+    # for arguments of goal template.
+    class BaseTerm
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/core/blackboard.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require_relative 'association_copy'
+require_relative 'bookmark'
+require_relative 'fusion'
+
+module MiniKraken
+  module Core
+    # A data structure that keeps the progress of a MiniKraken search.
+    class Blackboard
+      # This Hash answers to the question: given an i_name, what are
+      # its related moves (associations, fusions) ?
+      # @return [Hash{String=>Array<Integer>}] LIFO queue
+      attr_reader :i_name2moves
+
+      # A mapping from fused variable's i_name to a combining variable i_name
+      # @return [Hash{String => String}]
+      attr_reader :vars2cv
+
+      # A stack of indices of bookmarks. The indices corresponds to
+      # the positions of the bookmarks on the move_queue.
+      # The events that involve bookmarks are:
+      # - enter_scope       (when executing fresh expression)
+      # - leave_scope       (when all solutions for given scope found)
+      # - add_bk_point      (when a backtrack point must be added)
+      # - remove_bk_point   (when a backtrack point must be retracted)
+      # - next_alternative  (when a new solution is searched)
+      # - fail!             (when the current solution fails)
+      # @return [Array<Integer>]
+      attr_reader :bookmarks
+
+      # Serial numbers are assigned sequentially to bookmark objects.
+      # This attribute holds the next available serial number.
+      # @return [Integer] Next serial number to assign
+      attr_reader :next_serial_num
+
+      # A queue of entries that embodies the progress towards a solution.
+      # @return [Array<Association, Bookmark, Fusion>]
+      attr_reader :move_queue
+
+      # @return [Symbol] One of: :"#s" (success), :"#u" (failure)
+      attr_reader :resultant
+
+      # Constructor.
+      def initialize
+        @i_name2moves = {}
+        @vars2cv = {}
+        # @bookmarks = []
+        @next_serial_num = 0
+        @move_queue = []
+      end
+
+      # Returns iff there is no entry in the association queue
+      # @return [Boolean]
+      def empty?
+        move_queue.empty?
+      end
+
+      # Does the latest result represent a failure?
+      # @return [Boolean] true if failure, false otherwise
+      def failure?
+        resultant != :"#s"
+      end
+
+      # Does the latest result represent a success?
+      # @return [Boolean] true if success, false otherwise
+      def success?
+        resultant == :"#s"
+      end
+
+      # Return the most recent move.
+      # @return [Association, Bookmark, Fusion]
+      def last_move
+        move_queue.last
+      end
+
+      # Indicate whether the variable is fused with another one
+      # @param iName [String] Internal name of a logical variable
+      # @return [Boolean]
+      def fused?(iName)
+        vars2cv.include? iName
+      end
+
+      # If the variable is fused, then return the internal name of the
+      # combining variable, otherwise return the input value as is.
+      # @param iName [String] Internal name of a logical variable
+      # @return [String] Internal name of variable or combining variable.
+      def relevant_i_name(iName)
+        fused?(iName) ? vars2cv[iName] : iName
+      end
+
+      # Retrieve the associations for the given internal name.
+      # If requested, add the association(s) shared through the fusion
+      # with another variable.
+      # @param iName [String] Internal name of variable
+      # @param shared [Boolean]
+      # @return [Array<Association>]
+      def associations_for(iName, shared = false)
+        assocs_idx = nil
+        if shared && fused?(iName)
+          assocs_idx = i_name2moves[vars2cv[iName]]
+          if assocs_idx && move_queue[assocs_idx.first].kind_of?(Fusion)
+              assocs_idx = assocs_idx.dup
+              assocs_idx.shift
+          end
+        else
+          indices = i_name2moves[iName]
+          assocs_idx = indices.dup if indices
+        end
+
+        if assocs_idx
+          assocs_idx.map { |i| move_queue[i] }
+        else
+          []
+        end
+      end
+
+      # Push the given association onto the move queue
+      # @param anAssociation [Association]
+      # @return [Association]
+      def enqueue_association(anAssociation)
+        unless anAssociation.kind_of?(Association)
+          raise StandardError, "Unsupported item class #{anAssociation.class}"
+        end
+
+        enqueue_move(anAssociation)
+        anAssociation
+      end
+
+      # Push the given fusion object onto the move queue
+      # @param aFusion [Fusion]
+      # @return [Fusion]
+      def enqueue_fusion(aFusion)
+        aFusion.elements.each do |fused_i_nm|
+          vars2cv[fused_i_nm] = aFusion.i_name
+        end
+        enqueue_move(aFusion)
+
+        # If there is any existing association for the fused variables...
+        # Add them to the associations of the combining variables
+        bound = aFusion.elements.select { |i_nm| i_name2moves.include? i_nm }
+        unless bound.empty?
+          bound.each do |i_nm|
+            to_copy = i_name2moves[i_nm]
+            to_copy.each do |i|
+              as = move_queue[i]
+              new_as = AssociationCopy.new(aFusion.i_name, as)
+              enqueue_association(new_as)
+            end
+          end
+        end
+
+        aFusion
+      end
+
+      # Notification of failure of last executed goal.
+      # All moves up to most recent backtrack point are dropped.
+      def failed!
+        @resultant = :"#u"
+
+        # Remove all items until most recent backtrack point.
+        until move_queue.empty? ||
+              (last_move.kind_of?(Bookmark) && last_move.kind == :bt_point)
+          dequeue_item
+        end
+      end
+
+      # Notify success of last executed goal
+      def succeeded!
+        @resultant = :"#s"
+      end
+
+      # Place a backtrack point as a bookmark on move queue.
+      # @return [Integer] serial number of created bookmark
+      def place_bt_point
+        add_bookmark(:bt_point)
+      end
+
+      # Remove all items until most recent backtrack bookmark found.
+      # The boobmark is not remove from the queue
+      # @return [Array<Association, Bookmark, Fusion>]
+      def next_alternative
+        removed = []
+
+        # Remove all items until most recent scope bookmark.
+        until move_queue.empty? ||
+              (last_move.kind_of?(Bookmark) && last_move.kind == :bt_point)
+         removed << dequeue_item
+        end
+
+        removed
+      end
+
+      # Remove all items until most recent backtrack bookmark found.
+      # @return [Array<Association, Bookmark, Fusion>]
+      def retract_bt_point
+        removed = next_alternative
+        dequeue_item unless move_queue.empty? # Remove the bookmark (if any)
+
+        removed
+      end
+
+      # React to event 'enter_scope' by putting a scope bookmark on move queue.
+      # @return [Integer] serial number of created bookmark
+      def enter_scope
+        add_bookmark(:scope)
+      end
+
+      # Remove all items until most recent scope bookmark found.
+      # @return [Array<Association, Bookmark, Fusion>]
+      def leave_scope
+        removed = []
+
+        # Remove all items until most recent scope bookmark.
+        until move_queue.empty? ||
+              (last_move.kind_of?(Bookmark) && last_move.kind == :scope)
+         removed << dequeue_item
+        end
+        dequeue_item unless move_queue.empty? # Remove the bookmark (if any)
+
+        removed
+      end
+
+      private
+
+      # Push given move onto the queue and update the lookups.
+      # @param [aMove [Association, Fusion]
+      def enqueue_move(aMove)
+        last_index = move_queue.size
+        move_queue.push(aMove)
+        iname = aMove.i_name
+        if i_name2moves.include?(iname)
+          i_name2moves[iname] << last_index
+        else
+          i_name2moves[iname] = [last_index]
+        end
+
+        aMove
+      end
+
+      # Remove the last item inserted in the queue
+      # @return [Association, Bookmark, Fusion] Last item removed from LIFO queue
+      def dequeue_item
+        result = nil
+
+        # require 'debug'
+        return result unless last_move
+
+        result = case last_move
+          when Association
+            dequeue_move
+          when Bookmark
+            remove_bookmark
+          when Fusion
+            remove_fusion
+        end
+
+        return result
+      end
+
+      # Low-level bookmark addition method.
+      # @param aKind [Symbol] One of: :scope, :bt_point
+      # @return [Integer] Serial number of new bookmark
+      def add_bookmark(aKind)
+        move_queue.size
+        serial_number = next_serial_num
+        @move_queue << Bookmark.new(aKind, serial_number)
+        @next_serial_num += 1
+
+        serial_number
+      end
+
+      # Low-level association removal method.
+      # Pre-condition: association to remove is on top of stack
+      def dequeue_move
+        unless last_move.kind_of?(Association) || last_move.kind_of?(Fusion)
+          raise StandardError, 'Expected Assocation or Fusion on top of stack.'
+        end
+
+        i_name = last_move.i_name
+        assocs_idx = i_name2moves[i_name]
+
+        idx_last = assocs_idx.pop
+        unless idx_last == (move_queue.size - 1)
+          raise StandardError, 'Internal error'
+        end
+
+        i_name2moves.delete(i_name) if assocs_idx.empty?
+        move_queue.pop
+      end
+
+      # Low-level bookmark removal method.
+      # Pre-condition: bookmark to remove is on top of stack
+      def remove_bookmark
+        unless move_queue.last.kind_of?(Bookmark)
+          raise StandardError, 'Expected a bookmark on top of stack.'
+        end
+
+        move_queue.pop
+      end
+
+      # Low-level fusion removal method.
+      # Pre-condition: fusion to remove is on top of stack
+      def remove_fusion
+        unless  last_move.kind_of?(Fusion)
+          raise StandardError, 'Fusion on top of stack.'
+        end
+
+        last_move.elements.each { |e| vars2cv.delete(e) }
+
+        dequeue_move
+      end
+    end # class
+  end # module
+end # module