gamefic 0.2.0 → 0.6.0

data/lib/gamefic/node.rb

@@ -1,62 +1,69 @@
+# Exception raised when setting a node's parent would cause
+# a circular reference, e.g., A -> A or A -> B -> A
+class CircularNodeReferenceError < Exception
+end
+
 module Gamefic
 
-	module Node
-		def children
-			if @children == nil
-				@children = Array.new
-			end
-			@children.clone
-		end
-		def flatten
-			array = Array.new
-			children.each { |child|
-				array = array + recurse_flatten(child)
-			}
-			return array
-		end
-		protected
-		def add_child(node)
-			children
-			@children.push(node)
-		end
-		def rem_child(node)
-			children
-			@children.delete(node)
-		end
-		def concat_children(children)
-			children
-			@children.concat(children)
-		end
-		private
-		def recurse_flatten(node)
-			array = Array.new
-			array.push(node)
-			node.children.each { |child|
-				array = array + recurse_flatten(child)
-			}
-			return array
-		end
-	end
-	
-	module Branch
-		include Node
-		def parent
-			@parent
-		end
-		def parent=(node)
-			if node == self
-				raise "Entity cannot be its own parent"
-			end
-			if @parent != node
-				if @parent != nil
-					@parent.send(:rem_child, self)
-				end
-				@parent = node
-				if @parent != nil
-					@parent.send(:add_child, self)
-				end
-			end
-		end
-	end
+  module Node
+    # @return [Array]
+    def children
+      @children ||= []
+      @children.clone
+    end
+    def flatten
+      array = Array.new
+      children.each { |child|
+        array = array + recurse_flatten(child)
+      }
+      return array
+    end
+    def parent
+      @parent
+    end
+    def parent=(node)
+      return if node == @parent 
+      if node == self
+        raise CircularNodeReferenceError.new("Node cannot be its own parent")
+      end
+      # Do not permit circular references
+      if node != nil and node.parent == self
+        node.parent = nil
+      end
+      if node != nil and flatten.include?(node)
+        raise CircularNodeReferenceError.new("Node cannot be a child of a descendant")
+      end
+      if @parent != node
+        if @parent != nil
+          @parent.send(:rem_child, self)
+        end
+        @parent = node
+        if @parent != nil
+          @parent.send(:add_child, self)
+        end
+      end
+    end
+    protected
+    def add_child(node)
+      children
+      @children.push(node)
+    end
+    def rem_child(node)
+      children
+      @children.delete(node)
+    end
+    def concat_children(children)
+      children.concat(children)
+    end
+    private
+    def recurse_flatten(node)
+      array = Array.new
+      array.push(node)
+      node.children.each { |child|
+        array = array + recurse_flatten(child)
+      }
+      return array
+    end
+  end
 
 end

data/lib/gamefic/plot/article_mount.rb

@@ -0,0 +1,22 @@
+module Gamefic
+  module ArticleMount
+    def a(entity)
+      entity.indefinitely
+    end
+    def an(entity)
+      entity.indefinitely
+    end
+    def the(entity)
+      entity.definitely
+    end
+    def A(entity)
+      entity.indefinitely.cap_first
+    end
+    def An(entity)
+      entity.indefinitely.cap_first
+    end
+    def The(entity)
+      entity.definitely.cap_first
+    end
+  end
+end

data/lib/gamefic/plot/command_mount.rb

