gamefic 3.3.0 → 3.5.0

data/lib/gamefic/scanner.rb

@@ -1,132 +1,54 @@
 # frozen_string_literal: true
 
+require 'gamefic/scanner/result'
+require 'gamefic/scanner/base'
+require 'gamefic/scanner/strict'
+require 'gamefic/scanner/fuzzy'
+require 'gamefic/scanner/nesting'
+require 'gamefic/scanner/fuzzy_nesting'
+
 module Gamefic
   # A module for matching objects to tokens.
   #
   module Scanner
-    NEST_REGEXP = / in | on | of | from | inside | from inside /
-
-    # The result of an attempt to scan objects against a token in a Scanner. It
-    # provides an array of matching objects, the text that matched them, and the
-    # text that remains unmatched.
-    #
-    class Result
-      # The scanned objects
-      #
-      # @return [Array<Entity>, String, Regexp]
-      attr_reader :scanned
-
-      # The scanned token
-      #
-      # @return [String]
-      attr_reader :token
-
-      # The matched objects
-      #
-      # @return [Array<Entity>, String]
-      attr_reader :matched
-
-      # The remaining (unmatched) portion of the token
-      #
-      # @return [String]
-      attr_reader :remainder
-
-      def initialize scanned, token, matched, remainder
-        @scanned = scanned
-        @token = token
-        @matched = matched
-        @remainder = remainder
-      end
-    end
+    DEFAULT_PROCESSORS = [Nesting, Strict, FuzzyNesting, Fuzzy].freeze
 
     # Scan entities against a token.
     #
-    # @param selection [Array<Entity>, String, Regexp]
+    # @param selection [Array<Entity>]
     # @param token [String]
     # @return [Result]
     def self.scan selection, token
-      strict_result = strict(selection, token)
-      strict_result.matched.empty? ? fuzzy(selection, token) : strict_result
+      result = nil
+      processors.each do |processor|
+        result = processor.scan(selection, token)
+        break unless result.matched.empty?
+      end
+      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)
+    # Select the scanner processors to use in entity queries. Each processor
+    # will be used in order until one of them returns matches. The default
+    # processor list is `DEFAULT_PROCESSORS`.
+    #
+    # Processor classes should be in order from most to least strict rules
+    # for matching tokens to entities.
+    #
+    # @param klasses [Array<Class<Base>>]
+    # @return [Array<Class<Base>>]
+    def self.use *klasses
+      processors.replace klasses.flatten
     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)
+    # @return [Array<Class<Base>>]
+    def self.processors
+      @processors ||= []
     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
-
-      def select_fuzzy available, word
-        available.select { |obj| obj.keywords.any? { |wrd| wrd.start_with?(word) } }
-      end
-
-      def nested?(token)
-        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
-        last_result = scan(objects, current)
-        until parts.empty?
-          current = "#{parts.last} #{current}"
-          result = scan(last_result.matched, current)
-          break if result.matched.empty?
-
-          parts.pop
-          last_result = result
-        end
-        return Result.new(objects, token, [], '') if last_result.matched.empty? || last_result.matched.length > 1
-        return last_result if parts.empty?
-
-        denest(last_result.matched.first.children, parts.join(' '))
-      end
+    def self.strictness processor
+      (processors.length - (processors.find_index(processor) || processors.length)) * 100
     end
+
+    use DEFAULT_PROCESSORS
   end
 end

data/lib/gamefic/scope/descendants.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scope
+    # The Descendants scope returns an entity's children and accessible
+    # descendants.
+    #
+    class Descendants < Base
+      def matches
+        context.children.flat_map do |child|
+          [child] + subquery_accessible(child)
+        end
+      end
+    end
+  end
+end

data/lib/gamefic/scope/family.rb

@@ -2,18 +2,41 @@
 
 module Gamefic
   module Scope
-    # The Family scope returns an entity's parent, siblings, and descendants.
+    # The Family scope returns an entity's ascendants, descendants, siblings,
+    # and siblings' descendants.
     #
     class Family < Base
       def matches
-        result = context.parent ? [context.parent] : []
-        result.concat subquery_accessible(context.parent)
-        result.delete context
-        context.children.each do |c|
-          result.push c
-          result.concat subquery_accessible(c)
+        match_ascendants + match_descendants + match_siblings
+      end
+
+      private
+
+      def match_ascendants
+        [].tap do |result|
+          here = context.parent
+          while here
+            result.push here
+            here = here.parent
+          end
         end
-        result.uniq
+      end
+
+      def match_descendants
+        context.children.flat_map do |child|
+          [child] + subquery_accessible(child)
+        end
+      end
+
+      def match_siblings
+        return [] unless context.parent
+
+        context.parent
+               .children
+               .that_are_not(context)
+               .flat_map do |child|
+                 [child] + subquery_accessible(child)
+               end
       end
     end
   end

data/lib/gamefic/scope.rb

@@ -2,6 +2,7 @@
 
 require 'gamefic/scope/base'
 require 'gamefic/scope/children'
