inform-runtime 1.2.2 → 1.3.1

data/lib/story_teller/prototype.rb

@@ -2,7 +2,7 @@
 # encoding: utf-8
 # frozen_string_literal: false
 
-# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+# Copyright Nels Nelson 2008-2026 but freely usable (see license)
 #
 # This file is part of StoryTeller.
 #
@@ -34,7 +34,9 @@ module Inform
     end
 
     def values
-      super || instance_variables_map
+      result = super
+      return result if result && result != __method__
+      raise NoMethodError, "undefined method `#{__method__}' for #{self}"
     rescue StandardError => e
       log.warn "Unexpected error invoking super(Inform::Prototypical#values): #{e.message}"
       instance_variables_map
@@ -126,25 +128,44 @@ module Inform
     MethodWriterPattern = %r{=$}.freeze
     LinkPattern = %r{.+_to$}.freeze
 
+    # rubocop: disable Style/MissingRespondToMissing
+    def method_missing(method, *args, &block)
+      stack = Thread.current[:prototypical_method_missing_stack] ||= []
+      frame = [object_id, method]
+
+      if stack.include?(frame)
+        raise NoMethodError, "Aborting Prototypical missing method " \
+          "resolution #{self.class}##{method} on #{inspect}"
+      end
+
+      stack << frame
+      attempt_resolution(method, *args, &block)
+    ensure
+      stack&.pop
+    end
+    # rubocop: enable Style/MissingRespondToMissing
+
     # rubocop: disable Metrics/AbcSize
     # rubocop: disable Metrics/CyclomaticComplexity
     # rubocop: disable Metrics/MethodLength
     # rubocop: disable Metrics/PerceivedComplexity
-    # rubocop: disable Style/MissingRespondToMissing
-    def method_missing(method, *args, &block)
-      return super if method == :to_ary
+    def attempt_resolution(method, *args, &block)
+      raise NoMethodError, "undefined method `#{method}' for #{self}" if method == :to_ary
       m = method.to_s
-      return super if MethodBooleanOrBangPattern.match?(m)
+      raise NoMethodError, "undefined method `#{method}' for #{self}" if MethodBooleanOrBangPattern.match?(m)
       mname = MethodWriterPattern.match?(m) ? m.chop : m
       property = mname.to_sym
       variable = format(VariableTemplate, property: property).to_sym
       event = context_event
 
+      library = respond_to?(:inflib, true) ? inflib : nil
+      object_properties = respond_to?(:properties, true) ? properties : nil
+
       if MethodWriterPattern.match?(m) || (LinkPattern.match?(m) && !args.empty?)
         if !event.nil? && StoryTeller::Engine.invocation_properties.include?(property)
           event.send(method, *args, &block)
-        elsif inflib&.library_method?(method)
-          inflib.send(method, *args, &block)
+        elsif library&.library_method?(method)
+          library.send(method, *args, &block)
         else
           self.prototype(method, *args, &block)
         end
@@ -152,26 +173,33 @@ module Inform
         result = event.send(method, *args, &block)
         log.debug("Value for event #{event}.#{method} is: #{result || 'nil'}") if defined? DEBUG
         result
-      elsif inflib&.library_method?(method)
-        inflib.send(method, *args, &block)
-      elsif inflib.respond_to?(method) && StoryTeller::Engine.invocation_properties.include?(property)
-        inflib.send(method, *args, &block)
-      elsif inflib&.instance_variable_get(variable) || inflib&.instance_variables&.include?(variable)
-        inflib.instance_variable_get(variable)
-      elsif (properties.respond_to?(:key?) && properties.key?(property)) ||
+      elsif library&.library_method?(method)
+        library.send(method, *args, &block)
+      elsif library.respond_to?(method) && StoryTeller::Engine.invocation_properties.include?(property)
+        library.send(method, *args, &block)
+      elsif library&.instance_variable_get(variable) || library&.instance_variables&.include?(variable)
+        library.instance_variable_get(variable)
+      elsif property_defined?(object_properties, property) ||
           (respond_to?(:_key?) && _key?(property)) ||
           !args.empty?
         self.prototype(method, *args, &block)
