porolog 0.0.4 → 1.0.0

data/lib/porolog/rule.rb

@@ -0,0 +1,162 @@
+#
+#   lib/porolog/rule.rb      - Plain Old Ruby Objects Prolog Engine -- Rule
+#
+#     Luis Esteban   2 May 2018
+#       created
+#
+
+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 [Boolean] success
+    def self.reset
+      @@rules = []
+      true
+    end
+    
+    reset
+    
+    # Initializes the Rule.
+    # @param arguments [Porolog::Arguments] the Arguments of the Predicate for which this Rule applies.
+    # @param definition [Object] the definition of the Rule.
+    def initialize(arguments, definition = nil)
+      @arguments  = arguments
+      @definition = definition
+      @@rules << self
+    end
+    
+    # Convenience method for testing/debugging
+    # @return [String] pretty identification
+    def myid
+      "Rule#{(@@rules.index(self) || -1000) + 1}"
+    end
+    
+    # @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
+            goal.terminate!
+            goal.log << "TERMINATED after #{subgoal.inspect}"
+          end
+          
+          return result
+          
+        when false
+          return false
+        
+        when nil
+          block.call(subgoal)
+          return true
+      end
+      
+      # -- Unify Subsubgoal --
+      subsubgoal = arguments.goal(subgoal)
+      unified    = subsubgoal.inherit_variables(subgoal)
+      
+      # -- 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

data/lib/porolog/scope.rb

@@ -16,9 +16,9 @@ module Porolog
   class Scope
     
     # Error class for rescuing or detecting any Scope error.
-    class ScopeError        < PorologError ; end
+    class Error             < PorologError ; end
     # Error class indicating a non-Predicate was assigned to a Scope.
-    class NotPredicateError < ScopeError   ; end
+    class NotPredicateError < Error        ; end
     
     attr_reader :name
     
@@ -73,8 +73,8 @@ module Porolog
     # @param predicate [Porolog::Predicate] a Predicate to be assigned to the Scope.
     # @return [Porolog::Predicate] the Predicate assigned to the Scope.
     # @raise [NotPredicateError] when provided predicate is not actually a Predicate.
-    def []=(name,predicate)
-      raise NotPredicateError.new("#{predicate.inspect} is not a Predicate") unless predicate.is_a?(Predicate)
+    def []=(name, predicate)
+      raise NotPredicateError, "#{predicate.inspect} is not a Predicate" unless predicate.is_a?(Predicate)
       @predicates[name.to_sym] = predicate
     end
     

data/lib/porolog/tail.rb

@@ -0,0 +1,57 @@
+#
+#   lib/porolog/tail.rb      - Plain Old Ruby Objects Prolog Engine -- Tail
+#
+#     Luis Esteban   2 May 2018
+#       created
+#
+
+module Porolog
+  
+  # A Porolog::Tail is used to represent the tail of a list.
+  #
+  # It corresponds to the use of the splat operator within an Array.
+  #
+  # @author Luis Esteban
+  #
+  # @!attribute value
+  #   @return [Object] The value of the tail.
+  class Tail
+    
+    # Creates a new Tail for an Array.
+    # @param value [Object] the value of the tail.
+    def initialize(value = UNKNOWN_TAIL)
+      @value = value
+    end
+    
+    # @return [Symbol] the type of the Tail, which should be :tail.
+    def type
+      :tail
+    end
+    
+    # Returns the value of the Tail.
+    # The optional arguments are ignored; this is for polymorphic compatibility with Porolog::Value and Porolog::Variable,
+    # which are used to prevent inifinite recursion.
+    # @return [Object] the value of the Tail.
+    def value(*)
+      @value
+    end
+    
+    # @return [String] pretty representation.
+    def inspect
+      "*#{@value.inspect}"
+    end
+    
+    # @return [Array] embedded variables.
+    def variables
+      @value.variables
+    end
+    
+    # @param other [Object, #value]
+    # @return [Boolean] whether the value of the Tail is equal to the value of another Object.
+    def ==(other)
+      @value == other.value
+    end
+    
+  end
+  
+end

data/lib/porolog/value.rb

