gamefic 1.7.0 → 2.0.0

data/lib/gamefic/query.rb

@@ -1,18 +1,14 @@
-#require 'gamefic/keywords'
-
-module Gamefic
-
-  module Query
-    autoload :Base, 'gamefic/query/base'
-    autoload :Children, 'gamefic/query/children'
-    autoload :Descendants, 'gamefic/query/descendants'
-    autoload :External, 'gamefic/query/external'
-    autoload :Family, 'gamefic/query/family'
-    autoload :Itself, 'gamefic/query/itself'
-    autoload :Matches, 'gamefic/query/matches'
-    autoload :Parent, 'gamefic/query/parent'
-    autoload :Siblings, 'gamefic/query/siblings'
-    autoload :Text, 'gamefic/query/text'
-  end
-
-end
+module Gamefic
+  module Query
+    autoload :Base, 'gamefic/query/base'
+    autoload :Children, 'gamefic/query/children'
+    autoload :Descendants, 'gamefic/query/descendants'
+    autoload :External, 'gamefic/query/external'
+    autoload :Family, 'gamefic/query/family'
+    autoload :Itself, 'gamefic/query/itself'
+    autoload :Matches, 'gamefic/query/matches'
+    autoload :Parent, 'gamefic/query/parent'
+    autoload :Siblings, 'gamefic/query/siblings'
+    autoload :Text, 'gamefic/query/text'
+  end
+end

data/lib/gamefic/query/base.rb

@@ -9,6 +9,13 @@ module Gamefic
         @arguments = args
       end
 
+      # Determine whether the query allows ambiguous entity references.
+      # If false, actions that use this query will only be valid if the token
+      # passed into it resolves to a single entity. If true, actions will
+      # accept an array of matching entities instead.
+      # Queries are not ambiguous by default (ambiguous? == false).
+      #
+      # @return [Boolean]
       def ambiguous?
         false
       end
@@ -36,8 +43,8 @@ module Gamefic
           return Matches.new(drill, token, '') unless drill.length != 1
           return Matches.new([], '', token)
         end
