gamefic 1.7.0 → 2.0.0

data/lib/gamefic/actor.rb

@@ -1,5 +1,8 @@
-module Gamefic
-  class Actor < Gamefic::Entity
-    include Gamefic::Active
-  end
-end
+module Gamefic
+  # An entity that is capable of performing actions and participating in
+  # scenes.
+  #
+  class Actor < Gamefic::Entity
+    include Gamefic::Active
+  end
+end

data/lib/gamefic/command.rb

@@ -1,16 +1,18 @@
 module Gamefic
   # A Command is a collection of tokens parsed from a Syntax.
-  # The Director uses Commands to find and execute corresponding Actions.
+  # Playbooks use Commands to find and execute corresponding Actions.
   #
   class Command
-    # @!attribute [r] verb
-    #   @return [Symbol] A Symbol representing the command's verb or verbal phrase.
+    # A Symbol representing the command's verb or verbal phrase.
+    #
+    # @return [Symbol]
     attr_reader :verb
-    
-    # @!attribute [r] arguments
-    #   @return [Array<String>] An Array of arguments to be mapped to an Action's Queries.
+
+    # An Array of arguments to be mapped to an Action's Queries.
+    #
+    # @return [Array<String>]
     attr_reader :arguments
-    
+
     def initialize verb, arguments
       @verb = verb
       @arguments = arguments

data/lib/gamefic/core_ext/array.rb

@@ -1,5 +1,5 @@
 class Array
-  # Get a subset of the array that matches the argument.
+  # 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.
   # If the argument is a Symbol, it should be a method for which the elements must return true.
   # If the argument is an Object, the elements must equal the object.
@@ -11,45 +11,24 @@ class Array
   #   animals.that_are(:nil?)  #=> [nil]
   #
   # @return [Array]
-  def that_are(cls)
-    if (cls.kind_of?(Class) or cls.kind_of?(Module))
-      return self.clone.delete_if { |i| i.kind_of?(cls) == false }
-    elsif cls.kind_of?(Symbol)
-      return self.clone.delete_if { |i| i.send(cls) == false }      
-    else
-      if self.include?(cls)
-        return [cls]
-      end
-      return Array.new
+  def that_are(*cls)
+    result = self.clone
+    cls.each do |c|
+      _keep result, c, true
     end
+    result
   end
 
-  # Get a subset of the array that does not match the argument.
+  # Get a subset of the array that does not match the arguments.
   # See Array#that_are for information about how arguments are evaluated.
   #
   # @return [Array]
-  def that_are_not(cls)
-    if (cls.kind_of?(Class) or cls.kind_of?(Module))
-      return self.clone.delete_if { |i| i.kind_of?(cls) == true }
-    elsif cls.kind_of?(Symbol)
-      return self.clone.delete_if { |i| i.send(cls) == true }
-    else
-      return self.clone - [cls]
+  def that_are_not(*cls)
+    result = self.clone
+    cls.each do |c|
+      _keep result, c, false
     end
-  end
-
-  # Get a random element from the array.
-  # @deprecated Use Array#sample instead.
-  #
-  def random
-    return self[rand(self.length)]
-  end
-
-  # Pop a random element from the array.
-  # @deprecated Use Array#pop_sample instead.
-  #
-  def pop_random
-    pop_sample
+    result
   end
 
   # Pop a random element from the array.
@@ -58,22 +37,6 @@ class Array
     delete_at(rand(self.length))
   end
 
-  # @todo Candidate for deprecation
-  # @return [Array]
-  #def shuffle
-  #  self.sort { |a, b|
-  #    rand(3) <=> rand(3)
-  #  }
-  #end
-
-  # @todo Candidate for deprecation
-  # @return [Array]
-  #def shuffle!
-  #  self.sort! { |a, b|
-  #    rand(3) <=> rand(3)
-  #  }
-  #end
-
   # Get a string representation of the array that separates elements with
   # commas and adds a conjunction before the last element.
   #
@@ -97,4 +60,16 @@ class Array
   def join_or(sep = ', ', orSep = ' or ', serial = true)
     join_and(sep, orSep, serial)
   end
+
+  # private
+
+  def _keep(arr, cls, bool)
+    if (cls.kind_of?(Class) or cls.kind_of?(Module))
+      arr.keep_if { |i| i.is_a?(cls) == bool }
+    elsif cls.kind_of?(Symbol)
+      arr.keep_if { |i| i.send(cls) == bool }
+    else
+      arr.keep_if {|i| (i == cls) == bool}
+    end
+  end
 end

