PGAS and Games::Golf presentation

So you want to host a Perl golf contest? These games can be quite successful: for example the golf game organised by The Perl Review volume 0 issue 1 had more than 100 players, and a total of about 600 entries were submitted.

So you need tools to run one of those fun and successful games.

PGAS (Perl Golf Administration System) is such a tool. It may be used to host a Golf game and receive submission.

Games::Golf is a series of modules to help writing tests for golf games, and it should make the organisation and administration of a golf course as easy as possible.

Tools and features

The Games-Golf distribution features several modules and scripts.

Features for the organiser

The Games::Golf::TestSuite module provide a series of methods to easily write test scripts, to help players write their entries.

The testsuites can be used to test either scripts or subroutines. The testsuite files are used by the golf and referee scripts to check the validity of one or several entries.

Features for the referees

The referee script allows a referee to test players entries as a batch. It updates the information about all the entries in a cache, and autmatically produces a leaderboard.

Features for the players

The golf script lets a player test his entries before submitting them (through PGAS or via email). It keeps an history file, so that the player can browse through his old entries to find inspiration or look at his progress. Future tools might use this information too.

Author: Creating a test suite for use with Games::Golf

The concept of .glf files

A golf course author create a golf course as a .glf file. This is a Perl-like text file, containing Perl code and POD documentation.

The pod serves as the documentation and rules for the hole, so that any player can check what the hole defintion and the course rules are simply by typing:

    perldoc course.glf

The .glf is divided in several sections, using special POD markers.

Configuration section

The configuration section defines several configuration variables used by the Games::Golf architecture.

    =begin conf

    PGAS    = http://perlgolf.sourceforge.net/cgi-bin/PGAS/
    version = 1.3

    =end conf

Variables are case-insensitive. Several variables are defined:

pgas

Defines the base URL where Games::Golf will find the classic submit.cgi form. This item is mandatory if you want to use Games::Golf's submit capabilities.

version

The version string for the .glf file. This string is used to mark each Games::Golf::Entry object with the testsuite it was tested against. No specific format is defined for this string.

Hole definition section

A test suite is written in Perl. But since that code is in fact eval()ed somewhere deep in Games::Golf::TestSuite, you really have very little work to do.

The test script used by the players makes use of the methods provided by the Games::Golf::TestSuite object.

A typical test suite will look like this:

 # First test: the player script should at least compile
 $test->compile;
 # Second test:
 # - no arguments to the script
 # - for the given input, we wait for a specific output,
 #   no errput, and an exit code of 0
 $test->aioee( "", << INPUT, << OUTPUT, "", 0 );
 This is the input
 INPUT
 We wait for this output
 OUTPUT

Testing a script

Three methods are used only for scripts:

compile()

Checks that the script at least compile. This is the most basic test that each entry should pass, and every testsuite should test.

aioee()

aioee stands for arguments, input, output, errput and exit code. The player's script is run with the given command-line arguments and standard input, and the test passes if the output, errput and exit code correspond to the method parameters.

For the exit code, "" or undef indicate that we don't care about its value.

loop()

Testing a sub

Three methods are used only for subs:

makesub()

Creates the sub. This is equivalent to the compile() method. A coderef is created with the given code. If all goes well, it should at least compile.

sub( ... )

Calls the subroutine with the given arguments.

ok()

Similar to the Test module ok() function, this method validates the result of the test.

Other available methods

The following methods are used to test the code itself:

not_string( $string )

Checks that the code doesn't contain the forbidden string $string.

not_match( $regex )

Checks that the code doesn't match the forbidden regex $regex.

Placing restrictions on the code

You can force any test to break if some restrictions are not respected. More precisely, you can limit the running time of the script (by a timeout), and the size of stdout and stderr.

Player

Using the test script

The testsuite works almost like a Perl script. The documentation for the hole (what you are supposed to do) should be available through the usual perldoc hole command.

golf hole test the entry stored in the file hole.pl against the testsuite held in hole. Several command-line switches are available, for various needs.

!!FIXME!! which switches?

Using PGAS

Credits

Games::Golf and PGAS authors

This article's authors

cpanm Games::Golf

perl -MCPAN -e shell
install Games::Golf