gamefic 3.4.0 → 3.5.0

data/lib/gamefic/response.rb

@@ -8,19 +8,18 @@ module Gamefic
     # @return [Symbol]
     attr_reader :verb
 
-    # @return [Array<Query::Base>]
+    # @return [Array<Query::Base, Query::Text>]
     attr_reader :queries
 
     # @param verb [Symbol]
     # @param narrative [Narrative]
-    # @param queries [Array<Query::Base>]
+    # @param args [Array<Object>]
     # @param meta [Boolean]
     # @param block [Proc]
-    def initialize verb, narrative, *queries, meta: false, &block
+    def initialize verb, narrative, *args, meta: false, &block
       @verb = verb
-      @queries = map_queryable_objects(queries)
+      @queries = map_queries(args, narrative)
       @meta = meta
-      @block = block
       @callback = Callback.new(narrative, block)
     end
 
@@ -57,53 +56,85 @@ module Gamefic
     # @param actor [Active]
     # @param command [Command]
     def accept? actor, command
-      return false if command.verb != verb || command.arguments.length != queries.length
-
-      queries.each_with_index do |query, idx|
-        return false unless query.accept?(actor, command.arguments[idx])
-      end
-
-      true
+      command.verb == verb &&
+        command.arguments.length == queries.length &&
+        queries.zip(command.arguments).all? { |query, argument| query.accept?(actor, argument) }
     end
 
     def execute *args
-      @callback.run *args
+      @callback.run(*args)
     end
 
     def precision
       @precision ||= calculate_precision
     end
 
+    # Turn an actor and an expression into a command by matching the
+    # expression's tokens to queries. Return nil if the expression
+    # could not be matched.
+    #
+    # @param actor [Actor]
+    # @param expression [Expression]
+    # @return [Command, nil]
+    def to_command actor, expression
+      return nil unless expression.verb == verb && expression.tokens.length <= queries.length
+
+      results = filter(actor, expression)
+      return nil unless results
+
+      Command.new(
+        verb,
+        results.map(&:match),
+        results.sum(&:strictness),
+        precision
+      )
+    end
+
     private
 
+    def filter actor, expression
+      remainder = ''
+      result = queries.zip(expression.tokens)
+                      .map do |query, token|
+                        token = "#{remainder} #{token}".strip
+                        result = query.filter(actor, token)
+                        return nil unless result.match
+
+                        remainder = result.remainder
+                        result
+                      end
+      result if remainder.empty?
+    end
+
     def generate_default_syntax
-      user_friendly = verb.to_s.gsub(/_/, ' ')
-      args = []
-      used_names = []
-      queries.each do |_c|
-        num = 1
-        new_name = ":var"
-        while used_names.include? new_name
-          num += 1
-          new_name = ":var#{num}"
-        end
-        used_names.push new_name
-        user_friendly += " #{new_name}"
-        args.push new_name
-      end
-      Syntax.new(user_friendly.strip, "#{verb} #{args.join(' ')}".strip)
+      args = queries.length.times.map { |num| num.zero? ? ':var' : ":var#{num + 1}" }
+      tmpl = "#{verb} #{args.join(' ')}".strip
+      Syntax.new(tmpl.gsub('_', ' '), tmpl)
     end
 
     def calculate_precision
-      total = 0
-      queries.each { |q| total += q.precision }
-      total -= 1000 if verb.nil?
+      total = queries.sum(&:precision)
+      total -= 1000 unless verb
       total
     end
 
-    def map_queryable_objects queries
-      # @todo Considering moving mapping from Actions to here
-      queries
+    def map_queries args, narrative
+      args.map do |arg|
+        select_query(arg, narrative).tap { |qry| qry.narrative = narrative }
+      end
+    end
+
+    def select_query arg, narrative
+      case arg
+      when Entity, Class, Module, Proc, Proxy
+        narrative.available(arg)
+      when String, Regexp
+        narrative.plaintext(arg)
+      when Query::Base, Query::Text
+        arg
+      else
+        raise ArgumentError, "invalid argument in response: #{arg.inspect}"
+      end
     end
   end
 end

