story-teller 1.1.3

data/lib/story_teller/runtime.rb

@@ -0,0 +1,381 @@
+# lib/story_teller/teller.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/>.
+
+require_relative 'curses_adapter'
+
+# module StoryTeller
+module StoryTeller
+  # module InstanceMethods
+  module InstanceMethods
+    UndefinedMainPattern = %r{undefined method 'Main' for an instance of Object}.freeze
+
+    attr_accessor :main_object, :session
+
+    def default_config
+      @default_config ||= StoryTeller::Config.defaults.merge(@options).tap do |config|
+        config[:word_wrap] ||= StoryTeller::Terminal.word_wrap
+      end
+    end
+
+    def config_file_path
+      @config_file_path ||= game.config_file_path
+    end
+
+    def game_path
+      @game_path ||= game.path
+    end
+
+    def grammar_module_path
+      @grammar_module_path ||= File.join(game_path, @options[:game_grammar_module_name])
+    end
+
+    def game_file_path
+      @game_file_path ||= game.file_path
+    end
+
+    def game_dir_name
+      @game_dir_name ||= @options[:game_dir_name]
+    end
+
+    def game_components
+      @game_components ||= @options.fetch(:game_components, '').split.map(&:to_sym)
+    end
+
+    def project_dir_path
+      @project_dir_path ||= begin
+        story_dir_path = File.expand_path(__dir__)
+        lib_dir_path = File.expand_path(File.dirname(story_dir_path))
+        File.expand_path(File.dirname(lib_dir_path))
+      end
+    end
+
+    def invocation_properties
+      @invocation_properties ||= @options.fetch(:properties, '').split.map(&:to_sym)
+    end
+
+    def invocation_context
+      @invocation_context ||= Struct.new(*invocation_properties)
+    end
+
+    def configure!(options)
+      @options.merge!(options)
+      reset_config_cache
+      @game = StoryTeller::Game.new(@options)
+      self
+    end
+
+    def reset_config_cache
+      @config_file_path = nil
+      @default_config = nil
+      @game_components = nil
+      @game_dir_name = nil
+      @game_file_path = nil
+      @game_path = nil
+      @grammar_module_path = nil
+    end
+
+    def invoke_main
+      ::Object.new.send(:Main)
+    rescue NameError => e
+      if UndefinedMainPattern.match?(e.message)
+        log.fatal "Main() definition is missing"
+      else
+        log.fatal "Fatal error invoking Main(): #{e.message}"
+      end
+      abort 'Terminating'
+    end
+
+    def install_persisted_startup_location_hook
+      return if InformLibrary < StoryTeller::PersistedStartupMove
+
+      InformLibrary.prepend(StoryTeller::PersistedStartupMove)
+    end
+
+    def persist?
+      @options[:persist]
+    end
+
+    # TODO: Ensuring the location of the player object requires
+    # that this method be invoked before the move @player, @location
+    # operation in the InformLibrary#play method.  This means that
+    # ensuring the location must take place either in the game-
+    # defined Initialise() method, or else it can happen in a
+    # provided LibraryExtension method, but in that case it would
+    # be at risk of being overridden by a game-defined Initialise()
+    # method.
+    # TODO: Figure out what the best approach here is.  I think that
+    # if a multi-player game is to supply an entrypoint module, it
+    # will have to handle the location ensurance itself.
+    def ensuring_player_location(&block)
+      if persist?
+        install_persisted_startup_location_hook
+        persisted_location = StoryTeller::Engine.player_object&.location
+        StoryTeller::PersistedStartupLocation.with(persisted_location) { block.call }
+      else
+        block.call
+        location = location_candidate
+        raise "InformLibrary location may not be left unset" if location.nil?
+
+        inform_library&.PlayerTo(location, 1)
+      end
+    end
+
+    def location_candidate
+      return persisted_location_candidate if persist?
+
+      canonical_location_candidate
+    end
+
+    # rubocop: disable Metrics/CyclomaticComplexity
+    def canonical_location_candidate
+      inform_library&.location ||
+        inform_library&.player&.location ||
+        inform_library&.player&.spawn_point
+    end
+
+    def persisted_location_candidate
+      inform_library&.player&.location ||
+        inform_library&.location ||
+        inform_library&.player&.spawn_point
+    end
+    # rubocop: enable Metrics/CyclomaticComplexity
+
+    def restore_player_location
+      inform_library.PlayerTo(
+        inform_library.player.location,
+        -1 # Quietly
+      )
+    end
+
+    # Initially, inform_library defaults to using Inform::Parser::SelfObj.
+    # However, that SelfObj is by default an instance of an
+    # Inform::Ephemeral::Object. Of course, persistence is not really
+    # required for a play session of a single player story game, since
+    # the snapshot file save feature is implemented.  Nevertheless, it
+    # is the intention of this application to demonstrate persistence of
+    # Inform-esque data into a PostgreSQL database. And so the default
+    # selfobj is overridden here with a non-ephemeral version.
+    def use_persistent_selfobj
+      require_relative 'player_character'
+
+      StoryTeller::Engine.player_object = StoryTeller::PlayerCharacter("(self object)")
+    end
+
+    def inform_library
+      @inform_library ||= StoryTeller::Engine.library
+    end
+
+    def identity
+      self.object_id
+    end
+
+    def invocation_identity
+      @invocation_identity ||= StoryTeller::InvocationIdentity.new(self)
+    end
+
+    def privileged_identities(privilege)
+      [invocation_identity].select { |identity| identity.privileged?(privilege) }
+    end
+
+    def manage_privileges
+      apply_privileges(self.class, privileges: StoryTeller::Privileges)
+      apply_privileges(InformLibrary, privileges: StoryTeller::Privileges) if defined?(InformLibrary)
+      apply_privileges(StoryTeller::IO::Session, privileges: StoryTeller::Privileges)
+
+      StoryTeller::PrivilegeGrants.mode = @options.fetch(:privilege_mode, :session_only)
+      apply_invocation_privileges(self)
+    end
+
+    def apply_invocation_privileges(subject)
+      StoryTeller::PrivilegeGrants.grant_session(subject, :admin) if @options[:admin]
+      StoryTeller::PrivilegeGrants.grant_session(subject, :builder) if @options[:builder]
+    end
+
+    def apply_privileges(klass, privileges: StoryTeller::Privileges)
+      return if klass.nil? || klass < privileges
+
+      klass.include(privileges)
+    end
+
+    def bind_session(inflib = inform_library)
+      @session ||= StoryTeller::IO::Session.new(
+        machine: inflib,
+        player: inflib.selfobj,
+        state: :playing,
+        settings: default_config
+      ).tap do |session|
+        apply_invocation_privileges(session)
+      end
+
+      @session.expose_to(inflib)
+      @session
+    end
+
+    def persistence
+      StoryTeller::Persistence.instance
+    end
+
+    def read
+      flush_session_output unless session.nil?
+      $stdin.gets(chomp: true)
+    end
+
+    def configure_output
+      return unless @options[:curses]
+
+      StoryTeller::IO.default_output = StoryTeller::CursesAdapter.new
+    end
+
+    def write_output(value)
+      return if value.nil? || value.empty?
+
+      output = StoryTeller::IO.default_output || $stdout
+
+      output.write(value)
+      $stdout.flush if output.equal?($stdout)
+    end
+
+    def flush_session_output
+      write_output(session.drain_output)
+    end
+
+    def read_eval_print_loop
+      loop do
+        prompt unless session.state == :more
+        flush_session_output
+        write_output(session.process(read, inform_library))
+      end
+    rescue Interrupt => e
+      write_output("\n#{e.class.name}\n")
+    end
+
+    def play_game
+      log.trace "#{self}#play_game"
+      configure_output
+      use_persistent_selfobj
+      bind_session
+      ensuring_player_location { invoke_main }
+      flush_session_output
+      read_eval_print_loop
+    end
+
+    def quit_game
+      write_output "[Hit enter to exit.]"
+      $stdin.getc
+      # Curses.getch
+      # Curses.close_screen
+      exit
+    end
+
+    def restart_game
+      L__M(:Restart, 2)
+    end
+
+    # rubocop: disable Metrics/AbcSize
+    # rubocop: disable Metrics/MethodLength
+    def save_game(callback = nil)
+      timestamp = Time.now.utc.strftime('%Y-%m-%d_%H%M%S')
+      filename = format(
+        '%<game_name>s_%<timestamp>s.sav',
+        game_name: game.name,
+        timestamp: timestamp
+      )
+      println "Enter a file name."
+      print "Default is \"#{filename}\": "
+      flush_session_output
+      response = $stdin.gets&.strip.to_s
+      filename = response unless response.empty?
+      StoryTeller::Snapshots.export_to_file(filename)
+      inform_library.println(callback&.call)
+    end
+    # rubocop: enable Metrics/AbcSize
+    # rubocop: enable Metrics/MethodLength
+
+    # rubocop: disable Metrics/AbcSize
+    # rubocop: disable Metrics/MethodLength
+    def restore_game(callback = nil)
+      filename = format('%s.sav', game.name)
+      files = Dir.glob(File.join(format('%s_*.sav', game.name)))
+      filename = files.max unless files.empty?
+      println "Enter a file name."
+      print "Default is \"#{filename}\": "
+      flush_session_output
+      response = $stdin.gets&.strip.to_s
+      filename = response unless response.empty?
+      StoryTeller::Snapshots.import_from_file(filename)
+      restore_player_location
+      inform_library.println(callback&.call)
+    end
+    # rubocop: enable Metrics/AbcSize
+    # rubocop: enable Metrics/MethodLength
+
+    def to_s
+      "#<#{self.class.name}:#{object_id}>"
+    end
+
+    def inspect
+      to_s
+    end
+  end
+  # module InstanceMethods
+
+  # module ClassMethods
+  module ClassMethods
+    def project_dir_path
+      @project_dir_path ||= begin
+        story_dir_path = File.expand_path(__dir__)
+        lib_dir_path = File.expand_path(File.dirname(story_dir_path))
+        File.expand_path(File.dirname(lib_dir_path))
+      end
+    end
+
+    def game_saves_dir_path
+      File.join(
+        StoryTeller::Runtime.project_dir_path,
+        '.' + StoryTeller::Game.config[:game_name] + '_saves')
+    end
+
+    def instance(options = nil)
+      @instance ||= new(StoryTeller::Config.defaults)
+      @instance.tap { |obj| obj.configure!(options) unless options.nil? }
+    end
+  end
+  # module StoryTellerClassMethods
+
+  # A Runtime runs a story game.
+  class Runtime
+    include StoryTeller::InstanceMethods
+    include StoryTeller::IO
+    include StoryTeller::Publisher
+
+    class << self
+      include StoryTeller::ClassMethods
+    end
+
+    attr_reader :game, :options
+
+    def initialize(options = StoryTeller::Config.defaults)
+      @options = {}
+      configure!(options)
+    end
+  end
+end
+# module StoryTeller