/ 
Term-Chess-0.03
/ Term::Chess::Error

NAME

Term::Chess::Error - a refused move: a code, a sentence, and the legal list

VERSION

Version 0.03

SYNOPSIS

my $refusal = $game->play('e2e5');

if ($refusal) {
    say $refusal->code;         # 'not_legal'
    say $refusal->message;      # 'that piece cannot move there'
    say 1 if $refusal->not_legal;
}

DESCRIPTION

A refused move comes back as one of these. It is not thrown: a refused move is an ordinary thing for a player to do, and unwinding the stack for it would make every caller wrap every move in an eval. die is kept for programmer error, which here is a flag that does not exist.

Seven flags, exactly one of them set. The rules of chess themselves are Chess::Plisco's and are never judged here; the flag says why a move that Plisco did not list was refused, from what the board and the list say about the near misses.

ATTRIBUTES

bad_move

Not a move at all: a string Plisco could not read, or a promotion written without its piece where Plisco cannot tell what was meant.

game_over

The game has finished.

not_your_turn

The piece on the from-square belongs to the side not on move.

no_piece

The from-square is empty.

bad_promotion

A pawn move to the last rank with no piece named, or the wrong one.

in_check

The piece can make that move, and only the king forbids it: the side to move is in check and the move leaves it there, or the piece is pinned.

Everything else: the piece does not move that way, or something stands in the road.

error

Always true, so a refusal is true in boolean context and 0 from play means the move was played.

message

One sentence for a person.

The legal moves as coordinates, carried by in_check and not_legal so a caller can list what was possible instead.

METHODS

throw

Term::Chess::Error->throw('not_legal', legal => \@moves);

Builds a refusal with that flag set. Despite the name it returns the object and dies only for a flag that does not exist.

code

The one flag that is set, as a string.

stringify

The message. There is no "" overload on purpose: a refusal that quietly turns into a string hides the code that says what happened.

flags

Every flag, in the order code checks them.

message_for

Term::Chess::Error->message_for('in_check');

The sentence for a flag.

known

Whether a string is a flag.