/ 
Game-RoyalUr-0.01
/ Game::RoyalUr::Error

NAME

Game::RoyalUr::Error - why a move of the Royal Game of Ur was refused

VERSION

Version 0.01

SYNOPSIS

$game->play('a2-d2') or do {
    my $error = $game->error;
    print $error->code, ': ', $error->message, "\n";
    # safe_rosette: a piece on a rosette cannot be captured
};

DESCRIPTION

A refusal: which rule a move broke, in a word a program can act on and a sentence a person can read. A refused move is returned and never thrown, and leaves the game exactly as it was.

The codes

game_over

The game has ended.

no_roll

There is no roll to play. Only a game read from a record that carried no seed answers this, when it is asked to play on past the record's end.

bad_move

The text is not a move: not two places with a dash between them.

no_piece

The square named has no piece on it, or the hand is empty.

not_your_piece

The piece belongs to the side not to move.

wrong_distance

The square named is not as far from the piece as the roll.

own_piece

One of the mover's own pieces stands where the piece would land.

safe_rosette

An enemy piece stands where the piece would land, on a rosette, under a rule set in which a rosette protects it.

overshoot

The roll would carry the piece past the end of its route. A piece leaves the board only on the exact roll.

bad_record

A record being replayed does not describe a game that could have been played: its side, its roll or its move at some turn is not what the game has there.

A move can be wrong in more than one way. The first that applies, in the order above, is the one reported.

METHODS

of

my $error = Game::RoyalUr::Error->of('overshoot', roll => 3, from => 'h1');

A refusal with that code and its sentence. Anything after the code is kept as the detail. Croaks on a code that is not one of the ten.

code

The word.

message

The sentence, in English.

detail

A hash reference of whatever is known about the refusal: the roll, the places named, and for bad_record the turn at which the record went wrong.

codes

The ten codes, in the order they are checked.

message_for

my $sentence = Game::RoyalUr::Error->message_for('overshoot');

The sentence for a code, or undef for a word that is not one.

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)