+require 'gamefic/scope/descendants'
 require 'gamefic/scope/family'
 require 'gamefic/scope/parent'
 require 'gamefic/scope/siblings'

data/lib/gamefic/scriptable/actions.rb

@@ -26,12 +26,11 @@ module Gamefic
       #   end
       #
       # @param verb [Symbol] An imperative verb for the command
-      # @param queries [Array<Query::Base, Query::Text>] Filters for the command's tokens
+      # @param args [Array<Object>] Filters for the command's tokens
       # @yieldparam [Gamefic::Actor]
       # @return [Symbol]
-      def respond(verb, *queries, &proc)
-        args = map_response_args(queries)
-        rulebook.calls.add_response Response.new(verb, rulebook.narrative, *args, &proc)
+      def respond(verb, *args, &proc)
+        rulebook.calls.add_response Response.new(verb, self, *args, &proc)
         verb
       end
 
@@ -47,12 +46,11 @@ module Gamefic
       #   end
       #
       # @param verb [Symbol] An imperative verb for the command
-      # @param queries [Array<Query::Base, Query::Text>] Filters for the command's tokens
+      # @param args [Array<Object>] Filters for the command's tokens
       # @yieldparam [Gamefic::Actor]
       # @return [Symbol]
-      def meta(verb, *queries, &proc)
-        args = map_response_args(queries)
-        rulebook.calls.add_response Response.new(verb, rulebook.narrative, *args, meta: true, &proc)
+      def meta(verb, *args, &proc)
+        rulebook.calls.add_response Response.new(verb, self, *args, meta: true, &proc)
         verb
       end
 
@@ -64,7 +62,7 @@ module Gamefic
       # @yieldparam [Gamefic::Action]
       # @return [Action::Hook]
       def before_action *verbs, &block
-        rulebook.hooks.before_action *verbs, &block
+        rulebook.hooks.before_action self, *verbs, &block
       end
 
       # Add a proc to be evaluated after a character executes an action.
@@ -75,7 +73,7 @@ module Gamefic
       # @yieldparam [Gamefic::Action]
       # @return [Action::Hook]
       def after_action *verbs, &block
-        rulebook.hooks.after_action *verbs, &block
+        rulebook.hooks.after_action self, *verbs, &block
       end
 
       # Create an alternate Syntax for a response.
@@ -134,23 +132,6 @@ module Gamefic
       def syntaxes
         rulebook.syntaxes
       end
-
-      private
-
-      def map_response_args args
-        args.map do |arg|
-          case arg
-          when Entity, Class, Module, Proc, Proxy::Agent
-            available(arg)
-          when String, Regexp
-            plaintext(arg)
-          when Gamefic::Query::Base, Gamefic::Query::Text
-            arg
-          else
-            raise ArgumentError, "invalid argument in response: #{arg.inspect}"
-          end
-        end
-      end
     end
   end
 end

data/lib/gamefic/scriptable/entities.rb

@@ -9,7 +9,7 @@ module Gamefic
     #   #make and #destroy instead.
     #
     module Entities
-      include Proxy
+      include Proxies
 
       def entity_vault
         @entity_vault ||= Vault.new
@@ -63,6 +63,9 @@ module Gamefic
 
       # Same as #pick, but raise an error if a unique match could not be found.
       #
+      #
+      # @raise [RuntimeError] if a unique match was not found.
+      #
       # @param description [String]
       # @return [Gamefic::Entity, nil]
       def pick! description

data/lib/gamefic/scriptable/events.rb

@@ -14,7 +14,7 @@ module Gamefic
       #   end
       #
       def on_ready &block
-        rulebook.events.on_ready(&block)
+        rulebook.events.on_ready(Callback.new(self, block))
       end
 
       # Add a block to be executed for each player at the beginning of a turn.
@@ -28,37 +28,43 @@ module Gamefic
       #
       # @yieldparam [Gamefic::Actor]
       def on_player_ready &block
-        rulebook.events.on_player_ready(&block)
+        wrapper = proc do
+          players.each { |player| Stage.run(self, player, &block) }
+        end
+        on_ready &wrapper
       end
 
       # Add a block to be executed after the Plot is finished updating a turn.
       #
       def on_update &block
-        rulebook.events.on_update(&block)
+        rulebook.events.on_update(Callback.new(self, block))
       end
 
       # Add a block to be executed for each player at the end of a turn.
       #
       # @yieldparam [Gamefic::Actor]
       def on_player_update &block
-        rulebook.events.on_player_update(&block)
+        wrapper = proc do
+          players.each { |player| Stage.run(self, player, &block) }
+        end
+        on_update &wrapper
       end
 
       def on_conclude &block
-        rulebook.events.on_conclude(&block)
+        rulebook.events.on_conclude(Callback.new(self, block))
       end
 
       # @yieldparam [Actor]
       # @return [Proc]
       def on_player_conclude &block
