inform-runtime 1.0.4 → 1.2.0

data/lib/story_teller/library/bootstrap.rb

@@ -0,0 +1,66 @@
+# lib/story_teller/library/bootstrap.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller 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 StoryTeller 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 StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+# The StoryTeller module
+module StoryTeller
+  # The StoryTeller::Library module
+  module Library
+    # The StoryTeller::Library::Bootstrap module
+    module Bootstrap
+      module_function
+
+      def ensure_location(inflib)
+        return if inflib.nil?
+        return if inflib.location
+
+        player_obj = inflib.player
+        location = player_obj&.location
+        location ||= player_obj&.spawn_point if player_obj.respond_to?(:spawn_point)
+        inflib.instance_variable_set(:@location, location)
+      end
+
+      def set_selfobj(inflib, player)
+        inflib.selfobj = player unless player.nil?
+      end
+
+      # rubocop: disable Metrics/MethodLength
+      def manage_inform_library(player: nil, key: StoryTeller::Engine, &block)
+        inflib = StoryTeller::Engine.libraries[key]
+        unless inflib.nil? || player.nil?
+          set_selfobj(inflib, player)
+          return inflib
+        end
+
+        inflib = block_given? ? block.call : InformLibrary.new
+        return nil if inflib.nil?
+
+        set_selfobj(inflib, player)
+        inflib.subscribe(inflib.selfobj)
+        ensure_location(inflib)
+        StoryTeller::Engine.libraries[key] = inflib
+      end
+      # rubocop: enable Metrics/MethodLength
+    end
+    # module Bootstrap
+  end
+  # module Library
+end
+# module StoryTeller

data/lib/story_teller/library/declarations.rb

@@ -0,0 +1,53 @@
+# story/library/declarations.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller 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 StoryTeller 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 StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+# The StoryTeller module
+module StoryTeller
+  # The StoryTeller::Library module
+  module Library
+    # The StoryTeller::Library::Declarations class
+    class Declarations
+      attr_reader :properties, :attributes, :globals
+
+      def initialize
+        reset!
+      end
+
+      def reset!
+        @properties = Hash.new { |hash, key| hash[key] = [] }
+        @attributes = Set.new
+        @globals = []
+      end
+
+      def add_attribute(attribute)
+        @attributes << attribute
+      end
+
+      def add_property(property, value)
+        @properties[property] << value
+      end
+
+      def add_global(symbol)
+        @globals << symbol
+      end
+    end
+  end
+end

data/lib/story_teller/library/directives.rb

@@ -0,0 +1,91 @@
+# story/library/directives.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller 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 StoryTeller 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 StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+# The StoryTeller module
+module StoryTeller
+  # The StoryTeller::Library module
+  module Library
+    # The StoryTeller::Library::Directives module
+    module Directives
+      InclusionGrammarGuessTemplate = '%<inclusion>s.h.inf.rb'.freeze
+      InclusionGuessesTemplate = '%<inclusion>s.h'.freeze
+      PropertyModifiers = %i[additive].freeze
+
+      module_function
+
+      def Link(link)
+        # TODO: Implement
+        # Not a high priority, because in the original Inform6 links were
+        # effectively just pointers to objects loaded in memory, and so
+        # were ephemeral in nature.
+      end
+
+      def Include(inclusion)
+        # warn "StoryTeller::Engine.Include(#{inclusion}) from #{caller_locations(1, 5).map { |l|
+        #   "#{l.path}:#{l.lineno}"
+        # }.join(' | ')}"
+        inclusion = StoryTeller::Engine.language_name if /^language__$/.match(inclusion)
+        grammar_guess = format(InclusionGrammarGuessTemplate, inclusion: inclusion)
+        guess = File.expand_path(
+          File.join(
+            StoryTeller::Library.inform_gem_lib_path,
+            StoryTeller::Engine.inform_code_prefix,
+            grammar_guess))
+        return StoryTeller::Library::Loader.load_grammar_by_path(guess) if File.exist?(guess)
+        StoryTeller::Library::Loader.require_first_existing(
+          format(InclusionGuessesTemplate, inclusion: inclusion).split)
+      end
+
+      def Attribute(attribute)
+        StoryTeller::Library.declarations.add_attribute(attribute)
+      end
+
+      def Property(*args)
+        if PropertyModifiers.include?(modifier_or_property = args.shift)
+          StoryTeller::Library.declarations.add_property(args.shift, args.shift)
+        else
+          StoryTeller::Library.declarations.add_property(modifier_or_property, args.shift)
+        end
+      end
+
+      def Default(property, value)
+        Constant(property, value)
+      end
+
+      def Constant(constant, value, target = ::Object)
+        return if constant.nil?
+        silence_warnings do
+          target.instance_eval { const_set(constant.to_sym, value) }
+        end
+      rescue StandardError => e
+        log.error "Unexpected error resetting constant #{constant}", e
+        nil
+      end
+
+      def import_global(symbol)
+        StoryTeller::Library.declarations.add_global(symbol)
+      end
+    end
+    # module Directives
+  end
+  # module Library
+end
+# module StoryTeller

