mini_kraken 0.2.03 → 0.3.03

data/lib/mini_kraken/core/relation.rb

@@ -1,37 +1,23 @@
 # frozen_string_literal: true
 
+require_relative 'specification'
+require_relative 'context'
+
 module MiniKraken
   module Core
-    class Relation
-      # @return [String] Name of the relation.
-      attr_reader :name
-
-      # @return [String, NilClass] Optional alternative name of the relation.
-      attr_reader :alt_name
-
-      # @param aName [String] Name of the relation.
-      # @param alternateName [String, NilClass] Alternative name (optional).
-      def initialize(aName, alternateName = nil)
-        @name = aName
-        @alt_name = alternateName
-      end
-
-      # A relation is polyadic when it accepts an arbitrary number of arguments.
-      # Most built-in relation takes a fixed number of arguments (= arity).
-      # @return [Boolean]
-      def polyadic?
-        false
-      end
-
-      # Number of arguments for the relation.
-      # @return [Integer]
-      def arity
+    # Formally, a n-relation over R, where R represents the cartesian product
+    # (A1 x A2 x ... An) is a subset of R.
+    # In other words, a n-relation is a subset of all tuples represented by R.
+    # In MiniKraken, a n-relation is an object that indicates whether a given
+    # tuple -of length n- is valid (or non valid).
+    class Relation < Specification
+      # Abstract method to override in subclass(es).
+      # @param actuals [Array<Term>] Argument count must
+      # @param ctx [Core::Context] Runtime context
+      # @return [#resume] A Fiber-like object that yields Context.
+      def solver_for(actuals, ctx)
         raise NotImplementedError
       end
-
-      def inspect
-        alt_name || name
-      end
     end # class
   end # module
 end # module