@@ -0,0 +1,105 @@
+#
+#   lib/porolog/value.rb      - Plain Old Ruby Objects Prolog Engine -- Value
+#
+#     Luis Esteban   2 May 2018
+#       created
+#
+
+module Porolog
+  
+  # A Porolog::Value combines a value with a goal so that when the goal
+  # is closed, the value can be uninstantiated at the same time.
+  #
+  # @author Luis Esteban
+  #
+  # @!attribute goal
+  #   @return [Porolog::Goal] The goal in which the value was instantiated.
+  # @!attribute instantiations
+  #   @return [Array<Porolog::Instantiation>] Instantiations of this value.
+  #
+  class Value
+    
+    # Error class for rescuing or detecting any Value error.
+    class Error     < PorologError ; end
+    # Error class indicating that the supplied goal is not actually a goal.
+    class GoalError < Error        ; end
+    
+    attr_accessor :goal, :instantiations
+    
+    # @param value [Object] the value to be associated with a Goal.
+    # @param goal [Porolog::Goal] the Goal to be associated.
+    # @return [Porolog::Value] the Value.
+    def initialize(value, goal)
+      raise GoalError, "Not a Goal: #{goal.inspect}" unless goal.is_a?(Goal)
+      
+      @value = value
+      @value = value.value if value.is_a?(Value)
+      @goal  = goal
+      
+      @instantiations = []
+    end
+    
+    # Pretty presentation.
+    # @return [String] the inspect of the value prefixed by the goal id.
+    def inspect
+      "#{@goal.myid}.#{@value.inspect}"
+    end
+    
+    # Pretty presentation with instantiations and indexes.
+    # This method is for polymorphic compatibility with Porolog::Variable.
+    # It used by Porolog::Goal#inspect_variables.
+    # @param visited [Array] the values already visited (to prevent infinite recursion).
+    # @param depth [Integer] the level of indentation that shows containment.
+    # @param index [Integer,Symbol,Array] the index into this value.
+    # @param self_index [Integer,Symbol,Array] the index of which this value belongs.
+    # @return [String] the inspect of the value in the context of the variables of a goal.
+    def inspect_with_instantiations(visited = [], depth = 0, index = nil, self_index = nil)
+      index_str = index && "[#{index.inspect}]" || ''
+      prefix    = self_index&.inspect || ''
+      
+      "#{'  ' * depth}#{prefix}#{inspect}#{index_str}"
+    end
+    
+    # Uninstantiate the Value.
+    # @return [Boolean] true
+    def remove
+      @instantiations.dup.each(&:remove)
+      @instantiations[0..-1] = []
+      true
+    end
+    
+    # Passes on methods to the Value's value.
+    def method_missing(method, *args, &block)
+      @value.send(method, *args, &block)
+    end
+    
+    # Responds to all the Value's value methods as well as its own.
+    # @return [Boolean] whether the value responds to the method.
+    def respond_to?(method, include_all = false)
+      @value.respond_to?(method, include_all) || super
+    end
+    
+    # @return [Object] the value of the Value.
+    def value(*)
+      @value
+    end
+    
+    # @return [Symbol] the type of the value.
+    def type
+      @value.type
+    end
+    
+    # Compares Values for equality.
+    # @return [Boolean] whether the Values' values are equal.
+    def ==(other)
+      @value == other.value
+    end
+    
+    # @return [Array<Porolog::Variable,Symbol>] variables embedded in the value.
+    def variables
+      @value.variables
+    end
+    
+  end
+  
+end

data/lib/porolog/variable.rb