data/lib/story_teller/library/loader.rb

@@ -0,0 +1,104 @@
+# lib/story_teller/library/loader.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller 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 StoryTeller 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 StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+# The StoryTeller module
+module StoryTeller
+  # The StoryTeller::Library module
+  module Library
+    GEM_NAME = 'inform6lib'.freeze
+    GEM_PATH = Gem.loaded_specs[GEM_NAME]&.full_gem_path or raise "The #{GEM_NAME} gem is required"
+
+    class LibraryLoadError < StandardError; end
+
+    # The Library::Loader module provides methods for loading Library files.
+    module Loader
+      module_function
+
+      def augment_inform_library!
+        ensure_inform_object_model!
+        InformLibrary.extend(StoryTeller::Engine::Library)
+        InformLibrary.class_eval do
+          include Inform::Context unless include?(Inform::Context)
+          include Inform::StdLib unless include?(Inform::StdLib)
+        end
+        InformLibrary.prepend(StoryTeller::Library::Location)
+      end
+
+      def load_library
+        augment_inform_library!
+        StoryTeller::Library::Bootstrap.manage_inform_library
+      end
+
+      def inform_object_model?
+        object_class = StoryTeller::ModelAdapter.object_class
+        return false if object_class.nil?
+
+        object_class.method_defined?(:<<) &&
+          object_class.method_defined?(:with)
+      end
+
+      def ensure_inform_object_model!
+        return if inform_object_model?
+
+        StoryTeller::EphemeralAdapter.register!
+      end
+
+      # rubocop: disable Metrics/AbcSize
+      # rubocop: disable Metrics/MethodLength
+      def require_first_existing(guesses)
+        guessed_file_path = File.join(StoryTeller::Engine.inform_code_prefix, guesses.shift)
+        guessed_local_file_path = File.expand_path(guessed_file_path)
+        if File.exist?(guessed_local_file_path)
+          log.debug "Loading local library file: #{guessed_local_file_path}"
+          require_relative guessed_local_file_path
+        else
+          log.debug "Loading library: #{guessed_file_path}"
+          require guessed_file_path
+        end
+      rescue StandardError => e
+        log.error e.message
+        e.backtrace.each { |t| log.warn t }
+        raise e
+      rescue LoadError => e
+        log.warn e.message
+        e.backtrace.each { |t| log.warn t }
+        retry unless guesses.empty?
+      end
+      # rubocop: enable Metrics/AbcSize
+      # rubocop: enable Metrics/MethodLength
+      def load_grammar(module_name)
+        Inform::Grammar.load_by_name(module_name)
+      end
+
+      def load_grammar_by_path(module_path)
+        Inform::Grammar.load_by_path(module_path)
+      end
+
+      def unload_grammars!
+        log.debug "Unloading all grammars"
+        Inform::Grammar::Verbs.clear
+      end
+    end
+    # module Loader
+  end
+  # module Library
+end
+# module StoryTeller

data/lib/story_teller/library/location.rb

