root/trunk/lib/fm/gameobject.rb

#!/usr/bin/ruby

require 'digest/md5'
require 'logger'
require 'sync'
require 'uuidtools'

require 'fm'
require 'fm/linguistics'
require 'fm/mixins'

# 
# FaerieMUD::GameObject, an abstract base class for
# all objects used in the construction of the FaerieMUD game world. It contains
# variables and functions for tracking the attribution of "creation points" to
# object authors, the identities of the authors themselves, and utility
# functions to represent FaerieMUD objects as HTML.
#
# == Subversion ID
# 
# $Id$
# 
# == Authors
# 
# * Michael Granger <ged@FaerieMUD.org>
# 
# :include: LICENSE
#
#---
#
# Please see the file LICENSE for licensing details.
#
class FaerieMUD::GameObject
        include Sync_m,
                FaerieMUD::AbstractClass,
                FaerieMUD::Propertied,
                FaerieMUD::Loggable,
                FaerieMUD::Debuggable,
                FaerieMUD::HTML,
                FaerieMUD::Linguistics

        ### Class constants

        # SVN Revision
        SVNRev = %q$Rev$

        # SVN Id
        SVNId = %q$Id$

        # The total number of "attribution" points for this object. 
        PointTotal = 100

        # The ratio to use when distributing points between contributors.
        Ratio = 3.0/2.0


        #############################################################
        ###     C L A S S   M E T H O D S
        #############################################################

        # The authors hash for this class
        @authors = Hash.new( 0 )
        @contributors = []
        class << self
                attr_reader :authors
        end


        ### Inheritance callback method: Add an 'authors' instance variable to each
        ### derivative class.
        def self::inherited( klass )
                super
                klass.add_authors_data
        end


        ### Add authors instance data to calling classes
        def self::add_authors_data
                unless self.instance_variables.include?( "@authors" )
                        self.instance_variable_set( :@authors, Hash.new(0) )
                        self.instance_variable_set( :@contributors, [] )
                        class << self # :nodoc:
                                attr_reader :authors
                        end
                end
        end


        ### Add one or more authors to the contributors for the current class.
        def self::contributors( *userids)
                self.add_authors_data
                return @contributors if userids.empty?
                @contributors.replace( userids )
                chart = self.distribute_points( *userids )
                self.authors.replace( chart )
        end


        ### Given a list of contributors, distribute points among them in a
        ### rough 3/2 ratio and return a map of person => points. Thanks to
        ### stillflame@FaerieMUD.org for the algorithm.
        def self::distribute_points( *people )
                points = Array.new( people.nitems, 1 )

                (PointTotal - people.nitems).times do |n|
                        points.each_with_index do |total,i|
                                if points[i+1].nil? ||
                                        total.to_f <= (points[i+1].to_f * Ratio)
                                        points[i] += 1
                                        break
                                end
                        end
                end

                chart = Hash.new( 0 )
                people.each_with_index do |person, i|
                        chart[person] += points[i]
                end

                return chart
        end


        ### Versioning method -- return the subversion rev number for the object.
        def self::rev
                revno = self.const_get( :SVNRev )
                if revno.match( /(\d+)/ )
                        return Integer($1)
                else
                        return 0
                end
        end


        ### Create an example instance of the receiving class. This is used to ease
        ### the complexity of creating example objects for experimentation. This
        ### should be overridden by object classes which require instantiation
        ### arguments.
        def self::example( args={} )
                new( args )
        end


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

        # This must come after the declaration of the contributors method above.
        contributors :ged, :stillflame, :phaedrus

        ### Initialize a new FaerieMUD::GameObject. Arguments in the 
        def initialize( args={} )
                super()

                # Add unique ID, rev, and mutex
                @id = UUID.timestamp_create
                @rev = self.class.rev

                # Call setters for named arguments
                args.each do |method, value|
                        self.send( "#{method}=", value )
                end
        end


        ### Copy initializer -- generate a unique id for cloned objects.
        def initialize_copy( original )
                super
                @id = UUID.timestamp_create
        end


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

        # The object's unique id
        attr_reader :id
        alias_method :uuid, :id

        # The revision number of the class from which the object was instantiated at
        # the time of its creation or last upgrade.
        attr_reader :rev


        ### Return the number of contribution points for the given +author+ (a
        ### String) the object is worth.
        def contribution( author )
                self.class.authors[ author ]
        end


        ### Obtain a shared lock on the receiver for the duration of the
        ### block. The mutex object is passed as argument.
        def readlocked
                return unless block_given?
                self.synchronize( Sync::SH ) do
                        yield
                end
        end



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

        ### Obtain an exclusive lock on the receiver for the durection of the
        ### block. The mutex object is passed as argument.
        def writelocked
                return unless block_given?
                self.synchronize( Sync::EX ) do
                        yield
                end
        end

end # class FaerieMUD::GameObject