package Die;

use strict;
use vars qw($VERSION);

$VERSION = '0.07';

{
   sub _set_face { (shift)->{face} = $_[1] }
}

# Constructor->new sucks.  ->get a Die.
sub get {
   my ( $init, $type, $faced)  = @_;
   my $class = ref($init) || $init;
    
   # To store a face value or not to store . . .
   if ( $faced && $faced == 1 ) {
      return bless { type => $type, face => 0 }, $class;
   } else {
      return bless { type => $type }, $class;
   }
}

sub roll {
   my ( $self, $keeper ) = @_;

   my $type  = $self->{type};
   my $roll  = int( rand($type) + 1 );

   # Optionally stores face value
   if (  defined($self->{face}) && defined($keeper) && $keeper == 1 )
   {
      $self->_set_face($roll);
   }
   return $roll;
}
 
sub face {
   my $self = shift;

   if ( $self->{face} ) {
      return $self->{face}; 
   } else {
      return 0;
   }
}

1;
__END__

=head1 NAME

   Die - Perl module for a base die object  

=head1 SYNOPSIS

   use Die;

   Die->get($type, 1) Where $type is a mandantory parameter 
                      that specifies the number of sides to 
                      the die, and '1' is an optional 
                      parameter used to create a die with a
                      'face' attribute to store the value of
                      the die roll. At creation Die->{face}=0
                      The 0 signifies that the Die has yet to 
                      be rolled.

   Die->roll(1)       Where '1' is an optional parameter
                      that forces the 'face' value to be 
                      stored in a Die object that has been 
                      created with a 'face'. (See Die->get).

=head1 DESCRIPTION 

   This module is a base class for the more robust Dice 
   class.  Although Die methods can be called directly 
   via this module, perfomance begs the question as to 
   why not to just use: 

   int(rnd($num)+1 

   However one may have need of the Dice class and desire 
   to maintain code continuity, and still need a die roll.
   By default Die creates itself as lightweight as possible
   by not creating a 'face' attribute, and by not storing 
   the 'roll'.  Both of these abilities can be enabled by 
   specifiying a an optional parameter of 1.
 
   A comparison of a random number subroutine versus the 
   various incantations of Die->get and Die->roll:

                       Rate    FacedDieObjStored FacedDieObjNotStored 
FacedDieObjStored     8514/s          --                -13%         
FacedDieObjNotStored  9821/s          15%                --           
FacelessDieObj       10110/s          19%                 3%         
RndSubRoutine        54455/s          540%              454%        
   
                               FacelessDieObj     rndSubRoutine
FacedDieObjStored                     -16%              -84%
FacedDieObjNotStored                   -3%              -82%
FacelessDieObj                          --              -81%
RndSubRoutine                         439%                --

=head1 AUTHOR 

coreolyn@bereth.com

=head1 SEE ALSO 

perldoc Dice

=cut