@@ -0,0 +1,73 @@
+# lib/story_teller/library/location.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller 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 StoryTeller 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 StoryTeller. If not, see <http://www.gnu.org/licenses/>.
+
+# module StoryTeller
+module StoryTeller
+  # module Library
+  module Library
+    # module Location
+    module Location
+      def location
+        @player&.location
+      end
+
+      def location=(obj)
+        @player.location = obj
+      end
+    end
+
+    # module LocationInstaller
+    module LocationInstaller
+      module_function
+
+      def install!
+        return false unless defined?(InformLibrary)
+        return false if InformLibrary < StoryTeller::Library::Location
+
+        InformLibrary.prepend(StoryTeller::Library::Location)
+        true
+      end
+    end
+
+    # module LocationTracePoint
+    module LocationTracePoint
+      module_function
+
+      def install_or_defer!
+        return true if StoryTeller::Library::LocationInstaller.install!
+        return false if defined?(@trace_point) && @trace_point&.enabled?
+
+        @trace_point = TracePoint.new(:class) do |_tp|
+          next unless defined?(InformLibrary)
+          next unless StoryTeller::Library::LocationInstaller.install!
+
+          @trace_point.disable
+          @trace_point = nil
+        end
+
+        @trace_point.enable
+        false
+      end
+    end
+  end
+end
+
+StoryTeller::Library::LocationTracePoint.install_or_defer!

data/lib/{runtime → story_teller}/library.rb

@@ -1,31 +1,46 @@
+# lib/story_teller/library.rb
 # encoding: utf-8
 # frozen_string_literal: false
 
-# Copyright Nels Nelson 2008-2023 but freely usable (see license)
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
 #
-# This file is part of the Inform Runtime.
+# This file is part of the StoryTeller.
 #
-# The Inform Runtime is free software: you can redistribute it and/or
+# The StoryTeller 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,
+# The StoryTeller 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/>.
+# along with the StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
 
-require_relative 'library_loader'
+require_relative 'library/bootstrap'
+require_relative 'library/declarations'
+require_relative 'library/directives'
+require_relative 'library/loader'
+require_relative 'library/location'
 
-# The Inform module
-module Inform
+# The StoryTeller module
+module StoryTeller
   # The Library module
   module Library
     @methods_index = []
 
+    def inform_gem_lib_path
+      @inform_gem_lib_path ||= File.expand_path(File.join(StoryTeller::Library::GEM_PATH, 'lib'))
+    end
+    module_function :inform_gem_lib_path
+
+    def declarations
+      @declarations ||= Declarations.new
+    end
+    module_function :declarations
+
     def methods_index
       return @methods_index unless @methods_index.empty?
       load_library_methods
@@ -39,9 +54,9 @@ module Inform
     # rubocop: disable Metrics/MethodLength
     def load_library_methods
       library_methods = Set.new
-      library_methods.merge(StdLib.instance_methods(false))
-      library_methods.merge(Inform::IO.instance_methods(false))
-      library_methods.merge(Inform.instance_methods(false))
+      library_methods.merge(Inform::StdLib.instance_methods(false))
+      library_methods.merge(StoryTeller::IO.instance_methods(false))
+      library_methods.merge(StoryTeller.instance_methods(false))
       library_methods.merge(InformLibrary.instance_methods(false))
       Inform.included_modules.each do |mod|
         library_methods.merge(mod.instance_methods(false))
@@ -50,7 +65,7 @@ module Inform
         library_methods.merge(mod.instance_methods(false))
       end
       @methods_index.concat(library_methods.to_a).sort
-      log.debug "Loaded library methods: #{@methods_index}"
+      log.trace "Loaded library methods: #{@methods_index}"
     end
     # rubocop: enable Metrics/AbcSize
     # rubocop: enable Metrics/MethodLength

data/lib/{runtime → story_teller}/logging.rb

@@ -1,22 +1,23 @@
+# lib/story_teller/logging.rb
 # encoding: utf-8
 # frozen_string_literal: false
 
-# Copyright Nels Nelson 2008-2023 but freely usable (see license)
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
 #
-# This file is part of the Inform Runtime.
+# This file is part of StoryTeller.
 #
-# The Inform Runtime is free software: you can redistribute it and/or
+# StoryTeller 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,
+# StoryTeller 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/>.
+# along with StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
 
 require 'fileutils'
 require 'logger'
@@ -82,15 +83,26 @@ end
 # implicit backtrace printing
 # TODO: Figure out if this is actually useful.
 class Logger