+      # TODO: Remove (2026-04-28)
+      # Experiment with supporting only property setting for those
+      # declared in StoryTeller::Library.declarations.properties.
+      # elsif (properties.respond_to?(:key?) && properties.key?(property)) ||
+      #     (respond_to?(:_key?) && _key?(property)) ||
+      #     StoryTeller::Library.declarations.properties.key?(property)
+      #   self.prototype(method, *args, &block)
       else
-        super
+        raise NoMethodError, "undefined method `#{method}' for #{self}"
       end
     end
     # rubocop: enable Metrics/AbcSize
     # rubocop: enable Metrics/CyclomaticComplexity
     # rubocop: enable Metrics/MethodLength
     # rubocop: enable Metrics/PerceivedComplexity
-    # rubocop: enable Style/MissingRespondToMissing
 
+    # TODO: Remove (2026-04-28)
     # def respond_to_missing?(method, include_all=false)
     #   m = method.to_s
     #   return false if m =~ /\?$/
@@ -198,32 +226,81 @@ module Inform
     ).freeze
 
     # rubocop: disable Metrics/AbcSize
-    # rubocop: disable Metrics/CyclomaticComplexity
     # rubocop: disable Metrics/MethodLength
     def prototype(key, *args, &block)
       ensure_properties_attribute!
       accessor, writer = accessor_and_writer(key)
+      link_result = nil
+
       if key_refers_to_link?(key)
         self.will_change_column(:properties) if self.respond_to?(:will_change_column)
-        if args.empty? && self.properties.key?(key)
-          return if (to_obj = get_constant(self.properties[key])).nil? || !to_obj.object?
-          self.link(key, to_obj)
-          self.properties.delete(key)
-          self.save_changes if self.respond_to?(:save_changes)
-          return to_obj
+
+        if args.empty?
+          link_result = resolve_link_property(key)
+        else
+          linked_object = object_for_link_value(args.first)
+          if linked_object.nil?
+            self.properties[key] = args.first
+          else
+            link_result = set_link_property(key, linked_object)
+          end
         end
-        self.properties[key] = args.first
       end
+
       accessor = format(AccessorMethodTemplate, accessor: accessor)
       self.instance_eval(accessor, __FILE__, __LINE__)
       writer = format(WriterMethodTemplate, writer: writer)
       self.instance_eval(writer, __FILE__, __LINE__)
+
+      return link_result unless link_result.nil?
+
       self.send(key, *args, &block)
     end
     # rubocop: enable Metrics/AbcSize
-    # rubocop: enable Metrics/CyclomaticComplexity
     # rubocop: enable Metrics/MethodLength
 
+    # rubocop: disable Metrics/CyclomaticComplexity
+    def resolve_link_property(key)
+      return nil unless key_refers_to_link?(key)
+
+      linked_object = self._get_object(key) if self.respond_to?(:_key?) &&
+        self._key?(key) &&
+        self.respond_to?(:_get_object)
+      return linked_object unless linked_object.nil?
+
+      property_key = property_key_for(key)
+      return nil if property_key.nil?
+
+      linked_object = object_for_link_value(self.properties[property_key])
+      return nil if linked_object.nil?
+
+      set_link_property(key, linked_object, property_key: property_key)
+    end
+    # rubocop: enable Metrics/CyclomaticComplexity
+
+    def object_for_link_value(value)
+      return value if value.respond_to?(:object?) && value.object?
+      return nil unless value.is_a?(Symbol) || value.is_a?(String)
+
+      object = constant_for_link_value(value)
+      return object if object.respond_to?(:object?) && object.object?
+
+      nil
+    end
+
+    def constant_for_link_value(value)
+      names = value.to_s.split('::').reject(&:empty?)
+      return nil if names.empty?
+
+      names.inject(::Object) do |scope, name|
+        return nil unless scope.const_defined?(name)
+
+        scope.const_get(name)
+      end
+    rescue NameError
+      nil
+    end
+
     MISSING_PROPERTIES_MESSAGE = 'Missing properties attribute for: ' \
       '%<identity>s'.freeze
 
