gamefic 3.0.0 → 3.2.0

data/lib/gamefic/props/output.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Props
+    # A container for output sent to players with a hash interface for custom
+    # data.
+    #
+    class Output
+      READER_METHODS = %i[messages options queue scene prompt last_prompt last_input].freeze
+      WRITER_METHODS = %i[messages= prompt= last_prompt= last_input=].freeze
+
+      attr_reader :raw_data
+
+      def initialize **data
+        @raw_data = {
+          messages: '',
+          options: [],
+          queue: [],
+          scene: {},
+          prompt: ''
+        }
+        merge! data
+      end
+
+      # @!attribute [rw] messages
+      #   A text message to be displayed at the start of a scene.
+      #
+      #   @return [String]
+
+      # @!attribute [rw] options
+      #   An array of options to be presented to the player, e.g., in a
+      #   MultipleChoice scene.
+      #
+      #   @return [Array<String>]
+
+      # @!attribute [rw] queue
+      #   An array of commands waiting to be executed.
+      #
+      #   @return [Array<String>]
+
+      # @!attribute [rw] scene
+      #   A hash containing the scene's :name and :type.
+      #
+      #   @return [Hash]
+
+      # @!attribute [rw] [prompt]
+      #   The input prompt to be displayed to the player.
+      #
+      #   @return [String]
+
+      # @!attribute [rw] last_input
+      #   The input received from the player in the previous scene.
+      #
+      #   @return [String, nil]
+
+      # @!attribute [rw] last_prompt
+      #   The input prompt from the previous scene.
+      #
+      #   @return [String, nil]
+
+      # @param key [Symbol]
+      def [] key
+        raw_data[key]
+      end
+
+      # @param key [Symbol]
+      # @param value [Object]
+      def []= key, value
+        raw_data[key] = value
+      end
+
+      # @return [Hash]
+      def to_hash
+        raw_data.dup
+      end
+
+      def to_json _ = nil
+        raw_data.to_json
+      end
+
+      def merge! data
+        data.each { |key, val| self[key] = val }
+      end
+
+      def replace data
+        raw_data.replace data
+      end
+
+      def freeze
+        raw_data.freeze
+        super
+      end
+
+      def method_missing method, *args
+        return raw_data[method] if READER_METHODS.include?(method)
+
+        return raw_data[method.to_s[0..-2].to_sym] = args.first if WRITER_METHODS.include?(method)
+
+        super
+      end
+
+      def respond_to_missing?(method, _with_private = false)
+        READER_METHODS.include?(method) || WRITER_METHODS.include?(method)
+      end
+    end
+  end
+end

data/lib/gamefic/props/pause.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Gamefic
   module Props
     # Props for Pause scenes.

data/lib/gamefic/props.rb

@@ -6,5 +6,6 @@ module Gamefic
     require 'gamefic/props/multiple_choice'
     require 'gamefic/props/pause'
     require 'gamefic/props/yes_or_no'
+    require 'gamefic/props/output'
   end
 end

data/lib/gamefic/query/base.rb

@@ -24,6 +24,12 @@ module Gamefic
         @ambiguous = ambiguous
       end
 
+      # @deprecated Queries should only be used to select entities that are
+      #   eligible to be response arguments. After a text command is tokenized
+      #   into an array of expressions, the composer builds the command that
+      #   the dispatcher uses to execute actions. The #accept? method verifies
+      #   that the command's arguments match the response's queries.
+      #
       # @param subject [Gamefic::Entity]
       # @param token [String]
       # @return [Result]
@@ -31,6 +37,24 @@ module Gamefic
         raise "#query not implemented for #{self.class}"
       end
 
+      # Get an array of entities that match the query from the context of the
+      # subject.
+      #
+      # @param subject [Entity]
+      # @return [Array<Entity>]
+      def select subject
+        raise "#select not implemented for #{self.class}"
+      end
+
+      def accept?(subject, object)
+        available = select(subject)
+        if ambiguous?
+          object & available == object
+        else
+          available.include?(object)
+        end
+      end
+
       # @return [Integer]
       def precision
         @precision ||= calculate_precision