@@ -0,0 +1,88 @@
+require 'gamefic/action'
+
+module Gamefic
+
+  module Plot::CommandMount
+    # Create a Meta Action that responds to a command.
+    # Meta Actions are very similar to standard Actions, except the Plot
+    # understands them to be commands that operate above and/or outside of the
+    # actual game world. Examples of Meta Actions are commands that report the
+    # player's current score, save and restore saved games, or list the game's
+    # credits.
+    #
+    # @example A simple Meta Action
+    #   meta :credits do |actor|
+    #     actor.tell "This game was written by John Smith."
+    #   end
+    #
+    # @param command [Symbol] An imperative verb for the command
+    # @param *queries [Array<Query::Base>] Queries to filter the command's tokens
+    # @yieldparam [Character]
+    def meta(command, *queries, &proc)
+      act = self.action(command, *queries, &proc)
+      act.meta = true
+      act
+    end
+    def action(command, *queries, &proc)
+      Action.new(self, command, *queries, &proc)
+    end
+    # Create an Action that responds to a command.
+    # An Action uses the command argument to identify the imperative verb that
+    # triggers the action.
+    # It can also accept queries to tokenize the remainder of the input and
+    # filter for particular entities or properties.
+    # The block argument contains the code to be executed when the input
+    # matches all of the Action's criteria (i.e., verb and queries).
+    #
+    # @example A simple Action.
+    #   respond :salute do |actor|
+    #     actor.tell "Hello, sir!"
+    #   end
+    #   # The command "salute" will respond "Hello, sir!"
+    #
+    # @example An Action that accepts a Character
+    #   respond :salute, Use.visible(Character) do |actor, character|
+    #     actor.tell "#{The character} returns your salute."
+    #   end
+    #
+    # @param command [Symbol] An imperative verb for the command
+    # @param *queries [Array<Query::Base>] Queries to filter the command's tokens
+    # @yieldparam [Character]
+    def respond(command, *queries, &proc)
+      self.action(command, *queries, &proc)
+    end
+    # Create an alternate Syntax for an Action.
+    # The command and its translation can be parameterized.
+    #
+    # @example Create a synonym for the Inventory Action.
+    #   interpret "catalogue", "inventory"
+    #   # The command "catalogue" will be translated to "inventory"
+    #
+    # @example Create a parameterized synonym for the Look Action.
+    #   interpret "scrutinize :entity", "look :entity"
+    #   # The command "scrutinize chair" will be translated to "look chair"
+    #
+    # @param command [String] The format of the original command
+    # @param translation [String] The format of the translated command
+    # @return [Syntax] the Syntax object
+    def interpret command, translation
+      xlate command, translation
+    end
+    def syntax(*args)
+      xlate(*args)
+    end
+    def xlate(*args)
+      syn = Syntax.new(self, *args)
+      syn
+    end
+    def commandwords
+      words = Array.new
+      syntaxes.each { |s|
+        word = s.first_word
+        words.push(word) if !word.nil?
+      }
+      words.uniq
+    end
+  end
+  
+end

data/lib/gamefic/plot/entity_mount.rb

@@ -0,0 +1,45 @@
+module Gamefic
+
+  module Plot::EntityMount
+    # Make a new Entity with the provided properties.
+    #
+    # @example Create an Entity
+    #   chair = make Entity, :name => 'red chair'
+    #   chair.name #=> 'red chair'
+    #
+    # @param cls [Class] The Class of the Entity to be created.
+    # @param args [Hash] The entity's properties.
+    # @return The Entity instance.
+    def make(cls, args = {}, &block)
+      ent = cls.new(self, args, &block)
+      if ent.kind_of?(Entity) == false
+        raise "Invalid entity class"
+      end
+      ent
+    end
+    # Pick an entity based on its description.
+    # The description provided must match exactly one entity; otherwise
+    # an error is raised.
+    #
+    # @example Select the Entity that matches the description
+    #   red_chair = make Entity, :name => 'red chair'
+    #   blue_chair make Entity, :name => 'blue chair'
+    #   pick "red chair" #=> red_chair
+    #   pick "blue chair" #=> blue_chair
+    #   pick "chair" #=> IndexError: description is ambiguous
+    #
+    # @param @description [String] The description of the entity
+    # @return [Entity] The entity that matches the description
+    def pick(description)
+      query = Gamefic::Query::Base.new
+      result = query.match(description, entities)
+      if result.objects.length == 0
+        raise IndexError.new("Unable to find entity from '#{description}'")
+      elsif result.objects.length > 1
+        raise IndexError.new("Ambiguous entities found from '#{description}'")
+      end
+      result.objects[0]
+    end
+  end
+
+end

data/lib/gamefic/plot/query_mount.rb

@@ -0,0 +1,9 @@
+module Gamefic
+  module Plot::QueryMount
+  end
+  module Query
+    def self.siblings *arguments
+      Siblings.new *arguments
+    end
+  end
+end

data/lib/gamefic/plot/scene_mount.rb

