gamefic 2.2.3 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a57ab533bcfbcbd650cf3ee60c5a639b3ddd40ad3ad96d0d4e42e6658547f3d9
-  data.tar.gz: 904c5211a6bde65f870ae8bab1218423afd6618c6ddd79c44b01174bb069256b
+  metadata.gz: aa8d74d06ad87105050c1ca487acd976d293f4ca52fa6cc760061ccdbb3a14e7
+  data.tar.gz: f791519291a168cf31045d6bc2f136d4829f5ddce2fa7c370d6c4887f83f560e
 SHA512:
-  metadata.gz: afc3e6a06d6ac451827cea70db94b8c9e4b10c795dac9812df0c24f8c1e0ce654748dfae53c4c0565bbfff8abb5d2f853f866c1aac8b398c5cf8331ee3ea1795
-  data.tar.gz: dd790a5574ae81e91b61d01c7f18adba0abcd7e43650e72934329dfd84c9515adb54b6e1e0938814c9d6c6582d23801c66a470a28ae99700659fa0c462830660
+  metadata.gz: e8abcf0f9ca24db9b8bc3f61be5d0d28dcd86c24f047e420eb117bd09411b70d5f3ae7e9c2c5d2277062c4c72a970d2c9144eb0990a46872eb80b7a7bd75369e
+  data.tar.gz: 2bdec46fe7d946a05c3d9bf258314db25c61f32459993f03f1c2096dd31b0056917332fcd5c05ee011e3c352e373a1dcaa74f670d069398e481334ff64c07f1d

data/CHANGELOG.md

@@ -1,5 +1,10 @@
+## 2.3.0 - January 25, 2023
+- Remove unused Active#actions method
+- Add before_action and after_action hooks
+
 ## 2.2.3 - July 9, 2022
 - Fix Ruby version incompatibilities
+- Fix private attr_accessor call
 
 ## 2.2.2 - September 6, 2021
 - Darkroom indexes non-static elements

data/lib/gamefic/action.rb

@@ -1,5 +1,8 @@
 module Gamefic
   class Action
+    # @return [Gamefic::Actor]
+    attr_reader :actor
+
     # An array of objects on which the action will operate, e.g., an entity
     # that is a direct object of a command.
     #
@@ -7,17 +10,31 @@ module Gamefic
     attr_reader :arguments
     alias parameters arguments
 
-    def initialize actor, arguments
+    # @param actor [Gamefic::Actor]
+    # @param arguments [Array<Object>]
+    def initialize actor, arguments, with_callbacks = false
       @actor = actor
       @arguments = arguments
       @executed = false
+      @with_callbacks = with_callbacks
     end
 
     # Perform the action.
     #
     def execute
-      @executed = true
+      return if @cancelled
+      run_before_actions
+      return if @cancelled
       self.class.executor.call(@actor, *arguments) unless self.class.executor.nil?
+      @executed = true
+      run_after_actions
+    end
+
+    # Cancel an action. This method can be called in a before_action hook to
+    # prevent subsequent hooks and the action itself from being executed.
+    #
+    def cancel
+      @cancelled = true
     end
 
     # True if the #execute method has been called for this action.
@@ -68,6 +85,25 @@ module Gamefic
       act
     end
 
+    private
+
+    def run_before_actions
+      return unless @with_callbacks
+      @actor.playbooks
+            .flat_map(&:before_actions)
+            .each do |block|
+              block.call(self)
+              break if @cancelled
+            end
+    end
+
+    def run_after_actions
+      return unless @with_callbacks
+      @actor.playbooks
+            .flat_map(&:after_actions)
+            .each { |block| block.call(self) }
+    end
+
     class << self
       attr_reader :verb
 
@@ -135,7 +171,7 @@ module Gamefic
       # @param action [Gamefic::Entity]
       # @param command [Command]
       # @return [self, nil]
-      def attempt actor, command
+      def attempt actor, command, with_callbacks = false
         return nil if command.verb != verb
         tokens = command.arguments
         result = []
@@ -153,7 +189,7 @@ module Gamefic
             result.push accepted.first
           end
         end
-        new(actor, result)
+        new(actor, result, with_callbacks)
       end
 
       protected

data/lib/gamefic/active.rb

@@ -1,3 +1,5 @@
+require 'set'
+
 module Gamefic
   class NotConclusionError < RuntimeError; end
 
@@ -37,7 +39,7 @@ module Gamefic
     end
 
     def syntaxes
-      playbooks.map(&:syntaxes).flatten
+      playbooks.flat_map(&:syntaxes)
     end
 
     # An array of actions waiting to be performed.
@@ -84,28 +86,18 @@ module Gamefic
     end
 
     # Perform a command.
