root/trunk/lib/fm/entity.rb

#!/usr/bin/ruby
# 
# This file contains the FaerieMUD::Entity class, a derivative of
# FaerieMUD::GameObject. It is the base class for all objects which are capable
# of interaction with other objects via events.
#
# It provides event-handling behavior via the #handle_event method, which
# delegates handling to a secondary method which is based on the class of the
# event being handled. The event being handled is queried for
# appropriately-named handlers via its #handler_names method, and the first one
# which is implemented by the entity recieving the event is called with the
# event object as its argument. If no specific handlers are implemented, the
# #handle_any_event method is used instead, which by default raises a
# #FaerieMUD::UnhandledEventError.
# 
# == Synopsis
# 
#   
# 
# == To Do
# * Perhaps make the event handlers hash into something that dispatches
#   intelligently to superclasses, ala MUES::Event::Handler.
# 
# == Subversion ID
# 
# $Id$
# 
# == Authors
# 
# * Michael Granger <ged@FaerieMUD.org>
# 
# :include: LICENSE
#
#---
#
# Please see the file LICENSE for licensing details.
#


# 11. Tools
#     Thirty spokes meet at a nave;
#     Because of the hole we may use the wheel.
#     Clay is moulded into a vessel;
#     Because of the hollow we may use the cup.
#     Walls are built around a hearth;
#     Because of the doors we may use the house.
#     Thus tools come from what exists,
#     But use from what does not.
#
#       - Lao Tse, _Tao te Ching_
#          translated by Peter Merel

require 'fm/gameobject'
require 'fm/mixins'
require 'fm/exceptions'
require 'fm/event'
require 'fm/linguistics'


### The base class for all objects which are capable of interaction with
### other objects via events.
class FaerieMUD::Entity < FaerieMUD::GameObject
        contributors :ged
        include FaerieMUD::Hookable,
                FaerieMUD::Debuggable

        # SVN Revision
        SVNRev = %q$Rev$

        # SVN Id
        SVNId = %q$Id$


        #############################################################
        ###     I N S T A N C E   M E T H O D S
        #############################################################

        ### Initialize the entity's instance variables
        def initialize( args={} ) # :notnew:
                @event_handler_cache = {}
                super
        end


        ######
        public
        ######

        # The event-handler lookup cache (a Hash of method objects keyed by
        # event class).
        attr_reader :event_handler_cache


        ### Multi-event dispatch method. Calls #handle_event for each of the given
        ### +events+.
        def handle_events( *events )
                events.collect {|e| self.handle_event(e) }.flatten
        end


        ### Event dispatcher method. This method does dynamic dispatch to
        ### class-specific event handler methods. For each +event+ given, it will
        ### look for a method called <tt>handle<em>eventClass</em>>()</tt>, where
        ### <tt><em>eventClass</em></tt> is the class of the event to handle. If no
        ### explicit handler is found, each of the event's superclasses is tried as
        ### well. If no explicit handler is defined, it tries to call a fallback
        ### handler <tt>handle_any_event()</tt>. If no handler is found, a
        ### FaerieMUD::UnhandledEventError is raised.
        def handle_event( event )
                debug_msg( 1, "Handling a #{event.class.name} event." )
                handler = self.get_handler_for_event( event )
                result = handler.call( event )

                return Array( result )
        end


        ### Callback invoked whenever a singleton method is added to the
        ### receiver. Clears the event handler lookup cache if the method being
        ### added contains the word 'handle'. Also aliased to
        ### #singleton_method_removed and #singleton_method_undefined.
        def singleton_method_added( sym )
                debug_msg( 3, "Flushing event handler lookup cache" )
                @event_handler_cache.clear if /handler/ =~ sym.to_s
                super
        end
        alias_method :singleton_method_removed, :singleton_method_added
        alias_method :singleton_method_undefined, :singleton_method_added


        #
        #       Linguistics support
        #

        ### Returns +true+ if the entity should be considered plural for the
        ### purposes of generating english text.
        def plural?
                return false
        end



        #########
        protected
        #########

        ### Fallback event handler. The default implementation of this method
        ### just raises an UnhandledEventError, so deriviatives will probably
        ### want to override it.
        def handle_any_event( event )
                raise FaerieMUD::UnhandledEventError,
                          "No handler defined for #{event.class.name}s"
        end


        ### Get a handler as a callable object for the given +event+.
        def get_handler_for_event( event )
                handler = @event_handler_cache[event.class]

                # Search the event's class heirarchy for Event subclasses, and
                # look up handler methods based on the class name
                if handler.nil?
                        event.handler_names.each do |methodName|
                                debug_msg( 2, "Checking for a #{methodName} method..." )
                                if self.respond_to?( methodName )
                                        debug_msg( 2, "   found #{methodName}." )
                                        handler = self.method( methodName )
                                        break
                                end
                        end

                        # If no handler has yet been found, try to fetch the fallback
                        # handler.
                        if handler.nil?
                                if self.respond_to?( :handle_any_event )
                                        handler = self.method( :handle_any_event )
                                else
                                        raise UnhandledEventError,
                                                  "No handler defined for #{event.class.name}s"
                                end
                        end

                        @event_handler_cache[ event.class ] = handler
                end

                return handler
        end


end # class FaerieMUD::Entity