inform-runtime 1.0.4

data/lib/runtime/stdlib.rb

@@ -0,0 +1,604 @@
+# 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
+# These are built-ins primarily found used in the InformLibrary.
+module StdLib
+  def debug(n = nil)
+    if n.nil?
+      toggle_constant :DEBUG
+    else
+      @parser_trace = n
+      reset_constant :DEBUG, true
+    end
+  end
+
+  def executable
+    Runtime.main_gem_spec_executable
+  end
+
+  def inversion
+    print Inform::VERSION
+  end
+
+  def standard_interpreter
+    0
+  end
+
+  def version_number
+    0
+  end
+
+  def flush_automatically
+    toggle_constant :FLUSH_IO_INSTANTLY
+  end
+
+  def export(o, type = :xml)
+    o.send('export_' + type) if !o.nil? && o.respond_to?(('export_' + type).to_sym)
+  end
+
+  DotPattern = %r{\.}.freeze
+  UnderscoreString = '_'.freeze
+
+  def import_object(file)
+    type = File.extname(file)
+    return if type.nil?
+    send('import_object_' + type.gsub(DotPattern, UnderscoreString), file)
+  end
+
+  DefaultXMLAssociations = %i[tagged modularized].freeze
+
+  def import_object_xml(file, associations = DefaultXMLAssociations)
+    return unless defined? Nokogiri
+    return if file.nil?
+    Inform::Object.from_xml(File.open(file), associations: associations)
+  end
+
+  def import_object_yaml(file)
+    return unless defined? YAML
+    return if file.nil?
+    YAML.safe_load(File.read(file))
+  end
+  alias import_object_yml import_object_yaml
+
+  def import_object_json(file)
+    return unless defined? JSON
+    return if file.nil?
+    JSON.parse(File.read(file))
+  end
+
+  def consume_remaining_text
+    s = preceding_text
+    @wn = num_words
+    remaining_text = @input[s.length..]
+    remaining_text ? remaining_text.strip : ''
+  end
+
+  def preceding_text
+    @words[0..(@wn - 1)].join(' ')
+  end
+
+  def pcount
+    @pattern ? @pattern.length - 1 : 0
+  end
+
+  def location
+    @player.location
+  end
+
+  def location=(o)
+    log.warn "Trying to set the location directly"
+    log.warn caller[1] and abort
+    @player.location = o
+  end
+
+  def area
+    location&.area
+  end
+
+  # Stubs
+  #
+  # Designers may override these.
+
+  def ADirection(*)
+    compass.include?(noun)
+  end
+
+  def StatusLineHeight; end
+
+  def ScoreSub
+    false
+  end
+
+  def FullScoreSub
+    false
+  end
+
+  def DisplayStatus
+    false
+  end
+
+  def Message(*args)
+    println(args[:fatalerror] || args.values.first)
+  end
+
+  def BeginActivity(*)
+    false
+  end
+
+  def EndActivity(*)
+    false
+  end
+
+  def ForActivity(*)
+    false
+  end
+
+  def silently(*)
+    k = @keep_silent; @keep_silent = true
+    yield
+  ensure
+    @keep_silent = k
+  end
+
+  # rubocop: disable Metrics/AbcSize
+  # rubocop: disable Metrics/MethodLength
+  def invocation_context(action, *args)
+    ctx = Inform.context
+    ctx.results = [
+      ctx.action = ctx.action_to_be = action,
+      ctx.parameters = args.length,
+      ctx.noun = ctx.inp1 = args.shift,
+      ctx.second = ctx.inp2 = args.shift
+    ]
+    ctx.pattern = [
+      ctx.results[0].to_s.downcase,
+      ctx.results[2],
+      ctx.results[3]
+    ]
+    ctx.actor = player
+    ctx.special_number1 = ctx.special_number2 = nil
+    ctx.special_number1 = ctx.results[2] if ctx.results[2].number?
+    ctx.special_number2 = ctx.results[3] if ctx.results[3].number?
+    ctx.special_word = args.shift
+    ctx.consult_words = args.shift
+    ctx.consult_words = ctx.special_word = ctx.results[2] if ctx.results[2].is_a?(String)
+    ctx.consult_words = ctx.special_word = ctx.results[3] if ctx.results[3].is_a?(String)
+    ctx.match_from = ctx.wn = ctx.verb_wordnum = 0
+    ctx.words = []
+    ctx
+  end
+  # rubocop: enable Metrics/AbcSize
+  # rubocop: enable Metrics/MethodLength
+
+  # The invoke method executes without prompting afterward
+  # but appends the output to the contextual event's buffer
+  # which will be displayed upon completion of the contextual
+  # event.
+  #
+  # TODO: Test: Does this mean that invoke must always be executed
+  # within an event context to have its output displayed?
+  # !rubocop: disable Metrics/AbcSize
+  def invoke(action, *args)
+    raise "The action parameter may not be nil" if action.nil?
+
+    # log.debug 'Invocation: ' + name(@player) + ' <' + action + (args.empty? ? '' : ' ') + args.to_s + '>'
+    ctx = invocation_context(action, *args)
+    immediately(ctx) do
+      if BeforeRoutines(action) == false
+        send(VerbRoutine(action))
+      end
+    end
+  end
+  # !rubocop: enable Metrics/AbcSize
+
+  # Under invoke execute a routine but tries to prevent
+  # any output at all and does not provide other objects
+  # the opportunity to react to the action, like invoke
+  # does, above.
+  #
+  # This should be used to delegate an action outcome to
+  # another Verb action subroutine.  It should appear as
+  # if the invoked action is part of the original action.
+  # !rubocop: disable Metrics/AbcSize
+  def _invoke(action, *args)
+    raise "The action parameter may not be nil" if action.nil?
+
+    # log.debug 'Invocation: ' + name(@player) + ' <<' + action + (args.empty? ? '' : ' ') + args.to_s + '>>'
+    ctx = invocation_context(action, *args)
+    elementally(ctx) do
+      silently do
+        send(VerbRoutine(action))
+      end
+    end
+  end
+  # !rubocop: enable Metrics/AbcSize
+  alias silently_invoke _invoke
+
+  # rubocop: disable Metrics/AbcSize
+  # rubocop: disable Metrics/CyclomaticComplexity
+  # rubocop: disable Metrics/PerceivedComplexity
+  def indirect(action, *args)
+    return false if action.nil?
+    # raise "The action parameter may not be nil" if action.nil?
+    action = action.to_sym
+    subroutine = VerbRoutine(action, fail_on_error: false)
+    contextualize # TODO: Test removal
+    # Direct objects might need library built-ins
+    # noun.inflib = actor.inflib if (!noun.nil?) && noun.object? && noun.inflib.nil?
+    # second.inflib = actor.inflib if (!second.nil?) && second.object? && second.inflib.nil?
+    @noun.inflib = self if !@noun.nil? && @noun.object? && @noun.inflib.nil?
+    @second.inflib = self if !@second.nil? && @second.object? && @second.inflib.nil?
+    return send(subroutine, *args) if respond_to? subroutine
+    return send(action, *args) if respond_to? action
+    false
+  end
+  # rubocop: enable Metrics/AbcSize
+  # rubocop: enable Metrics/CyclomaticComplexity
+  # rubocop: enable Metrics/PerceivedComplexity
+
+  ParseRoutineString = '_parse_routine'.freeze
+  SubString = 'Sub'.freeze
+  DefaultVerbRoutineOptions = { fail_on_error: true }.freeze
+
+  # rubocop: disable Metrics/AbcSize
+  # rubocop: disable Metrics/MethodLength
+  # rubocop: disable Metrics/CyclomaticComplexity
+  # rubocop: disable Metrics/PerceivedComplexity
+  def VerbRoutine(action, opts = {})
+    raise 'The action parameter may not be nil' if action.nil?
+    opts = DefaultVerbRoutineOptions.merge(opts)
+    if action.respond_to?(:underscore) && respond_to?(
+      sub_routine = (action.underscore(downcase: false) + ParseRoutineString))
+      sub_routine.to_sym
+    elsif respond_to?(sub_routine = (action + SubString))
+      sub_routine.to_sym
+    elsif respond_to?(sub_routine = (action.camelize + SubString))
+      sub_routine.to_sym
+    elsif action.respond_to?(:snake_case) && respond_to?(sub_routine = action.snake_case)
+      sub_routine.to_sym
+    elsif respond_to?(sub_routine = action)
+      sub_routine.to_sym
+    elsif opts[:fail_on_error]
+      raise NoVerbRoutine, 'Please define a verb subroutine for the action ' + action
+    else
+      log.warn "Please define a verb subroutine for the action #{action}"
+      false
+    end
+  end
+  # rubocop: enable Metrics/AbcSize
+  # rubocop: enable Metrics/MethodLength
+  # rubocop: enable Metrics/CyclomaticComplexity
+  # rubocop: enable Metrics/PerceivedComplexity
+
+  PrimaryHandlers = %i[before after life].freeze
+  SynchronousHandlers = PrimaryHandlers + %i[react_before].freeze
+  ReactionHandlers = SynchronousHandlers + %i[react_after].freeze
+
+  # Hack for Ruby so we can do action-specific reaction handlers.
+  # With Inform, one can just implement before [; Whatever: "hi" ]
+  # on an Object and include some action-specifying cases as if the
+  # before method were a functional switch or case statement.
+  # rubocop: disable Metrics/AbcSize
+  # rubocop: disable Metrics/MethodLength
+  # rubocop: disable Metrics/CyclomaticComplexity
+  # rubocop: disable Metrics/PerceivedComplexity
+  # rubocop: disable Style/ReturnNilInPredicateMethodDefinition
+  def reacts_to?(obj, prop, *args)
+    raise "Nothing is not an object" if obj.nil?
+    return false unless ReactionHandlers.include?(prop)
+    # TODO: Only apply Behavior modules if object is not being controlled
+    # by a player.
+    obj.apply_modules if obj.respond_to?(:apply_modules)
+    si = obj.inflib
+    obj.inflib = self
+
+    # TODO: I have prototyped a possible Inform-esque
+    # switch-style dsl for reaction methods based on
+    # action name.  Here, the prop would be sent the
+    # object normally, but the object reaction method
+    # would contain a series of method invocations with
+    # a block parameter.  If any of the method missing
+    # invocations method name parameter resembled the
+    # action name, then the given block would get
+    # executed on the subject, thereby simulating the
+    # Inform-style functional switch idiom. Like this:
+    #
+    #   def method_missing(method, *args, &block)
+    #     return yield if method == action
+    #     super
+    #   end
+    #
+    #   def before
+    #     Touch {
+    #       publish The(self) + " shudders."
+    #       println "Your skin crawls."
+    #       true
+    #     }
+    #     Show {
+    #       publish The(self) + " is uninterested in " + the(noun) + "."
+    #       "Nothing special."
+    #     }
+    #   end
+    #
+
+    # TODO: Zarf has recommended implementing a check for code persisted as
+    # a property of an observant object.  For instance:
+    # object:
+    #   properties:
+    #     ---
+    #     before:
+    #       ---
+    #       Touch: publish The(self) + "shudders."; println "Your skin crawls."; true
+
+    # To preserve support for a game designer to implement catch-all
+    # reactions by observant objects, just have the receiver object
+    # read the action variable in order to determine course.  For example:
+    #
+    #   def before
+    #     case action
+    #     when :Poke then println "Keep your hands to yourself!"
+    #
+    if PrimaryHandlers.include?(prop) && obj.respond_to?(prop)
+      # contextualize
+      # obj.contextualize
+      # TODO: Test
+      context_action = Thread.current[:event]&.action
+      log.debug "Inform#reacts_to?(obj=#{obj}, prop=#{prop}) action: #{context_action}"
+      if (result = obj.send(prop, *args))
+        return result
+      end
+    end
+
+    # TODO: TESTME Confirm that using the parser's @action variable
+    # is sufficiently reliable for composing reaction handler methods.
+    # As of 2021-07-21, there appears to be some evidence that using
+    # the #invoke method to generate reaction callbacks here is not
+    # usable with the @action approach. Apparently, @action is the least
+    # reliable because it can include a leftover value from a previous
+    # interaction, since the #invoke method does not set the value on
+    # the library (and nor should it, since #invoke is for ad-hoc events).
+    # The longer term and more correct fix here is likely to consolidate
+    # all references to @action as simply action which would pull from an
+    # event context. For now I think that I'll simply include @action at
+    # the end of the chain, in order to ensure that some action is
+    # available for reaction handler method reference construction.
+    # act = obj.action || action || @action
+    # act = @action || obj.inflib.action || action
+    # act = obj.inflib.action || action
+    # act = obj.inflib.action || action || @action
+    act = Thread.current[:event]&.action || action || @action
+    # TODO: Remove debug logging here.
+    # log.debug "Inform#reacts_to? #{prop}"
+    # log.debug "  #{self}.@action: #{@action}"
+    # log.debug "  #{obj.inflib}.action: #{obj.inflib.action}"
+    # log.debug "  #{Thread.current[:event]}.current.thread.event.action: #{action}"
+    # log.debug "  act: #{act}"
+    if act.nil?
+      log.warn "Failed to reference action invoking #reacts_to?"
+      return nil
+    end
+    reaction = "#{prop}_#{act}"
+    # log.debug "obj: #{obj.identity}, reaction: #{reaction}"
+    # log.debug "obj.respond_to?(reaction.downcase!):"
+    # log.debug "  #{obj.respond_to?(reaction.downcase!)} (#{obj.respond_to?(reaction)})"
+    if obj.respond_to?(reaction)
+      handler = obj.method(reaction)
+    elsif obj.respond_to?(reaction.downcase!)
+      handler = obj.method(reaction)
+    else
+      return nil # false
+    end
+    log.debug "Found reaction handler for #{obj}.#{reaction}: #{handler}"
+    if SynchronousHandlers.include?(prop)
+      # Go ahead and print any string results from designer-implemented
+      # handlers, and return true if there are any.
+      # contextualize
+      result = obj.instance_exec(*args, &handler)
+      return result unless result.is_a?(String)
+      println result
+      return true
+    end
+    # ctx = invocation_context(@action, @noun, @second, @special_word, @consult_words)
+    ctx = invocation_context(act, noun, second, special_word, consult_words)
+    obj.register_callback(ctx, *args, &handler)
+    # Because of the event-oriented nature of actions in a multiplayer
+    # system, other objects may not interfere with original actions
+    # once they have taken place. So, false must always be returned.
+    # However, game designers must still have the ability to direct an
+    # object, particular an animate one, to respond to an action if
+    # appropriate.
+    nil # false
+  rescue StandardError => e
+    log.error "Error getting reaction from #{obj}", e
+    e.backtrace.each { |t| log.error t }
+  ensure
+    obj.inflib = si
+  end
+  # rubocop: enable Metrics/AbcSize
+  # rubocop: enable Metrics/MethodLength
+  # rubocop: enable Metrics/CyclomaticComplexity
+  # rubocop: enable Metrics/PerceivedComplexity
+  # rubocop: enable Style/ReturnNilInPredicateMethodDefinition
+end
+# module StdLib
+
+# ------------------------------------------------------------------------------
+#  Final task: provide trivial routines if the user hasn't already:
+# ------------------------------------------------------------------------------
+
+# The StdLib module
+# TODO: Decide if these should go somewhere else. Inform 6 has them
+# in the standard library grammar.inf.
+module StdLib
+  def AfterLife(*)
+    false
+  end
+
+  def AfterPrompt(*)
+    false
+  end
+
+  def Amusing(*)
+    false
+  end
+
+  def BeforeParsing(*)
+    false
+  end
+
+  def ChooseObjects(_object, _code)
+    2
+  end
+
+  def DarkToDark(*)
+    false
+  end
+
+  def DeathMessage(*)
+    false
+  end
+
+  def Epilogue(*)
+    false
+  end
+
+  def GamePostRoutine(*)
+    false
+  end
+
+  def GamePreRoutine(*)
+    false
+  end
+
+  def InScope(*)
+    true
+  end
+
+  def LookRoutine(*)
+    false
+  end
+
+  def NewRoom(*)
+    false
+  end
+
+  def ObjectDoesNotFit(*)
+    2
+  end
+
+  def ParseNumber(*)
+    2
+  end
+
+  def ParserError(*)
+    true
+  end
+
+  def PrintTaskName(*)
+    true
+  end
+
+  def PrintVerb(*)
+    true
+  end
+
+  def TimePasses(*)
+    false
+  end
+
+  def UnknownVerb(verb, *)
+    verb
+  end
+
+  unless defined? ParseNoun
+  # ----------------------------------------------------------------------------
+  # To do the job of parsing the name property (if parse_name hasn’t done it
+  # already). This takes one argument, the object in question, and returns a
+  # value as if it were a parse_name routine.
+  #
+  # ParseNoun returns the number of words matched, or 0 if there is no match,
+  # or -1 to decline to make a decision and give the job back to the parser.
+  # Note that if -1 is returned, the word number variable wn must be left set
+  # to the first word the parser should look at -- probably the same value it
+  # had when ParseNoun was called, but not necessarily.
+  # ----------------------------------------------------------------------------
+
+  # rubocop: disable Lint/SelfAssignment
+  # rubocop: disable Lint/UselessAssignment
+  def ParseNoun(obj); obj = obj; return -1; end
+  # rubocop: enable Lint/SelfAssignment
+  # rubocop: enable Lint/UselessAssignment
+  end
+  # ParseNoun
+
+# ==============================================================================
+end
+# module StdLib
+
+# The StdLib module to re-define the InScope method
+# rubocop: disable Metrics/AbcSize
+# rubocop: disable Lint/DuplicateMethods
+module StdLib
+  # ----------------------------------------------------------------------------
+  #  (From the Inform Designer's Manual)
+  #  §32 Scope and what you can see
+  # ----------------------------------------------------------------------------
+  #  "In scope" roughly means "the compass directions, what you're carrying
+  #  and what you can see". It exactly means this:
+  #
+  #  1. the compass directions;
+  #  2. the player's immediate possessions;
+  #  3. if there is light, then the contents of the player's visibility
+  #     ceiling (see §21 for definition, but roughly speaking the
+  #     outermost object containing the player which remains visible,
+  #     which is usually the player's location);
+  #  4. if there is darkness, then the contents of the library's object
+  #     thedark (by default there are no such contents, but some
+  #     designers have been known to move objects into thedark: see
+  #     'Ruins');
+  #  5. if the player is inside a container, then that container;
+  #  6. if O is in scope and is see-through (see §21), then the contents of O;
+  #  7. if O is in scope, then any object which it "adds to scope".
+  # ----------------------------------------------------------------------------
+
+  def InScope(obj, scope = [])
+    # This routine may be overridden at the designer's discretion.
+    # Returning false here, and leaving the rest of the code in place
+    # as instructions for how to go about assembling a scope.
+    # Note to designers: remove this line in your override.
+    return false if true # rubocop: disable Lint/LiteralAsCondition
+    return false if obj.nil?
+    scope |= InformLibrary::Compass.descendants.flatten # 1
+    scope |= @player.descendants.flatten                # 2
+    scope |= @visibility_ceiling.descendants.flatten    # 3
+    scope |= thedark.descendants.flatten                # 4
+    scope |= @player.parent if @player.parent.hasany?(:container, :supporter) # 5
+    scope |= scope.collect { |o| o.descendants if o.has?(:transparent) }.flatten # 6
+    scope |= scope.select { |o| o.&(:add_to_scope) }.flatten                     # 7
+    return scope.include?(obj)
+  end
+end
+# rubocop: enable Metrics/AbcSize
+# rubocop: enable Lint/DuplicateMethods
+# module StdLib
+end
+# module Inform

data/lib/runtime/subscription.rb

@@ -0,0 +1,47 @@
+# 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
+  # The Subscribers module
+  module Subscribers
+    REGISTRY = Struct.new(:memo).new(defined?(Java) ? java.util.concurrent.ConcurrentHashMap.new : {})
+
+    def subscribe(obj)
+      explicit_subscribers << obj
+    end
+
+    def unsubscribe(obj)
+      explicit_subscribers.delete(obj)
+    end
+
+    def unsubscribe_all
+      explicit_subscribers.clear
+    end
+
+    def subscribers
+      explicit_subscribers.dup
+    end
+
+    def explicit_subscribers
+      Inform::Subscribers::REGISTRY.memo[identity] ||= []
+    end
+  end
+end