porolog 0.0.7 → 0.0.8

data/lib/porolog/instantiation.rb

@@ -0,0 +1,300 @@
+#
+#   lib/porolog/instantiation.rb      - Plain Old Ruby Objects Prolog Engine -- Instantiation
+#
+#     Luis Esteban   2 May 2018
+#       created
+#
+
+module Porolog
+  
+  # A Porolog::Instantiation implements an instantiation of a Variable of a Goal.
+  # An Instantiation joins two expressions.  At least one expression must have a variable.
+  # An index may be provided to index into the value of either expression, or both may have an index.
+  # Thus, an element of each list could be instantiated without reference to the other elements:
+  #   x = [a,b,c,d,e]
+  #            |
+  #   y =   [p,q,r,s]
+  #
+  # @author Luis Esteban
+  #
+  # @!attribute variable1
+  #   @return [Variable,Object] one end of the instantiation.
+  # @!attribute variable2
+  #   @return [Variable,Object] the other end of the instantiation.
+  # @!attribute index1
+  #   @return [Object,nil] the index into the value of variable1.
+  # @!attribute index2
+  #   @return [Object,nil] the index into the value of variable2.
+  #
+  class Instantiation
+    
+    # Error class for rescuing or detecting any Instantiation error.
+    class Error               < PorologError ; end
+    # Error class indicating that an instantiation was created without any Variables.
+    class NoVariableError     < Error        ; end
+    # Error class indicating that an index could not be used although requested.
+    class UnhandledIndexError < Error        ; end
+    
+    attr_accessor :variable1, :variable2, :index1, :index2
+    
+    # Clears all instantiations.
+    # @return [Boolean] success
+    def self.reset
+      @@instantiations = {}
+      true
+    end
+    
+    reset
+    
+    # @return [Hash{Array => Porolog::Instantiation}] all Instantiations
+    def self.instantiations
+      @@instantiations
+    end
+    
+    # Finds or creates a new instantiation.  At least one of the variables must be a Variable.
+    # @param variable1 [Porolog::Variable,Porolog::Value,Object] one end of the instantiation to be made.
+    # @param variable2 [Porolog::Variable,Porolog::Value,Object] the other end of the instantiation to be made.
+    # @param index1 [Integer,Symbol,nil] index into the value of variable1.
+    # @param index2 [Integer,Symbol,nil] index into the value of variable2.
+    # @return [Porolog::Instantiation] the found or created Instantiation.
+    def self.new(variable1, index1, variable2, index2)
+      raise NoVariableError, "Cannot instantiate non-variables: #{variable1.inspect} and #{variable2.inspect}" unless variable1.is_a?(Variable) || variable2.is_a?(Variable)
+      
+      variable1 = Value.new variable1, variable2.goal unless variable1.is_a?(Variable) || variable1.is_a?(Value)
+      variable2 = Value.new variable2, variable1.goal unless variable2.is_a?(Variable) || variable2.is_a?(Value)
+      
+      instantiation = \
+        @@instantiations[[variable1, index1, variable2, index2]] ||
+        @@instantiations[[variable2, index2, variable1, index1]] ||
+        super
+      
+      instantiation
+    end
+    
+    # Initializes and registers a new Instantiation.  At least one of the variables must be a Variable.
+    # @param variable1 [Porolog::Variable,Porolog::Value,Object] one end of the instantiation to be made.
+    # @param variable2 [Porolog::Variable,Porolog::Value,Object] the other end of the instantiation to be made.
+    # @param index1 [Integer,Symbol,nil] index into the value of variable1.
+    # @param index2 [Integer,Symbol,nil] index into the value of variable2.
+    # @return [Porolog::Instantiation] the found or created Instantiation.
+    def initialize(variable1, index1, variable2, index2)
+      @variable1 = variable1
+      @variable2 = variable2
+      @index1    = index1
+      @index2    = index2
+      
+      @variable1.instantiations << self
+      @variable2.instantiations << self
+      
+      @@instantiations[signature] = self
+    end
+    
+    # @return [Array] the signature of the Instantiation, which aids in avoiding duplication instantiations.
+    def signature
+      @signature ||= [@variable1, @index1, @variable2, @index2].freeze
+      @signature
+    end
+    
+    # @return [String] pretty representation.
+    def inspect(indent = 0)
+      index1 = @index1 ? "[#{@index1.inspect}]" : ''
+      index2 = @index2 ? "[#{@index2.inspect}]" : ''
+      
+      "#{'  ' * indent}#{@variable1.inspect}#{index1} = #{@variable2.inspect}#{index2}"
+    end
+    
+    # Removes itself from its variables' Instantiations and unregisters itself.
+    # @return [Boolean] success
+    def remove
+      @variable1.instantiations.delete(self)  if @variable1.is_a?(Variable) || @variable1.is_a?(Value)
+      @variable2.instantiations.delete(self)  if @variable2.is_a?(Variable) || @variable2.is_a?(Value)
+      
+      @deleted = true
+      @@instantiations.delete(signature)
+      @deleted
+    end
+    
+    # Returns the Goal of the other Variable to the one provided.
+    # @param variable [Porolog::Variable] the provided Variable.
+    # @return [Porolog::Goal,nil] the Goal of the other Variable.
+    def other_goal_to(variable)
+      return nil unless variables.include?(variable)
+      
+      other_variable = (variables - [variable]).first
+      other_variable && other_variable.goal
+    end
+    
+    # @return [Array<Porolog::Goal>] the Goals of the Variables of the Instantiation.
+    def goals
+      [@variable1.goal,@variable2.goal]
+    end
+    
+    # @return [Array<Porolog::Variable,Object>] the Variables of the Instantiation.
+    def variables
+      [@variable1,@variable2]
+    end
+    
+    # @param visited [Array] prevents infinite recursion.
+    # @return [Array] the values of the Variables of the Instantiation.
+    def values(visited = [])
+      return [] if visited.include?(self)
+      
+      vv1 = values_for(@variable1, visited)
+      vv2 = values_for(@variable2, visited)
+      
+      (vv1 + vv2).uniq
+    end
+    
+    # @param value [Object] the provided value.
+    # @param index [Integer,Symbol,Array<Integer>] the index.
+    # @param visited [Array] prevents infinite recursion.
+    # @return [Object] the indexed value of the provided value.
+    def value_indexed(value, index, visited = [])
+      return nil unless value
+      return nil if value.type == :variable
+      return nil if value == [] && index == :tail
+      
+      visit = [value, index]
+      return nil if visited.include?(visit)
+      visited = visited + [visit]
+      
+      case index
+        when Integer
+          if value.respond_to?(:last) && value.last == UNKNOWN_TAIL
+            if index >= value.length - 1
+              UNKNOWN_TAIL
+            else
+              value[index]
+            end
+          elsif value.is_a?(Numeric)
+            value
+          else
+            value[index]
+          end
+        
+        when Symbol
+          value_value = value.value(visited)
+          if value_value.respond_to?(index)
+            value_value.send(index)
+          else
+            value
+          end
+        
+        when Array
+          if index.empty?
+            value[1..-1]
+          else
+            value[0...index.first]
+          end
+        
+        else
+          if index
+            raise UnhandledIndexError, "Unhandled index: #{index.inspect} of #{value.inspect}"
+          else
+            value
+          end
+      end
+    end
+    
+    # @param variable [Porolog::Variable,Porolog::Value] the specified variable (or end of the Instantiation).
+    # @param visited [Array] prevents infinite recursion.
+    # @return [Array<Object>] the values for the specified variable by finding the values of the other variable (i.e. the other end) and applying any indexes.
+    def values_for(variable, visited = [])
+      return [] if visited.include?(self)
+      visited = visited + [self]
+      
+      if variable == @variable1
+        if @index1
+          [value_at_index(value_indexed(@variable2.value(visited), @index2, visited), @index1)]
+        else
+          if @variable2.is_a?(Variable)
+            [value_indexed(@variable2.value(visited), @index2, visited)]
+          else
+            [value_indexed(@variable2, @index2, visited)]
+          end
+        end
+      elsif variable == @variable2
+        if @index2
+          [value_at_index(value_indexed(@variable1.value(visited), @index1, visited), @index2)]
+        else
+          if @variable1.is_a?(Variable)
+            [value_indexed(@variable1.value(visited), @index1, visited)]
+          else
+            [value_indexed(@variable1, @index1, visited)]
+          end
+        end
+      else
+        []
+      end.compact
+    end
+    
+    # @param value [Object] the known value.
+    # @param index [Integer,Symbol,Array] the known index.
+    # @return [Array] an Array where the known value is at the known index.
+    def value_at_index(value, index)
+      value && case index
+        when Integer
+          result        = []
+          result[index] = value
+          result       << UNKNOWN_TAIL
+          result
+        
+        when Symbol
+          case index
+            when :head
+              [value, UNKNOWN_TAIL]
+            when :tail
+              [nil, *value]
+            else
+              raise UnhandledIndexError, "Unhandled index: #{index.inspect} for #{value.inspect}"
+          end
+        
+        when Array
+          if index.empty?
+            [nil, *value]
+          else
+            #result                 = []
+            #result[0..index.first] = value
+            #result
+            #[*([*value][0..index.first]), UNKNOWN_TAIL]
+            [value, UNKNOWN_TAIL]
+          end
+        
+        else
+          if index
+            raise UnhandledIndexError, "Unhandled index: #{index.inspect} for #{value.inspect}"
+          else
+            value
+          end
+      end
+    end
+    
+    # @param variable [Porolog::Variable,Porolog::Value] the specified variable.
+    # @return [Boolean] whether the specified variable is not indexed.
+    def without_index_on?(variable)
+      [
+        [@variable1,@index1],
+        [@variable2,@index2],
+      ].any?{|pair|
+        pair.first == variable && pair.last.nil?
+      }
+    end
+    
+    # @return [Boolean] whether the Instantiation has been deleted (memoized).
+    def deleted?
+      @deleted ||= @variable1.goal.deleted? || @variable2.goal.deleted?
+      @deleted
+    end
+    
+    # @param goal [Porolog::Goal] the provided Goal.
+    # @return [Boolean] whether the Instantiation attaches to a variable in the provided Goal.
+    def belongs_to?(goal)
+      [
+        @variable1.goal,
+        @variable2.goal,
+      ].include?(goal)
+    end
+    
+  end
+  
+end

