porolog 0.0.4 → 1.0.0

data/lib/porolog/arguments.rb

@@ -11,14 +11,16 @@ module Porolog
   # A predicate is not like a subroutine, although there are many similarities.
   # An Arguments represents an instance of a predicate with a specific set of arguments.
   # This forms the basis for implementing a goal to solve the predicate with those specific arguments.
+  #
   # @author Luis Esteban
+  #
   # @!attribute [r] predicate
   #   The Predicate for which these are the arguments.
   # @!attribute [r] arguments
   #   The actual arguments.
   class Arguments
     
-    attr_reader :predicate, :arguments
+    attr_reader :predicate, :arguments, :block
     
     # Unregisters all Arguments
     # @return [true]
@@ -32,9 +34,10 @@ module Porolog
     # Creates a new Arguments for a Predicate
     # @param predicate [Porolog::Predicate] the Predicate for which these are the arguments
     # @param arguments [Array<Object>] the actual arguments
-    def initialize(predicate, arguments)
+    def initialize(predicate, arguments, &block)
       @predicate = predicate
       @arguments = arguments
+      @block     = block
       @@arguments << self
     end
     
@@ -52,7 +55,8 @@ module Porolog
     
     # @return [String] pretty representation
     def inspect
-      "#{@predicate.name}(#{@arguments && @arguments.map(&:inspect).join(',')})"
+      block_inspect = block.nil? ? '' : "{#{block.inspect}}"
+      "#{@predicate&.name}(#{@arguments&.map(&:inspect).join(',')})#{block_inspect}"
     end
     
     # Creates a fact rule that states that these arguments satisfy the Predicate.
@@ -101,9 +105,7 @@ module Porolog
     
     # @return [Array<Symbol>] the variables contained in the arguments
     def variables
-      @arguments.map{|argument|
-        argument.variables
-      }.flatten.uniq
+      @arguments.map(&:variables).flatten.uniq
     end
     
     # Creates a Goal for solving this Arguments for the Predicate
@@ -114,22 +116,23 @@ module Porolog
     end
     
     # Returns memoized solutions
-    # @param number [Integer] the maximum number of solutions to find (nil means find all)
-    # @return [Array<Hash>] the solutions found (memoized)
-    def solutions(number = nil)
-      @solutions ||= solve(number)
-      @solutions
+    # @param max_solutions [Integer] the maximum number of solutions to find (nil means find all)
+    # @return [Array<Hash{Symbol => Object}>] the solutions found (memoized)
+    def solutions(max_solutions = nil)
+      @solutions ||= solve(max_solutions)
+      max_solutions && @solutions[0...max_solutions] || @solutions
     end
     
     # Solves the Arguments
-    # @param number_of_solutions [Integer] the maximum number of solutions to find (nil means find all)
-    # @return [Array<Hash>] the solutions found
-    def solve(number_of_solutions = nil)
-      @solutions = goal.solve(number_of_solutions)
+    # @param max_solutions [Integer] the maximum number of solutions to find (nil means find all)
+    # @return [Array<Hash{Symbol => Object}>] the solutions found
+    def solve(max_solutions = nil)
+      @solutions = goal.solve(max_solutions)
     end
     
     # Extracts solution values.
     # @param variables [Symbol, Array<Symbol>] variable or variables
+    # @param max_solutions [Integer] the maximum number of solutions to find (nil means find all)
     # @return [Array<Object>] all the values for the variables given
     # @example
     #   predicate :treasure_at
@@ -138,27 +141,28 @@ module Porolog
     #   xs = arguments.solve_for(:X)
     #   ys = arguments.solve_for(:Y)
     #   coords = xs.zip(ys)
-    def solve_for(*variables)
+    def solve_for(*variables, max_solutions: nil)
       variables = [*variables]
