mini_kraken 0.2.02 → 0.3.02

data/lib/mini_kraken/core/duck_fiber.rb

@@ -1,45 +1,47 @@
 # frozen_string_literal: true
 
-require_relative 'outcome'
+require_relative 'context'
 
 module MiniKraken
   module Core
     # A mock class that mimicks the behavior of a Fiber instance.
+    # More specifically, it responds to `resume` message & returns a Context.
     class DuckFiber
-      # @return [Outcome] The sole outcome to yield.
-      attr_reader :outcome
+      # @return [Proc, #call] The callable object to yield.
+      attr_reader :callable
 
       # @return [Symbol] one of: :initial, :yielded
       attr_reader :state
 
-      # @param outcomeKind [Symbol] One of: :failure, :basic_success, :custom
-      def initialize(outcomeKind, &customization)
+      # Constructor.
+      # @param aCallable [Proc, #call] The receiver of the 'call' message.
+      def initialize(aCallable)
+        @callable = valid_callable(aCallable)
         @state = :initial
-        if outcomeKind == :custom && block_given?
-          @outcome = customization.call
-        else
-          @outcome = valid_outcome(outcomeKind)
-        end
       end
 
+      # Quacks like a Fiber object.
+      # The first time, this method will return a Context objet.
+      # Subsequents calls just return nil (= no other solution available)
+      # @return [Core::Context, NilClass]
       def resume(*_args)
         if state == :initial
           @state = :yielded
-          return outcome
+          return callable.call
         else
           return nil
         end
       end
 
-      def valid_outcome(outcomeKind)
-        case outcomeKind
-          when :failure
-            Failure
-          when :success
-            Outcome.new(:"#s")
-          else
-            raise StandardError, "Unknonw outcome kind #{outcomeKind}"
+      private
+
+      def valid_callable(aCallable)
+        unless aCallable.kind_of?(Proc) || aCallable.respond_to?(:call)
+          err_msg = "Expected a Proc instead of #{aCallable.class}."
+          raise StandardError, err_msg
         end
+
+        aCallable
       end
     end # class
   end # module

data/lib/mini_kraken/core/entry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module MiniKraken
+  module Core
+    # Mix-in module that implements the expected common behaviour of entries
+    # placed in the symbol table.
+    module Entry
+      # @return [String] User-defined name of the entry.
+      attr_reader :name
+
+      # @return [String] Suffix for building the internal name of the entry.
+      attr_accessor :suffix
+
+      alias label name
+
+      # Initialize the entry with given name
+      # @param aName [String] The name of the entry
+      def init_name(aName)
+        @name = aName.dup
+        @name.freeze
+      end
+
+      # Return the internal name of the entry
+      # Internal names used to disambiguate entry names.
+      # There might be homonyns between variable because:
+      #   - A child Scope may have a entry with same name as one of its
+      #     ancestor(s).
+      #   - Multiple calls to same defrel or procedure may imply multiple creation
+      #     of a entry given name...
+      # @return [String] internal name
+      def i_name
+        if suffix =~ /^_/
+          label + suffix
+        else
+          (suffix.nil? || suffix.empty?) ? label : suffix
+        end
+      end
+    end # module
+  end # module
+end # module

data/lib/mini_kraken/core/fail.rb

@@ -4,24 +4,26 @@ require 'singleton'
 require_relative 'duck_fiber'
 require_relative 'nullary_relation'
 
-unless MiniKraken::Core.constants(false).include? :Fail
-  module MiniKraken
-    module Core
-      # A nullary relation that unconditionally always fails.
-      class Fail < NullaryRelation
-        include Singleton
+module MiniKraken
+  module Core
+    # A nullary relation that always returns a failure outcome.
+    class Fail < NullaryRelation
+      include Singleton
 
-        def initialize
-          super('fail', '#u')
-        end
+      # Constructor. Initialize the relation's name & freeze it...
+      def initialize
+        super('fail')
+      end
 
-        # @return [DuckFiber]
-        def solver_for(_actuals, _env)
-          DuckFiber.new(:failure)
-        end
-      end # class
-
-      Fail.instance.freeze
-    end # module
+      # Returns a Fiber-like object (a DuckFiber).
+      # When that object receives the message resume, it will
+      # signal a failure to the provided context.
+      # @param _actuals [Array] MUST be empty array for nullary relation.
+      # @param ctx [Core::Context] Runtime context
+      # @return [Core::DuckFiber]
+      def solver_for(_actuals, ctx)
+        DuckFiber.new(-> { ctx.failed! })
+      end
+    end # class
   end # module
-end # unless
+end # module

