NAME
Game::Terminal::Kit::History - take a turn back, and play it again
VERSION
Version 0.05
SYNOPSIS
use Game::Terminal::Kit::History;
my $history = Game::Terminal::Kit::History->new(
save => sub { my ($game) = @_; $game->to_text },
load => sub { my ($text) = @_; Game::Reversi->from_text($text) },
);
$history->start($game);
while (!$game->over) {
$history->turn($game) if $self->is_person($game->turn);
...
if ($key eq 'u' and my $earlier = $history->undo) {
$self->game($earlier);
}
if ($key eq 'r' and my $later = $history->redo) {
$self->game($later);
}
}DESCRIPTION
Undo and redo for a game played at a terminal, kept in a State::Store.
What is kept
The game itself is never kept: a game engine changes as it is played, and a version kept in a history must not. What is kept is the game written as a string by save, and what comes back from "undo" and "redo" is a new game built from that string by load. A string cannot change once kept, and a string the same as the last one kept is no change, so recording a game nobody has moved makes no step.
save must write everything the game needs to play on as it would have: the position, whose turn it is, the moves where a rule depends on them, and the seed and counters its dice and deals come from. load must build a game that save writes the same string for.
What a step is
A step is whatever the game records between two calls of "record". A game records when the turn passes to the person at the keys, so one undo takes back that person's move and every reply the program made to it. In a game two people play at one keyboard, every move is a step.
A move made after an undo throws away what could have been redone.
ATTRIBUTES
save
A code reference given the game and returning it as a string. Needed.
load
A code reference given a string from save and returning a new game. Needed.
limit
The most steps kept to undo; 200 by default. The oldest is forgotten when one more is made. 0 keeps every step.
store
The State::Store underneath, made in new unless one is given.
METHODS
start
$history->start($game);The game as it starts, or as it is when loaded: it becomes the current version, and there is nothing to undo or redo. Returns the history.
record
$history->record($game);The game as it is now, as a new step, unless it is the same as the last one kept. Returns the history. Dies naming the game's class when save gives back anything but a string.
undo
my $game = $history->undo;
my $game = $history->undo($steps);A new game, built as it was one step back, or that many steps back, or as far back as there is; undef when there is no step to take. Only one game is built, however many steps are taken. Dies when load gives back nothing, rather than look like a history with no step to take: a load that returns a list must be called so that the game comes first.
redo
my $game = $history->redo;
my $game = $history->redo($steps);The same, forwards again.
can_undo
can_redo
undo_count
redo_count
Whether there is a step to take back or forward, and how many.
turn
$history->turn($game);What a game calls when the turn passes to the person at the keys. The first call after "start" makes that position the beginning, so a move the program made before the person had a turn is never a step to take back; every later call is "record". Returns the history.
begun
True once "turn" has been called since "start".
text
The current version, as the string save wrote.
clear
Forgets every step both ways and keeps the current version. Returns the history.
game_keys
my $picker = Game::Terminal::Kit::Picker->new(
game_keys => { %{ $history->game_keys }, '?' => 'help' },
...
);u for undo and r for redo, as a hash reference for a picker.
legend
'u undo, r redo'The keys that do something now, for the line under a board: empty at the start of a game, u undo once there is a step, and r redo after one has been taken back.
SEE ALSO
State::Store, Game::Terminal::Kit, Game::Terminal::Kit::Picker.
AUTHOR
LNATION, <email at lnation.org>
LICENSE AND COPYRIGHT
This software is Copyright (c) 2026 by LNATION.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)