data/lib/gamefic/query/general.rb

@@ -19,6 +19,10 @@ module Gamefic
         @entities = entities
       end
 
+      def select subject
+        available_entities(subject).that_are(*@arguments)
+      end
+
       def query subject, token
         filtered = available_entities(subject).that_are(*@arguments)
         return Result.new(token, nil) if filtered.include?(token)

data/lib/gamefic/query/scoped.rb

@@ -16,6 +16,11 @@ module Gamefic
         @scope = scope
       end
 
+      def select(subject)
+        @scope.matches(subject)
+              .that_are(*@arguments)
+      end
+
       # @return [Result]
       def query(subject, token)
         available = @scope.matches(subject)

data/lib/gamefic/query/text.rb

@@ -5,12 +5,17 @@ module Gamefic
     # A special query that handles text instead of entities.
     #
     class Text
-      # @param argument [String, Regexp, nil]
-      def initialize argument = nil
+      # @param argument [String, Regexp]
+      def initialize argument = /.*/
         @argument = argument
         validate
       end
 
+      # @return [String, Regexp]
+      def select(_subject)
+        @argument
+      end
+
       def query _subject, token
         if match? token
           Result.new(token, '')
@@ -23,11 +28,17 @@ module Gamefic
         0
       end
 
+      def accept? _subject, argument
+        match? argument
+      end
+
+      def ambiguous?
+        true
+      end
+
       private
 
       def match? token
-        return true if @argument.nil?
-
         case @argument
         when Regexp
           token =~ @argument
@@ -37,7 +48,7 @@ module Gamefic
       end
 
       def validate
-        return if @argument.nil? || @argument.is_a?(String) || @argument.is_a?(Regexp)
+        return if @argument.is_a?(String) || @argument.is_a?(Regexp)
 
         raise ArgumentError, 'Invalid text query argument'
       end

data/lib/gamefic/response.rb

@@ -1,4 +1,4 @@
-# frozen_literal_string: true
+# frozen_string_literal: true
 
 module Gamefic
   # A proc to be executed in response to a command that matches its verb and
@@ -11,17 +11,17 @@ module Gamefic
     # @return [Array<Query::Base>]
     attr_reader :queries
 
-    # @return [Proc]
-    # attr_reader :block
+    # @return [Narrative]
+    attr_reader :narrative
 
     # @param verb [Symbol]
-    # @param stage [Object]
+    # @param narrative [Narrative]
     # @param queries [Array<Query::Base>]
     # @param meta [Boolean]
     # @param block [Proc]
-    def initialize verb, stage, *queries, meta: false, &block
+    def initialize verb, narrative, *queries, meta: false, &block
       @verb = verb
-      @stage = stage
+      @narrative = narrative
       @queries = map_queryable_objects(queries)
       @meta = meta
       @block = block
@@ -48,35 +48,29 @@ module Gamefic
     #
     # @param actor [Entity]
     # @param command [Command]
-    # @param with_hooks [Boolean]
     # @return [Action, nil]
     def attempt actor, command
-      return nil if command.verb != verb
+      return nil unless accept?(actor, command)
 
-      tokens = command.arguments.clone
-      result = []
-      remainder = ''
-
-      queries.each do |qd|
-        token = tokens.shift
-        txt = "#{remainder} #{token}".strip
-        return nil if txt.empty?
-
-        response = qd.query(actor, txt)
-        return nil if response.match.nil?
+      Action.new(actor, command.arguments, self)
+    end
 
-        result.push response.match
+    # True if the Response can be executed for the given actor and command.
+    #
+    # @param actor [Active]
+    # @param command [Command]
+    def accept? actor, command
+      return false if command.verb != verb || command.arguments.length != queries.length
 