data/lib/porolog/predicate.rb

@@ -10,17 +10,21 @@ module Porolog
   # A Porolog::Predicate corresponds to a Prolog predicate.
   # It contains rules (Porolog::Rule) and belongs to a Porolog::Scope.
   # When provided with arguments, it produces a Porolog::Arguments.
+  #
   # @author Luis Esteban
+  #
   # @!attribute [r] name
   #   Name of the Predicate.
+  #
   # @!attribute [r] rules
   #   Rules of the Predicate.
+  #
   class Predicate
     
     # Error class for rescuing or detecting any Predicate error.
-    class PredicateError < PorologError   ; end
+    class Error          < PorologError   ; end
     # Error class indicating an error with the name of a Predicate.
-    class NameError      < PredicateError ; end
+    class NameError      < Error          ; end
     
     attr_reader :name, :rules
     
@@ -40,9 +44,7 @@ module Porolog
     # @param scope_name [Object] the name (or otherwise object) used to register a scope.
     # @return [Porolog::Scope] the current Scope.
     def self.scope=(scope_name)
-      if scope_name
-        @@current_scope = Scope[scope_name] || Scope.new(scope_name)
-      end
+      @@current_scope = Scope[scope_name] || Scope.new(scope_name)  if scope_name
       @@current_scope
     end
     