@@ -0,0 +1,325 @@
+#
+#   lib/porolog/variable.rb      - Plain Old Ruby Objects Prolog Engine -- Variable
+#
+#     Luis Esteban   2 May 2018
+#       created
+#
+
+module Porolog
+  
+  # A Porolog::Variable is used to hold instantiations during the process of satisfying a goal.
+  # It implements a variable of a goal.
+  # It allows instantiations to be made and removed as the goal
+  # is attempted to be satisfied.
+  #
+  # @author Luis Esteban
+  #
+  # @!attribute name
+  #   @return [Symbol] The name of the variable.
+  # @!attribute goal
+  #   @return [Porolog::Goal] The Goal for which this Variable's instantiations are bound.
+  # @!attribute instantiations
+  #   @return [Array<Porolog::Instantiation>] The Instantiations of this Variable.
+  # @!attribute values
+  #   @return [Array<Porolog::Value>] the Values of the Variable when used as an anonymous Variable.
+  #
+  class Variable
+    
+    # Error class for rescuing or detecting any Variable error.
+    class Error                 < PorologError  ; end
+    # Error class indicating a Variable has been instantiated to multiple different values at the same time.
+    class MultipleValuesError   < Error         ; end
+    # Error class indicating a Variable has been created without a Goal.
+    class GoalError             < Error         ; end
+    # Error class indicating a Variable has been instantiated to a value that contains itself.
+    class SelfReferentialError  < Error         ; end
+    # Error class indicating an unexpected scenario has occurred.
+    class UnexpectedError       < Error         ; end
+    
+    attr_accessor :name, :goal, :instantiations, :values
+    
+    # Initializes the Variable and attaches it to the Goal.
+    # @param name [Object] the name used to refer to the Variable.
+    # @param goal [Porolog::Goal] the Goal the Variable is to be attached to.
+    def initialize(name, goal)
+      raise GoalError, "Not a Goal: #{goal.inspect}" unless goal.is_a?(Goal)
+      @goal = goal
+      name  = name.to_sym  if name.is_a?(String)
+      
+      case name
+        when Symbol
+          @name   = name
+          @values = []
+        when Variable
+          @name   = name.name
+          @values = []
+        when Value
+          @name   = name.value
+          @values = [name]
+        else
+          @name   = name.to_s
+          @values = [Value.new(name, goal)]
+      end
+      
+      @instantiations = []
+      @goal.variable(self)
+    end
+    
+    # Converts a Variable back to a Symbol.
+    # @return [Symbol, nil] the name of the Variable.
+    def to_sym
+      @name&.to_sym
+    end
+    
+    # @return [Symbol] the type of the Variable, which should be :variable.
+    def type
+      :variable
+    end
+    
+    # @return [String] pretty representation.
+    def inspect
+      "#{@goal.myid}.#{@name.inspect}"
+    end
+    
+    # @param visited [Array] used to prevent infinite recursion.
+    # @param depth [Integer] the current level of indentation.
+    # @param index [Object, nil] the index into this Variable that is instantiated.
+    # @param self_index [Object, nil] the index where this Variable is instantiated.
+    # @return [String] the inspect of the Variable showing instantiations using indentation.
+    def inspect_with_instantiations(visited = [], depth = 0, index = nil, self_index = nil)
+      return if visited.include?(self)
+      
+      index_str = index      && "[#{index.inspect}]"      || ''
+      prefix    = self_index && "[#{self_index.inspect}]" || ''
+      name      = "#{'  ' * depth}#{prefix}#{@goal.myid}.#{@name.inspect}#{index_str}"
+      
+      name = "#{name} = #{@values.map(&:inspect).join(',')}#{index_str}" if @values && !@values.empty? && @instantiations.empty?
+      
+      others = @instantiations.map{|instantiation|
+        [
+          instantiation.variable1.inspect_with_instantiations(visited + [self], depth + 1, instantiation.index1, instantiation.index2),
+          instantiation.variable2.inspect_with_instantiations(visited + [self], depth + 1, instantiation.index2, instantiation.index1),
+        ].compact
+      }.reject(&:empty?)
+      
+      [
+        name,
+        *others,
+      ].join("\n")
+    end
+    
+    # @return [Object,self] returns the current value of the Variable based on its current instantiations.
+    #   If there are no concrete instantiations, it returns itself, indicating no value.
+    # @param visited [Array] prevents infinite recursion.
+    def value(visited = [])
+      return nil if visited.include?(self)
+      visited = visited + [self]
+      
+      # -- Collect values --
+      values = [*@values]
+      
+      @instantiations.each do |instantiation|
+        values += instantiation.values_for(self, visited)
+      end
+     
+      values.uniq!
+     
+      # -- Filter trivial values --
+      values = [[nil]] if values == [[UNKNOWN_TAIL], [nil]] || values == [[nil], [UNKNOWN_TAIL]]
+     
+      values = values.reject{|value| value == UNKNOWN_TAIL }
+     
+      values_values = values.map{|value| value.value(visited) }.reject{|value| value == UNKNOWN_ARRAY }
+      
+      # -- Condense Values --
+      result = if values_values.size > 1
+        # -- Potentially Multiple Values Found --
+        unifications = []
+        if values_values.all?{|value| value.is_a?(Array) }
+          # -- All Values Are Arrays --
+          values = values.reject{|value| value == UNKNOWN_ARRAY } if values.size > 2 && values.include?(UNKNOWN_ARRAY)
+          values_goals = values.map{|value|
+            value.respond_to?(:goal) && value.goal || value.variables.map(&:goal).first || values.variables.map(&:goal).first
+          }
+
+          if values.size > 2
+            merged, unifications = unify_many_arrays(values, values_goals, visited)
+          elsif values.size == 2
+            no_variables = values.map(&:variables).flatten.empty?
+            if no_variables
+              left_value  = values[0].value.value
+              right_value = values[1].value.value
+              if left_value.last == UNKNOWN_TAIL && right_value.first == UNKNOWN_TAIL
+                return [*left_value[0...-1], *right_value[1..-1]]
+              elsif right_value.last == UNKNOWN_TAIL && left_value.first == UNKNOWN_TAIL
+                return [*right_value[0...-1], *left_value[1..-1]]
+              elsif left_value != right_value
+                return nil
+              end
+            end
+            merged, unifications = unify_arrays(*values, *values_goals, visited)
+          else
+            # :nocov: NOT REACHED
+            merged, unifications = values.first, []
+            # :nocov:
+          end
+          
+          merged.value(visited).to_a
+        else
+          # -- Not All Values Are Arrays --
+          values.each_cons(2){|left,right|
+            unification = unify(left, right, @goal, @goal, visited)
+            if unification && unifications
+              unifications += unification
+            else
+              unifications = nil
+            end
+          }
+          if unifications
+            values.min_by{|value|
+              case value
+                when Variable, Symbol             then  2
+                when UNKNOWN_TAIL, UNKNOWN_ARRAY  then  9
+                else                              0
+              end
+            } || self
+          else
+            raise MultipleValuesError, "Multiple values detected for #{inspect}: #{values.inspect}"
+          end
+        end
+      else
+        # -- One (or None) Value Found --
+        values.min_by{|value|
+          case value
+            when Variable, Symbol             then  2
+            when UNKNOWN_TAIL, UNKNOWN_ARRAY  then  9
+            else                              0
+          end
+        } || self
+      end
+      
+      # -- Splat Tail --
+      if result.is_a?(Array) && result.size == 1 && result.first.is_a?(Tail)
+        result = result.first.value
+      end
+      
+      result
+    end
+    
+    # Instantiates Variable to another experssion.
+    # @param other [Object] the other value (or object) being instantiated.
+    # @param index_into_other [] the index into the other value.
+    # @param index_into_self [] the index into this Variable.
+    # @return [Porolog::Instantiation,nil] the instantiation made.
+    # @example
+    #   # To instantiate the third element of x to the second element of y,
+    #   # x = [a,b,c,d,e]
+    #   #          |
+    #   # y =   [p,q,r,s]
+    #     x = goal.variable(:x)
+    #     y = goal.variable(:y)
+    #     x.instantiate(y, 1, 2)
+    # @example
+    #   # To instantiate the tail of x to y,
+    #     x.instantiate(y, nil, :tail)
+    def instantiate(other, index_into_other = nil, index_into_self = nil)
+      raise SelfReferentialError, "Cannot instantiate self-referential definition for #{(self.variables & other.variables).inspect}"  unless (self.variables & other.variables).empty?
+      
+      # -- Check Instantiation is Unifiable --
+      unless self.value.is_a?(Variable) || other.value.is_a?(Variable)
+        # -- Determine Other Goal --
+        other_goal = nil
+        other_goal = other.goal if other.respond_to?(:goal)
+        other_goal ||= self.goal
+        
+        # -- Check Unification --
+        unless unify(self, other, self.goal, other_goal)
+          self.goal.log << "Cannot unify: #{self.inspect} and #{other.inspect}"
+          return nil
+        end
+      end
+      
+      # -- Create Instantiation --
+      instantiation = Instantiation.new(self, index_into_self, other, index_into_other)
+      
+      # -- Create Reverse Assymetric Instantiations --
+      if other.value.is_a?(Array) && other.value.last.is_a?(Tail)
+        array = other.value
+        if array.length == 2
+          if array.first.is_a?(Variable)
+            Instantiation.new(array.first, nil, self, :head)
+          end
+          if array.last.is_a?(Tail) && array.last.value.is_a?(Variable)
+            Instantiation.new(array.last.value, nil, self, :tail)
+          end
+        end
+      end
+      
+      # -- Return --
+      instantiation
+    end
+    
+    # Removes this Variable by removing all of its insantiations.
+    # @return [Boolean] success.
+    def remove
+      @instantiations.dup.each(&:remove)
+      @instantiations[0..-1] = []
+      true
+    end
+    
+    # Removes instantiations from another goal.
+    # @param other_goal [Porolog::Goal] the Goal of which instantiations are to be removed.
+    # @return [Boolean] success.
+    def uninstantiate(other_goal)
+      @instantiations.delete_if do |instantiation|
+        instantiation.remove  if instantiation.other_goal_to(self) == other_goal
+      end
+      
+      @values.delete_if{|value| value.goal == other_goal }
+      true
+    end
+    
+    # Indexes the value of the Variable.
+    # @param index [Object] the index into the value.
+    # @return [Object, nil] the value at the index in the value of the Variable.
+    def [](index)
+      value = self.value
+      value = value.value if value.is_a?(Value)
+      
+      case value
+        when Array
+          case index
+            when Integer
+              value[index]
+            when Symbol
+              case index
+                when :head
+                  value[0]
+                when :tail
+                  value[1..-1]
+                else
+                  nil
+              end
+            else
+              nil
+          end
+        else
+          nil
+      end
+    end
+    
+    # @return [Array<Porolog::Variable>] the Variables in itself, which is just itself.
+    def variables
+      [self]
+    end
+    
+    # Compares Variables.
+    # @param other [Porolog::Variable] the other Variable.
+    # @return [Boolean] whether the two Variables have the same name in the same Goal.
+    def ==(other)
+      other.is_a?(Variable) && @name == other.name && @goal == other.goal
+    end
+    
+  end
+  
+end