@@ -0,0 +1,181 @@
+class NotConclusionError < Exception
+end
+
+module Gamefic
+
+  module Plot::SceneMount
+    # Get a Hash of SceneManager objects.
+    #
+    # @return [Hash<Symbol, SceneManager>]
+    def scene_managers
+      if @scene_managers.nil?
+        @scene_managers ||= {}
+        @scene_managers[:active] = ActiveSceneManager.new
+        @scene_managers[:concluded] = ConcludedSceneManager.new
+      end
+      @scene_managers
+    end
+    
+    # Create a multiple-choice scene.
+    # The user will be required to make a valid choice to continue
+    #
+    # @yieldparam [Character]
+    # @yieldparam [MultipleChoiceSceneData]
+    def multiple_choice key, *args, &block
+      scene_managers[key] = MultipleChoiceSceneManager.new do |config|
+        config.start do |actor, data|
+          data.options = args
+        end
+        config.finish(&block)
+      end
+    end
+    
+    # Create a yes-or-no scene.
+    # The user will be required to answer Yes or No to continue.
+    #
+    # @yieldparam [Character]
+    # @yieldparam [YesOrNoSceneData]
+    def yes_or_no key, prompt = nil, &block
+      manager = YesOrNoSceneManager.new do |config|
+        config.prompt = prompt
+        config.finish do |actor, data|
+          if data.answer.nil?
+            actor.tell "Please answer Yes or No."
+          else
+            data.next_cue ||= :active
+            block.call(actor, data)
+          end
+        end
+      end
+      scene_managers[key] = manager
+    end
+    
+    # Create a scene with a prompt.
+    # This scene will use the provided block to process arbitrary input
+    # from the user.
+    #
+    # @param key [Symbol] A unique name for the scene.
+    # @param prompt [String] The prompt message to display to the user.
+    # @yieldparam [Character]
+    # @yieldparam [SceneData]
+    def prompt key, prompt, &block
+      scene_managers[key] = SceneManager.new do |config|
+        config.prompt = prompt
+        config.finish do |actor, data|
+          data.next_cue ||= :active
+          block.call actor, data
+        end
+      end
+      scene_managers[key].state = "Prompted"
+    end
+    
+    # Create a scene that pauses the game.
+    # This scene will execute the specified block and wait for input
+    # from the user (e.g., pressing Enter) to continue.
+    #
+    # @param key [Symbol] A unique name for the scene.
+    # @yieldparam [Character]
+    # @yieldparam [SceneData]
+    def pause key, &block
+      manager = PausedSceneManager.new do |config|
+        config.start do |actor, data|
+          data.next_cue = :active
+          block.call actor, data
+        end
+      end
+      scene_managers[key] = manager
+    end
+    
+    # Create a conclusion.
+    # The game will end after this scene is complete.
+    #
+    # @param key [Symbol] A unique name for the scene.
+    # @yieldparam [Character]
+    # @yieldparam [SceneData]
+    def conclusion key, &block
+      manager = ConcludedSceneManager.new do |config|
+        config.start(&block)
+      end
+      scene_managers[key] = manager
+    end
+    
+    # Create a generic scene.
+    # After the scene is complete, it will automatically start the next cue.
+    #
+    # @param [Symbol] A unique name for the scene.
+    # @yieldparam [Character]
+    # @yieldparam [SceneData]
+    def scene key, &block
+      scene = SceneManager.new do |manager|
+        manager.start do |actor, data|
+          data.next_cue = :active
+          block.call(actor, data) if !block.nil?
+          cue actor, data.next_cue
+          actor.scene.start actor
+        end
+        # Since generic scenes always cue a new scene, there's no reason to
+        # define a finish block.
+      end
+      scene_managers[key] = scene
+    end
+    
+    # Branch to a new scene based on a list of options.
+    # This is a specialized type of multiple-choice scene that determines
+    # which scene to cue based on a Hash of choices and scene keys.
+    #
+    # @example Select a scene
+    #   branch :select_one_or_two, { "one" => :scene_one, "two" => :scene_two }
+    #   scene :scene_one do |actor|
+    #     actor.tell "You went to scene one"
+    #   end
+    #   scene :scene_two do |actor|
+    #     actor.tell "You went to scene two"
+    #   end
+    #   introduction do |actor|
+    #     cue actor, :select_one_or_two # The actor will be prompted to select "one" or "two" and get sent to the corresponding scene
+    #   end
+    #
+    # @param key [Symbol] A unique name for the scene.
+    # @param options [Hash] A Hash of options and associated scene keys.
+    def branch key, options
+      multiple_choice key, *options.keys do |actor, data|
+        cue actor, options[data.selection]
+      end
+    end
+    
+    # Cue a Character's next scene
+    #
+    # @param actor [Character] The character being cued
+    # @param key [Symbol] The name of the scene
+    def cue actor, key
+      if !actor.scene.nil? and actor.scene.state == "Concluded"
+        return
+      end
+      if key.nil?
+        raise "Cueing scene with nil key"
+      end
+      manager = scene_managers[key]
+      if manager.nil?
+        raise "No '#{key}' scene found"
+      else
+        actor.scene = manager.prepare key
+      end
+      @scene
+    end
+    
+    # This is functionally identical to #cue, but it also raises an
+    # exception if the selected scene is not a Concluded state.
+    #
+    # @param actor [Character] The character being cued
+    # @param key [Symbol] The name of the scene
+    def conclude actor, key
+      key = :concluded if key.nil?
+      manager = scene_managers[key]
+      if manager.state != "Concluded"
+        raise NotConclusionError("Cued scene '#{key}' is not a conclusion")
+      end
+      cue actor, key
+    end
+  end
+
+end

data/lib/gamefic/plot/you_mount.rb

@@ -0,0 +1,22 @@
+require 'gamefic'
+require 'gamefic/grammar'
+
+module Gamefic
+  module YouMount
+    class YouGrammarSet
+      include Grammar::Gender
+      include Grammar::Person
+      include Grammar::Plural
+      include Grammar::WordAdapter
+    end
+    # @return [YouGrammarSet]
+    def you
+      if @you.nil?
+        @you = YouGrammarSet.new
+        @you.person = 2
+      end
+      @you
+    end
+  end
+  
+end