/ 
Game-Brandubh-0.01
/ Game::Brandubh::Error

NAME

Game::Brandubh::Error - a refusal, returned and never thrown

VERSION

Version 0.01

SYNOPSIS

my $refused = $game->play('a4a7');

if ($refused) {
    print $refused->code, "\n";         # corner_closed
    print $refused->message, "\n";      # only the king may stand on a corner
    print "the corner\n" if $refused->corner_closed;
}

DESCRIPTION

What Game::Brandubh hands back when it will not do what it was asked. It is an object and never a string to match against: ask it which refusal it is with code, or with the accessor of that name.

A refusal is an ordinary thing for a player to cause, so it is returned. Nothing here dies. The game is left exactly as it was.

The refusals

bad_move

The string is not written as a move.

game_over

The game has ended.

not_a_seat

A seat was named that is neither p1 nor p2.

not_your_turn

A seat was named and it is the other seat's move.

no_piece

Nothing stands on the square the move leaves.

not_your_piece

The piece there belongs to the side that is not to move.

no_move

The move leaves a square and arrives on the same one.

not_a_line

The two squares share neither a rank nor a file.

path_blocked

Another piece stands on the way, or on the square to be reached.

throne_closed

The move would stop on the throne, or would cross a throne the rule set does not let it cross.

corner_closed

A piece other than the king would stop on a corner.

no_offer

A draw was accepted or declined when none had been offered.

own_offer

A seat tried to answer the draw it offered itself.

offer_standing

A draw was offered while an offer was already waiting for its answer.

METHODS

throw

my $refusal = Game::Brandubh::Error->throw('path_blocked', move => 'd1d3');

Makes a refusal. Despite the name it returns the object; the name is the one the sibling distributions use. move is optional and is kept as given. Croaks on a name that is not one of the refusals, because that is a mistake in the caller and not something a player did.

A refusal is made by throw and by nothing else: new croaks unless exactly one refusal is named.

code

The name of the refusal, one of the list above.

message

A sentence in English saying what was wrong.

move

The move that was refused, as it was given, when there was one.

bad_move

game_over

not_a_seat

not_your_turn

no_piece

not_your_piece

no_move

not_a_line

path_blocked

throne_closed

corner_closed

no_offer

own_offer

offer_standing

True on the refusal of that name and false on every other.

flags

my @names = Game::Brandubh::Error->flags;

The names of all the refusals.

message_for

my $sentence = Game::Brandubh::Error->message_for('no_piece');

The sentence for a name, or undef for a name that is not a refusal.

known

if (Game::Brandubh::Error->known($name)) { ... }

True when the name is one of the refusals.

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)