-        result = available.select{ |e| e.match?(token) }
-        result = available.select{ |e| e.match?(token, fuzzy: true) } if result.empty?
+        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
@@ -52,15 +59,6 @@ module Gamefic
         if @precision.nil?
           @precision = 1
           arguments.each { |a|
-            #if a.kind_of?(Symbol) or a.kind_of?(Regexp)
-            #  @precision += 1
-            #elsif a.kind_of?(Class)
-            #  @precision += (count_superclasses(a) * 100)
-            #elsif a.kind_of?(Module)
-            #  @precision += 10
-            #elsif a.kind_of?(Object)
-            #  @precision += 1000
-            #end
             if a.kind_of?(Class)
               @precision += 100
             elsif a.kind_of?(Gamefic::Entity)
@@ -77,9 +75,12 @@ module Gamefic
       end
 
       def signature
-        "#{self.class.to_s.downcase}(#{@arguments.join(',')})"
+        "#{self.class.to_s.split('::').last.downcase}(#{simplify_arguments.join(', ')})"
       end
 
+      # Determine whether the specified entity passes the query's arguments.
+      #
+      # @return [Boolean]
       def accept?(entity)
         result = true
         arguments.each { |a|
@@ -98,13 +99,14 @@ module Gamefic
       end
 
       protected
-      
-      # Return an array of the entity's children. If the child is neighborly,
+
+      # Return an array of the entity's children. If the child is accessible,
       # recursively append its children.
       # The result will NOT include the original entity itself.
       #
       # @return [Array<Object>]
       def subquery_accessible entity
+        return [] if entity.nil?
         result = []
         if entity.accessible?
           entity.children.each { |c|
@@ -117,6 +119,16 @@ module Gamefic
 
       private
 
+      def simplify_arguments
+        arguments.map do |a|
+          if a.kind_of?(Class) or a.kind_of?(Object)
+            a.to_s.split('::').last.downcase
+          else
+            a.to_s.downcase
+          end
+        end
+      end
+
       def nested?(token)
         !token.match(NEST_REGEXP).nil?
       end
@@ -124,13 +136,13 @@ module Gamefic
       def denest(objects, token)
         parts = token.split(NEST_REGEXP)
         current = parts.pop
-        last_result = objects.select{ |e| e.match?(current) }
-        last_result = objects.select{ |e| e.match?(current, fuzzy: true) } if last_result.empty?
+        last_result = objects.select{ |e| e.specified?(current) }
+        last_result = objects.select{ |e| e.specified?(current, fuzzy: true) } if last_result.empty?
         result = last_result
         while parts.length > 0
           current = "#{parts.last} #{current}"
-          result = last_result.select{ |e| e.match?(current) }
-          result = last_result.select{ |e| e.match?(current, fuzzy: true) } if result.empty?
+          result = last_result.select{ |e| e.specified?(current) }
+          result = last_result.select{ |e| e.specified?(current, fuzzy: true) } if result.empty?
           break if result.empty?
           parts.pop
           last_result = result

data/lib/gamefic/query/external.rb

@@ -1,14 +1,18 @@
-module Gamefic
-  module Query
-    class External < Base
-      def initialize objects, *args
-        super(*args)
-        @objects = objects
-      end
-      
-      def context_from subject
-        @objects
-      end
-    end
-  end
-end
+module Gamefic
+  module Query
+    class External < Base
+      def initialize objects, *args
+        super(*args)
+        @objects = objects
+      end
+
+      def context_from subject
+        @objects
+      end
+
+      def accept?(entity)
+        @objects.include?(entity) && super(entity)
+      end
+    end
+  end
+end

data/lib/gamefic/query/family.rb

@@ -3,13 +3,7 @@ module Gamefic
     class Family < Base
       def context_from(subject)
         result = []
-        top = subject.parent
-        unless top.nil?
-          #until top.parent.nil?
-          #  top = top.parent
-          #end
-          result.concat subquery_accessible(top)
-        end
+        result.concat subquery_accessible(subject.parent)
         result.delete subject
         subject.children.each { |c|
           result.push c

data/lib/gamefic/query/matches.rb

@@ -1,67 +1,75 @@
-module Gamefic
-  module Query
-    class Matches
-      attr_accessor :objects, :matching, :remaining
-
-      def initialize objects, matching, remaining
-        @objects = objects
-        @matching = matching
-        @remaining = remaining
-      end
-
-      def self.execute objects, description, continued: false
-        if continued
-          match_with_remainder objects, description
-        else
-          match_without_remainder objects, description
-        end
-      end
-
-      class << self
-        private
-
-        def match_without_remainder objects, description
-          matches = objects.select{ |e| e.match?(description) }
-          if matches.empty?
-            matching = ''
-            remaining = description
-          else
-            matching = description
-            remaining = ''
-          end
-          Matches.new(matches, matching, remaining)
-        end
-
-        def match_with_remainder objects, description
-          matching_objects = objects
-          matching_text = []
-          words = description.split(Matchable::SPLIT_REGEXP)
-          i = 0
-          #cursor = []
-          words.each { |w|
-            cursor = inner_match matching_objects, words, matching_text, i, w
-            break if cursor.empty? or (cursor & matching_objects).empty?
-            matching_objects = (cursor & matching_objects)
-            i += 1
-          }
-          objects = matching_objects
-          matching = matching_text.uniq.join(' ')
-          remaining = words[i..-1].join(' ')
-          m = Matches.new(objects, matching, remaining)
-          m
-        end
-
-        def inner_match matching_objects, words, matching_text, i, w
-          cursor = []
-          matching_objects.each { |o|
-            if o.match?(words[0..i].join(' '), fuzzy: true)
-              cursor.push o
-              matching_text.push w
-            end
-          }
-          cursor
-        end
-      end
-    end
-  end
-end
+module Gamefic
+  module Query
+    class Matches
+      # The resolved tokens
+      # @return [Array<Object>]
+      attr_reader :objects
+
+      # The matching string
+      # @return [String]
+      attr_reader :matching
+
+      # The remaining (unmatched) string
+      # @return [String]
+      attr_reader :remaining
+
+      def initialize objects, matching, remaining
+        @objects = objects
+        @matching = matching
+        @remaining = remaining
+      end
+
+      def self.execute objects, description, continued: false
+        if continued
+          match_with_remainder objects, description
+        else
+          match_without_remainder objects, description
+        end
+      end
+
+      class << self
+        private
+
+        def match_without_remainder objects, description
+          matches = objects.select{ |e| e.specified?(description) }
+          if matches.empty?
+            matching = ''
+            remaining = description
+          else
+            matching = description
+            remaining = ''
+          end
+          Matches.new(matches, matching, remaining)
+        end
+
+        def match_with_remainder objects, description
+          matching_objects = objects
+          matching_text = []
+          words = description.split(Keywords::SPLIT_REGEXP)
+          i = 0
+          words.each { |w|
+            cursor = inner_match matching_objects, words, matching_text, i, w
+            break if cursor.empty? or (cursor & matching_objects).empty?
+            matching_objects = (cursor & matching_objects)
+            i += 1
+          }
+          objects = matching_objects
+          matching = matching_text.uniq.join(' ')
+          remaining = words[i..-1].join(' ')
+          Matches.new(objects, matching, remaining)
+        end
+
+        def inner_match matching_objects, words, matching_text, i, w
+          cursor = []
+          matching_objects.each { |o|
+            if o.specified?(words[0..i].join(' '), fuzzy: true)
+              cursor.push o
+              matching_text.push w
+            end
+          }
+          cursor
+        end
+      end
+    end
+  end
+end

data/lib/gamefic/query/text.rb

@@ -10,7 +10,8 @@ module Gamefic
         super
       end
       def resolve(subject, token, continued: false)
-        parts = token.split(Matchable::SPLIT_REGEXP)
+        return Matches.new([], '', token) unless accept?(token)
+        parts = token.split(Keywords::SPLIT_REGEXP)
         cursor = []
         matches = []
         i = 0

data/lib/gamefic/scene.rb

@@ -1,5 +1,4 @@
 module Gamefic
-
   module Scene
     autoload :Base, 'gamefic/scene/base'
     autoload :Custom, 'gamefic/scene/custom'
@@ -10,5 +9,4 @@ module Gamefic
     autoload :MultipleScene, 'gamefic/scene/multiple_scene'
     autoload :YesOrNo, 'gamefic/scene/yes_or_no'
   end
-
 end

data/lib/gamefic/scene/activity.rb

@@ -1,26 +1,24 @@
-module Gamefic
-
-  # Active Scenes handle the default command prompt, where input is parsed
-  # into an Action performed by the Character. This is the default scene in
-  # a Plot.
-  #
-  class Scene::Activity < Scene::Base
-    def post_initialize
-      self.type = 'Activity'
-    end
-
-    def finish
-      super
-      o = nil
-      o = actor.perform input.strip unless input.to_s.strip.empty?
-      actor.performed o
-    end
-
-    class << self
-      def type
-        'Activity'
-      end
-    end
-  end
-  
-end
+module Gamefic
+  # Active Scenes handle the default command prompt, where input is parsed
+  # into an Action performed by the Character. This is the default scene in
+  # a Plot.
+  #
+  class Scene::Activity < Scene::Base
+    def post_initialize
+      self.type = 'Activity'
+    end
+
+    def finish
+      super
+      o = nil
+      o = actor.perform input.strip unless input.to_s.strip.empty?
+      actor.performed o
+    end
+
+    class << self
+      def type
+        'Activity'
+      end
+    end
+  end
+end

data/lib/gamefic/scene/base.rb

@@ -1,61 +1,100 @@
 module Gamefic
-  
   # The Base Scene is not intended for instantiation. Other Scene classes
   # should inherit from it.
   #
   class Scene::Base
+    # The scene's primary actor.
+    #
+    # @return [Gamefic::Actor]
     attr_reader :actor
+
+    # A human-readable string identifying the type of scene.
+    #
+    # @return [String]
     attr_writer :type
+
+    # The text to display when requesting input.
+    #
+    # @return [String]
     attr_writer :prompt
+
+    # The input received from the actor.
+    #
+    # @return [String]
     attr_reader :input
 
-    def initialize actor
+    # @return [Hash{Symbol => Object}]
+    attr_reader :data
+
+    def initialize actor, **data
       @actor = actor
+      @data = data
       post_initialize
     end
 
+    # A shortcut for the #data hash.
+    #
+    # @param key [Symbol]
+    # @return [Object]
+    def [] key
+      data[key]
+    end
+
     def post_initialize
     end
 
+    # Set a proc to be executed at the end of the scene.
+    #
     def on_finish &block
       @finish_block = block
     end
 
+    # Update the scene.
+    #
     def update
       @input = actor.queue.shift
       finish
     end
 
+    # Start the scene.
+    #
     def start
       self.class.start_block.call @actor, self unless self.class.start_block.nil?
+      @actor.entered self if tracked?
     end
 
+    # Finish the scene.
+    #
     def finish
       @finish_block.call @actor, self unless @finish_block.nil?
       @finished = true
     end
 
+    # Determine whether the scene's execution is finished.
+    #
+    # @return [Boolean]
     def finished?
       @finished ||= false
     end
 
-    def flush
-      @state.clear
-    end
-
+    # Get a hash that describes the current state of the scene.
+    #
+    # @return [Hash]
     def state
       {
         scene: type, prompt: prompt
       }
     end
 
+    # @yieldparam [Class<Gamefic::Actor>]
+    # @return [Class<Gamefic::Scene::Base>]
     def self.subclass &block
       c = Class.new(self) do
         on_start &block
       end
       c
     end
-    
+
     # Get the prompt to be displayed to the user when accepting input.
     #
     # @return [String] The text to be displayed.
@@ -63,19 +102,36 @@ module Gamefic
       @prompt ||= '>'
     end
 
+    # Get a String that describes the type of scene.
+    #
+    # @return [String]
     def type
       @type ||= 'Scene'
     end
 
+    # @yieldparam [Class<Gamefic::Scene::Base>]
     def self.on_start &block
       @start_block = block
     end
 
+    def tracked?
+      self.class.tracked?
+    end
+
+    def tracked= bool
+      self.class.tracked = bool
+    end
+
     class << self
+      attr_writer :tracked
+
       def start_block
         @start_block
       end
+
+      def tracked?
+        @tracked ||= false
+      end
     end
   end
-
 end