NAME

Chess::Piece - a base class for chess pieces

SYNOPSIS

    $piece = Chess::Piece->new("e2", "white", "White King's pawn");
    $piece->set_current_square("e4");
    $e4 = $piece->get_current_square();
    $piece->set_description("My Piece");
    $description = $piece->get_description();
    $color = $piece->get_color();
    if (!$piece->moved()) {
	# do something with the unmoved piece
    }
    $piece->set_moved(1);
    if ($piece->threatened()) {
	# do something with the threatened piece
    }
    $piece->set_threatened(1);
    if ($piece->captured()) {
	# do something with the captured piece
    }
    $piece->set_captured(1);

DESCRIPTION

The Chess module provides a framework for writing chess programs with Perl.

This class represents the parent class for all Chess pieces, and contains accessors and mutators for all the common properties of chess pieces. The following is an exhaustive list of the properties of a Chess::Piece:

* initial square (read-only, specified at construction)
* color (read-only, specified at construction)
* current square
* description
* a flag indicating whether or not the piece has moved
* a flag indicating whether or not the piece is threatened
* a flag indicating whether or not the piece was captured

See "METHODS" for details of the methods which manipulate and return these properties.

METHODS

Construction

new()

Constructs a new Chess::Piece. Requires a two scalar arguments containing the initial square this piece is on and the color of the piece. If the program will use colors other than 'black' and 'white', then subclasses of Chess::Piece will need to override the "can_reach()" method to take these colors into account. Optionally takes a third argument containing a text description of the piece. Returns a blessed Chess::Piece object reference that can be used to call any of the methods listed in "Object methods". The square is not tested for validity, so the program must validate the square before calling new().

$piece = Chess::Piece->new("e2", "white");
$piece = Chess::Piece->new("e2", "white", "White King's pawn");

See also "clone" to construct a new Chess::Piece from an existing one.

Class methods

There are no class methods for this class.

Object methods

clone()

Clones an existing Chess::Piece. Requires no arguments. Returns a blessed Chess::Piece object reference which has data identical to the cloned piece, but can be manipulated separately.

$clone = $piece->clone();
$clone->set_description("Cloned piece");

get_initial_square()

Takes no parameters. Returns the initial square property that the piece was constructed with.

get_current_square()

Takes no parameters. Returns the value of the current square property.

set_current_square()

Takes a single scalar parameter containing the current square of this piece. Sets the current square property to this value. Like "new()", this square is not tested for validity and should be tested before calling the function.

get_description()

Takes no parameters. Returns the value of the description property.

set_description()

Takes a single scalar parameter containing a description for the piece. Sets the description property to this value.

get_color()

Takes no parameters. Returns the color property the piece was constructed with.

moved()

Takes no parameters. Returns true iff the piece has not been moved (as determined by a call to "set_moved()").

set_moved()

Takes a single scalar parameter containing true or false. Sets the moved flag if the parameter is true.

threatened()

Takes no parameters. Returns true iff the piece is not threatened (as determined by a call to "set_threatened()").

set_threatened()

Takes a single scalar parameter containing true or false. Sets the threatened flag if the parameter is true.

captured()

Takes no parameters. Returns true iff the piece is not captured (as determined by a call to "set_captured()"

set_captured()

Takes a single scalar parameter containing true or false. Sets the captured flag, and also sets the current square property to undef, if the parameter is true.

can_reach()

Takes a single scalar parameter containing the square to be tested. Returns true if the piece can reach the given square from its current location, as determined by a call to the abstract method "reachable_squares()".

reachable_squares()

This is an abstract method and must be overridden in all subclasses of Chess::Piece. Returns a list of squares (in lower-case) that the piece can reach. This list is used by "can_reach()" and various methods of Chess::Game to determine legality of moves and other high-level analyses. Thus, subclasses of Chess::Piece not provided by this framework must return all squares that may be reached, regardless of the current state of the board. The "is_move_legal()" in Chess::Game method will then determine if all conditions for a particular move have been met.

DIAGNOSTICS

Missing argument to Chess::Piece::new()

The initial square argument is required. See "new()" for details on how to call this method.

Invalid Chess::Piece reference

The program uses a reference which is undefined, or was obtained without using "new()" or "clone()". Ensure that the program only obtains its references from new() or clone() and that the reference refers to a defined value.

Call to abstract method Chess::Piece::reachable_squares()

The "reachable_squares()" function is abstract. Any class which subclasses Chess::Piece must provide its own implementation of this method.

BUGS

Please report any 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.