@@ -69,7 +71,7 @@ module Porolog
       @name  = name.to_sym
       @rules = []
       
-      raise NameError.new("Cannot name a predicate 'predicate'") if @name == :predicate
+      raise NameError, "Cannot name a predicate 'predicate'" if @name == :predicate
       
       scope = Scope[scope_name] || Scope.new(scope_name)
       scope[@name] = self
@@ -83,14 +85,17 @@ module Porolog
     end
     
     # Create Arguments for the Predicate.
-    # Provides the syntax options:
-    # * p.(x,y,z)
+    # Provides the syntax option:
+    #     p.(x,y,z)
+    # for
+    #     p.arguments(x,y,z)
     # @return [Porolog::Arguments] Arguments of the Predicate with the given arguments.
     def call(*args)
       Arguments.new(self,args)
     end
     
     # Create Arguments for the Predicate.
+    # @return [Porolog::Arguments] Arguments of the Predicate with the given arguments.
     def arguments(*args)
       Arguments.new(self,args)
     end
@@ -106,18 +111,13 @@ module Porolog
     # A pretty print String of the Predicate.
     # @return [String] the Predicate as a String.
     def inspect
-      lines = []
-      
       if @rules.size == 1
-        lines << "#{@name}:-#{@rules.first.inspect}"
+        "#{@name}:-#{@rules.first.inspect}"
       else