data/lib/mini_kraken/core/scope.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'log_var'
+
+module MiniKraken
+  module Core
+    # A scope is a name space that corresponds either to a specific
+    # delimited region in MiniKraken source code or to an activation record
+    # of a relation or a relation definition.
+    # It contains a map of names to the objects they name (e.g. logical var)
+    class Scope
+      # The parent (enclosing) scope.
+      # @return [Scope, NilClass]
+      attr_accessor :parent
+
+      # Mapping from user-defined name to related definition
+      #  (say, a logical variable object)
+      # @return [Hash{String => LogVar}] Pairs of the kind
+      attr_reader :defns
+
+      # Construct a scope instance.
+      # TODO: extend with defrel and procedure
+      # @param aParent [Scope, NilClass] Parent scope to this one.
+      def initialize(aParent = nil)
+        @parent = aParent
+        @defns = {}
+      end
+
+      # Add a new logical variable to the scope.
+      # @param anEntry [LogVar]
+      # @return [LogVar] the variable
+      def insert(anEntry)
+        e = validated_entry(anEntry)
+        e.suffix = default_suffix if e.kind_of?(LogVar)
+        defns[e.name] = e
+
+        e
+      end
+
+      # Returns a string with a human-readable representation of the object.
+      # @return [String]
+      def inspect
+        +"#<#{self.class}:#{object_id.to_s(16)}>"
+      end
+
+      private
+
+      def validated_entry(anEntry)
+        name = anEntry.name
+        unless name.kind_of?(String) && !name.empty?
+          err_msg = 'Invalid variable name argument.'
+          raise StandardError, err_msg
+        end
+        if defns.include?(name)
+          err_msg = "Variable with name '#{name}' already exists."
+          raise StandardError, err_msg
+        end
+
+        anEntry
+      end
+
+      def default_suffix
+        @default_suffix ||= "_#{object_id.to_s(16)}"
+      end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/core/solver_adapter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module MiniKraken
+  module Core
+    # A wrapper around a "solver" object.
+    # A solver in MiniKraken is Fiber or an object that quacks like
+    # a Fiber in that its has a 'resume' method.
+    # To be a solver, the adaptee object must yield a Context or nil.
+    # A SolverAdapter implements a customized resume method that
+    # acts as an "execute around" method for the adaptee's ´resume´ method.
+    class SolverAdapter
+      # @return [#resume] A Fiber-like object as adaptee
+      attr_reader :adaptee
+
+      # ->(adapter, aContext) do
+        # aContext.push_bookmark(adapter.adaptee)
+        # result = adapter.adaptee.resume
+        # aContext.pop_bookmark
+        # result
+      # end
+      # @return [Proc] lambda to execute when resume is called
+      attr_reader :around_resume
+
+      # Constructor.
+      # @param fib [#resume] A Fiber-like object
+      def initialize(fib, &blk)
+        @adaptee = validated_adaptee(fib)
+        @around_resume = blk if block_given?
+      end
+
+      # Update the bookmarks and resume the Fiber
+      # @param aContext [Core::Context]
+      # @return [Core::Context, NilClass]
+      def resume(aContext)
+        ctx = validated_ctx(aContext)
+        if around_resume
+          around_resume.call(self, ctx)
+        else
+          adaptee.resume
+        end
+      end
+
+      private
+
+      def validated_adaptee(fib)
+        raise StandardError, 'No resume method' unless fib.respond_to?(:resume)
+
+        fib
+      end
+
+      def validated_ctx(aContext)
+        raise StandardError unless aContext.kind_of?(Context)
+
+        aContext
+      end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/core/specification.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'arity'
+
+module MiniKraken
+  module Core
+    class Specification
+      # @return [String] Name of the specification object.
+      attr_reader :name
+
+      # @return [Arity] arity = allowed number of arguments
+      attr_reader :arity
+
+      # @param aName [String] Name of the relation.
+      # @param anArity [Arity, Integer] Arity of the relation.
+      def initialize(aName, anArity)
+        @name = aName
+        @arity = anArity.is_a?(Integer) ? Arity.new(anArity, anArity) : anArity
+      end
+
+      # A relation is variadic when it accepts an arbitrary number of arguments.
+      # Most built-in relation takes a fixed number of arguments (= arity).
+      # @return [Boolean]
+      def variadic?
+        arity.variadic?
+      end
+
+      def inspect
+        name + "[#{arity.low}]"
+      end
+
+      # Control that the number of actual arguments matches
+      # the relation's arity.
+      # Raise an exception if the check fails
+      # @param actuals [Array<Term>] Actuals from a goal.
+      # @return [Array<Term>] Input array if compatible with arity.
+      def check_arity(actuals)
+        unless arity.match?(actuals.size)
+          msg1 = "Count of arguments (#{actuals.size})"
+          msg2 = " is out of allowed range (#{arity.low}, #{arity.high})."
+          raise StandardError, msg1 + msg2
+        end
+
+        actuals
+      end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/core/succeed.rb

@@ -4,23 +4,27 @@ require 'singleton'
 require_relative 'duck_fiber'
 require_relative 'nullary_relation'
 
-unless MiniKraken::Core.constants(false).include? :Succeed
-  module MiniKraken
-    module Core
-      # A nullary relation that unconditionally always fails.
-      class Succeed < NullaryRelation
-        include Singleton
+module MiniKraken
+  module Core
+    # A nullary relation that always returns success outcomes.
+    class Succeed < NullaryRelation
+      include Singleton
 
-        def initialize
-          super('succeed', '#s')
-        end
+      # Constructor. Initialize the relation's name & freeze it...
+      def initialize
+        super('succeed')
+      end
 
-        def solver_for(_actuals, _env)
-          DuckFiber.new(:success)
-        end
-      end # class
-
-      Succeed.instance.freeze
-    end # module
+      # Returns a Fiber-like object (a DuckFiber).
+      # When that object receives the message resume, it will
+      # return a success 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)
+        # Important: every `solver_for` call will result in a distinct Context.
+        DuckFiber.new(-> { ctx.succeeded! })
+      end
+    end # class
   end # module
-end # unless
+end # module

