Games::Ratings - generic methods for rating calculation (e.g. chess ratings)

 ## not very useful, but one could do

 use Games::Ratings;
 my $player = Games::Ratings->new();
 $player->set_rating(2240);
 $player->add_game( {
                      opponent_rating => 2114,
                      result          => 'win',   ## or 'draw' or 'loss'
                    }
                  );
 my $n                = $player->get_number_of_games_played();
 my $points_scored    = $player->get_points_scored();
 my $opponents_rating = $player->get_average_rating_of_opponents();
 $player->remove_all_games;

  

  my $player = Games::Rating->new();

  $player->set_rating(2235);

  my $own_rating = $player->get_rating();

  $player->set_coefficient(15);

  my $own_coefficient = $player->get_coefficient();

  $player->add_game( {
                       opponent_rating => 2184,
                       result          => 'draw',
                     }
                   );

  my @list_of_games = $player->get_all_games();

  $player->remove_all_games();

  $player->DESTROY();

  my $n = $player->get_number_of_games_player();

  my $points_scored = $player->get_points_scored();

  my $percentage_score = $player->get_percentage_score();

  my $opponents_rating = $player->get_average_rating_of_opponents();

package Games::Ratings;

## TODO: Error handling
##       * croak()
##       check arguments for subroutines (use Data::Checker)?

use warnings;
use strict;
use Carp;

use 5.6.1;               # 'our' was introduced in perl 5.6
use version; our $VERSION = qv('0.0.5');

use Class::Std::Utils;   # we are using inside-out objects

{
    ## objects of this class (players) will have the following attributes
    my %rating_of;       # rating of player
    my %coefficient_of;  # coefficient of player
    my %games_of;        # list of games of player

    ## create new object (inside-out object -- see "Encapsulation" in PBP)
    sub new {
        my ($class) = @_;

        ## bless a scalar to instantiate the new object
        my $new_player_object = bless anon_scalar(), $class;

        return $new_player_object;
    }

    ## set rating according to passed argument
    sub set_rating {
        my ($self, $rating) = @_;

        ## check that rating is passed as argument
        croak( 'Usage: $obj->set_rating($rating)' )
            if @_ < 2;

        ## store rating in player object
        $rating_of{ident $self} = $rating;

        return;
    }
    
    ## return previously set rating
    sub get_rating {
        my ($self) = @_;
        return $rating_of{ident $self};
    }
    
    ## set coefficient according to passed argument
    sub set_coefficient {
        my ($self, $coefficient) = @_;

        ## check that coefficient is passed as argument
        croak( 'Usage: $obj->set_coefficient($coefficient)' )
            if @_ < 2;
        
        ## store coefficient in player object
        $coefficient_of{ident $self} = $coefficient;

        return;
    }
    
    ## return previously set coefficient
    sub get_coefficient {
        my ($self) = @_;
        return $coefficient_of{ident $self};
    }
    
    ## add new game to list of games ($games_of{ident $self} is list of games)
    sub add_game {
        my ($self, $game_ref) = @_;

        ## check that new game is passed as argument (hash reference) 
        croak( 'Usage: $obj->add_game( { 
                                                  opponent_rating => 2300,
                                                  result          => \'draw\',
                                              }
                                          );
                                          ' )
            if @_ < 2;

        ## store additional game in player object
        push @{ $games_of{ident $self} }, $game_ref;

        return;
    }

    ## return all previously added games as a list of hash references
    sub get_all_games {
        my ($self) = @_;

        ## return list of games or throw an error if $self doesn't have games
        if ( $games_of{ident $self} ) {
            return @{ $games_of{ident $self} };
        }
        else {
            croak( 'There aren\'t any games played. Please use add_game().' )
        }
    }
    
    ## delete all previously added games
    sub remove_all_games {
        my ($self) = @_;
        $games_of{ident $self} = undef;
        return;
    }

    ## clean up attributes when object is destroyed
    sub DESTROY {
        my ($self) = @_;

        delete $rating_of{ident $self};
        delete $coefficient_of{ident $self};
        delete $games_of{ident $self};

        return;
    }
}
    
## return number of played games
sub get_number_of_games_played {
    my ($self) = @_;

    ## number of played games equals length of array of played games
    return scalar $self->get_all_games();
}

## calculate and return scored points
sub get_points_scored {
    my ($self) = @_;
    
    ## compute scored points from list of played games
    my $points_scored;
    foreach my $game_ref ( $self->get_all_games() ) {
        $points_scored += _get_numerical_result( $game_ref->{result} );
    }

    ## return scored points
    return $points_scored;
}

## calculate percentage score
sub get_percentage_score {
    my ($self) = @_;

    ## compute percentage score
    my $percentage_score = $self->get_points_scored() 
                           / $self->get_number_of_games_played();

    ## return percentage score
    return $percentage_score;
}

## calculate and return return average rating of opponents
sub get_average_rating_of_opponents {
    my ($self) = @_;
    
    ## calculate average rating of opponents from (list of) stored games
    my $rat_opps;
    foreach my $game_ref ( $self->get_all_games() ) {
        $rat_opps += $game_ref->{opponent_rating},
    }
    $rat_opps = sprintf( "%.f", $rat_opps 
                                / $self->get_number_of_games_played() );

    ## return average rating of opponents
    return $rat_opps;
}

## define lookup table for conversion 'verbal results' -> 'numerical results'
my %numerical_results = (
    win  =>   1,
    draw => 0.5,
    loss =>   0,
);

## get numerical result of $result (win, draw, loss)
sub _get_numerical_result {
    my ($result) = @_;

    ## numerical result is looked up in a small table (see above)
    my $numerical_result = $numerical_results{$result};

    ## return numerical result
    return $numerical_result;
}

1; # Magic true value required at end of module
__END__