-        lines << "#{@name}:-"
-        @rules.each do |rule|
+        @rules.each_with_object(["#{@name}:-"]) do |rule, lines|
           lines << rule.inspect
-        end
+        end.join("\n")
       end
-        
-      lines.join("\n")
     end
     
     # Return a builtin Predicate based on its key.
@@ -130,6 +130,23 @@ module Porolog
       self.new("_#{key}_#{@builtin_predicate_ids[key]}")
     end
     
+    # Satisfy the Predicate within the supplied Goal.
+    # Satisfy of each rule of the Predicate is called with the Goal and success block.
+    # @param goal [Porolog::Goal] the Goal within which to satisfy the Predicate.
+    # @param block [Proc] the block to be called each time a Rule of the Predicate is satisfied.
+    # @return [Boolean] whether any Rule was satisfied.
+    def satisfy(goal, &block)
+      satisfied = false
+      @rules.each do |rule|
+        rule.satisfy(goal) do |subgoal|
+          satisfied = true
+          block.call(subgoal)
+        end
+        break if goal.terminated?
+      end
+      satisfied
+    end
+    
   end
 
 end

data/lib/porolog/rule.rb

@@ -8,17 +8,25 @@
 module Porolog
   
   # A Porolog::Rule is one clause of a Porolog::Predicate.
+  #
   # @author Luis Esteban
+  #
   # @!attribute [r] arguments
   #   The Arguments of the Predicate for which this Rule applies.
   # @!attribute [r] definition
   #   The definition of the Rule.
+  #
   class Rule
     
+    # Error class for rescuing or detecting any Rule error.
+    class Error           < PorologError ; end
+    # Error class indicating that there is an error in the definition of the Rule.
+    class DefinitionError < Error        ; end
+    
     attr_reader :arguments, :definition
     
     # Clears all Rules.
-    # @return [true]
+    # @return [Boolean] success
     def self.reset
       @@rules = []
       true
@@ -41,11 +49,130 @@ module Porolog
       "Rule#{(@@rules.index(self) || -1000) + 1}"
     end
     
-    # @return [String] pretty representation
+    # @return [String] pretty representation.
     def inspect
       "  #{@arguments.inspect}:- #{@definition.inspect}"
     end
     