-    # The command can be specified as a String or a verb with a list of
-    # parameters. Either form should yield the same result, but the
-    # verb/parameter form can yield better performance since it bypasses the
-    # parser.
     #
-    # The command will be executed immediately regardless of the entity's
-    # state.
+    # The command's action will be executed immediately regardless of the
+    # entity's state.
     #
     # @example Send a command as a string
     #   character.perform "take the key"
     #
-    # @example Send a command as a verb with parameters
-    #   character.perform :take, @key
-    #
-    # @todo Modify this method so it only accepts a single command.
-    #   Verbs with parameters should use Active#execute instead.
-    #   It might be necessary to support command splats with a deprecation
-    #   warning until version 3.
-    #
+    # @param command [String, Symbol]
     # @return [Gamefic::Action]
     def perform(*command)
       if command.length > 1
+        STDERR.puts "[WARN] #{caller[0]}: Passing a verb and arguments to #perform is deprecated. Use #execute instead."
         execute command.first, *command[1..-1]
       else
         dispatchers.push Dispatcher.dispatch(self, command.first.to_s)
@@ -118,16 +110,18 @@ module Gamefic
     # This method executes the command exactly as #perform does, except it
     # buffers the resulting output instead of sending it to the user.
     #
-    # @todo Modify this method so it only accepts a single command.
-    #   See Active#perform for more information.
-    #
+    # @param command [String, Symbol]
     # @return [String] The output that resulted from performing the command.
     def quietly(*command)
-      clear_buffer if buffer_stack == 0
-      set_buffer_stack buffer_stack + 1
-      self.perform *command
-      set_buffer_stack buffer_stack - 1
-      buffer
+      if command.length > 1
+        STDERR.puts "#{caller[0]}: Passing a verb and arguments to #quietly is deprecated. Use #execute instead"
+        execute command.first, *command[1..-1], quietly: true
+      else
+        dispatchers.push Dispatcher.dispatch(self, command.first.to_s)
+        result = proceed quietly: true
+        dispatchers.pop
+        result
+      end
     end
 
     # Perform an action.
@@ -141,6 +135,9 @@ module Gamefic
     # @example
     #   character.execute :take, @key
     #
+    # @param verb [Symbol]
+    # @param params [Array]
+    # @params quietly [Boolean]
     # @return [Gamefic::Action]
     def execute(verb, *params, quietly: false)
       dispatchers.push Dispatcher.dispatch_from_params(self, verb, params)
@@ -171,21 +168,15 @@ module Gamefic
     #     end
     #   end
     #
+    # @param quietly [Boolean] If true, return the action's output instead of appending it to #messages
+    # @return [String, nil]
     def proceed quietly: false
       return if dispatchers.empty?
       a = dispatchers.last.next
       return if a.nil?
-      if quietly
-        if buffer_stack == 0
-          @buffer = ""
-        end
-        set_buffer_stack(buffer_stack + 1)
-      end
+      prepare_buffer quietly
       a.execute
-      if quietly
-        set_buffer_stack(buffer_stack - 1)
-        @buffer
-      end
+      flush_buffer quietly
     end
 
     # Immediately start a new scene for the character.
@@ -251,8 +242,8 @@ module Gamefic
     # Track the entity's performance of a scene.
     #
     def entered scene
-      klass = (scene.kind_of?(Gamefic::Scene::Base) ? scene.class : scene)
-      entered_scenes.push klass unless entered_scenes.include?(klass)
+      klass = (scene.is_a?(Gamefic::Scene::Base) ? scene.class : scene)
+      entered_scenes.add klass
     end
 
     # Determine whether the entity has performed the specified scene.
@@ -265,9 +256,25 @@ module Gamefic
 
     private
 
-    # @return [Array<Gamefic::Scene::Base>]
+    def prepare_buffer quietly
+      if quietly
+        if buffer_stack == 0
+          @buffer = ""
+        end
+        set_buffer_stack(buffer_stack + 1)
+      end
+    end
+
+    def flush_buffer quietly
+      if quietly
+        set_buffer_stack(buffer_stack - 1)
+        @buffer
+      end
+    end
+
+    # @return [Set<Gamefic::Scene::Base>]
     def entered_scenes
-      @entered_scenes ||= []
+      @entered_scenes ||= Set.new
     end
 
     def buffer_stack

data/lib/gamefic/core_ext/array.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Array
   # Get a subset of the array that matches the arguments.
   # If the argument is a Class or Module, the elements must be of the type.
@@ -12,7 +14,7 @@ class Array
   #
   # @return [Array]
   def that_are(*cls)
-    result = self.clone
+    result = clone
     cls.each do |c|
       _keep result, c, true
     end
@@ -24,7 +26,7 @@ class Array
   #
   # @return [Array]
   def that_are_not(*cls)
-    result = self.clone
+    result = clone
     cls.each do |c|
       _keep result, c, false
     end
