NAME

Chess::Game - a class to record and validate the moves of a game of chess

SYNOPSIS

    use Chess::Game;

    $game = Chess::Game->new();
    $clone = $game->clone();
    $move = $game->make_move("e2", "e4");
    $move_c = $clone->make_move("e2", "e4");
    $true = ($move->get_piece() ne $move_c->get_piece());
    $move = $game->delete_move();
    ...
    while (!defined($result = $game->result())) {
	# get a move
	$move = $game->make_move($sq1, $sq2);
	if (!defined($move)) {
	    print $game->get_message();
	}
    }
    if ($result == 1) {
	print "White wins!\n";
    }
    elsif ($result == 0) {
	print "Draw!\n"
    }
    else {
	print "Black wins!\n";
    }

DESCRIPTION

The Chess module provides a framework for writing chess programs with Perl. This class forms part of that framework, providing move validation for all moves recorded using the Chess::Game class. The Game contains a Chess::Board, 32 Chess::Pieces and a Chess::Game::MoveList that contains a series of Chess::Game::MoveListEntrys that record the exact state of the game as it progresses. Moves can be taken back one-at-a-time to allow for simple movelist manipulation.

METHODS

Construction

new()

Takes two optional parameters containing optional names for the players. If none are provided, the player names 'white' and 'black' are used. Creates a new Chess::Board and places 16 Chess::Pieces per player and initializes an empty Chess::Game::MoveList.

Class methods

There are no class methods for this class.

Object methods

clone()

Takes no parameters. Returns a new blessed Chess::Game reference in an identical state to the calling object, but which can be manipulated entirely separately.

is_move_legal()

Takes two parameters containing the name of the square to move from and the name of the square to move to. They should be validated with "square_is_valid()" in Chess::Board prior to calling. Returns true if the provided move is legal within the context of the current game.

make_move()

Takes two parameters containing the name of the square to move from and the name of the square to move to. They should be validated with "square_is_valid()" in Chess::Board before calling. Optionally takes a third parameter, which can be set to zero to indicate that no legality checking should be done. In this case, flags indicating 'en passant' pawn captures or castling will not be set! Only by entirely validating the move do these flags have any meaning. The default is to validate every move. Returns a Chess::Game::MoveListEntry representing the move just made.

get_message()

Takes no parameters. Returns the message containing the reason "make_move()" or "is_move_legal()" returned false, such as "Can't castle out of check".

delete_move()

Takes no parameters. Returns a Chess::Game::MoveListEntry representing the last move made, and sets the state of the game to what it was prior to the returned move being made.

player_in_check()

Takes a single parameter containing the name of the player to consider. Returns true if the named player is in check.

player_checkmated()

Takes a single parameter containing the name of the player to consider. Returns true if the named player has been checkmated.

player_stalemated()

Takes a single parameter containing the name of the player to consider. Returns true if the named player has been stalemated.

result()

Takes no parameters. Returns undef as long as the game is in progress. When a conclusion has been reached, returns 1 if the first player checkmated the second player, 0 if either player has been stalemated, or -1 if the second player checkmated the first player. Is not currently able to determine if the game was drawn by a three-fold repetition of positions.

do_promotion()

Takes one parameters. If the last move was a promotion (as determined by a call to "is_promotion()" in Chess::Game::MoveListEntry, then calling this function will change the newly promoted pawn to the piece specified by the provided parameter. Valid values are (case-insensitive) "bishop", "knight", "queen" and "rook".

DIAGNOSTICS

Invalid Chess::Game reference

The program contains a reference to a Chess::Game not obtained through "new()" or "clone()". Ensure the program only uses these methods to create Chess::Game references, and the the reference refers to a defined value.

Invalid square 'q9'

The program made a call to make_move() or is_move_legal() with invalid squares. Ensure that all variables containing squares are validated with "square_is_valid()" in Chess::Board.

BUGS

The framework is not currently able to determine when a game has been drawn by three-fold repetition of position. Please report any other bugs to the author.

AUTHOR

Brian Richardson <bjr@cpan.org>

COPYRIGHT

Copyright (c) 2002, 2005 Brian Richardson. All rights reserved. This module is Free Software. It may be modified and redistributed under the same terms as Perl itself.