File Coverage

blib/lib/Games/Ratings.pm

Criterion	Covered	Total	%
statement	69	70	98.5
branch	4	8	50.0
condition			n/a
subroutine	20	20	100.0
pod	12	12	100.0
total	105	110	95.4

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__