data/lib/mini_kraken/core/fusion.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+
+module MiniKraken
+  module Core
+    # A record of the fusion / merge of two or more logical variables.
+    class Fusion
+      # @return [String] i_name of substituting variable.
+      attr_reader :i_name
+
+      # @return [Array<String>] i_names of variables being substituted
+      attr_reader :elements
+
+      # Records the fusion of two or more logical variables.
+      # The fused variables are substituted by a new variable
+      # @param aName [String] Internal name of the substituting variable
+      # @param fused [Array<String>] The i_names of the fused variables
+      def initialize(aName, fused)
+        @i_name = aName
+        @elements = fused
+      end
+
+      # @return [Set] The empty set
+      def dependencies(_ctx)
+        @dependencies ||= Set.new(elements)
+      end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/core/goal.rb

@@ -1,48 +1,39 @@
 # frozen_string_literal: true
 
-require_relative 'environment'
+require_relative 'parametrized_term'
+require_relative 'context'
 
 module MiniKraken
-  require_relative 'goal_arg'
-
   module Core
-    class Goal < GoalArg
-      # @return [Relation] The relation corresponding to this goal
-      attr_reader :relation
-
-      # @return [Array<Term>] The actual aguments of the goal
-      attr_reader :actuals
-
-      # @param aRelation [Relation] The relation corresponding to this goal
-      # @param args [Array<Term>] The actual aguments of the goal
-      def initialize(aRelation, args)
-        super()
-        @relation = aRelation
-        @actuals = validated_actuals(args)
-      end
-
-      # Attempt to achieve the goal for a given context (environment)
-      # @param anEnv [Environment] The context in which the goal take place.
-      # @return [Fiber<Outcome>] A Fiber object that will generate the results.
-      def attain(anEnv)
-        relation.solver_for(actuals, anEnv)
+    class Goal < ParametrizedTerm
+      alias relation specification
+
+      # Attempt to obtain one or more solutions for the goal in a given context.
+      # @param ctx [Core::Context] The context in which the goal takes place.
+      # @return [Fiber<Context>] A Fiber object that will generate the results.
+      def achieve(ctx)
+        relation.solver_for(actuals, ctx)
       end
 
       private
 
-      def validated_actuals(args)
-        if !relation.polyadic? && (args.size != relation.arity)
-          err_msg = "Goal has #{args.size} arguments, expected #{relation.arity}"
-          raise StandardError, err_msg
+      def validated_specification(theSpec)
+        spec = super(theSpec)
+        unless spec.kind_of?(Relation)
+          raise StandardError, "Expected a Relation instead of #{theSpec.class}."
         end
 
-        prefix = 'Invalid goal argument'
+        spec
+      end
+
+      def validated_actuals(args)
         args.each do |actual|
-          if actual.kind_of?(GoalArg) || actual.kind_of?(Environment)
+          if actual.kind_of?(Term) || actual.respond_to?(:attain)
             next
           elsif actual.kind_of?(Array)
             validated_actuals(actual)
           else
+            prefix = 'Invalid goal argument'
             actual_display = actual.nil? ? 'nil' : actual.to_s
             raise StandardError, "#{prefix} '#{actual_display}'"
           end