data/lib/mini_kraken/core/symbol_table.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative 'scope'
+
+module MiniKraken
+  module Core
+    # A symbol table is basically a mapping from a name onto an object
+    # that holds information associated with that name. It is a data structure
+    # that keeps track of variables and their respective scope where they are
+    # declared. The key requirements for the symbol are:
+    # - To perform fast lookup operations: given a name, retrieve the corresponding
+    #   object.
+    # - To allow the efficient insertion of names and related information
+    # - To support the nesting of scopes
+    # - To handle the entry scope and exit scope events,
+    # - To cope with variable redefinition in nested scope
+    # The terminology 'symbol table' comes from the compiler design
+    # community.
+    class SymbolTable
+      # Mapping between a name and the scope(s) where it is defined
+      # @return [Hash{String => Array<Scope>}]
+      attr_reader :name2scopes
+
+      # @return [Scope] The top-level scope (= root of the tree of scopes)
+      attr_reader :root
+
+      # @return [Scope] The current scope.
+      attr_reader :current_scope
+
+      # Build symbol table with given scope as root.
+      # @param aScope [Core::Scope,NilClass] The top-level Scope
+      def initialize(aScope = nil)
+        @name2scopes = {}
+        init_root(aScope) # Set default (global) scope
+      end
+
+      # Returns iff there is no entry in the symbol table
+      # @return [Boolean]
+      def empty?
+        name2scopes.empty?
+      end
+
+      # Use this method to signal the interpreter that a given scope
+      # to be a child of current scope and to be itself the new current scope.
+      # @param aScope [Core::Scope] the Scope that
+      def enter_scope(aScope)
+        aScope.parent = current_scope
+        @current_scope = aScope
+      end
+
+      def leave_scope
+        # TODO: take dependencies between scopes into account
+
+        current_scope.defns.each_pair do |nm, _item|
+          scopes = name2scopes[nm]
+          if scopes.size == 1
+            name2scopes.delete(nm)
+          else
+            scopes.pop
+            name2scopes[nm] = scopes
+          end
+        end
+        raise StandardError, 'Cannot remove root scope.' if current_scope == root
+
+        @current_scope = current_scope.parent
+      end
+
+      # Add an entry with given name to current scope.
+      # @param anEntry [LogVar]
+      # @return [String] Internal name of the entry
+      def insert(anEntry)
+        current_scope.insert(anEntry)
+        name = anEntry.name
+        if name2scopes.include?(name)
+          name2scopes[name] << current_scope
+        else
+          name2scopes[name] = [current_scope]
+        end
+
+        anEntry.i_name
+      end
+
+      # Search for the object with the given name
+      # @param aName [String]
+      # @return [Core::LogVar]
+      def lookup(aName)
+        scopes = name2scopes.fetch(aName, nil)
+        return nil if scopes.nil?
+
+        sc = scopes.last
+        sc.defns[aName]
+      end
+
+      # Search for the object with the given i_name
+      # @param anIName [String]
+      # @return [Core::LogVar]
+      def lookup_i_name(anIName)
+        found = nil
+        scope = current_scope
+
+        begin
+          found = scope.defns.values.find { |e| e.i_name == anIName }
+          break if found
+
+          scope = scope.parent
+        end while scope
+
+        found
+      end
+
+      # Return all variables defined in the current .. root chain.
+      # Variables are sorted top-down and left-to-right.
+      def all_variables
+        vars = []
+        skope = current_scope
+        while skope
+          vars_of_scope = skope.defns.select { |_, item| item.kind_of?(LogVar) }
+          vars = vars_of_scope.values.concat(vars)
+          skope = skope.parent
+        end
+
+        vars
+      end
+
+      private
+
+      def init_root(aScope)
+        @root = valid_scope(aScope)
+        @current_scope = @root
+      end
+
+      def valid_scope(aScope)
+        aScope.nil? ? Scope.new : aScope
+      end
+    end # class
+  end # module
+end # module

data/lib/mini_kraken/core/term.rb

@@ -1,12 +1,23 @@
 # frozen_string_literal: true
 
-require_relative 'goal_arg'
+require_relative 'base_term'
 
 module MiniKraken
   module Core
-    # The generalization of any data value that can be
-    # passed as arugement to a goal.
-    class Term < GoalArg
+    # The generalization of any object that can be:
+    #   - passed as argument to a goal.
+    #   - passed as argument to a MiniKraken procedure
+    #   - contained in a compositer term,
+    #   - associated with a logical variable.
+    class Term < BaseTerm
+      # Abstract method.
+      # 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)
+        raise NotImplementedError, "Not implementation for #{self.class}."
+      end
     end # class
   end # module
 end # module