-        remainder = response.remainder
+      queries.each_with_index do |query, idx|
+        return false unless query.accept?(actor, command.arguments[idx])
       end
 
-      return nil unless tokens.empty? && remainder.empty?
-
-      Action.new(actor, result, self)
+      true
     end
 
     def execute *args
-      Stage.run(@stage, *args, &@block)
+      Stage.run(narrative, *args, &@block)
     end
 
     def precision

data/lib/gamefic/rulebook/events.rb

@@ -34,16 +34,16 @@ module Gamefic
         self
       end
 
-      # @return [Proc]
+      # @return [void]
       def on_ready &block
         @ready_blocks.push block
       end
 
       # @yieldparam [Actor]
-      # @return [Proc]
+      # @return [void]
       def on_player_ready &block
         @ready_blocks.push(proc do
-          players.each { |plyr| block.call plyr }
+          players.each { |plyr| instance_exec plyr, &block }
         end)
       end
 
@@ -53,24 +53,24 @@ module Gamefic
 
       def on_player_update &block
         @update_blocks.push(proc do
-          players.each { |plyr| block.call plyr }
+          players.each { |plyr| instance_exec plyr, &block }
         end)
       end
 
-      # @return [Proc]
+      # @return [void]
       def on_conclude &block
         @conclude_blocks.push block
       end
 
       # @yieldparam [Actor]
-      # @return [Proc]
+      # @return [void]
       def on_player_conclude &block
         @player_conclude_blocks.push block
       end
 
       # @yieldparam [Actor]
       # @yieldparam [Hash]
-      # @return [Proc]
+      # @return [void]
       def on_player_output &block
         @player_output_blocks.push block
       end

data/lib/gamefic/rulebook.rb

@@ -116,11 +116,11 @@ module Gamefic
     end
 
     def run_player_conclude_blocks player
-      events.player_conclude_blocks.each { |blk| Stage.run(narrative) { blk.call(player) } }
+      events.player_conclude_blocks.each { |blk| Stage.run(narrative, player, &blk) }
     end
 
     def run_player_output_blocks player, output
-      events.player_output_blocks.each { |blk| Stage.run(narrative) { blk.call(player, output) } }
+      events.player_output_blocks.each { |blk| Stage.run(narrative, player, output, &blk) }
     end
 
     def empty?

data/lib/gamefic/scanner.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Gamefic
   # A module for matching objects to tokens.
   #
@@ -11,7 +13,7 @@ module Gamefic
     class Result
       # The scanned objects
       #
-      # @return [Array<Object>]
+      # @return [Array<Entity>, String, Regexp]
       attr_reader :scanned
 
       # The scanned token
@@ -21,7 +23,7 @@ module Gamefic
 
       # The matched objects
       #
-      # @return [Array<Object>]
+      # @return [Array<Entity>, String]
       attr_reader :matched
 
       # The remaining (unmatched) portion of the token
@@ -39,36 +41,53 @@ module Gamefic
 
     # Scan entities against a token.
     #
-    # @param objects [Array<Gamefic::Entity>]
+    # @param selection [Array<Entity>, String, Regexp]
     # @param token [String]
     # @return [Result]
