NAME

Games::Golf::Entry - Single solution for a golf hole.

SYNOPSIS

use Games::Golf;

my $entry = new Games::Golf::Entry ( "hole.pl" );

$entry->test;

$entry->print_report;

$entry->test_ok or die;

DESCRIPTION

Internal object to be used by Games::Golf. Each solution represents a single hole.

CONSTRUCTOR

new( "author", "hole_name", "/path/to/solution/file" )

Creates a new Games::Golf::Entry object. You should pass the path to the file that holds the solution.

!!FIXME!! We should pass the hole name in order to know which test suite to apply.

!!FIXME!! Should we pass arguments as an array or as a hash?

!!FIXME!! Maybe we could create another constructor that will accept directly the code to test? Don't sure this is a good idea.

ACCESSORS

All the accessors are autoloaded.

author()

Full name of the author.

email()

Author's email address.

nick()

Author's nickname.

hole()

The name of the hole this solution solves.

date()

Date of the entry.

code()

The entry's code.

result()

The entry's test result. This is updated by the ok() method, which should only be used by the check() method of Games::Golf::TestSuite (do I make myself clear?).

This structure is an array reference. The first parameter is the total number of tests taken. The second parameters is the number of tests passed. The rest of the array is the list of errors messages. "" means the test passed. For example:

$result = [
    5,  # total number of tests taken
    3,  # number of tests passed
    "", # ok 1
    "", # ok 2
    "expected:\n--\n3--\ngot:\n--\n4--\n" # not ok 3
    "", # ok 4
];

file()

Filename of the entry.

id()

MD5 sum of the file, to make caching easier.

METHODS

score()

Compute and return this Entry's score.

tiebreak( $tie, [ $tie2 , ... ] );

Compute and return this entry tie-breaking scores.

This method is meant to be used as an accessor.

If $tie is a string, it's used to look up one of the predefined tie-breaking values. If it's a coderef, the given subroutine is used to compute the tie-breaking value. This value is not cached.

Examples of use:

# return the date tie-breaker
$tie = $entry->tiebreak( "date" );

# yet another way to break ties
$tie = $entry->tiebreak( sub { rand } );

# return both in a hash
%tie = $entry->tiebreak( "date",  sub { rand } );

# all predefined tie-breaking values
%tie = $entry->tiebreak;

Several tie-breaking score are predefined. They are meant to be used as the decimal part of a score. So they should be such that the lower $entry->score() + $entry->tiebreak(), the better the overall score is.

The predefined tie-breaking values are:

date

The sooner the code is submitted, the better. This value is simply computed as YYYYMMDDhhmmss, or in POSIX strftime() parlance: "%Y%m%d%H%M%S".

weird

The bigger the percentage of "weird characters", the better. Weird characters are defined as [^\w\s].

!!FIXME!! 1 is an invalid value! It'll increase the score by one, if we use this tiebreaker in an addition. My proposition is to compute the percentage as the number of non weird char divied by score + 1.

ok( $status, $msg )

WARNING: This method should only be used in the Games::Golf::TestSuite object.

Updates the result attribute of the Games::Golf::Entry object.

If the test passed, $status should be true (and the message stored will be empty).

If the test failed, $status should be false, and a message should be given. If no message is given, ok() will store a default message in result. This means that you can be sure that if a message in result is true, then the test failed.

BUGS

Please report all bugs to:

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Games-Golf

TODO

Lots of stuff.

AUTHORS

Philippe 'BooK' Bruhat <book@cpan.org>

Dave Hoover <dave@redsquirreldesign.com>

Steffen Müller <games-golf@steffen-mueller.net>

Jonathan E. Paton <jonathanpaton@yahoo.com>

Jérôme Quelin <jquelin@cpan.org>

Eugène Van der Pijll <E.C.vanderPijll@phys.uu.nl>

COPYRIGHT

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

SEE ALSO

perl, Games::Golf.