-      solutions.map{|solution|
-        variables.map{|variable| solution[variable] }
+      solutions(max_solutions).map{|solution|
+        values = variables.map{|variable| solution[variable] }
+        if values.size == 1
+          values.first
+        else
+          values
+        end
       }
     end
     
     # @return [Boolean] whether any solutions were found
     def valid?
-      !solutions.empty?
+      !solutions(1).empty?
     end
     
     # Duplicates the Arguments in the context of the given goal
     # @param goal [Porolog::Goal] the destination goal
     # @return [Porolog::Arguments] the duplicated Arguments
     def dup(goal)
-      arguments_dup = arguments.dup
-      (0...arguments_dup.size).each do |i|
-        arguments_dup[i] = arguments_dup[i].dup(goal) if arguments_dup[i].is_a?(HeadTail)
-      end
-      self.class.new @predicate, arguments_dup
+      self.class.new @predicate, goal.variablise(arguments), &@block
     end
     
     # @param other [Porolog::Arguments] arguments for comparison

data/lib/porolog/core_ext.rb

@@ -0,0 +1,188 @@
+#
+#   lib/porolog/core_ext.rb      - Plain Old Ruby Objects Prolog Engine -- Core Extensions
+#
+#     Luis Esteban   2 May 2018
+#       created
+#
+# @author Luis Esteban
+# Extends Core Ruy Classes
+#
+
+# In Porolog, Objects represent atomic values.
+class Object
+  
+  # A convenience method for testing/debugging.
+  # @return [String] the equivalent of inspect.
+  def myid
+    inspect
+  end
+  
+  # @return [Array] embedded variables (for an Object, should be none).
+  def variables
+    []
+  end
+  
+  # @return [Symbol] the type of the object (for an Object, should be :atomic)
+  def type
+    :atomic
+  end
+  
+  # @return [Object] the value of the object, which is itself.
+  def value(*)
+    self
+  end
+  
+  # @param other [Object] the Object which is to be the tail
+  # @return [Array] an Array with the Object being the head and the other Object being the tail.
+  # @example
+  #   'head' / ['body', 'foot']   # ==> ['head', 'body', 'foot']
+  #   7.tail(:t)                  # ==> [7, *:t]
+  def tail(other)
+    [self]/other
+  end
+  
+  # Syntactic sugar to look like Prolog's [H|T]
+  alias / :tail
+  
+  # @return [Boolean] whether the Object is an Array with a head and a tail (for an Object, should be false).
+  def headtail?
+    false
+  end
+  
+end
+
+
+# In Porolog, Symbols represent Variables.
+class Symbol
+  
+  # A convenience method for testing/debugging.
+  # @return [String] the equivalent of inspect.
+  def myid
+    inspect
+  end
+  
+  # @return [Array] embedded variables (for a Symbol, should be itself).
+  def variables
+    [self]
+  end
+  
+  # @return [Symbol] the type of the object (for a Symbol, should be :variable)
+  def type
+    :variable
+  end
+  
+  # @param other [Object] the Object which is to be the tail
+  # @return [Array] an Array with the Object being the head and the other Object being the tail.
+  def /(other)
+    [self]/other
+  end
+  
+end
+
+
+# In Porolog, Arrays are the equivalent of lists.
+class Array
+  
+  # @return [Array] embedded variables.
+  def variables
+    map(&:variables).flatten
+  end
+  
+  # @return [Array] the values of its elements.
+  def value(visited = [])
+    return self if visited.include?(self)
+    visited = visited + [self]
+    flat_map{|element|
+      if element.is_a?(Tail)
+        tail = element.value(visited)
+        if tail.is_a?(Array)
+          tail
+        elsif tail.is_a?(Variable) || tail.is_a?(Value)
+          tail = tail.value(visited)
+          if tail.is_a?(Array)
+            tail
+          elsif tail.is_a?(Variable) || tail.is_a?(Value)
+            tail = tail.goal.variablise(tail.value(visited))
+            if tail.is_a?(Array)
+              tail
+            else
+              [element]
+            end
+          else
+            [element]
+          end
+        else
+          [element]
+        end
+      else
+        [element.value(visited)]
+      end
+    }
+  end
+  
+  # Removes Porolog processing objects.
+  # @return [Array] the values of its elements with variables replaced by nil and Tails replaced by UNKNOWN_TAIL.
+  def clean
+    value.map{|element|
+      if element.is_a?(Array)
+        element.clean
+      elsif element.is_a?(Tail)
+        UNKNOWN_TAIL
+      elsif element.is_a?(Variable)
+        nil
+      else
+        element.value
+      end
+    }
+  end
+  
+  # @return [Symbol] the type of the object (for an Array, should be :array)
+  def type
+    :array
+  end
+  
+  # @param other [Object] the Object which is to be the tail
+  # @return [Array] an Array with the Object being the head and the other Object being the tail.
+  def /(other)
+    if other.is_a?(Porolog::Variable) || other.is_a?(Symbol)
+      self + [Tail.new(other)]
+    else
+      self + [*other]
+    end
+  end
+  
+  # @param head_size [Integer] specifies the size of the head
+  # @return [Object] the head of the Array
+  def head(head_size = 1)
+    if head_size == 1
+      if first == Porolog::UNKNOWN_TAIL
+        nil
+      else
+        first
+      end
+    else
+      self[0...head_size]
+    end
+  end
+  
+  # @param head_size [Integer] specifies the size of the head
+  # @return [Object] the tail of the Array
+  def tail(head_size = 1)
+    if last == Porolog::UNKNOWN_TAIL
+      [*self[head_size..-2], Porolog::UNKNOWN_TAIL]
+    else
+      [*self[head_size..-1]]
+    end
+  end
+  
+  # @return [Boolean] whether the Object is an Array with a head and a tail.
+  def headtail?
+    length == 2 && (last.is_a?(Tail) || last == UNKNOWN_TAIL)
+  end
+  
+  # @return [Porolog::Goal] the goal that is most likely to be the goal for this array.
+  def goal
+    map{|element| element.goal if element.respond_to?(:goal) }.flatten.find{|goal| goal.is_a?(Porolog::Goal) }
+  end
+  
+end

data/lib/porolog/error.rb

@@ -8,6 +8,15 @@
 module Porolog
 
   # Error class to enable rescuing or detecting any Porolog error.
+  #
+  # @author Luis Esteban
+  #
   class PorologError < RuntimeError ; end
+  
+  # Error indicating that a Goal is needed but could not be found.
+  class NoGoalError  < PorologError ; end
+  
+  # Error indicating that a Variable is needed but was not provided.
+  class NonVariableError  < PorologError ; end
 
 end

data/lib/porolog/goal.rb

@@ -0,0 +1,357 @@
+#
+#   lib/porolog/goal.rb      - Plain Old Ruby Objects Prolog Engine -- Goal
+#
+#     Luis Esteban   2 May 2018
+#       created
+#
+
+module Porolog
+  
+  # A Porolog::Goal finds solutions for specific Arguments of a Predicate.
+  #
+  # @author Luis Esteban
+  #
+  # @!attribute calling_goal
+  #   @return [Porolog::Goal, nil] The parent goal if this goal is a subgoal, otherwise nil.
+  # @!attribute arguments
+  #   @return [Porolog::Arguments] The specific Arguments this goal is trying to solve.
+  # @!attribute index
+  #   @return [Integer, nil] Solution index for builtin predicates.
+  # @!attribute result
+  #   @return [Boolean] Whether any result has been found.
+  # @!attribute description
+  #   @return [String] Description of the Arguments the Goal is attempting to solve.
+  # @!attribute log
+  #   @return [Array<String>] Log of events, namely unification failures.
+  #
+  class Goal
+    
+    # Error class for rescuing or detecting any Goal error.
+    class Error             < PorologError ; end
+    # Error class indicating an unexpected type of Rule definition.
+    class DefinitionError   < Error        ; end
+    # Error class indicating a non-Variable was attempted to be instantiated.
+    class NotVariableError  < Error        ; end
+    
+    # Clears all goals and ensures they are deleted.
+    # @return [Boolean] success
+    def self.reset
+      @@goals ||= []
+      goals = @@goals
+      @@goals = []
+      @@goal_count = 0
+      goals.map(&:deleted?)
+      true
+    end
+    
+    # @return [Integer] the number of goals created
+    def self.goal_count
+      @@goal_count
+    end
+    
+    reset
+    
+    attr_accessor :calling_goal, :arguments, :index, :result, :description, :log
+    
+    # Initializes and registers the Goal.
+    # @param arguments [Porolog::Arguments] the Predicate Arguments that this Goal is to solve.
+    # @param calling_goal [Porolog::Goal] the parent Goal if this Goal is a subgoal.
+    def initialize(arguments, calling_goal = nil)
+      @@goals << self
+      @@goal_count += 1
+      
+      @arguments    = arguments
+      @terminate    = false
+      @calling_goal = calling_goal
+      @variables    = {}
+      @values       = {}
+      @result       = nil
+      @description  = "Solve #{arguments.inspect}"
+      @log          = []
+      
+      @arguments = @arguments.dup(self) if @arguments.is_a?(Arguments)
+      @solutions = []
+    end
+    
+    # @return [Array<Porolog::Goal>] the calling chain for this goal.
+    def ancestors
+      ancestors = []
+      goal      = self
+      
+      while goal
+        ancestors << goal
+        goal = goal.calling_goal
+      end
+      
+      ancestors.reverse
+    end
+    
+    # A convenience method for testing/debugging.
+    # @return [String] the calling chain for this goal as a String.
+    def ancestry
+      indent = -1
+      ancestors.map do |goal|
+        indent += 1
+        "#{'  ' * indent}#{goal.myid} -- #{goal.description}  #{goal.variables.inspect}"
+      end.join("\n")
+    end
+    
+    # A convenience method for testing/debugging.
+    # @return [String] the id of the goal.
+    def myid
+      "Goal#{(@@goals.index(self) || -1000) + 1}"
+    end
+    
+    # @return [String] pretty representation.
+    def inspect
+      "#{myid} -- #{description}"
+    end
+    
+    # A convenience method for testing/debugging.
+    # @return [Array<Porolog::Goal>]
+    def self.goals
+      @@goals
+    end
+    
+    # Delete the Goal
+    # @return [Boolean] whether the Goal has been deleted (memoized)
+    def delete!
+      @@goals.delete(self)
+      deleted?
+    end
+    
+    # @return [Boolean] whether the Goal has been deleted (memoized)
+    def deleted?
+      @deleted ||= check_deleted
+      @deleted
+    end
+    
+    # Determines whether the Goal has been deleted and removes its Variables and Values if it has.
+    # @return [Boolean] whether the Goal has been deleted
+    def check_deleted
+      return false if @@goals.include?(self)
+      
+      @variables.delete_if do |_name,variable|
+        variable.remove
+        true
+      end
+      
+      @values.delete_if do |_name,value|
+        value.remove
+        true
+      end
+      
+      true
+    end
+    
+    # Sets that the goal should no longer search any further rules for the current predicate
+    # once the current rule has finished being evaluated.
+    # This method implements the :CUT rule.
+    # That is, backtracking does not go back past the point of the cut.
+    # @return [Boolean] true.
+    def terminate!
+      @log << 'terminating'
+      @terminate = true
+    end
+    
+    # @return [Boolean] whether the goal has been cut.
+    def terminated?
+      @terminate
+    end
+    
+    # Converts all embedded Symbols to Variables within this Goal.
+    # @param object [Object] the object to variablise.
+    # @return [Object] the variablised object.
+    def variablise(object)
+      case object
+        when Symbol,Variable
+          variable(object)
+        when Array
+          object.map{|element| variablise(element) }
+        when Arguments
+          object.dup(self)
+        when Tail
+          Tail.new variablise(object.value)
+        when Value
+          object
+        when NilClass
+          nil
+        else
+          if [UNKNOWN_TAIL, UNKNOWN_ARRAY].include?(object)
+            object
+          else
+            value(object)
+          end
+      end
+    end
+    
+    alias [] variablise
+    
+    # @return [Hash{Symbol => Object}] the Variables and their current values of this Goal
+    def variables
+      @variables.keys.each_with_object({}){|variable,variable_list|
+        value = value_of(variable).value.value
+        if value.is_a?(Variable)
+          variable_list[variable] = nil
+        elsif value.is_a?(Array)
+          variable_list[variable] = value.clean
+        else
+          variable_list[variable] = value
+        end
+      }
+    end
+    
+    # A convenience method for testing/debugging.
+    # @return [String] a tree representation of all the instantiations of this goal's variables.
+    def inspect_variables
+      @variables.values.map(&:inspect_with_instantiations).join("\n")
+    end
+    
+    # A convenience method for testing/debugging.
+    # @return [Array<Object>] the values instantiated for this goal.
+    def values
+      @values.values.map(&:value)
+    end
+    
+    # Finds or tries to create a variable in the goal (as much as possible) otherwise passes the parameter back.
+    # @param name [Object] name of variable or variable
+    # @return [Porolog::Variable, Object] a variable of the goal or the original parameter
+    def variable(name)
+      return name unless name.is_a?(Symbol) || name.is_a?(Variable)
+      
+      if name.is_a?(Variable)
+        variable = name
+        @variables[variable.name] = variable if variable.goal == self
+        return variable
+      end
+      
+      @variables[name] ||= (name.is_a?(Variable) && name || Variable.new(name, self))
+      @variables[name]
+    end
+    
+    # @param value [Object] the value that needs to be associated with this Goal.
+    # @return [Porolog::Value] a Value, ensuring it has been associated with this Goal so that it can be uninstantiated.
+    def value(value)
+      @values[value] ||= Value.new(value, self)
+      @values[value]
+    end
+    
+    # Returns the value of the indicated variable or value
+    # @param name [Symbol, Object] name of the variable or value
+    # @param index [Object] index is not yet used
+    # @param visited [Array] used to avoid infinite recursion
+    # @return [Object] the value
+    def value_of(name, index = nil, visited = [])
+      variable(name).value(visited)
+    end
+    
+    # Returns the values of an Object.  For most objects, this will basically just be the object.
+    # For Arrays, an Array will be returned where the elements are the value of the elements.
+    # @param object [Object] the Object to find the values of.
+    # @return [Object,Array<Object>] the value(s) of the object.
+    def values_of(object)
+      case object
+        when Array
+          object.map{|element| values_of(element) }
+        when Variable,Symbol,Value
+          value_of(object)
+        when Tail
+          # TODO: This needs to splat outwards; in the meantime, it splats just the first.
+          value_of(object.value).first
+        else
+          object
+      end
+    end
+    
+    # Finds all possible solutions to the Predicate for the specific Arguments.
+    # @param max_solutions [Integer] if provided, the search is stopped once the number of solutions has been found
+    # @return [Array<Hash{Symbol => Object}>]
+    def solve(max_solutions = nil)
+      return @solutions unless @arguments
+      
+      predicate = @arguments.predicate
+      
+      predicate&.satisfy(self) do |goal|
+        # TODO: Refactor to overrideable method (or another solution, say a lambda)
+        
+        @solutions << variables
+        @log << "SOLUTION: #{variables}"
+        @log << goal.ancestry
+        @log << goal.inspect_variables
+        
+        return @solutions if max_solutions && @solutions.size >= max_solutions
+      end
+      
+      @solutions
+    end
+    
+    # Solves the goal but not as the root goal for a query.
+    # That is, solves an intermediate goal.
+    # @param block [Proc] code to perform when the Goal is satisfied.
+    # @return [Boolean] whether the definition was satisfied.
+    def satisfy(&block)
+      return false unless @arguments
+      
+      predicate = @arguments.predicate
+      
+      satisfied = false
+      predicate&.satisfy(self) do |subgoal|
+        subgoal_satisfied = block.call(subgoal)
+        satisfied ||= subgoal_satisfied
+      end
+      satisfied
+    end
+    
+    # Instantiates a Variable to another Variable or Value, for this Goal.
+    # @param name [Symbol,Porolog::Variable,Object] the name that references the variable to be instantiated.
+    # @param other [Object] the value that the variable is to be instantiated to.
+    # @param other_goal [Porolog::Goal,nil] the Goal of the other value.
+    # @return [Porolog::Instantiation] the instantiation.
+    def instantiate(name, other, other_goal = self)
+      variable = self.variable(name)
+      
+      other = if other.type == :variable
+        other_goal.variable(other)
+      else
+        other_goal.value(other)
+      end
+      
+      variable.instantiate(other)
+    end
+    
+    # Inherits variables and their instantiations from another goal.
+    # @param other_goal [Porolog::Goal,nil] the Goal to inherit variables from.
+    # @return [Boolean] whether the variables could be inherited (unified).
+    def inherit_variables(other_goal = @calling_goal)
+      return true unless other_goal
+      
+      unified      = true
+      unifications = []
+      variables    = (
+        other_goal.arguments.variables +
+        other_goal.variables.keys +
+        self.arguments.variables
+      ).map(&:to_sym).uniq
+      
+      variables.each do |variable|
+        name = variable
+        
+        unification = unify(name, name, other_goal, self)
+        unified   &&= !!unification
+        if unified
+          unifications += unification
+        else
+          #:nocov:
+          self.log << "Couldn't unify: #{name.inspect} WITH #{other_goal.myid} AND #{self.myid}"
+          break
+          #:nocov:
+        end
+      end
+      unified &&= instantiate_unifications(unifications) if unified
+      
+      unified
+    end
+    
+  end
+  
+end