+    # Try to satisfy the Rule for the given Goal.
+    # @param goal [Porolog::Goal] the Goal in which to satisfy this Rule.
+    # @param block [Proc] code to perform when the Rule is satisfied.
+    # @return [Boolean] the success of deleting the subgoal.
+    def satisfy(goal, &block)
+      subgoal = Goal.new self.arguments, goal
+      
+      unified_goals = unify_goals(goal, subgoal)
+      if unified_goals
+        satisfy_definition(goal, subgoal) do |solution_goal|
+          block.call(solution_goal)
+        end
+      else
+        subgoal.log << "Dead-end: Cannot unify with #{goal.inspect}"
+      end
+      
+      subgoal.delete!
+    end
+    
+    # Try to satisfy the definition of the Rule for a given Goal.
+    # @param goal [Porolog::Goal] the given Goal for the Rule.
+    # @param subgoal [Porolog::Goal] the subgoal for the Rule's definition.
+    # @param block [Proc] code to perform when the definition is satisfied.
+    # @return [Boolean] whether the definition was satisfied.
+    def satisfy_definition(goal, subgoal, &block)
+      case @definition
+        when TrueClass
+          block.call(subgoal)
+          true
+        
+        when FalseClass
+          false
+        
+        when Array
+          satisfy_conjunction(goal, subgoal, @definition) do |solution_goal|
+            block.call(solution_goal)
+          end
+        
+        else
+          raise DefinitionError, "UNEXPECTED TYPE OF DEFINITION: #{@definition.inspect} (#{@definition.class})"
+      end
+    end
+    
+    # Try to satisfy the conjunction of the definition of the Rule for a given Goal.
+    # A conjunction is a sequence of expressions where the sequence is true
+    # if all the expressions are true.
+    #
+    # @param goal [Porolog::Goal] the given Goal for the Rule.
+    # @param subgoal [Porolog::Goal] the subgoal for the Rule's definition.
+    # @param conjunction [Array] the conjunction to satisfy.
+    # @param block [Proc] code to perform when the definition is satisfied.
+    # @return [Boolean] whether the definition was satisfied.
+    def satisfy_conjunction(goal, subgoal, conjunction, &block)
+      arguments   = conjunction.first
+      conjunction = conjunction[1..-1]
+      
+      # -- Handle non-Arguments --
+      case arguments
+        when :CUT, true
+          subgoal.log << "CUTTING #{goal.inspect}..."
+          result = true
+          if conjunction.empty?
+            block.call(subgoal)
+          else
+            result = satisfy_conjunction(goal, subgoal, conjunction, &block)
+          end
+          
+          if arguments == :CUT
+            subgoal.calling_goal.terminate!
+            subgoal.calling_goal.log << "TERMINATED by #{subgoal.inspect}"
+          end
+          
+          return result
+          
+        when false
+          return false
+      end
+      
+      # -- Unify Subgoal --
+      subsubgoal   = arguments.goal(subgoal)
+      variables    = (subgoal.arguments.variables + subsubgoal.arguments.variables).map(&:to_sym).uniq
+      unified      = true
+      unifications = []
+      
+      variables.each do |variable|
+        name = variable
+        
+        unification = unify(name, name, subgoal, subsubgoal)
+        unified   &&= !!unification
+        if unified
+          unifications += unification
+        else
+          #:nocov:
+          subsubgoal.log << "Couldn't unify: #{name.inspect} WITH #{subgoal.myid} AND #{subsubgoal.myid}"
+          break
+          #:nocov:
+        end
+      end
+      
+      # -- Instantiate Unifications --
+      unified &&= instantiate_unifications(unifications) if unified
+      
+      # -- Satisfy Subgoal --
+      result = false
+      unified && subsubgoal.satisfy() do
+        result = true
+        if conjunction.empty?
+          block.call(goal)
+        else
+          result = satisfy_conjunction(goal, subsubgoal, conjunction, &block)
+        end
+      end
+      
+      # -- Uninstantiate --
+      subsubgoal.delete!
+      
+      result
+    end
+    
   end
   
 end