@@ -232,14 +309,46 @@ module Inform
       raise StandardError, format(MISSING_PROPERTIES_MESSAGE, identity: self.identity)
     end
 
+    def property_defined?(object_properties, property)
+      return false unless object_properties.respond_to?(:key?)
+
+      object_properties.key?(property) || object_properties.key?(property.to_s)
+    end
+
     def key_refers_to_link?(key)
-      StoryTeller::Library.declarations.properties.key?(key) && LinkPattern.match?(key.to_s)
+      return false unless LinkPattern.match?(key.to_s)
+
+      declared_property?(key)
+    end
+
+    def declared_property?(key)
+      return false unless defined?(StoryTeller::Library)
+      return false unless StoryTeller::Library.respond_to?(:declarations)
+
+      declarations = StoryTeller::Library.declarations
+      properties = declarations.properties if declarations.respond_to?(:properties)
+      return false unless properties.respond_to?(:key?)
+
+      properties.key?(key.to_sym) || properties.key?(key.to_s)
+    rescue StandardError
+      false
+    end
+
+    def property_key_for(key)
+      return key if self.properties.key?(key)
+
+      string_key = key.to_s
+      return string_key if self.properties.key?(string_key)
+
+      nil
     end
 
     def _get(key)
       result = nil
       result = self._get_object(key) if self.respond_to?(:_key?) && self._key?(key)
-      result || self.properties.dup[key]
+      return result unless result.nil?
+
+      resolve_link_property(key) || self.properties.dup[property_key_for(key)]
     end
 
     # rubocop: disable Metrics/AbcSize
@@ -252,11 +361,13 @@ module Inform
       result = nil
       if values.first.object?
         result = self._set_object(key, values.first) if respond_to? :_set_object
+      elsif key_refers_to_link?(key) && (linked_object = object_for_link_value(values.first))
+        result = set_link_property(key, linked_object)
       elsif values.first.nil? && self.respond_to?(:_key?) && self._key?(key)
         result = self._unset_object(key) if self.respond_to?(:_unset_object)
       elsif values.first.nil?
         self.will_change_column(:properties) if self.respond_to?(:will_change_column)
-        self.properties.delete(key)
+        self.properties.delete(property_key_for(key))
         self.save_changes if self.respond_to?(:save_changes)
       elsif values.length > 1
         self.will_change_column(:properties) if self.respond_to?(:will_change_column)
@@ -269,7 +380,7 @@ module Inform
         self.properties[key] = values.first
         self.save_changes if self.respond_to?(:save_changes)
       end
-      result || self.properties.dup[key]
+      result || self.properties.dup[property_key_for(key)]
     end
     # rubocop: enable Metrics/AbcSize
     # rubocop: enable Metrics/CyclomaticComplexity
@@ -285,23 +396,38 @@ module Inform
       result = nil
       if value.object?
         result = self._set_object(key, value) if self.respond_to?(:_set_object)
+      elsif key_refers_to_link?(key) && (linked_object = object_for_link_value(value))
+        result = set_link_property(key, linked_object)
       elsif value.nil? && self.respond_to?(:_key?) && self._key?(key)
         result = self._unset_object(key) if self.respond_to?(:_unset_object)
       elsif value.nil? && self.properties.key?(key)
         self.will_change_column(:properties) if self.respond_to?(:will_change_column)
-        self.properties.delete(key)
+        self.properties.delete(property_key_for(key))
         self.save_changes if self.respond_to?(:save_changes)
       else
         self.will_change_column(:properties) if self.respond_to?(:will_change_column)
         self.properties[key] = value
         self.save_changes if self.respond_to?(:save_changes)
       end