-    def self.scan objects, token
-      # @note Theoretically, scanned objects only have to implement two
-      #   methods:
-      #     *  #keywords => [Array<String>]
-      #     *  #children => [Array<#keywords, #children>]
-
-      words = token.keywords
-      available = objects.clone
-      filtered = []
-      if nested?(token) && objects.all?(&:children)
-        denest(objects, token)
-      else
-        words.each_with_index do |word, idx|
-          tested = select_strict(available, word)
-          tested = select_fuzzy(available, word) if tested.empty?
-          return Result.new(objects, token, filtered, words[idx..].join(' ')) if tested.empty?
-
-          filtered = tested
-          available = filtered
-        end
-        Result.new(objects, token, filtered, '')
-      end
+    def self.scan selection, token
+      strict_result = strict(selection, token)
+      strict_result.matched.empty? ? fuzzy(selection, token) : strict_result
+    end
+
+    # @param selection [Array<Entity>, String, Regexp]
+    # @param token [String]
+    # @return [Result]
+    def self.strict selection, token
+      return Result.new(selection, token, '', token) unless selection.is_a?(Array)
+
+      scan_strict_or_fuzzy(selection, token, :select_strict)
+    end
+
+    # @param selection [Array<Entity>, String, Regexp]
+    # @param token [String]
+    # @return [Result]
+    def self.fuzzy selection, token
+      return scan_text(selection, token) unless selection.is_a?(Array)
+
+      scan_strict_or_fuzzy(selection, token, :select_fuzzy)
     end
 
     class << self
       private
 
+      def scan_strict_or_fuzzy objects, token, method
+        if nested?(token) && objects.all?(&:children)
+          denest(objects, token)
+        else
+          words = token.keywords
+          available = objects.clone
+          filtered = []
+          words.each_with_index do |word, idx|
+            tested = send(method, available, word)
+            return Result.new(objects, token, filtered, words[idx..].join(' ')) if tested.empty?
+
+            filtered = tested
+            available = filtered
+          end
+          Result.new(objects, token, filtered, '')
+        end
+      end
+
       def select_strict available, word
         available.select { |obj| obj.keywords.include?(word) }
       end
@@ -81,6 +100,16 @@ module Gamefic
         token.match(NEST_REGEXP)
       end
 
+      def scan_text selection, token
+        case selection
+        when Regexp
+          return Result.new(selection, token, token, '') if token =~ selection
+        else
+          return Result.new(selection, token, selection, token[selection.length..]) if token.start_with?(selection)
+        end
+        Result.new(selection, token, '', token)
+      end
+
       def denest(objects, token)
         parts = token.split(NEST_REGEXP)
         current = parts.pop

data/lib/gamefic/scene/default.rb

@@ -30,7 +30,7 @@ module Gamefic
       end
 
       def new_props(**context)
-        self.class.props_class.new(name, type, **context)
+        self.class.props_class.new(self, **context)
       end
 
       def on_start &block
@@ -45,8 +45,8 @@ module Gamefic
       # @param props [Props::Default]
       # @return [void]
       def start actor, props
-        actor.output[:scene] = to_hash
-        actor.output[:prompt] = props.prompt
+        props.output[:scene] = to_hash
+        props.output[:prompt] = props.prompt
       end
 
       # @param actor [Gamefic::Actor]

data/lib/gamefic/scene/multiple_choice.rb

@@ -10,7 +10,7 @@ module Gamefic
 
       def start actor, props
         super
-        actor.output[:options] = props.options
+        props.output[:options] = props.options
       end
 
       def finish actor, props

data/lib/gamefic/scriptable/entities.rb

@@ -55,7 +55,10 @@ module Gamefic
       # @param description [String]
       # @return [Gamefic::Entity, nil]
       def pick description
-        Gamefic::Query::General.new(entities).query(nil, description).match
+        result = Scanner.scan(entities, description)
+        return nil unless result.matched.one?
+
+        result.matched.first
       end
 
       # Same as #pick, but raise an error if a unique match could not be found.
@@ -63,13 +66,13 @@ module Gamefic
       # @param description [String]
       # @return [Gamefic::Entity, nil]
       def pick! description
-        ary = Gamefic::Query::General.new(entities, ambiguous: true).query(nil, description).match
+        result = Scanner.scan(entities, description)
 
-        raise "no entity matching '#{description}'" if ary.nil?
+        raise "no entity matching '#{description}'" if result.matched.empty?
 
-        raise "multiple entities matching '#{description}': #{ary.join_and}" unless ary.one?
+        raise "multiple entities matching '#{description}': #{result.matched.join_and}" unless result.matched.one?
 