@@ -34,7 +36,7 @@ class Array
   # Pop a random element from the array.
   #
   def pop_sample
-    delete_at(rand(self.length))
+    delete_at(rand(length))
   end
 
   # Get a string representation of the array that separates elements with
@@ -48,31 +50,32 @@ class Array
   # @param andSep [String] The separator for the last element
   # @param serial [Boolean] Use serial separators (e.g., serial commas)
   # @return [String]
-  def join_and(sep = ', ', andSep = ' and ', serial = true)
-    if self.length < 3
-      self.join(andSep)
+  def join_and(sep = ', ', and_sep = ' and ', serial = true)
+    if length < 3
+      join(and_sep)
     else
       start = self[0..-2]
-      start.join(sep) + "#{serial ? sep.strip : ''}#{andSep}#{self.last}"
+      start.join(sep) + "#{serial ? sep.strip : ''}#{and_sep}#{last}"
     end
   end
 
   # @see Array#join_and
   #
   # @return [String]
-  def join_or(sep = ', ', orSep = ' or ', serial = true)
-    join_and(sep, orSep, serial)
+  def join_or(sep = ', ', or_sep = ' or ', serial = true)
+    join_and(sep, or_sep, serial)
   end
 
   private
 
   def _keep(arr, cls, bool)
-    if (cls.kind_of?(Class) or cls.kind_of?(Module))
+    case cls
+    when Class, Module
       arr.keep_if { |i| i.is_a?(cls) == bool }
-    elsif cls.kind_of?(Symbol)
+    when Symbol
       arr.keep_if { |i| i.send(cls) == bool }
     else
-      arr.keep_if {|i| (i == cls) == bool}
+      arr.keep_if { |i| (i == cls) == bool }
     end
   end
 end

data/lib/gamefic/dispatcher.rb

@@ -9,6 +9,7 @@ module Gamefic
       @actor = actor
       @commands = commands
       @actions = actions
+      @started = false
     end
 
     def merge dispatcher
@@ -21,13 +22,9 @@ module Gamefic
       while instance.nil? && !@actions.empty?
         action = actions.shift
         commands.each do |cmd|
-          instance = action.attempt(actor, cmd)
+          instance = action.attempt(actor, cmd, !@started)
           if instance
-            unless instance.meta?
-              actor.playbooks.reverse.each do |playbook|
-                return nil unless validate_playbook(playbook, instance)
-              end
-            end
+            @started = true
             break
           end
         end
@@ -66,11 +63,5 @@ module Gamefic
 
     # @return [Array<Action>]
     attr_reader :actions
-
-    private
-
-    def validate_playbook playbook, action
-      playbook.validators.all? { |v| v.call(actor, action.verb, action.parameters) != false }
-    end
   end
 end

data/lib/gamefic/plot.rb

@@ -34,6 +34,10 @@ module Gamefic
       @static = [self] + scene_classes + entities
     end
 
+    def plot
+      self
+    end
+
     # Get an Array of the Plot's current Syntaxes.
     #
     # @return [Array<Syntax>]

data/lib/gamefic/query/base.rb

@@ -1,7 +1,7 @@
 module Gamefic
   module Query
     class Base
-      NEST_REGEXP = / in | on | of | from | inside /
+      NEST_REGEXP = / in | on | of | from | inside | from inside /
 
       attr_reader :arguments
 
@@ -31,6 +31,9 @@ module Gamefic
       # Get a collection of objects that exist in the subject's context and
       # match the provided token. The result is provided as a Matches object.
       #
+      # @param subject [Entity]
+      # @param token [String]
+      # @param continued [Boolean]
       # @return [Gamefic::Query::Matches]
       def resolve(subject, token, continued: false)
         available = context_from(subject)
@@ -38,14 +41,13 @@ module Gamefic
         if continued
           return Matches.execute(available, token, continued: continued)
         elsif nested?(token)
-          drill = denest(available, token)
-          drill.keep_if{ |e| accept?(e) }
+          drill = denest(available, token).select { |e| accept?(e) }
           return Matches.new(drill, token, '') unless drill.length != 1
           return Matches.new([], '', token)
         end
-        result = available.select{ |e| e.specified?(token) }
-        result = available.select{ |e| e.specified?(token, fuzzy: true) } if result.empty?
-        result.keep_if{ |e| accept? e }
+        result = available.select { |e| e.specified?(token) }
+        result = available.select { |e| e.specified?(token, fuzzy: true) } if result.empty?
+        result.keep_if { |e| accept? e }
         Matches.new(result, (result.empty? ? '' : token), (result.empty? ? token : ''))
       end
 
@@ -82,6 +84,7 @@ module Gamefic
 
       # Determine whether the specified entity passes the query's arguments.
       #