-      result || self.properties.dup[key]
+      result || self.properties.dup[property_key_for(key)]
     end
     # rubocop: enable Metrics/AbcSize
     # rubocop: enable Metrics/CyclomaticComplexity
     # rubocop: enable Metrics/MethodLength
     # rubocop: enable Metrics/PerceivedComplexity
+
+    def set_link_property(key, object, property_key: property_key_for(key))
+      result = if self.respond_to?(:_set_object)
+        self._set_object(key, object)
+      elsif self.respond_to?(:link)
+        self.link(key, object)
+        object
+      end
+      self.properties.delete(property_key) unless property_key.nil?
+      self.will_change_column(:properties) if self.respond_to?(:will_change_column)
+      self.save_changes if self.respond_to?(:save_changes)
+      result || object
+    end
   end
   # module Prototypical
 end

data/lib/story_teller/publication.rb

@@ -1,7 +1,8 @@
+# lib/story_teller/publication.rb
 # encoding: utf-8
 # frozen_string_literal: false
 
-# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+# Copyright Nels Nelson 2008-2026 but freely usable (see license)
 #
 # This file is part of the StoryTeller.
 #

data/lib/story_teller/session.rb

@@ -1,7 +1,8 @@
+# lib/story_teller/session.rb
 # encoding: utf-8
 # frozen_string_literal: false
 
-# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+# Copyright Nels Nelson 2008-2026 but freely usable (see license)
 #
 # This file is part of StoryTeller.
 #
@@ -22,6 +23,7 @@
 module SessionManagementMethods
   class Registry < Hash; end
   SessionsByChannel = Registry.new
+  SessionsByPlayer = Registry.new
 
   def add_promiscuous_states(*states)
     Promiscuous.merge states.flatten
@@ -31,12 +33,52 @@ module SessionManagementMethods
     SessionsByChannel
   end
 
+  def sessions_by_player
+    SessionsByPlayer
+  end
+
   def register(channel, session)
     sessions_by_channel[channel] = session
+    session.channel = channel if session.respond_to?(:channel=)
+    session
+  end
+
+  def register_player(player, session)
+    sessions_by_player[player] = session
+    session
   end
 
   def unregister(channel)
-    sessions_by_channel.delete(channel)
+    session = sessions_by_channel.delete(channel)
+    sessions_by_player.delete_if { |_player, candidate| candidate.equal?(session) }
+    session
+  end
+
+  def release_player(player, session = nil)
+    return nil if player.nil?
+    return sessions_by_player.delete(player) if session.nil?
+    return sessions_by_player.delete(player) if sessions_by_player[player].equal?(session)
+
+    nil
+  end
+
+  def of(obj)
+    return nil if obj.nil?
+    return obj if obj.is_a?(self)
+
+    sessions_by_channel[obj] ||
+      sessions_by_player[obj] ||
+      session_for_method(obj, :player) ||
+      session_for_method(obj, :selfobj) ||
+      session_for_ivar(obj, :@player)
+  end
+
+  def players
+    sessions_by_player.keys
+  end
+
+  def channels
+    sessions_by_channel.keys
   end
 
   def [](channel)
@@ -52,7 +94,21 @@ module SessionManagementMethods
   end
 
   def get(channel)
-    sessions_by_channel[channel] ||= Session.new(channel)
+    sessions_by_channel[channel] ||= new(channel)
+  end
+
+  private
+
+  def session_for_method(obj, method_name)
+    return nil unless obj.respond_to?(method_name)
+
+    sessions_by_player[obj.public_send(method_name)]
+  end
+
+  def session_for_ivar(obj, ivar_name)
+    return nil unless obj.instance_variable_defined?(ivar_name)
+
+    sessions_by_player[obj.instance_variable_get(ivar_name)]
   end
 end
 # module SessionManagementMethods
@@ -84,28 +140,43 @@ module SessionStateManagementMethods
   end
 end
 