data/lib/gamefic/core_ext/string.rb

@@ -1,16 +1,25 @@
-class String
-  include Gamefic::Matchable
-  # Capitalize the first letter without changing the rest of the string.
-  # (String#capitalize makes the rest of the string lower-case.)
-  def capitalize_first
-    "#{self[0,1].upcase}#{self[1,self.length]}"
-  end
-  # @return [String]
-  def cap_first
-    self.capitalize_first
-  end
-  # @return [Array]
-  def split_words
-    self.gsub(/ +/, ' ').strip.split
-  end
-end
+class String
+  include Gamefic::Keywords
+
+  # Capitalize the first letter without changing the rest of the string.
+  # (String#capitalize makes the rest of the string lower-case.)
+  #
+  # @return [String] The capitalized text
+  def capitalize_first
+    "#{self[0,1].upcase}#{self[1,self.length]}"
+  end
+
+  # An alias for #capitalize_first.
+  #
+  # @return [String]
+  def cap_first
+    self.capitalize_first
+  end
+
+  # Get an array of words split by any whitespace.
+  #
+  # @return [Array]
+  def split_words
+    self.gsub(/[\s]+/, ' ').strip.split
+  end
+end

data/lib/gamefic/describable.rb

@@ -1,13 +1,8 @@
-#require 'gamefic/keywords'
-require 'gamefic/grammar'
-
 module Gamefic
-
   # Add a variety of text properties for naming, describing, and referencing
   # objects.
   module Describable
-    include Grammar::Person, Grammar::Plural
-    include Matchable
+    include Keywords
 
     # Get the name of the object.
     # The name is usually presented without articles (e.g., "object" instead
@@ -17,25 +12,28 @@ module Gamefic
     # @return [String]
     attr_reader :name
 
+    # Alternate words that can be used to describe the object. Synonyms are
+    # used in conjunction with the object's name when generating keywords.
+    #
     # @return [String]
     attr_reader :synonyms
 
-    # Get the object's indefinite article (usually "a" or "an").
+    # The object's indefinite article (usually "a" or "an").
     #
     # @return [String]
     attr_reader :indefinite_article
 
-    # Get the object's definite article (usually "the").
+    # The object's definite article (usually "the").
     #
     # @return [String]
     attr_reader :definite_article
 
-    # Get a set of Keywords associated with the object.
+    # Get a set of keywords associated with the object.
     # Keywords are typically the words in the object's name plus its synonyms.
     #
-    # @return [Keywords]
+    # @return [Array<String>]
     def keywords
-      @keywords ||= "#{definite_article} #{indefinite_article} #{name} #{synonyms}".downcase.split(Matchable::SPLIT_REGEXP).uniq
+      @keywords ||= "#{definite_article} #{indefinite_article} #{name} #{synonyms}".downcase.split(Keywords::SPLIT_REGEXP).uniq
     end
 
     # Get the name of the object with an indefinite article.
@@ -46,7 +44,7 @@ module Gamefic
     def indefinitely
       ((proper_named? or indefinite_article == '') ? '' : "#{indefinite_article} ") + name.to_s
     end
-    
+
     # Get the name of the object with a definite article.
     # Note: proper-named objects never append an article, though an article
     # may be included in its proper name.
@@ -55,14 +53,14 @@ module Gamefic
     def definitely
       ((proper_named? or definite_article == '') ? '' : "#{definite_article} ") + name.to_s
     end
-    
+
     # Get the definite article for this object (usually "the").
     #
     # @return [String]
     def definite_article
       @definite_article || "the"
     end
-    
+
     # Set the definite article.
     #
     # @param [String] article
@@ -78,7 +76,7 @@ module Gamefic
       @keywords = nil
       @indefinite_article = article
     end
-    
+
     # Is the object proper-named?
     # Proper-named objects typically do not add articles to their names when
     # referenced #definitely or #indefinitely, e.g., "Jane Doe" instead of
@@ -88,7 +86,7 @@ module Gamefic
     def proper_named?
       (@proper_named == true)
     end
-    
+
     # Set whether the object has a proper name.
     #
     # @param bool [Boolean]
@@ -101,7 +99,7 @@ module Gamefic
       end
       @proper_named = bool
     end
