porolog 0.0.4 → 1.0.0

data/lib/porolog/instantiation.rb

@@ -0,0 +1,346 @@
+#
+#   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&.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)
+      
+      values_for_variable1 = values_for(@variable1, visited)
+      values_for_variable2 = values_for(@variable2, visited)
+      
+      (values_for_variable1 + values_for_variable2).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 index == :flathead
+            # value_value = [..., 4, 5, 6]
+            if value_value.first == UNKNOWN_TAIL
+              UNKNOWN_ARRAY
+            else
+              nil
+            end
+          elsif index == :flattail
+            # value_value = [1, 2, 3, ...]
+            if value_value.first == UNKNOWN_TAIL
+              nil
+            elsif value_value.last == UNKNOWN_TAIL
+              UNKNOWN_ARRAY
+            end
+          elsif 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 == :flathead
+          flathead = value_at_index(value_indexed(@variable2.value(visited), @index2, visited), @index1).value.value
+          if flathead
+            return [[*flathead]]
+          else
+            return []
+          end
+        end
+        if @index1 == :flattail
+          flattail = value_at_index(value_indexed(@variable2.value(visited), @index2, visited), @index1).value.value
+          if flattail
+            return [[UNKNOWN_TAIL, *flattail]]
+          else
+            return []
+          end
+        end
+        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 == :flathead
+          flathead = value_at_index(value_indexed(@variable1.value(visited), @index1, visited), @index2).value.value
+          if flathead
+            return [[*flathead]]
+          else
+            return []
+          end
+        end
+        if @index2 == :flattail
+          flattail = value_at_index(value_indexed(@variable1.value(visited), @index1, visited), @index2).value.value
+          if flattail
+            return [[UNKNOWN_TAIL, *flattail]]
+          else
+            return []
+          end
+        end
+        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 :flathead
+              [*value, UNKNOWN_TAIL]
+            when :head
+              [value, UNKNOWN_TAIL]
+            when :tail
+              [nil, *value]
+            when :flattail
+              value
+            else
+              raise UnhandledIndexError, "Unhandled index: #{index.inspect} for #{value.inspect}"
+          end
+        
+        when Array
+          if index.empty?
+            [nil, *value]
+          else
+            [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,20 +10,28 @@ 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
     
+    # A unique value used to verify instantiations.
+    UNIQUE_VALUE = Object.new.freeze
+    private_constant :UNIQUE_VALUE
+    
     # Returns the current scope, or sets the current scope if a paramter is provided
     # (creating the new scope if necessary).
     # @param scope_name [Object] the name (or otherwise object) used to register a scope.
@@ -40,9 +48,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
     
@@ -65,11 +71,12 @@ module Porolog
     # Initializes a Porolog::Predicate and registers it by its name.
     # @param name [#to_sym] the input object to read from
     # @param scope_name the name of the scope in which to register the Predicate; if omitted, defaults to the name of the current scope
-    def initialize(name, scope_name = Predicate.scope.name)
-      @name  = name.to_sym
-      @rules = []
+    def initialize(name, scope_name = Predicate.scope.name, builtin: false)
+      @name    = name.to_sym
+      @rules   = []
+      @builtin = builtin
       
-      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
@@ -78,21 +85,23 @@ module Porolog
     # Creates a new Predicate, or returns an existing Predicate if one already exists with the given name in the current scope.
     # @return [Porolog::Predicate] a new or existing Predicate.
     def self.new(*args)
-      name, _ = *args
-      scope[name.to_sym] || super
+      scope[args.first.to_sym] || super
     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)
+    def call(*args, &block)
+      Arguments.new(self, args, &block)
     end
     
     # Create Arguments for the Predicate.
-    def arguments(*args)
-      Arguments.new(self,args)
+    # @return [Porolog::Arguments] Arguments of the Predicate with the given arguments.
+    def arguments(*args, &block)
+      Arguments.new(self, args, &block)
     end
     
     # Add a Rule to the Predicate.
@@ -106,28 +115,62 @@ 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.join("\n")
+      end
+    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)
+      if builtin?
+        satisfy_builtin(goal, &block)
+      else
+        satisfied = false
+        @rules.each do |rule|
+          rule.satisfy(goal) do |subgoal|
+            satisfied = true
+            block.call(subgoal)
+          end
+          break if goal.terminated?
         end
+        satisfied
       end
-        
-      lines.join("\n")
     end
     
-    # Return a builtin Predicate based on its key.
-    # @param key [Symbol] the name (or otherwise object) used to register a scope.
-    # @return [Porolog::Predicate] a Predicate with the next id based on the key.
-    def self.builtin(key)
-      @builtin_predicate_ids[key] ||= 0
-      @builtin_predicate_ids[key]  += 1
+    # @return [Boolean] whether the Predicate is a builtin predicate.
+    def builtin?
+      @builtin
+    end
+    
+    # Satisfy the builtin Predicate within the supplied Goal.
+    # Call the builtin Predicate method with the Goal and success block.
+    # The arguments and block are extracted from the Goal's Arguments.
+    # @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_builtin(goal, &block)
+      predicate = goal.arguments.predicate.name
+      arguments = goal.arguments.arguments
+      arg_block = goal.arguments.block
       
-      self.new("_#{key}_#{@builtin_predicate_ids[key]}")
+      Predicate.call_builtin(predicate, goal, block, *arguments, &arg_block)
+    end
+    
+    # Call a builtin predicate
+    # @param predicate [Symbol] the name of the predicate to call.
+    # @param args [Array<Object>] arguments for the predicate call.
+    # @param arg_block [Proc] the block provided in the Arguments of the Predicate.
+    # @return [Boolean] whether the predicate was satisfied.
+    def self.call_builtin(predicate, *args, &arg_block)
+      Porolog::Predicate::Builtin.instance_method(predicate).bind(self).call(*args, &arg_block)
     end
     
   end