-        ary.first
+        result.matched.first
       end
     end
   end

data/lib/gamefic/scriptable/proxy.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Gamefic
   module Scriptable
     # Functions that provide proxies for referencing a narrative's entities
@@ -15,6 +17,15 @@ module Gamefic
         end
 
         def fetch container
+          result = safe_fetch(container)
+          raise ArgumentError, "Unable to fetch entity from proxy agent symbol `#{symbol}`" unless result
+
+          result
+        end
+
+        private
+
+        def safe_fetch container
           if symbol.to_s =~ /^\d+$/
             Stage.run(container, symbol) { |sym| entities[sym] }
           elsif symbol.to_s.start_with?('@')
@@ -22,6 +33,8 @@ module Gamefic
           else
             Stage.run(container, symbol) { |sym| send(sym) }
           end
+        rescue NoMethodError
+          nil
         end
       end
 

data/lib/gamefic/scriptable/queries.rb

@@ -63,9 +63,9 @@ module Gamefic
       # any text it finds in the command. A successful query returns the
       # corresponding text instead of an entity.
       #
-      # @param arg [String, Regrxp] The string or regular expression to match
+      # @param arg [String, Regexp] The string or regular expression to match
       # @return [Query::Text]
-      def plaintext arg = nil
+      def plaintext arg = /.*/
         Query::Text.new arg
       end
     end

data/lib/gamefic/scriptable/scenes.rb

@@ -32,8 +32,8 @@ module Gamefic
       # @param block [Proc]
       # @yieldparam [Scene]
       # @return [Symbol]
-      def block name, klass = Scene::Default, on_start: nil, on_finish: nil, &block
-        rulebook.scenes.add klass.new(name, rulebook.narrative, on_start: on_start, on_finish: on_finish, &block)
+      def block name, klass = Scene::Default, on_start: nil, on_finish: nil, &blk
+        rulebook.scenes.add klass.new(name, rulebook.narrative, on_start: on_start, on_finish: on_finish, &blk)
         name
       end
       alias scene block
@@ -77,14 +77,14 @@ module Gamefic
       # @yieldparam [Actor]
       # @yieldparam [Props::MultipleChoice]
       # @return [Symbol]
-      def multiple_choice name, choices = [], prompt = 'What is your choice?', &block
+      def multiple_choice name, choices = [], prompt = 'What is your choice?', &blk
         block name,
               Scene::MultipleChoice,
               on_start: proc { |_actor, props|
                 props.prompt = prompt
                 props.options.concat choices
               },
-              on_finish: block
+              on_finish: blk
       end
 
       # Create a yes-or-no scene.
@@ -105,13 +105,13 @@ module Gamefic
       # @yieldparam [Actor]
       # @yieldparam [Props::YesOrNo]
       # @return [Symbol]
-      def yes_or_no name, prompt = 'Answer:', &block
+      def yes_or_no name, prompt = 'Answer:', &blk
         block name,
               Scene::YesOrNo,
               on_start: proc { |_actor, props|
                 props.prompt = prompt
               },
-              on_finish: block
+              on_finish: blk
       end
 
       # Create a scene that pauses the game.

data/lib/gamefic/snapshot.rb

@@ -27,10 +27,18 @@ module Gamefic
       Marshal.load(binary).tap do |plot|
         plot.hydrate
         # @todo Opal marshal dumps are not idempotent
-        next if RUBY_ENGINE == 'opal' || Snapshot.save(plot) == snapshot
+        next if RUBY_ENGINE == 'opal' || match?(plot, snapshot)
 
         Logging.logger.warn "Scripts modified #{plot.class} data. Snapshot may not have restored properly"
       end
     end
+
+    # True if the plot's state matches the snapshot.
+    #
+    # @param plot [Plot]
+    # @param snapshot [String]
+    def self.match?(plot, snapshot)
+      save(plot) == snapshot
+    end
   end
 end