view release on metacpan or  search on metacpan

lib/Chess/Board.pm  view on Meta::CPAN

C<undef> and prints a warning to STDERR (see L</"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");

=item 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
C<undef> and prints a warning to STDERR (see L</"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");

=item 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
C<undef> and prints a warning to STDERR (see L</"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");

=item horz_distance()

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

=item vert_distance()

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

=item 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 C<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.

=back

=head2 Object methods

=over 4

=item clone()

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

=item 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 C<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.

=item 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 C<undef> if 
there is none. Returns C<undef> and prints a warning to STDERR (See
L</"DIAGNOSTICS">) if the provided square is not valid.

=item 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
C<Chess::Piece>, but could be something else if the board is being used
stand-alone. See L<Chess::Piece/"DESCRIPTION"> 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 L</"DIAGNOSTICS">) otherwise.

=back

=head1 DIAGNOSTICS

=over 4

=item '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 C<undef>. Use the class method 
L</"square_is_valid()"> to validate the square before passing it to any
method requiring a valid square.

=item 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 L</"new()"> or to L</"clone()">, and that the reference 
refers to a defined value.

=item 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 L</"new()"> or L</"clone()">. Make sure that all references have
been obtained through these methods.

=back

=head1 BUGS

Please report any bugs to the author.

=head1 AUTHOR

Brian Richardson <bjr@cpan.org>

=head1 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.