data/lib/mini_kraken/core/log_var.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'entry'
+
+module MiniKraken
+  module Core
+    # Representation of a MiniKraken logical variable.
+    # It is a named slot that can be associated with one value at the time.
+    # In relational programming, there is no explicit assignment expression.
+    # A logical variable acquires a value through an algorithm called
+    # 'unification'.
+    class LogVar
+      include Entry # Add expected behaviour for symbol table entries
+
+      # Create a logical variable with given name
+      # @param aName [String] The name of the variable
+      def initialize(aName)
+        init_name(aName)
+      end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/core/log_var_ref.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'set'
+require_relative 'term'
+
+module MiniKraken
+  module Core
+    # Representation of a reference to a MiniKraken logical variable.
+    class LogVarRef < Term
+      # @return [String] User-friendly name of the variable.
+      attr_reader :name
+
+      # @return [String] Unique internal name of the variable.
+      attr_accessor :i_name
+
+      # Create a reference to a logical variable with given name
+      # @param aName [String] The name of the variable
+      def initialize(aName)
+        super()
+        init_name(aName)
+      end
+
+      # Return a text representation of this logical variable reference.
+      # @return [String]
+      def to_s
+        name
+      end
+
+      # Is the related log variable unbound in the given context?
+      # A log var is unbound when there is no association for the variable.
+      # @param aContext [Core::Context]
+      # @return [Boolean] true if log var is unbound
+      def unbound?(aContext)
+        vr = aContext.lookup(name)
+        raise StandardError, "Unknown variable #{name}" unless vr
+
+        bindings = aContext.associations_for(name)
+        bindings.empty? || (bindings.size == 1 && bindings[0].kind_of?(Fusion))
+      end
+
+      # Does the variable have at least one association AND
+      # each of these association refer to at least one unbound variable
+      # or a floating variable?
+      # @param aContext [Core::Context]
+      # @return [Boolean] true if log var is floating
+      def floating?(aContext)
+        vr = aContext.lookup(name)
+        raise StandardError, "Unknown variable #{name}" unless vr
+
+        assocs = aContext.associations_for(name)
+        unless assocs.empty?
+          assocs.none? { |as| as.pinned?(aContext) }
+        else
+          false
+        end
+      end
+
+      # Is the variable pinned?
+      # In other words, does the referenced variable have a definite value?
+      # @param aContext [Core::Context]
+      # @return [Boolean] true if log var is pinned
+      def pinned?(aContext)
+        return true if @pinned
+
+        vr = aContext.lookup(name)
+        raise StandardError, "Unknown variable #{name}" unless vr
+
+        assocs = aContext.associations_for(name)
+        unless assocs.empty?
+          @pinned = assocs.all? { |as| as.pinned?(aContext) }
+        else
+          false
+        end
+      end
+
+      # Return the list of variable (i_names) that this term depends on.
+      # For a variable reference, it will return the i_names of its variable
+      # @param ctx [Core::Context]
+      # @return [Set<String>] a set containing the i_name of the variable
+      def dependencies(ctx)
+        @i_name ||= ctx.lookup(name).i_name
+        s = Set.new
+        s << i_name
+        s
+      end
+
+      # Make a copy of self with all the variable reference being
+      # replaced by the corresponding value in the Hash.
+      # @param substitutions [Hash {String => Term}]
+      # @return [Term]
+      def dup_cond(substitutions)
+        key = i_name || name
+        if substitutions.include? key
+          val = substitutions[key]
+          val.kind_of?(Term) ? val.dup_cond(substitutions) : val
+        else
+          dup
+        end
+      end
+
+      private
+
+      def init_name(aName)
+        @name = aName.dup
+      end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/core/nullary_relation.rb

@@ -6,17 +6,10 @@ module MiniKraken
   module Core
     class NullaryRelation < Relation
       # @param aName [String] Name of the relation.
-      # @param alternateName [String, NilClass] Alternative name (optional).
-      def initialize(aName, alternateName = nil)
-        super(aName, alternateName)
+      def initialize(aName)
+        super(aName, 0)
         freeze
       end
-
-      # Number of arguments for the relation.
-      # @return [Integer]
-      def arity
-        0
-      end
     end # class
   end # module
 end # module

data/lib/mini_kraken/core/parametrized_term.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'term'
+require_relative 'specification'
+
+module MiniKraken
+  module Core
+    # A specialization of Term class for objects that take arguments.
+    class ParametrizedTerm < Term
+      # @return [Specification] The specification that must be invoked with arguments.
+      attr_reader :specification
+
+      # @return [Array<Term>] The actual aguments of the goal
+      attr_reader :actuals
+
+      # Constructor.
+      # @param theSpecification [Specification] The callable object.
+      # @param theArgs [Array<Term>] The actual aguments
+      def initialize(theSpecification, theArgs)
+        super()
+        @specification = validated_specification(theSpecification)
+        args = specification.check_arity(theArgs)
+        @actuals = validated_actuals(args)
+      end
+
+      def initialize_copy(orig)
+        @specification = orig.specification
+        @actuals = []
+      end
+
+      # Make a copy of self with all the variable reference being
+      # replaced by the corresponding value in the Hash.
+      # @param substitutions [Hash {String => Term}]
+      # @return [Term]
+      def dup_cond(substitutions)
+        duplicate = dup
+        updated_actuals = actuals.map { |e| e.dup_cond(substitutions) }
+        duplicate.actuals.concat(updated_actuals)
+
+        duplicate
+      end
+
+      protected
+
+      def validated_specification(theSpecification)
+        unless theSpecification.kind_of?(Specification)
+          msg_part1 = 'Expected kind_of Specification,'
+          msg_part2 = "instead of #{theSpecification.class}."
+          raise StandardError, "#{msg_part1} #{msg_part2}"
+        end
+
+        theSpecification
+      end
+
+      # This method should be overridden in subclasses
+      def validated_actuals(args)
+        args
+      end
+    end # class
+  end # module
+end # module