-    
+
     # Set the name of the object.
     # Setting the name performs some magic to determine how to handle
     # articles ("an object" and "the object").
@@ -132,21 +130,21 @@ module Gamefic
       end
       @name = value
     end
-    
+
     # Does the object have a description?
     #
     # @return [Boolean]
     def has_description?
       (@description.to_s != '')
     end
-    
+
     # Get the object's description.
     #
     # @return [String]
     def description
       @description || (Describable.default_description % { :name => self.definitely, :Name => self.definitely.capitalize_first })
     end
-    
+
     # Set the object's description.
     #
     # @param text [String]
@@ -157,7 +155,7 @@ module Gamefic
         @description = nil
       end
     end
-    
+
     def synonyms= text
       @keywords = nil
       @synonyms = text
@@ -172,14 +170,14 @@ module Gamefic
     def self.default_description=(text)
       @default_description = text
     end
-    
+
     # Get the object's default description.
     #
     # @return [String]
     def self.default_description
       @default_description || "There's nothing special about %{name}."
     end
-    
+
     # Get a String representation of the object. By default, this is the
     # object's name with an indefinite article, e.g., "a person" or "a red
     # dog."

data/lib/gamefic/element.rb

@@ -1,31 +1,43 @@
-module Gamefic
-  class Element
-    include Gamefic::Describable
-
-    def initialize(args = {})
-      self.class.default_attributes.merge(args).each { |key, value|
-        send "#{key}=", value
-      }
-      post_initialize
-      yield self if block_given?
-    end
-
-    def post_initialize
-      # raise NotImplementedError, "#{self.class} must implement post_initialize"
-    end
-
-    class << self
-      def set_default attrs = {}
-        default_attributes.merge! attrs
-      end
-
-      def default_attributes
-        @default_attributes ||= {}
-      end
-
-      def inherited subclass
-        subclass.set_default default_attributes
-      end
-    end
-  end
-end
+module Gamefic
+  # The simplest class that can compose an object for use in a plot.
+  # Most game objects, especially tangible items in the game, should derive
+  # from the Entity class. Elements, on the other hand, can be used for
+  # abstractions and ideas that don't have a physical presence but still might
+  # need to be referenced in a command.
+  #
+  class Element
+    include Gamefic::Describable
+    include Gamefic::Index
+
+    # @todo It would be nice if this initialization wasn't necessary.
+    def initialize(args = {})
+      super self.class.default_attributes.merge(args)
+      post_initialize
+      yield self if block_given?
+    end
+
+    def post_initialize
+      # raise NotImplementedError, "#{self.class} must implement post_initialize"
+    end
+
+    class << self
+      # Set or update the default values for new instances.
+      #
+      # @param attrs [Hash] The attributes to be merged into the defaults.
+      def set_default attrs = {}
+        default_attributes.merge! attrs
+      end
+
+      # A hash of default values for attributes when creating an instance.
+      #
+      # @return [Hash]
+      def default_attributes
+        @default_attributes ||= {}
+      end
+
+      def inherited subclass
+        subclass.set_default default_attributes
+      end
+    end
+  end
+end

data/lib/gamefic/entity.rb

@@ -3,22 +3,17 @@ require "gamefic/describable"
 require 'gamefic/messaging'
 
 module Gamefic
-
+  # A physical object that can exist in a plot. Most objects with which
+  # players interact are entities. Player characters themselves typically
+  # derive from entities, e.g., the Gamefic::Actor class.
+  #
   class Entity < Element
     include Node
     include Messaging
-    include Grammar::WordAdapter
 
-    # Execute the entity's on_update blocks.
-    # This method is typically called by the Engine that manages game execution.
-    # The base method does nothing. Subclasses can override it.
-    #
-    def update
-    end
-    
     # Set the Entity's parent.
     #
-    # @param node [Entity] The new parent.
+    # @param node [Gamefic::Entity] The new parent.
     def parent=(node)
       if node != nil and node.kind_of?(Entity) == false
         raise "Entity's parent must be an Entity"
@@ -43,7 +38,7 @@ module Gamefic
     def [](key)
       session[key]
     end
-    
+
     # Set a custom property.
     #
     # @param key [Symbol] The property's name
@@ -52,5 +47,4 @@ module Gamefic
       session[key] = value
     end
   end
-
 end