Games::Chess - represent chess positions and games
use Games::Chess qw(:constants); my $p = Games::Chess::Position->new; $p->at(0,0,BLACK,ROOK); $p->at(7,7,WHITE,ROOK); print $p->to_text;
The
Games::Chess package provides the class
Games::Chess::Piece to represent chess pieces, and the class
Games::Chess::Position to represent a position in a chess game. Objects can be instantiated from data in standard formats and exported to these formats.
See Games::Chess::PGN for full details of the notations.
Standard Algebraic Notation. The modern international notation for chess games. For example,
1. e4 e5 2. f4 exf4 3. Nf3 g5
Portable Game Notation. A notation for chess games, including the moves, commentary, variations, and metadata such as the players, the event, the round number, and the date of the match. For example,

Extended Position Description. An extensible notation based on FEN. Intended for data interchange between chess-playing programs and for the construction of opening databases. Not used by
Games::Chess..)
To import all these functions into your namespace, include the tag
:functions in the
use statement, for example
use Games::Chess qw(:functions);
If $square represents a square in Standard Algebraic Notation (from a1 to h8), return a list of two elements ($x,$y) giving the coordinates of that square, from (0,0) to (7,7). Return undefined otherwise.
Return 1 if $colour is a valid colour value,
WHITE or
BLACK. Return undefined otherwise.
Set the debugging level. See "ERROR HANDLING".
Return a description of the most recent error in any of the
Games::Chess::* packages, or the empty string if no errors have occurred. See "ERROR HANDLING".
Return 1 if $halfmove is a valid value for the halfmove clock, which counts the number of ply (moves by either player) since the last pawn move or capture. Return undefined otherwise.
Return 1 if $move is a valid value for the full move count (the number of black moves since the start of the game, plus 1). Return undefined otherwise.
Return 1 if $piece is a valid piece value, from
PAWN to
KING. Return undefined otherwise.
If ($x,$y) is a valid board position, from (0,0) to (7,7), return the algebraic notation for that square, from
a1 to
h8. Return undefined otherwise.
Return 1 if ($x,$y) is a valid board position, from (0,0) to (7,7). Return undefined otherwise.
A chess piece, or an empty square on a chess board, is represented as an object belonging to the
Games::Chess::Piece class.).
With no argument, return an object representing an empty square.
With a single argument that is a member of the
Games::Chess::Piece class, return an object representing the same piece as $piece.
With a numeric argument, return an object representing a piece with that encoding. Return undefined if $number is not an integer in the range 0 to 255..
Return an object representing the piece described. Return undefined if $color is not WHITE or BLACK, or $piece is not PAWN, KNIGHT, BISHOP, ROOK, QUEEN or KING.
Return the FEN code for the piece as a single character (PNBRQKpnbrqk), or a space if the piece represents an empty square.
Return
EMPTY,
WHITE or
BLACK as appropriate.
Return "empty", "white" or "black" as appropriate.
Return a string describing the piece, for example "black knight", or "white king", or "empty square".
Return
EMPTY,
PAWN,
KNIGHT,
BISHOP,
ROOK,
QUEEN, or
KING as appropriate.
Return "square", "pawn", "knight", "bishop", "rook", "queen", or "king" as appropriate.
A chess position represented as an object belonging to the
Games::Chess::Position class..
With no argument, return an object representing a position with all 16 pieces in their initial positions.
With a single argument that is a member of the
Games::Chess::Position class, return a copy of $position..
If ($x,$y) is a valid board position, return an object of class
Games::Chess::Piece representing the square at ($x,$y). Return undefined otherwise.
If ($x,$y) is a valid board position, and @piece would be valid as arguments to the
Games::Chess::Piece constructor (see "PIECE CONSTRUCTORS"), put the specified piece on the specified square and return 1. Return undefined otherwise.
Return the board position as a vector of 64 bytes.
If $colour is a valid colour, and $piece is
KING or
QUEEN, return true if the player given by $colour can castle on the side given by $piece, false if they cannot. Return undefined otherwise.
If $colour is a valid colour, and $piece is
KING or
QUEEN, set the castling availability for the player given by $colour and the side given by $piece to the truth value of $can_castle, and return 1. Return undefined otherwise.
If ($x,$y) is a valid board position, clear the specified square and return 1. Return undefined otherwise. Equivalent to
Position->at($x,$y,Piece->new);
Return the en passant target square as the list (FILE,RANK), or undefined if there is no en passant target square.
If ($x,$y) is a valid board position, set the en passant target square to ($x,$y) and return 1. Return undefined otherwise.
Return the halfmove clock (the number of ply since the last pawn move or capture).
If $halfmove is a valid halfmove clock value, set the halfmove clock to $halfmove and return 1. Return undefined otherwise.
Return the move number (the number of full moves since the beginning of the game, plus 1).
If $move is a valid move number, set the move number to $move and return 1. Return undefined otherwise.
Return
WHITE if white is to move,
BLACK otherwise.
If $colour is
WHITE or
BLACK, set the player to move to $colour and return 1. Return undefined otherwise.
Return a string representing the board position as a GIF (an image in Graphics Interchange Format). The following options can be passed to control the image:
The width of the black border around the chess board, in pixels (defaults to 2).
If true, draw a margin to the left of the board containing rank numbers, and a margin below the board containing file letters (defaults to true).
The height of the margin to draw below the board (containing the file letters), in pixels (defaults to 20). Ignored if the
letters option is false.
The width of the margin to draw to the left of the board (containing the rank numbers), in pixels (defaults to 20). Ignored if the
letters option is false.
A reference to a
GD::Font object describing the font to use to draw the rank numbers and file letters (defaults to
GD::Font::Giant). Ignored if the
letters option is false.
Apply some simple validation tests to the position. Return 1 if the position passes the tests, undefined otherwise. If the position fails to validate, the reason for failure can be found by calling
Games::Chess::errmsg.
These tests are applied:)
Gareth Rees
<garethr@cre.canon.co.uk>.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.