gamefic 3.4.0 → 3.6.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,11 +26,10 @@ 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)
+      def respond(verb, *args, &proc)
         rulebook.calls.add_response Response.new(verb, self, *args, &proc)
         verb
       end
@@ -47,11 +46,10 @@ 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)
+      def meta(verb, *args, &proc)
         rulebook.calls.add_response Response.new(verb, self, *args, meta: true, &proc)
         verb
       end
@@ -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
@@ -49,30 +49,45 @@ module Gamefic
         entity_vault.delete entity
       end
 
-      # Pick an entity based on a unique name or description. Return nil if an
-      # entity could not be found or there is more than one possible match.
+      def find *args
+        args.inject(entities) do |entities, arg|
+          case arg
+          when String
+            result = Scanner.scan(entities, arg)
+            result.remainder.empty? ? result.match : []
+          else
+            entities.that_are(arg)
+          end
+        end
+      end
+
+      # Pick a unique entity based on the given arguments. String arguments are
+      # used to scan the entities for matching names and synonyms. Return nil
+      # if an entity could not be found or there is more than one possible
+      # match.
       #
-      # @param description [String]
+      # @param description [Array]
       # @return [Gamefic::Entity, nil]
-      def pick description
-        result = Scanner.scan(entities, description)
-        return nil unless result.matched.one?
+      def pick *args
+        matches = find(*args)
+        return nil unless matches.one?
 
-        result.matched.first
+        matches.first
       end
 
       # Same as #pick, but raise an error if a unique match could not be found.
       #
-      # @param description [String]
-      # @return [Gamefic::Entity, nil]
-      def pick! description
-        result = Scanner.scan(entities, description)
-
-        raise "no entity matching '#{description}'" if result.matched.empty?
-
-        raise "multiple entities matching '#{description}': #{result.matched.join_and}" unless result.matched.one?
+      #
+      # @raise [RuntimeError] if a unique match was not found.
+      #
+      # @param args [Array]
+      # @return [Gamefic::Entity]
+      def pick! *args
+        matches = find(*args)
+        raise "no entity matching '#{args.inspect}'" if matches.empty?
+        raise "multiple entities matching '#{args.inspect}': #{matches.join_and}" unless matches.one?
 
-        result.matched.first
+        matches.first
       end
     end
   end

data/lib/gamefic/scriptable/plot_proxies.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    module PlotProxies
+      def lazy_plot key
+        Logging.logger.warn "#{caller.first ? "#{caller.first}: " : ''}`lazy_plot` is deprecated. Use `plot_pick`, `plot_pick!, or pass the entity from the plot in a `config` option instead."
+        Proxy.new(:attr, [:plot, key])
+      end
+      alias _plot lazy_plot
+
+      def attr_plot attr
+        define_method(attr) { plot.send(attr) }
+      end
+
+      def plot_pick *args
+        Proxy::PlotPick.new(*args)
+      end
+      alias lazy_plot_pick plot_pick
+      alias _plot_pick plot_pick
+
+      def plot_pick! *args
+        Proxy::PlotPick.new(*args)
+      end
+      alias lazy_plot_pick! plot_pick!
+      alias _plot_pick! plot_pick!
+    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, Proxy::Base
+          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,25 @@ 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, name: 'anywhere'
+      end
+
+      # Define a query that searches for abstract entities.
+      #
+      # An abstract entity is a pseudo-entity that is describable but does
+      # not have a parent or children.
+      #
+      # @param args [Array<Object>] Query arguments
+      # @return [Query::Abstract]
+      def abstract *args, ambiguous: false
+        Query::Abstract.new -> { entities }, *args, ambiguous: ambiguous
       end
 
       # Define a query that searches an actor's family of entities. The
@@ -22,7 +33,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, name: 'available'
       end
       alias family available
 
@@ -31,7 +42,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, name: 'parent'
       end
 
       # Define a query that searches an actor's children.
@@ -39,7 +50,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, name: 'children'
+      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 +66,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, name: 'siblings'
       end
 
       # Define a query that returns the actor itself.
@@ -55,7 +74,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, name: 'myself'
       end
 
       # Define a query that performs a plaintext search. It can take a String
@@ -66,7 +85,7 @@ module Gamefic
       # @param arg [String, Regexp] The string or regular expression to match
       # @return [Query::Text]
       def plaintext arg = /.*/
-        Query::Text.new arg
+        Query::Text.new arg, name: 'plaintext'
       end
     end
   end

data/lib/gamefic/scriptable/scenes.rb

@@ -36,7 +36,6 @@ module Gamefic
         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, self, on_start: start)
@@ -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

data/lib/gamefic/scriptable.rb

@@ -23,14 +23,14 @@ module Gamefic
   #   end
   #
   module Scriptable