data/lib/mini_kraken/glue/dsl.rb

@@ -1,26 +1,12 @@
 # frozen_string_literal: true
 
 require 'set'
-require_relative '../core/any_value'
-require_relative '../core/conde'
-require_relative '../core/conj2'
-require_relative '../core/cons_cell'
-require_relative '../core/def_relation'
-require_relative '../core/disj2'
-require_relative '../core/equals'
-require_relative '../core/fail'
-require_relative '../core/formal_arg'
-require_relative '../core/formal_ref'
-require_relative '../glue/fresh_env'
-require_relative '../glue/fresh_env_factory'
-require_relative '../core/goal_template'
-require_relative '../core/k_boolean'
-require_relative '../core/k_symbol'
-require_relative '../core/succeed'
-require_relative '../core/variable_ref'
-require_relative 'fresh_env'
-require_relative 'run_star_expression'
 
+require_relative '../core/all_core'
+require_relative '../atomic/all_atomic'
+require_relative '../composite/cons_cell'
+require_relative '../rela/all_rela'
+require_relative 'run_star_expression'
 
 module MiniKraken
   module Glue
@@ -30,14 +16,13 @@ module MiniKraken
     module DSL
       # A run* expression tries to find all the solutions
       # that meet the given goal.
-      # @return [Core::ConsCell] A list of solutions
+      # @return [Composite::ConsCell] A list of solutions
       def run_star(var_names, goal)
         program = RunStarExpression.new(var_names, goal)
         program.run
       end
 
       def conde(*goals)
-        # require 'debug'
         args = goals.map do |goal_maybe|
           if goal_maybe.kind_of?(Array)
             goal_maybe.map { |g| convert(g) }
@@ -46,7 +31,7 @@ module MiniKraken
           end
         end
 
-        Core::Goal.new(Core::Conde.instance, args)
+        Core::Goal.new(Rela::Conde.instance, args)
       end
 
       # conj2 stands for conjunction of two arguments.
@@ -56,35 +41,32 @@ module MiniKraken
       # @param arg2 [Core::Goal]
       # @return [Core::Failure|Core::Success]
       def conj2(arg1, arg2)
-       goal_class.new(Core::Conj2.instance, [convert(arg1), convert(arg2)])
+       goal_class.new(Rela::Conj2.instance, [convert(arg1), convert(arg2)])
       end
 
       def cons(car_item, cdr_item = nil)
         tail = cdr_item.nil? ? cdr_item : convert(cdr_item)
-        Core::ConsCell.new(convert(car_item), tail)
+        Composite::ConsCell.new(convert(car_item), tail)
       end
 
-      def defrel(relationName, theFormals, &aGoalTemplateExpr)
-        start_defrel
+      def null_list
+        Composite::ConsCell.new(nil, nil)
+      end
 
+      def defrel(relationName, theFormals, aGoalExpr)
         case theFormals
           when String
-            @defrel_formals << theFormals
+            formals = [theFormals]
           when Array
-            @defrel_formals.merge(theFormals)
+            formals = theFormals
         end
 
-        formals = @defrel_formals.map { |name| Core::FormalArg.new(name) }
-        g_template = aGoalTemplateExpr.call
-        result = Core::DefRelation.new(relationName, g_template, formals)
-        add_defrel(result)
-
-        end_defrel
-        result
+        rela = Rela::DefRelation.new(relationName, aGoalExpr, formals)
+        add_defrel(rela)
       end
 
       def disj2(arg1, arg2)
-        goal_class.new(Core::Disj2.instance, [convert(arg1), convert(arg2)])
+        goal_class.new(Rela::Disj2.instance, [convert(arg1), convert(arg2)])
       end
 
       # @return [Core::Fail] A goal that unconditionally fails.
@@ -92,43 +74,26 @@ module MiniKraken
         goal_class.new(Core::Fail.instance, [])
       end
 
-      def equals(arg1, arg2)
-        # require 'debug'
-        goal_class.new(Core::Equals.instance, [convert(arg1), convert(arg2)])
+      def unify(arg1, arg2)
+        goal_class.new(Rela::Unify.instance, [convert(arg1), convert(arg2)])
       end
 