-module Inform
+# module StoryTeller
+module StoryTeller
+# module IO
 module IO
 # The Session class
 # TODO: Refactor method implementations into modules
+# rubocop: disable Metrics/ClassLength
 class Session
-  # These states accept any input, including no input
-  Promiscuous = Set.new
   include SessionStateManagementMethods
 
   class << self
     include SessionManagementMethods
   end
-  attr_accessor :channel, :state, :status
+  attr_accessor :channel, :machine, :player, :state, :status
   attr_reader :last_good_state, :last_activity, :previous, :inbound, :outbound, :settings
 
-  def initialize(channel = nil)
-    init_channel_session(channel) unless channel.nil?
-    @status = nil
-    @last_good_state = @state = default if respond_to? :default
+  # These states accept any input, including no input
+  Promiscuous = Set.new
+
+  # rubocop: disable Metrics/MethodLength
+  def initialize(channel = nil, machine: nil, player: nil, state: :playing, settings: {})
+    @channel = channel
+    @machine = machine
+    @player = nil
+    @state = state
+    @last_good_state = state
     @session_data = {}
-    @settings = {}
+    @settings = settings
+    @status = nil
+    @last_activity = Time.now
+
+    self.class.register(channel, self) unless channel.nil?
+    control(player) unless player.nil?
   end
+  # rubocop: enable Metrics/MethodLength
+
+  alias preferences settings
 
   def init_channel_session(channel)
     Session[channel] = self
@@ -115,6 +186,13 @@ class Session
     @last_activity = Time.now
   end
 
+  def control(player)
+    self.class.release_player(@player, self)
+    @player = player
+    self.class.register_player(player, self) unless player.nil?
+    self
+  end
+
   def receive(message)
     return if message.nil? # It is okay if the message parameter is an empty string
     return disconnected if @channel.nil?
@@ -122,7 +200,7 @@ class Session
     process(sanitize(message))
   end
 
-  def update(machine = self)
+  def update(machine = @machine)
     safely_progress(machine)
     after_update if self.respond_to?(:after_update)
     @last_good_state = @state unless @state == :confused
@@ -140,24 +218,27 @@ class Session
     self
   end
 
+  def expose_to(machine)
+    machine.instance_variable_set(:@buffer, @buffer)
+    machine.instance_variable_set(:@session, self)
+  end
+
   ExitCommandPattern = /^(exit|quit|q)$/i.freeze
 
   def exit_command?(message)
     !Promiscuous.include?(@state) && ExitCommandPattern.match?(message)
   end
 
-  def process(message)
-    return disconnect if exit_command?(message)
-    @buffer = message
+  def process(message, machine = @machine)
+    raise ArgumentError, 'session machine is required' if machine.nil?
+
+    @machine = machine
+    @buffer = sanitize(message)
     @last_activity = Time.now
     @status = :active
-    if valid_state?
-      update
-    else
-      @inbound.publish @buffer
-    end
 
-    respond
+    expose_to(machine)
+    update(machine)
   end
 
   def respond
@@ -165,7 +246,7 @@ class Session
   end
 
   def safely_progress(machine = self)
-    @state = machine.send(@state)
+    @state = machine.public_send(@state)
     raise 'Bad state machine implementation: nil state' if @state.nil?
   rescue StandardError => e
     log.error "Error updating state: #{e.message}", e
@@ -176,7 +257,7 @@ class Session
   def valid_state?(machine = self)
     case @state
     when String, Symbol
-      machine.respond_to? @state
+      machine.respond_to?(@state)
     else
       false
     end
@@ -189,12 +270,21 @@ class Session
     prompt
     @last_good_state
   end
+
+  private
+
+  def prepare_machine(machine)
+    return if machine.equal?(self)
+
+    machine.instance_variable_set(:@buffer, @buffer)
+  end
 end
 # class Session
+# rubocop: enable Metrics/ClassLength
 
 # The Connection class
 class Connection; end
 end
 # module IO
 end
-# module Inform
+# module StoryTeller