data/lib/gamefic/scanner/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scanner
+    # A base class for scanners that match tokens to entities.
+    #
+    class Base
+      # @return [Array<Entity>]
+      attr_reader :selection
+
+      # @return [String]
+      attr_reader :token
+
+      # @param selection [Array<Entity>]
+      # @param token [String]
+      def initialize selection, token
+        @selection = selection
+        @token = token
+      end
+
+      # @return [Result]
+      def scan
+        unmatched_result
+      end
+
+      # @param selection [Array<Entity>]
+      # @param token [String]
+      # @return [Result]
+      def self.scan selection, token
+        new(selection, token).scan
+      end
+
+      private
+
+      def unmatched_result
+        Result.unmatched(selection, token, self.class)
+      end
+
+      def matched_result matched, remainder
+        Result.new(selection, token, matched, remainder, self.class)
+      end
+    end
+  end
+end

data/lib/gamefic/scanner/fuzzy.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scanner
+    # Fuzzy token matching.
+    #
+    # An entity will match a word in a fuzzy scan if it matches the beginning
+    # of one of the entity's keywords, e.g., `pen` is a fuzzy token match for
+    # the keyword `pencil`.
+    #
+    class Fuzzy < Strict
+      def match_word available, word
+        available.select { |obj| obj.keywords.any? { |wrd| wrd.start_with?(word) } }
+      end
+    end
+  end
+end

data/lib/gamefic/scanner/fuzzy_nesting.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scanner
+    # Fuzzy scanning for entities inside of other entities, e.g., `soc in draw`
+    # would match `sock in drawer`.
+    #
+    class FuzzyNesting < Nesting
+      def subprocessor
+        Fuzzy
+      end
+    end
+  end
+end

data/lib/gamefic/scanner/nesting.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scanner
+    # Strict scanning for entities inside of other entities, e.g., `sock inside drawer`.
+    #
+    class Nesting < Base
+      NEST_REGEXP = / in | on | of | from | inside | inside of | from inside | off | out | out of /.freeze
+
+      def subprocessor
+        Strict
+      end
+
+      def scan
+        return Result.unmatched(selection, token, self.class) unless token =~ NEST_REGEXP
+
+        denest selection, token
+      end
+
+      private
+
+      def denest objects, token
+        near = objects
+        far = objects
+        parts = token.split(NEST_REGEXP)
+        until parts.empty?
+          current = parts.pop
+          last_result = subprocessor.scan(near, current)
+          last_result = subprocessor.scan(far, current) if last_result.matched.empty? && near != far
+          return Result.unmatched(selection, token, self.class) if last_result.matched.empty? || last_result.matched.length > 1
+
+          near = last_result.matched.first.children & objects
+          far = last_result.matched.first.flatten & objects
+        end
+        last_result
+      end
+    end
+  end
+end

data/lib/gamefic/scanner/result.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scanner
+    # 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
+      alias match matched
+
+      # The remaining (unmatched) portion of the token
+      #
+      # @return [String]
+      attr_reader :remainder
+
+      attr_reader :processor
+
+      def initialize scanned, token, matched, remainder, processor
+        @scanned = scanned
+        @token = token
+        @matched = matched
+        @remainder = remainder
+        @processor = processor
+      end
+
+      def strictness
+        @strictness ||= Scanner.strictness(processor)
+      end
+
+      def self.unmatched scanned, token, processor
+        new(scanned, token, [], token, processor)
+      end
+    end
+  end
+end

data/lib/gamefic/scanner/strict.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scanner
+    # Strict token matching.
+    #
+    # An entity will only match a word in a strict scan if the entire word
+    # matches one of the entity's keywords.
+    #
+    class Strict < Base
+      # @return [Result]
+      def scan
+        words = token.keywords
+        available = selection.clone
+        filtered = []
+        words.each_with_index do |word, idx|
+          tested = match_word(available, word)
+          return matched_result(filtered, words[idx..].join(' ')) if tested.empty?
+
+          filtered = tested
+          available = filtered
+        end
+        matched_result filtered, ''
+      end
+
+      def match_word available, word
+        available.select { |obj| obj.keywords.include?(word) }
+      end
+    end
+  end
+end

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
@@ -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/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