-      def fresh(var_names, goal)
-        vars = nil
-        if @dsl_mode == :defrel
-          if var_names.kind_of?(String)
-            vars = [var_names]
-          else
-            vars = var_names
-          end
-          FreshEnvFactory.new(vars, goal)
-        else
-          if var_names.kind_of?(String) || var_names.kind_of?(Core::VariableRef)
-            vars = [var_names]
-          else
-            vars = var_names
-          end
-
-          FreshEnv.new(vars, goal)
-        end
+      # @return [Core::Goal]
+      def fresh(names, subgoal)
+        # puts "#{__callee__} #{names}"
+        Rela::Fresh.build_goal(names, subgoal)
       end
 
       def list(*members)
         return null if members.empty?
 
-        head = nil
-        members.reverse_each { |elem| head = Core::ConsCell.new(convert(elem), head) }
-
-        head
+        converted = members.map { |e| convert(e) }
+        Composite::List.make_list(converted)
       end
 
       # @return [ConsCell] Returns an empty list, that is, a pair whose members are nil.
       def null
-        Core::ConsCell.new(nil, nil)
+        Composite::ConsCell.null
       end
 
       # @return [Core::Succeed] A goal that unconditionally succeeds.
@@ -143,38 +108,29 @@ module MiniKraken
 
         case anArgument
           when Symbol
-            if anArgument.id2name =~ /_\d+/
-              rank = anArgument.id2name.slice(1..-1).to_i
-              any_val = Core::AnyValue.allocate
-              any_val.instance_variable_set(:@rank, rank)
-              converted = any_val
-            elsif anArgument.id2name =~ /^"#[ft]"$/
-              converted = Core::KBoolean.new(anArgument)
-            else
-              converted = Core::KSymbol.new(anArgument)
+            case anArgument.id2name
+              when /_\d+/
+                rank = anArgument.id2name.slice(1..-1).to_i
+                any_val = Core::AnyValue.allocate
+                any_val.instance_variable_set(:@rank, rank)
+                converted = any_val
+              when /^"#[ft]"$/
+                converted = Atomic::KBoolean.new(anArgument)
+              else
+                converted = Atomic::KSymbol.new(anArgument)
             end
           when String
             if anArgument =~ /^#[ft]$/
-              converted = Core::KBoolean.new(anArgument)
+              converted = Atomic::KBoolean.new(anArgument)
             else
               msg = "Internal error: undefined conversion for #{anArgument.class}"
               raise StandardError, msg
             end
           when false, true
-            converted = Core::KBoolean.new(anArgument)
-          when Core::KBoolean
-            converted = anArgument
-          when Core::FormalRef
-            converted = anArgument
-          when FreshEnv
-            converted = anArgument
-          when Core::Goal
-            converted = anArgument
-          when Core::GoalTemplate
-            converted = anArgument
-          when Core::VariableRef
+            converted = Atomic::KBoolean.new(anArgument)
+          when NilClass, Atomic::KBoolean, Atomic::KSymbol
             converted = anArgument
-          when Core::ConsCell
+          when Core::Goal, Core::LogVarRef, Composite::ConsCell
             converted = anArgument
           else
             msg = "Internal error: undefined conversion for #{anArgument.class}"
@@ -204,7 +160,7 @@ module MiniKraken
       end
 
       def add_defrel(aDefRelation)
-        @defrels = {} unless instance_variable_defined?(:@defrels)
+        @defrels ||= {}
         @defrels[aDefRelation.name] = aDefRelation
       end
 
@@ -215,7 +171,7 @@ module MiniKraken
           result = super(mth, *args)
         rescue NameError
           name = mth.id2name
-          @defrels = {} unless instance_variable_defined?(:@defrels)
+          @defrels ||= {}
           if @defrels.include?(name)
             def_relation = @defrels[name]
             result = Core::Goal.new(def_relation, args.map { |el| convert(el) })
@@ -224,7 +180,7 @@ module MiniKraken
             if @dsl_mode == :defrel && @defrel_formals.include?(name)
               result = Core::FormalRef.new(name)
             else
-              result = Core::VariableRef.new(name)
+              result = Core::LogVarRef.new(name)
             end
           end
         end