Brian Richardson > Chess > Chess::Board

Download:
Chess-0.6.2.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  3
Open  1
View/Report Bugs
Source  

NAME ^

Chess::Board - an object representation of a chessboard

SYNOPSIS ^

    $light = Chess::Board->get_color('h1');
    $dark = Chess::Board->get_color('a1');
    $e3 = Chess::Board->square_down_from('e4');
    $e5 = Chess::Board->square_up_from('e4');
    $d4 = Chess::Board->square_left_of('e4');
    $f4 = Chess::Board->square_right_of('e4');
    $board = Chess::Board->new();
    $is_valid = Chess::Board->square_is_valid($sq);
    if ($is_valid) {
        $board->set_piece_at($sq, $piece);
        $clone = $board->clone();
        $piece = $clone->get_piece_at($sq);
        $clone->set_piece_at($sq, undef);
        $clone->set_piece_at(Chess::Board->square_up_from($sq), $piece);
    }

DESCRIPTION ^

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

This class forms part of the framework, but it could also be used by itself, even to put objects that aren't subclasses of Chess::Piece on it.

METHODS ^

Construction

new()

Takes no arguments. Returns a blessed Chess::Board object reference. This reference can be used to call any of the methods listed in "Object methods".

    $board = Chess::Board->new();

See also "clone()" to construct a new Chess::Board from an existing one.

Class methods

square_is_valid()

Takes a single scalar parameter with the square to be tested. Returns true if the given square falls within the range a1-h8. Returns false otherwise. It is case-insensitive, though all functions that return squares will return lower-case.

    if (Chess::Board->square_is_valid($sq)) {
         # call method requiring valid square
    }
get_color_of()

Takes a single scalar parameter containing the square whose color is requested. Returns a scalar containing either of the strings 'light' or 'dark'. Returns undef and prints a warning to STDERR (see "DIAGNOSTICS") if the square is not valid.

    $light = Chess::Board->get_color_of("h1");
    $dark = Chess::Board->get_color_of("a1");
square_left_of()

Takes a single scalar parameter containing the square right of the requested square. Returns a string containing the square left of the parameter. Returns undef and prints a warning to STDERR (see "DIAGNOSTICS") if the square is not valid. Returns undef (but doesn't print a warning) if there is no square left of the given square.

    $d4 = Chess::Board->square_left_of("e4");
square_right_of()

Takes a single scalar parameter containing the square left of the requested square. Returns a string containing the square right of the parameter. Returns undef and prints a warning to STDERR (see "DIAGNOSTICS") if the square is not valid. Returns undef (but doesn't print a warning) if there is no square right of the given square.

    $f4 = Chess::Board->square_left_of("e4");
square_up_from()

Takes a single scalar parameter containing the square down from the requested square. Returns a string containing the square up from the parameter. Returns undef and prints a warning to STDERR (see "DIAGNOSTICS") if the square is not valid. Returns undef (but doesn't print a warning) if there is no square up from the given square.

    $e5 = Chess::Board->square_up_from("e4");
square_down_from()

Takes a single scalar parameter containing the square up from the requested square. Returns a string containing the square down from the parameter. Returns undef and prints a warning to STDERR (see "DIAGNOSTICS") if the square is not valid. Returns undef (but doesn't print a warning) if there is no square down from the given square.

    $e3 = Chess::Board->square_down_from("e4");
horz_distance()

Takes a single scalar parameter containing the square to calculate distance from. Returns the horizontal distance in squares between the two points.

vert_distance()

Takes a single scalar parameter containing the square to calculate distance from. Returns the vertical distance in squares between the two points.

squares_in_line()

Takes two scalar parameters containing two distinct endpoints in a line. Returns a list of scalars in lower-case with an entry for each square in that line, or undef if the two endpoints do not define a line. In the case where both squares are the same, will return a list containing that square.

Object methods

clone()

Takes no arguments. Returns a blessed Chess::Board object reference which is identical to the caller object. However, it is a deep copy which allows the clone()'d object to be manipulated separately of the caller object.

line_is_open()

Takes two scalar arguments, valid squares defining the endpoints of a line on the Chess::Board. Returns true if there are no pieces on either of the endpoints, or on any of the intervening squares. Returns false if the line is blocked by one or more pieces, and undef if the two squares do not define endpoints of a line. In the case where both squares are equal, will return true if the square is empty and false otherwise.

get_piece_at()

Takes a single scalar argument containing the square to retrieve the piece from. Returns a scalar representing the piece on that square, or undef if there is none. Returns undef and prints a warning to STDERR (See "DIAGNOSTICS") if the provided square is not valid.

set_piece_at()

Takes two scalar arguments: the square whose piece to set, and a scalar representing the piece to place there. Usually this will be a subclass of Chess::Piece, but could be something else if the board is being used stand-alone. See "DESCRIPTION" in Chess::Piece for more information on using other things as pieces. Sets the piece at that square if the square is valid, and prints a warning to STDERR (see "DIAGNOSTICS") otherwise.

DIAGNOSTICS ^

'q9' is not a valid square

The function which generated this message was called with a square outside the range a1-h8, causing it to return undef. Use the class method "square_is_valid()" to validate the square before passing it to any method requiring a valid square.

Invalid Chess::Board reference

The function which generated this message was passed an invalid Chess::Board reference. Make sure that the function call is passing a reference obtained either from a call to "new()" or to "clone()", and that the reference refers to a defined value.

Can't modify this board. Use Chess::Board->new() instead.

The program contains a reference to a Chess::Board that wasn't obtained through a call to "new()" or "clone()". Make sure that all references have been obtained through these methods.

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.

syntax highlighting: