/ 
Game-Dominoes-0.01
/ Game::Dominoes::Error

NAME

Game::Dominoes::Error - why a move was refused

VERSION

Version 0.01

SYNOPSIS

my $out = $game->play(1, '6-4@L');

if (ref $out eq 'Game::Dominoes::Error') {
    $out->code;       # 'tile_not_held'
    $out->message;    # 'you do not hold that tile'
}

DESCRIPTION

Returned, never thrown. Every rejection a player can cause comes back as one of these, so a caller tests the return value and never has to wrap a play in an eval. die is kept for programmer error: a seat that does not exist, a face outside 0 to 6, a variant nobody defined.

One flag is set per error. The flag is the thing to switch on, and P2PGames::Game::Dominoes maps it onto a P2PGames::Game::Illegal code through one table, so nothing engine-shaped escapes into the site.

This is the shape Game::Cribbage::Error and Game::Checkers::Error use.

PROPERTIES

error

$error->error;   # always 1

There so that a caller with a value that is either a result or an error can ask one question about it.

message

$error->message;

The sentence for a person, already filled in from the flag.

$error->legal;

What the seat could have done instead, when saying so is cheap. An arrayref, empty by default.

not_your_turn, tile_not_held, end_mismatch, no_such_arm, arm_closed, game_over, bad_move

The flags. Exactly one is set, and every one of them is reachable from a real refusal, which t/11-legal.t asserts one at a time.

There is no flag for drawing or passing wrongly, and none for playing between hands, because Game::Dominoes resolves a forced turn itself: drawing is never a move a caller makes, so it can never be refused, and a hand boundary is crossed inside the play that causes it.

FUNCTIONS

throw

return Game::Dominoes::Error->throw('tile_not_held');

Returns the error. The name is kept from the classes this follows, and it is a lie about the control flow on purpose: renaming it would break the shape every other engine here uses. Dies only if the flag does not exist, which is a typo in the engine and not a move.

code

$error->code;   # 'tile_not_held'

The one flag that is set.

flags

Game::Dominoes::Error->flags;

Every flag this class can carry, as an arrayref, so a test can assert that each one is reachable from a real refusal.

stringify

$error->stringify;   # 'tile_not_held: you do not hold that tile'

SEE ALSO

Game::Dominoes, which returns these.

AUTHOR

LNATION <email@lnation.org>

BUGS

Please report any bugs or feature requests to bug-game-dominoes at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Game-Dominoes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Game::Dominoes::Error

ACKNOWLEDGEMENTS

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)