inform-runtime 1.0.4

data/lib/runtime/command.rb

@@ -0,0 +1,470 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2023 but freely usable (see license)
+#
+# This file is part of the Inform Runtime.
+#
+# The Inform Runtime is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The Inform Runtime is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the Inform Runtime.  If not, see <http://www.gnu.org/licenses/>.
+
+# Re-open the Proc class to define #to_lambda
+class Proc
+  def to_lambda
+    return self if lambda?
+
+    # Save local reference to self so we can use it in module_exec/lambda scopes
+    source_proc = self
+
+    # Convert proc to unbound method
+    unbound_method = Module.new.module_exec do
+      instance_method(define_method(:_proc_call, &source_proc))
+    end
+
+    # Return lambda which binds our unbound method to correct receiver and calls it with given args/block
+    lambda do |*args, &block|
+      # If binding doesn't changed (eg. lambda_obj.call) then bind method to original proc binding,
+      # otherwise bind to current binding (eg. instance_exec(&lambda_obj)).
+      unbound_method.bind(self == source_proc ? source_proc.receiver : self).call(*args, &block)
+    end
+  end
+
+  def receiver
+    binding.eval('self')
+  end
+end
+
+# The Inform module
+module Inform
+  # The CommandCauseRecordNotFoundError class
+  class CommandCauseRecordNotFoundError < StandardError; end
+
+  # The Commands module
+  module Commands
+  end
+end
+
+# The PublicCommandMethods module
+module PublicCommandMethods
+  def <<(event)
+    @successors.add event
+    event.antecedent = self
+  end
+
+  def origin(x = self)
+    x = origin x.antecedent if x.antecedent
+    x.object? ? x : x.cause
+  end
+
+  def termination(x = self)
+    event = x.successors.first
+    event || x.terminus
+  end
+
+  def elemental?
+    @type == :elemental
+  end
+
+  def integral?
+    @type == :integral
+  end
+
+  def immediately?
+    @when == :immediately
+  end
+
+  def cancelled?
+    return true if future.nil?
+    future.cancelled?
+  end
+
+  def antecedent_cancelled?
+    return false if self.antecedent.nil?
+    return false unless self.antecedent.cancelled?
+    return false if self.terminus.nil?
+    log.warn "Command antecedent #{self.antecedent} was cancelled"
+    true
+  end
+
+  def concluded?
+    semaphore.synchronize { concluded == true }
+  end
+
+  def now(params = {}, &block)
+    # TODO: Determine if :cause should be overwritten
+    # by any :cause params given by the params Hash
+    Inform::Command.new({ cause: cause, antecedent: self }.merge(params), &block)
+  end
+  alias add_event now
+  alias event now
+  alias and_then now
+  alias chain now
+  alias eventually now
+  alias later now
+
+  # Shortcut for using delays
+  def delay(delay, &block)
+    Inform::Command.new({ cause: cause, antecedent: self, delay: delay }, &block)
+  end
+  alias after_delay delay
+
+  def finally(&block)
+    Inform::Command.new({ cause: cause, antecedent: self, terminus: true }, &block)
+  end
+  alias on_cancel finally
+  alias when_completed finally
+  alias when_done finally
+  alias when_finished finally
+  alias when_over finally
+  alias ultimately finally
+
+  def parse_activity
+    self.cause.parse(self.activity)
+  end
+
+  def call_activity
+    return self.activity.call(self) if self.activity.arity == 1
+    self.activity.call(*self.args)
+  end
+
+  def call
+    process self
+  end
+
+  def run
+    call
+  end
+
+  def on_failure(_cause)
+    cancelled
+  end
+
+  def on_success(_result)
+    completed
+  end
+
+  def on_cancelled_antecedent
+    schedule self unless terminus.nil?
+    successors.each(&:on_cancelled_antecedent)
+  end
+
+  def to_s
+    self.identity
+  end
+
+  RecordNotFoundErrorPattern = %r{Record not found}.freeze
+
+  def mandate_cause_record_exists!
+    self.cause.refresh
+  rescue StandardError => e
+    if RecordNotFoundErrorPattern.match?(e.message)
+      message = e.message + ' for cause of event ' + self.to_s
+      raise Inform::CommandCauseRecordNotFoundError, message
+    end
+    log.warn "Unexpected error refreshing event cause object: #{e.message}"
+  end
+
+  AttributeFieldReferenceTemplate = '@%<attribute>s'.freeze
+
+  def get_value(from, attribute)
+    return from.send(attribute) if from.respond_to?(attribute)
+    from.instance_variable_get(format(AttributeFieldReferenceTemplate, attribute: attribute).to_sym)
+  end
+
+  def warn_when_nilling_noun(from, attribute, value)
+    return unless attribute == :noun
+    return unless value.nil?
+    return if (current_value = self.send(attribute)).nil?
+    return if attribute == :parameters && current_value <= 1
+    log.warn "Overwriting #{self}.#{attribute} (#{current_value}) with #{from}.#{attribute} (nil)!"
+    log.warn " #{self}.context: #{self.context.inspect}"
+    maybe_log_nilling_warning
+  end
+
+  def maybe_log_nilling_warning
+    return if callstack.grep('channel_read')
+    ['===========', (caller[-4...] + callstack), '==========='].each { |t| log.warn t unless t.nil? }
+  end
+end
+# module PublicCommandMethods
+
+# The PrivateCommandMethods module
+module PrivateCommandMethods
+  private
+
+  def to_java_future(future)
+    future.to_java(com.google.common.util.concurrent.ListenableFuture)
+  end
+
+  # TODO: Implement a mechanism by which new event scheduling may
+  # be deferred or discarded entirely.  The reason for this is that
+  # during shutdown, there will certainly be ongoing events which
+  # require some form of state resolution.  The spinning top, for
+  # instance -- once spun, is given the spinning attribute. Now,
+  # perhaps this is unnecessary, but the case remains that the state
+  # of the top must be returned to its resting state even though the
+  # game is being shutdown.  Perhaps a special on_cancel hook could
+  # be provided for such events which require such state resolution.
+  # Otherwise, at this point, some way of deciding if incoming
+  # events are newly spawned, or if they are part of a chain of
+  # events which must be allowed to transpire for the sake of an
+  # object's state consistency.
+  # It occurs to me that this is what a message queue is for, so I
+  # need to figure out how to integrate with a message broker.
+  # rubocop: disable Metrics/AbcSize
+  def schedule(event, delay = 0)
+    raise "The event parameter may not be nil" if event.nil?
+    delay = event.time_delay.to_f * 1000 if event.time_delay > 0
+    event.future = Inform::Commands::Scheduler.schedule(event, delay, TimeUnit::MILLISECONDS)
+    Futures.addCallback(to_java_future(event.future), event, Inform::Commands::Scheduler)
+    event.cause.events << event
+    Inform::Commands::ActiveObjects << event.cause unless Inform::Commands::ActiveObjects.include?(event.cause)
+    event.future
+  end
+  # rubocop: enable Metrics/AbcSize
+
+  # rubocop: disable Metrics/AbcSize
+  # rubocop: disable Metrics/CyclomaticComplexity
+  # rubocop: disable Metrics/MethodLength
+  def process(event)
+    raise "The event parameter may not be nil" if event.nil?
+    Thread.current[:event] = event
+    event.mandate_cause_record_exists!
+    # TODO: This is probably racey so consider wrapping this in a semaphore.
+    return if event.antecedent_cancelled?
+    case event.activity
+    when String
+      result = event.parse_activity
+      # log.info "Parsed activity: #{self.activity.inspect}; result: #{result.inspect}"
+      # event.cause.inflib&.println(result)
+      event.cause.println(result)
+    when Proc
+      # event.cause.inflib&.println(event.call_activity, isolate: event.elemental?)
+      event.cause.println(event.call_activity, isolate: event.elemental?)
+    else
+      log.error "Command activity type is unknown: #{event.activity} (#{event.activity.class})"
+    end
+  rescue Inform::CommandCauseRecordNotFoundError => e
+    log.error "Error refreshing cause object: #{e.message}"
+  rescue LocalJumpError => e
+    # It is a shame that this happens.  It used to not happen, so long
+    # as event.activity was wrapped in lambda(event.activity).
+    # Then one day, this exception began to be thrown again.
+    # TODO: Either use this kludgey hack to fix it:
+    # https://stackoverflow.com/questions/2946603/ruby-convert-proc-to-lambda
+    # https://stackoverflow.com/a/24965981/328469
+    # Or, try to get jruby fixed:
+    # https://github.com/jruby/jruby/issues/4369 (2016)
+    # https://github.com/jruby/jruby/pull/4423 (2017)
+    # https://github.com/jruby/jruby/issues/4577 (2017)
+    log.warn "Command block used return keyword: #{e.message}"
+    log.debug "Local jump error: #{e.message}"
+    e.backtrace.each { |t| log.warn t }
+  rescue SystemExit => e
+    raise e
+  rescue StandardError => e
+    log.error "Unexpected error processing #{event}: #{e.message}", e
+    event.callstack.each { |t| log.error t }
+  ensure
+    Thread.current[:event] = nil
+  end
+  # rubocop: enable Metrics/AbcSize
+  # rubocop: enable Metrics/CyclomaticComplexity
+  # rubocop: enable Metrics/MethodLength
+
+  # rubocop: disable Metrics/AbcSize
+  # rubocop: disable Metrics/MethodLength
+  def invoke(event)
+    raise "The event parameter may not be nil" if event.nil?
+    event.antecedent << event if !event.antecedent.nil? && !event.antecedent.concluded?
+    se = Thread.current[:event]
+    Thread.current[:event] = event
+    log.debug "Queueing #{event}"
+    event.future = Inform::Commands.pool.java_send(:submit, [java.lang.Runnable], event)
+    Futures.addCallback(to_java_future(event.future), event, Inform::Commands.pool)
+    event.cause.events << event
+    Inform::Commands.active_objects << event.cause unless Inform::Commands.active_objects.include?(event.cause)
+    event.future.get
+    event.future
+  rescue SystemExit => e
+    raise e
+  rescue Java::JavaUtilConcurrent::CancellationException => e
+    log.warn "Cancelled #{event}"
+    log.debug "Reason for event cancellation: #{e}"
+  rescue Java::JavaUtilConcurrent::ExecutionException => e
+    log.error "Command execution exception: #{e.message}"
+  rescue StandardError => e
+    log.error "Unexpected error invoking #{event}: #{e.message}", e
+    event.callstack.each { |t| log.error t }
+  ensure
+    Thread.current[:event] = se
+  end
+  # rubocop: enable Metrics/AbcSize
+  # rubocop: enable Metrics/MethodLength
+
+  def deactivate(obj)
+    raise "The obj parameter may not be nil" if obj.nil?
+    obj.events.remove self
+    Inform::Commands::ActiveObjects.remove obj if obj.events.empty?
+  end
+
+  def cancelled
+    successors.each(&:on_cancelled_antecedent)
+  rescue StandardError => e
+    log.error "Error cancelling #{self}: #{e.message}", e
+  ensure
+    deactivate cause
+  end
+
+  # rubocop: disable Metrics/AbcSize
+  # rubocop: disable Metrics/CyclomaticComplexity
+  def completed
+    semaphore.synchronize { self.concluded = true }
+    return if !antecedent.nil? && antecedent.cancelled? && terminus.nil?
+    return if cancelled? && terminus.nil?
+    successors.each { |event| schedule event }
+  rescue StandardError => e
+    log.error "Error completing #{self}: #{e.message}", e
+  ensure
+    deactivate cause
+  end
+  # rubocop: enable Metrics/AbcSize
+  # rubocop: enable Metrics/CyclomaticComplexity
+end
+# module PrivateCommandMethods
+
+# The CommandInitializationMethods module
+module CommandInitializationMethods
+  CommandNameTemplate = 'event:%<time>s'.freeze
+
+  # rubocop: disable Metrics/AbcSize
+  # rubocop: disable Metrics/MethodLength
+  # rubocop: disable Lint/LambdaWithoutLiteralBlock
+  def init_fields(params, &block)
+    @successors = defined?(Java) ? java.util.concurrent.CopyOnWriteArrayList.new : []
+    @time = Time.ms
+    @cause = params[:cause]
+    @name = params.fetch(:name, format(CommandNameTemplate, time: @time))
+    @args = params[:args]
+    # TODO: FIXME This causes an error:
+    # Command block used return keyword: unexpected return
+    @activity = params.fetch(:activity, block_given? ? lambda(&block) : @name)
+    # Converting a given block to a lambda supposedly enables the use of return
+    # statements inside the event activity blocks.
+    # TODO: Cite documentation source.
+    # TODO: Implement tests.
+    # @activity = params.fetch(:activity, block_given? ? block.to_lambda : @name)
+    @antecedent = params[:antecedent]
+    @time_delay = params.fetch(:delay, 0)
+    @terminus = params[:terminus] ? self : nil
+    @type = params.fetch(:type, :integral)
+    @when = params.fetch(:when, :eventually)
+    @callstack = caller.slice((%i[immediately elementally].include?(@when) ? 4 : 3)..-1)
+    @concluded = false
+    @cause = @cause.player if @cause.is_a? InformLibrary
+    @identity = generate_identity
+    @context = params[:context]
+  end
+  # rubocop: enable Metrics/AbcSize
+  # rubocop: enable Metrics/MethodLength
+  # rubocop: enable Lint/LambdaWithoutLiteralBlock
+
+  CommandCauseIdentityTemplate = '%<identity>s:%<name>s'.freeze
+  CommandSourceTemplate = ':%<source_location>s:%<source_line_number>s'.freeze
+  CommandSourceFullTemplate = ':%<method_name>s:%<source_location>s:%<source_line_number>s'.freeze
+  CommandActivityTemplate = ':%<activity>s'.freeze
+  CommandAntecedantTemplate = ' < %<antecedent>s'.freeze
+  CallerPattern = %r{([^:]+):([^:]+):in `([^']+)'}.freeze
+
+  # rubocop: disable Metrics/AbcSize
+  # rubocop: disable Metrics/MethodLength
+  def generate_identity
+    s = format(CommandCauseIdentityTemplate, identity: @cause.identity, name: @cause.name)
+    if !callstack.empty?
+      trace = @callstack.first.gsub(Inform::Runtime.project_dir_path, '')
+      location, line_number, method_name = CallerPattern.match(trace)&.captures
+      s << format(CommandSourceFullTemplate,
+        method_name: method_name, source_location: location, source_line_number: line_number)
+    elsif @activity.respond_to?(:source_location) || @activity.is_a?(Proc)
+      activity_source_location_enumerator = @activity.source_location.each
+      source_location = activity_source_location_enumerator.next.gsub(Inform::Runtime.project_dir_path, '')
+      source_line_number = activity_source_location_enumerator.next
+      s << format(CommandSourceTemplate, source_location: source_location, source_line_number: source_line_number)
+    elsif name != @activity.to_s
+      s << format(CommandActivityTemplate, activity: @activity)
+    end
+    s << format(CommandAntecedantTemplate, antecedent: @antecedent) unless @antecedent.nil?
+    s
+  end
+  # rubocop: enable Metrics/AbcSize
+  # rubocop: enable Metrics/MethodLength
+
+  def init_context(context, antecedent, cause)
+    return contextualize(context) unless context.nil?
+    if antecedent&.cause.respond_to?(:inflib)
+      return contextualize(antecedent.cause.inflib) unless antecedent&.cause&.inflib.nil?
+    end
+    contextualize(cause) unless cause.nil? # TODO: Maybe remove
+  end
+
+  def defer(event)
+    event.antecedent << event
+  end
+
+  def schedule_or_defer(event)
+    return defer(event) if !event.antecedent.nil? && !event.antecedent.concluded?
+    schedule(event) if event.antecedent.nil? || event.antecedent.cancelled?
+  end
+end
+# module CommandInitializationMethods
+
+# The Inform module
+module Inform
+  # The Inform::Command class
+  class Command
+    attr_accessor :future
+    attr_reader :time, :name, :args, :type, :context, :semaphore, :identity
+
+    # Note that block if given is converted to lambda.  This enables
+    # the use of return statements inside the event activity blocks.
+    def initialize(params = {}, &block)
+      @semaphore = Mutex.new
+      init_fields(params, &block)
+      init_context(@context)
+      puts "Invoking #{self}"
+      invoke(self)
+      # @when == :immediately ? invoke(self) : schedule_or_defer(self)
+    end
+
+    def init_context(context)
+      return if context.nil?
+      contextualize(context)
+    end
+
+    def contextualize(from)
+      # log.info "Initializing context for command #{self} from #{from} (#{from.class})"
+      Inform::Context.get.members.each do |attribute|
+        value = get_value(from, attribute)
+        warn_when_nilling_noun(from, attribute, value)
+        setter_method = format('%<attribute>s=', attribute: attribute).to_sym
+        send(setter_method, value)
+      end
+    end
+
+    private
+
+    include CommandInitializationMethods
+  end
+  # class Command
+end
+# module Inform

data/lib/runtime/config.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2023 but freely usable (see license)
+#
+# This file is part of the Inform Runtime.
+#
+# The Inform Runtime is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The Inform Runtime is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the Inform Runtime.  If not, see <http://www.gnu.org/licenses/>.
+
+# The Inform module
+module Inform
+  RUNTIME_DIR_PATH = File.expand_path(__dir__) unless defined?(RUNTIME_DIR_PATH)
+  LIB_DIR_PATH = File.expand_path(File.dirname(RUNTIME_DIR_PATH)) unless defined?(LIB_DIR_PATH)
+  INFORM_DIR_PATH = 'inform'.freeze unless defined?(INFORM_DIR_PATH)
+  PROJECT_DIR_PATH = File.expand_path(File.dirname(LIB_DIR_PATH)) unless defined?(PROJECT_DIR_PATH)
+
+  # The Config class
+  class Config
+    DEFAULTS = {
+      environment: 'default',
+      admin: false,
+      language: 'English',
+      game_path: File.expand_path(File.join(PROJECT_DIR_PATH, 'game')),
+      game_dir_name: 'game',
+      game_grammar_module_name: 'grammar',
+      game_config_file_name: 'config.yml',
+      game_components: 'modules world models rules verbs languages', # This order is required
+      properties: 'player actor action action_to_be ' \
+        'results parameters pattern ' \
+        'noun second inp1 inp2 ' \
+        'special_word special_number special_number1 special_number2 ' \
+        'consult_words match_from wn verb_wordnum words ' \
+        'parser_action parser_one parser_two scope_reason',
+      log_level: Logger::INFO
+    }.freeze
+  end
+end

data/lib/runtime/context.rb

@@ -0,0 +1,78 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2023 but freely usable (see license)
+#
+# This file is part of the Inform Runtime.
+#
+# The Inform Runtime is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The Inform Runtime is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the Inform Runtime.  If not, see <http://www.gnu.org/licenses/>.
+
+# The Inform module
+module Inform
+  def self.context_class
+    Inform::Context.definition || Inform::Context.set(Inform::Runtime.invocation_context)
+  end
+
+  def self.context
+    context_class.new
+  end
+
+  # Define Context module
+  module Context
+    Registry = Struct.new(:memo).new(nil)
+    def definition
+      Inform::Context::Registry.memo
+    end
+    module_function :definition
+
+    def get
+      Inform::Context.definition
+    end
+    module_function :get
+
+    AttributeFieldReferenceTemplate = '@%<attribute>s'.freeze
+
+    def get_value(from, attribute)
+      return from.send(attribute) if from.respond_to?(attribute)
+      from.instance_variable_get(format(AttributeFieldReferenceTemplate, attribute: attribute).to_sym)
+    end
+    module_function :get_value
+
+    AttributeSetterMethodTemplate = '%<attribute>s='.freeze
+
+    def setter_method(attribute)
+      format(AttributeSetterMethodTemplate, attribute: attribute).to_sym
+    end
+    module_function :setter_method
+
+    def each_attribute(obj)
+      get&.members&.each do |attribute|
+        yield(attribute, get_value(obj, attribute))
+      end
+    end
+    module_function :each_attribute
+
+    def set(definition)
+      Inform::Context::Registry.memo = definition
+      get&.members&.each do |attribute|
+        Inform::Command.send(:attr_accessor, attribute) unless Inform::Command.respond_to? attribute
+        Inform::Event.send(:attr_accessor, attribute) unless Inform::Event.respond_to? attribute
+      end
+      definition
+    end
+    module_function :set
+  end
+  # module Context
+end
+# module Inform