+  TRACE = DEBUG - 1 unless const_defined?(:TRACE)
+
   include LoggerHelpers
 
   alias original_error error
+
   def error(error_or_message, error = nil)
     warn error_or_message
     return extract_backtrace(error_or_message) if error.nil?
     original_error(generate_message(error_or_message, error))
     extract_backtrace(original_error(error))
   end
+
+  def trace(progname = nil, &block)
+    add(TRACE, nil, progname, &block)
+  end
+
+  def trace?
+    @level <= TRACE
+  end
 end
 
 # The Logging module
@@ -100,6 +112,18 @@ module Logging
   java_import Java::org.apache.logging.log4j.LogManager
   end
 
+  RubyLogLevels = {
+    all: -Float::INFINITY,
+    trace: Logger::TRACE,
+    debug: Logger::DEBUG,
+    info: Logger::INFO,
+    warn: Logger::WARN,
+    error: Logger::ERROR,
+    fatal: Logger::FATAL,
+    unknown: Logger::UNKNOWN,
+    off: Logger::UNKNOWN + 1
+  }.freeze
+
   def init_logger(level = :info, logger_name = nil)
     return init_java_logger(level, logger_name, caller[2]) if defined?(Java)
     init_ruby_logger(level, logger_name, caller[2])
@@ -118,7 +142,7 @@ module Logging
     logger_name = get_formatted_logger_name(logger_name)
     logger_name = source_location.split(ForwardSlashPattern).last if logger_name.empty?
     log = Logger.new($stdout, progname: logger_name)
-    log.level = level.to_s unless level.nil?
+    log.level = normalize_ruby_log_level(level) unless level.nil?
     log.formatter = method(:ruby_log_formatter)
     log
   end
@@ -131,6 +155,14 @@ module Logging
     log
   end
 
+  def normalize_ruby_log_level(level)
+    return level if level.is_a?(Integer)
+
+    RubyLogLevels.fetch(level.to_sym) do
+      raise ArgumentError, "Unknown Ruby log level: #{level.inspect}"
+    end
+  end
+
   def get_formatted_logger_name(logger_name = nil)
     return logger_name.to_s[/\w+$/] unless logger_name.nil?
     return name[/\w+$/] if is_a?(Class) || is_a?(Module)
@@ -162,7 +194,10 @@ module Logging
   # rubocop: enable Metrics/CyclomaticComplexity
 
   def log_level=(level)
-    Logging.config[:level] = symbolize_numeric_log_level(level)
+    raise "Parameter level may not be nil" if level.nil?
+    normalized_level = symbolize_numeric_log_level(level)
+
+    Logging.config[:level] = normalized_level
   end
   module_function :log_level=
 
@@ -178,20 +213,8 @@ module Logging
 end
 # module Logging
 
-# The Module class
-class Module
-  # Universally include Logging
-  include ::Logging
-end
-
-# The Class class
-class Class
-  # Universally include Logging
-  include ::Logging
-end
-
-# The Object class
-class Object
-  # Universally include Logging
-  include ::Logging
-end
+# Make logging universally available
+# Yeah, yeah, I know this is a "bad idea".  Too bad.
+# Logging should be a universal runtime facility, period.
+# The fact that it isn't is an absurdity to me.
+Object.include(Logging)

data/lib/{runtime → story_teller}/mixins.rb

@@ -1,22 +1,22 @@
 # encoding: utf-8
 # frozen_string_literal: false
 
-# Copyright Nels Nelson 2008-2023 but freely usable (see license)
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
 #
-# This file is part of the Inform Runtime.
+# This file is part of StoryTeller.
 #
-# The Inform Runtime is free software: you can redistribute it and/or
+# StoryTeller 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,
+# StoryTeller 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/>.
+# along with StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
 
 
 JoinedTemplate = '%<str>s%<other>s'.freeze
@@ -501,7 +501,7 @@ class Array
   def to_s(separator = CommaSpaceString)
     # This will make it possible to print Lists nicely, but not screw up
     # the behavior of the List.
-    map(&:to_s).join(separator)
+    self.join(separator)
   end
 
   alias random sample