-        rulebook.events.on_player_conclude(&block)
+        rulebook.events.on_player_conclude(Callback.new(self, block))
       end
 
       # @yieldparam [Actor]
       # @yieldparam [Hash]
       # @return [Proc]
       def on_player_output &block
-        rulebook.events.on_player_output(&block)
+        rulebook.events.on_player_output Callback.new(self, block)
       end
     end
   end

data/lib/gamefic/scriptable/plot_proxies.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    module PlotProxies
+      def lazy_plot key
+        Proxy.new(:attr, [:plot, key])
+      end
+      alias _plot lazy_plot
+
+      def attr_plot attr
+        define_method(attr) { plot.send(attr) }
+      end
+    end
+  end
+end

data/lib/gamefic/scriptable/proxies.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    # Methods for referencing entities from proxies.
+    #
+    module Proxies
+      # Convert a proxy into its referenced entity.
+      #
+      # This method can receive any kind of object. If it's a proxy, its entity
+      # will be returned. If it's an array, each of its elements will be
+      # unproxied. If it's a hash, each of its values will be unproxied. Any
+      # other object will be returned unchanged.
+      #
+      # @param object [Object]
+      # @return [Object]
+      def unproxy object
+        case object
+        when Proxy
+          object.fetch self
+        when Array
+          object.map { |obj| unproxy obj }
+        when Hash
+          object.transform_values { |val| unproxy val }
+        else
+          object
+        end
+      end
+    end
+  end
+end

data/lib/gamefic/scriptable/queries.rb

@@ -5,14 +5,14 @@ module Gamefic
     # Scriptable methods related to creating action queries.
     #
     module Queries
-      include Proxy
+      include Proxies
 
       # Define a query that searches the entire plot's entities.
       #
       # @param args [Array<Object>] Query arguments
       # @return [Query::General]
       def anywhere *args, ambiguous: false
-        Query::General.new -> { entities }, *unproxy(args), ambiguous: ambiguous
+        Query::General.new -> { entities }, *args, ambiguous: ambiguous
       end
 
       # Define a query that searches an actor's family of entities. The
@@ -22,7 +22,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def available *args, ambiguous: false
-        Query::Scoped.new Scope::Family, *unproxy(args), ambiguous: ambiguous
+        Query::Scoped.new Scope::Family, *args, ambiguous: ambiguous
       end
       alias family available
 
@@ -31,7 +31,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def parent *args, ambiguous: false
-        Query::Scoped.new Scope::Parent, *unproxy(args), ambiguous: ambiguous
+        Query::Scoped.new Scope::Parent, *args, ambiguous: ambiguous
       end
 
       # Define a query that searches an actor's children.
@@ -39,7 +39,15 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def children *args, ambiguous: false
-        Query::Scoped.new Scope::Children, *unproxy(args), ambiguous: ambiguous
+        Query::Scoped.new Scope::Children, *args, ambiguous: ambiguous
+      end
+
+      # Define a query that searches an actor's descendants.
+      #
+      # @param args [Array<Object>] Query arguments
+      # @return [Query::Scoped]
+      def descendants *args, ambiguous: false
+        Query::Scoped.new Scope::Descendants, *args, ambiguous: ambiguous
       end
 
       # Define a query that searches an actor's siblings.
@@ -47,7 +55,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def siblings *args, ambiguous: false
-        Query::Scoped.new Scope::Siblings, *unproxy(args), ambiguous: ambiguous
+        Query::Scoped.new Scope::Siblings, *args, ambiguous: ambiguous
       end
 
       # Define a query that returns the actor itself.
@@ -55,7 +63,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def myself *args, ambiguous: false
-        Query::Scoped.new Scope::Myself, *unproxy(args), ambiguous: ambiguous
+        Query::Scoped.new Scope::Myself, *args, ambiguous: ambiguous
       end
 
       # Define a query that performs a plaintext search. It can take a String

data/lib/gamefic/scriptable/scenes.rb

@@ -33,13 +33,12 @@ module Gamefic
       # @yieldparam [Scene]
       # @return [Symbol]
       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)
+        rulebook.scenes.add klass.new(name, self, on_start: on_start, on_finish: on_finish, &blk)
         name
       end
-      alias scene block
 
       def preface name, klass = Scene::Activity, &start
-        rulebook.scenes.add klass.new(name, rulebook.narrative, on_start: start)
+        rulebook.scenes.add klass.new(name, self, on_start: start)
         name
       end
       alias precursor preface
@@ -60,7 +59,7 @@ module Gamefic
       def introduction(&start)
         rulebook.scenes
                 .introduction Scene::Default.new nil,
-                                                 rulebook.narrative,
+                                                 self,
                                                  on_start: proc { |actor, _props| Stage.run(self, actor, &start) }
       end
 
@@ -160,9 +159,16 @@ module Gamefic
               on_start: start
       end
 
+      # @return [Array<Symbol>]
       def scenes
         rulebook.scenes.names
       end
+
+      # @param name [Symbol]
+      # @return [Scene::Default, nil]
+      def scene(name)
+        rulebook.scenes[name]
+      end
     end
   end
 end