-    autoload :Actions,   'gamefic/scriptable/actions'
-    autoload :Entities,  'gamefic/scriptable/entities'
-    autoload :Events,    'gamefic/scriptable/events'
-    autoload :Queries,   'gamefic/scriptable/queries'
-    autoload :Proxy,     'gamefic/scriptable/proxy'
-    autoload :Scenes,    'gamefic/scriptable/scenes'
-
-    include Proxy
+    autoload :Actions,     'gamefic/scriptable/actions'
+    autoload :Entities,    'gamefic/scriptable/entities'
+    autoload :Events,      'gamefic/scriptable/events'
+    autoload :Queries,     'gamefic/scriptable/queries'
+    autoload :Proxies,     'gamefic/scriptable/proxies'
+    autoload :Scenes,      'gamefic/scriptable/scenes'
+    autoload :PlotProxies, 'gamefic/scriptable/plot_proxies'
+
     include Queries
     # @!parse
     #   include Scriptable::Actions
@@ -101,11 +101,12 @@ module Gamefic
     #   make_seed Gamefic::Entity, name: 'thing'
     #
     # @param klass [Class<Gamefic::Entity>]
+    # @return [Proxy]
     def make_seed klass, **opts
-      @count ||= 0
       seed { make(klass, **opts) }
-      Proxy::Agent.new(@count.tap { @count += 1 })
+      Proxy::Pick.new(klass, opts[:name], raise: true)
     end
+    alias make make_seed
 
     # Seed an entity with an attribute method.
     #
@@ -119,15 +120,76 @@ module Gamefic
     #
     # @param name [Symbol] The attribute name
     # @param klass [Class<Gamefic::Entity>]
+    # @return [Proxy]
     def attr_seed name, klass, **opts
-      @count ||= 0
-      seed do
-        instance_variable_set("@#{name}", make(klass, **opts))
-        self.class.define_method(name) { instance_variable_get("@#{name}") }
+      ivname = "@#{name}"
+      define_method(name) do
+        return instance_variable_get(ivname) if instance_variable_defined?(ivname)
+
+        instance_variable_set(ivname, make(klass, **opts))
+      end
+      seed { send name }
+      Proxy.new(:attr, name)
+    end
+
+    # @param symbol [Symbol]
+    # @return [Proxy]
+    def proxy symbol
+      Logging.logger.warn "#{caller.first ? "#{caller.first}: " : ''}`proxy` is deprecated. Use `pick` or `pick!` instead."
+      if symbol.to_s.start_with?('@')
+        Proxy.new(:ivar, symbol)
+      else
+        Proxy.new(:attr, symbol)
       end
-      Proxy::Agent.new(@count.tap { @count += 1 })
     end
 
+    # Lazy reference an entity by its instance variable.
+    #
+    # @example
+    #   lazy_ivar(:@variable)
+    #
+    # @param key [Symbol]
+    # @return [Proxy]
+    def lazy_ivar key
+      Gamefic.logger.warn "#{caller.first ? "#{caller.first}: " : ''}`lazy_ivar` is deprecated. Use `pick` or `pick!` instead."
+      Proxy.new(:ivar, key)
+    end
+    alias _ivar lazy_ivar
+
+    # Lazy reference an entity by its attribute or method.
+    #
+    # @example
+    #   lazy_attr(:method)
+    #
+    # @param key [Symbol]
+    # @return [Proxy]
+    def lazy_attr key
+      Gamefic.logger.warn "#{caller.first ? "#{caller.first}: " : ''}`lazy_attr` is deprecated. Use `pick` or `pick!` instead."
+      Proxy.new(:attr, key)
+    end
+    alias _attr lazy_attr
+
+    # Lazy pick an entity.
+    #
+    # @example
+    #   pick('the red box')
+    #
+    # @param args [Array]
+    # @return [Proxy]
+    def pick *args
+      Proxy::Pick.new(*args)
+    end
+    alias lazy_pick pick
+    alias _pick pick
+
+    # Lazy pick an entity or raise
+    #
+    def pick! *args
+      Proxy::Pick.new(*args)
+    end
+    alias lazy_pick! pick
+    alias _pick! pick
+
     if RUBY_ENGINE == 'opal'
       # :nocov:
       def method_missing method, *args, &block
@@ -160,7 +222,7 @@ module Gamefic
     #
     # @return [Module<self>]
     def no_scripts
-      Logging.logger.warn 'Calling `no_scripts` on Scriptable modules is no longer necessary.'
+      Logging.logger.warn "#{caller.first ? "#{caller.first}: " : ''}Calling `no_scripts` on Scriptable modules is no longer necessary."
       self
     end
   end

data/lib/gamefic/stage.rb

@@ -14,7 +14,7 @@ module Gamefic
 
     OVERWRITEABLE_CLASSES = [String, Numeric, Symbol].freeze
 
-    SWAPPABLE_VALUES = [true, false, nil].freeze
+    SWAPPABLE_VALUES = [true, false].freeze
 
     class << self
       private
@@ -37,7 +37,7 @@ module Gamefic
       end
 
       def overwriteable? cval, nval
-        return true if swappable?(cval, nval)
+        return true if cval.nil? || swappable?(cval, nval)
 
         allowed = OVERWRITEABLE_CLASSES.find { |klass| cval.is_a?(klass) }
         allowed && cval.is_a?(allowed)