/ 
Game-Go-0.01
/ Game::Go::Error

NAME

Game::Go::Error - a flagged rejection, returned and never thrown

VERSION

Version 0.01

SYNOPSIS

my $move = $game->play('b', $pt);

if (ref $move eq 'Game::Go::Error') {
    say $move->message;      # "the ko rule forbids retaking that point..."
    say $move->code;         # "is_ko"
    say 1 if $move->is_ko;
}

DESCRIPTION

A refused move comes back as one of these. It is not thrown, and that is a decision rather than an oversight: 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: a bad board size, a flag that does not exist, an engine code with no name.

ATTRIBUTES

not_your_turn

game_over

off_board

point_taken

is_ko

is_suicide

is_repeat

not_marking

still_marking

alive_chain

not_a_chain

bad_colour

One accessor per reason, true on the one that applies and false on the rest.

alive_chain is the confirmation phase's veto. A chain that Benson's algorithm finds unconditionally alive is alive even if its owner never answers another move, so no agreement between the players can make it dead, and the attempt is refused rather than negotiated.

is_ko and is_repeat are both repetition rules and they stay separate. The first is Article 6 and is the sentence a Go player expects; the second is the positional superko amendment, and telling a player their move "repeats a position" when what happened was a ko would be a worse answer than no answer.

error

Always 1. It is there so that a caller holding something which may be a move or may be a refusal can ask one question of either.

message

The sentence for the flag, as a player should be shown it.

The legal alternatives where offering them helps. An arrayref even when empty, because the normal case is a caller dereferencing it without checking.

METHODS

throw

Game::Go::Error->throw('is_ko', legal => \@points)

Returns the error. It does not die. The name is the house's.

Dies only if the flag does not exist, which is programmer error.

from_code

Game::Go::Error->from_code(3)

The error for a refusal code from the C engine. Dies if the code has no flag, which is how a code added to the ABI without a name here is found immediately rather than becoming an unexplained failure somewhere downstream.

code

The flag that is set, as a string, or undef.

flags

Every flag that is set, as an arrayref. There is normally one.

stringify

The message.

SEE ALSO

Game::Go, Game::Go::Rules.

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)