+      # @param [Entity]
       # @return [Boolean]
       def accept?(entity)
         result = true
@@ -106,6 +109,7 @@ module Gamefic
       # recursively append its children.
       # The result will NOT include the original entity itself.
       #
+      # @param [Entity]
       # @return [Array<Object>]
       def subquery_accessible entity
         return [] if entity.nil?

data/lib/gamefic/query/external.rb

@@ -1,17 +1,38 @@
 module Gamefic
   module Query
     class External < Base
-      def initialize objects, *args
+      # @param container [Plot, Subplot, Array]
+      def initialize container, *args
         super(*args)
-        @objects = objects
+        @container = container
       end
 
       def context_from subject
-        @objects
+        Set.new
+           .merge(container_entities)
+           .merge(container_subplots_for(@container, subject))
+           .to_a
       end
 
-      def accept?(entity)
-        @objects.include?(entity) && super(entity)
+      private
+
+      # @return [Array<Entity>]
+      def container_entities
+        if @container.is_a?(World::Entities)
+          @container.entities
+        elsif @container.is_a?(Enumerable)
+          @container
+        else
+          raise ArgumentError, "Unable to derive entities from #{@container}"
+        end
+      end
+
+      # @return [Array<Entity>]
+      def container_subplots_for container, subject
+        return [] unless container.is_a?(Plot::Host)
+        container.subplots_featuring(subject).flat_map do |subplot|
+          subplot.entities + container_subplots_for(subplot, subject)
+        end
       end
     end
   end

data/lib/gamefic/subplot.rb

@@ -1,7 +1,10 @@
 require 'gamefic/plot'
 
 module Gamefic
-  class Subplot #< Container
+  # Subplots are disposable plots that run inside a parent plot. They can be
+  # started and concluded at any time during the parent plot's execution.
+  #
+  class Subplot
     include World
     include Scriptable
     include Gamefic::Serialize

data/lib/gamefic/version.rb

@@ -1,3 +1,3 @@
 module Gamefic
-  VERSION = '2.2.3'
+  VERSION = '2.3.0'
 end

data/lib/gamefic/world/commands.rb

@@ -95,11 +95,19 @@ module Gamefic
         playbook.meta command, *queries, &proc
       end
 
-      # Validate an order before a character can execute its command.
+      # Add a proc to be evaluated before a character executes an action.
       #
-      # @yieldparam [Gamefic::Director::Order]
-      def validate &block
-        playbook.validate &block
+      # @yieldparam [Gamefic::Action]
+      def before_action &block
+        playbook.before_actions.push block
+      end
+      alias validate before_action
+
+      # Add a proc to be evaluated after a character executes an action.
+      #
+      # @yieldparam [Gamefic::Action]
+      def after_action &block
+        playbook.after_actions.push block
       end
 
       # Create an alternate Syntax for an Action.

data/lib/gamefic/world/playbook.rb

@@ -10,19 +10,26 @@ module Gamefic
       # @return [Array<Gamefic::Syntax>]
       attr_reader :syntaxes
 
-      # An array of defined validators.
+      # An array of blocks to execute before actions.
       #
       # @return [Array<Proc>]
-      attr_reader :validators
+      attr_reader :before_actions
+
+      # An array of blocks to execute after actions.
+      #
+      # @return [Array<Proc>]
+      attr_reader :after_actions
 
       # @param commands [Hash]
       # @param syntaxes [Array<Syntax>, Set<Syntax>]
-      # @param validators [Array]
-      def initialize commands: {}, syntaxes: [], validators: []
+      # @param before_actions [Array]
+      # @param after_actions [Array]
+      def initialize commands: {}, syntaxes: [], before_actions: [], after_actions: []
         @commands = commands
         @syntax_set = syntaxes.to_set
         sort_syntaxes
-        @validators = validators
+        @before_actions = before_actions
+        @after_actions = after_actions
       end
 
       # An array of available actions.
@@ -39,10 +46,19 @@ module Gamefic
         @commands.keys
       end
 
-      # Add a block that determines whether an action can be executed.
+      # Add a proc to be evaluated before a character executes an action.
+      #
+      # @yieldparam [Gamefic::Action]
+      def before_action &block
+        @before_actions.push block
+      end
+      alias validate before_action
+
+      # Add a proc to be evaluated after a character executes an action.
       #
-      def validate &block
-        @validators.push block
+      # @yieldparam [Gamefic::Action]
+      def after_action &block
+        @after_actions.push block
       end
 
       # Get an Array of all Actions associated with the specified verb.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gamefic
 version: !ruby/object:Gem::Version
-  version: 2.2.3
+  version: 2.3.0
 platform: ruby
 authors:
 - Fred Snyder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-09 00:00:00.000000000 Z
+date: 2023-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake