NAME
Game::Merrills::Terminal - the game at a prompt, on a drawn board
VERSION
Version 0.02
SYNOPSIS
use Game::Merrills;
use Game::Merrills::Bot;
use Game::Merrills::Terminal;
Game::Merrills::Terminal->new(
game => Game::Merrills->new,
bot => Game::Merrills::Bot->new(level => 3),
human => 'white',
)->start;
DESCRIPTION
Everything in this distribution that reads a handle or writes to one is here. Game::Merrills and the modules under it do no input and no output, and nothing in the engine loads this module: the merrills script does.
The handles are properties. in and out default to STDIN and STDOUT, and a test, or a program that wants the game somewhere else, hands in its own.
The board
The board is drawn as it is on a table: three squares, one inside the next, joined at the middle of each side, with a rank number down the left and a file letter along the bottom.
7 .-----------.-----------.
| | |
6 | .-------W-------. |
| | | | |
5 | | .---.---. | |
| | | | | |
4 .---B---. .---.---.
| | | | | |
3 | | .---.---. | |
| | | | |
2 | .-------.-------. |
| | | | |
1 .-----------.-----------.
a b c d e f g
Beside it stand the two sides, each with the men it has in hand, on the board and lost.
There are three ways it can be drawn:
- painted
-
On a terminal with colour: a wooden board, gold lines, and the men as white and black discs. The men of a closed mill stand on a lighter ground.
- drawn
-
Without colour: the same board in line-drawing characters, white men as hollow discs and black men as solid ones.
- ascii
-
Dashes, bars,
WandB, as above. Every character is plain ASCII, for a terminal or a file that can take nothing else.
Marks
What the last move did is marked on the board, and the marks are shapes, so they are there with colour off as well as on:
(W) the man that just moved, where it landed
(.) the point it left
(x) the point a man was taken from
[W] the point under the cursor, drawn as the move would leave it
{B} a man that could be taken
<W> a part of the move already chosen
With colour on each mark has a ground of its own as well.
Under the board
The last two moves, said in words; each side's mills; whose turn it is and what they are to do; a warning once the game is half way to a draw for want of a mill; a draw offer, if one stands; and the result, once there is one.
Choosing a move with the keys
On a terminal, with Term::ReadKey installed, a move is chosen and not typed. The cursor is on the board itself, on one of the points that can be chosen, and the board is drawn as it would stand if the move were played.
A move is built a step at a time, because a move in this game has up to three parts: the man, the point it goes to, and the man it takes when it closes a mill. At each step only the points that some legal move allows next can be chosen, so no run of choices can end anywhere but on a legal move. The step that decides whether a mill closes shows at once which men could be taken, before anything is committed.
arrows to the nearest point that can be chosen that way
tab, shift-tab round every such point in turn; j and k do the same
a letter, a digit straight to that point, d then 2 for d2
enter, space choose
backspace, escape back a step
h what the bot would play, with the cursor moved to it
u take a move back
t go back to typing
: type one command
q quit
? these, on the screen
Giving up and offering a draw are not on a key, so that a slip of the finger cannot end a game. Type them after :.
Each keystroke draws the whole screen again, so the last two moves are drawn with it, above the board's own lines, and are never wiped by the move that answers them.
Without Term::ReadKey, or off a terminal, moves are typed, and nothing else changes.
Typing
At the prompt, type a move as Game::Merrills::Notation writes it, a number from the moves list, or a command: help lists them. A move that is refused says why and what could be played instead, and the board is not drawn again, so the reason stays on the screen.
undo takes back your last move and, against a bot, the reply to it.
Off a terminal
When the input is not a terminal the screen is not cleared, nothing is painted unless colour is asked for, each line typed is echoed so that a transcript reads as a conversation, and the end of the input ends the game with Bye..
PROPERTIES
game
The Game::Merrills being played. Defaults to a new one.
$terminal->game;
bot
The Game::Merrills::Bot that plays the side the human does not, or a hashref of one for white and one for black. Without one, both sides are typed.
$terminal->bot;
human
Which side is typed: white, black, both for two people at one keyboard, or none for the bots to play each other. Defaults to white.
$terminal->human;
in
The handle read from. Defaults to STDIN.
$terminal->in;
out
The handle written to. Defaults to STDOUT.
$terminal->out;
interactive
Whether the input is a terminal. Worked out from in unless given.
$terminal->interactive;
colour
Whether to paint. On for a terminal unless the NO_COLOR environment variable is set, off otherwise, unless given.
$terminal->colour;
ascii
Whether to keep to plain ASCII. Defaults to false.
$terminal->ascii;
redraw
Whether the board is to be drawn before the next prompt.
$terminal->redraw(1);
highlight
A hashref of extra marks to draw, point number to candidate, takeable, chosen or option, on top of the marks of the last move. An option, a point that could be chosen, has a ground of its own and no brackets.
$terminal->highlight({ 19 => 'candidate' });
recent
An arrayref of the last moves played, in words.
$terminal->recent;
picking
Whether moves are chosen with the keys. On for a terminal that can be read a key at a time, off otherwise, unless given.
$terminal->picking;
raw
Whether the terminal is at present being read a key at a time.
$terminal->raw;
keysource
A coderef that supplies the keys, one character a call and undef when there are no more, in place of the terminal. With one set, the whole of the key handling runs with no terminal at all.
my @keys = split //, "\e[B\r";
my $terminal = Game::Merrills::Terminal->new(keysource => sub { shift @keys });
pending
An arrayref of characters read and put back, to be read again first.
$terminal->pending;
heard
An arrayref of the lines printed since the last command was read, kept so that the answer to a command can be shown again after the screen is cleared.
$terminal->heard;
preview
The Game::Merrills::Board drawn in place of the game's own while a move is being chosen, or undef.
$terminal->preview;
frames
How many times the choosing screen has been drawn.
$terminal->frames;
METHODS
layer
Sets the output handle to carry what the current ascii setting needs. Called whenever that setting changes. Returns the terminal.
$terminal->layer;
run
exit Game::Merrills::Terminal->run(@ARGV);
The whole command line program as a class method: parses the options bin/merrills documents, builds the game and the terminal, plays or replays, and returns the exit status rather than calling exit: 0 if you won, drew or quit, 1 if you lost, 2 for a bad option, a leftover word or a refused value, with the reason and the usage on STDERR. --help and --version print to STDOUT and return 0. Options are read from the arguments passed in, never from @ARGV, and the Getopt configuration the parse needs is restored before it returns. Signal handlers are local to the call and the terminal is left in cooked mode on every way out, so a launcher such as Game::Terminal can call it in its own process and carry on afterwards. Colour is off under NO_COLOR as well as off a terminal.
start
Plays the game until it ends or the input does, and returns the game's result, undef if it was left unfinished.
my $result = $terminal->start;
replay
Shows a written game a move at a time: the board, then each move in words with the board after it. On a terminal it waits for enter before each move and stops at q. The game shown becomes the terminal's game. Returns its result, undef when the record stops short of one. Dies, naming the move, when the record does not play.
$terminal->replay($text);
turns
The loop inside "start": draw, let the bot move or read a line and act on it, until done.
$terminal->turns;
keys_available
True when keys can be read one at a time: a key source was given, or the input is a terminal and Term::ReadKey loads.
$terminal->keys_available;
enter_raw
Starts reading the terminal a key at a time. Returns the terminal, or undef when that cannot be done.
$terminal->enter_raw;
leave_raw
Puts the terminal back to reading whole lines. Returns the terminal.
$terminal->leave_raw;
read_char
One character, from what was put back, the key source or the terminal. Given a true value it waits for one; otherwise it returns undef when none is there.
my $char = $terminal->read_char(1);
read_key
One key. A character comes back as itself and the rest by name: up, down, left, right, home, end, page_up, page_down, enter, tab, back_tab, backspace, escape, interrupt, eof. Returns undef when there are no more.
my $key = $terminal->read_key;
read_sequence
The key that follows an escape character. A character that does not begin a sequence is put back, so a pressed escape does not swallow the next key.
my $key = $terminal->read_sequence;
components
The parts of a move in the order they are chosen, as an arrayref of points: the point left, when there is one, the point landed on, and the man taken, when there is one.
$terminal->components($move);
matching
The legal moves whose parts begin with those given, as an arrayref.
$terminal->matching([ $from ]);
options_for
The points that can be chosen next, given the parts chosen so far: the next part of every legal move that begins with them, each once, in point order.
my $points = $terminal->options_for([ $from, $to ]);
complete
The legal move whose parts are exactly those given, or undef when the move is not finished.
my $move = $terminal->complete([ $from, $to ]);
nearest
The point among some candidates that an arrow key reaches from another: up, down, left or right. A point straight along the row or the file is preferred to a nearer one off to the side. Returns the point started from when there is nothing that way.
my $point = $terminal->nearest($from, 'right', \@candidates);
step_of
Which part is to be chosen next, given the parts chosen so far: from, to or remove.
$terminal->step_of([ $from ]);
pick
Lets the player choose a move with the keys and plays it. Returns an empty string when a move was played, a command when a key asked for one, and undef at the end of the input.
my $line = $terminal->pick;
done_picking
Clears what choosing put on the board. Returns the terminal.
$terminal->done_picking;
show_choice
Draws the choosing screen: the parts chosen, the points that can be chosen, the point under the cursor, and anything to be said.
$terminal->show_choice(\@prefix, \@options, $at, \@notice);
legend
The line naming the keys, at the foot of the choosing screen.
$terminal->legend;
key_lines
What the keys do, as an arrayref of lines.
$terminal->key_lines;
keyed_line
Reads a line a key at a time, echoing it, for a command typed while keys are being read. Returns undef at the end of the input.
my $line = $terminal->keyed_line;
set_picking
Switches between choosing with the keys and typing, for the pick and type commands.
$terminal->set_picking('type');
later
Says a line so that it survives the screen being drawn again: after the board when typing, and on the next choosing screen when choosing.
$terminal->later('Taken back.');
bot_for
The bot that plays a side, or undef.
$terminal->bot_for('black');
bot_plays
True when a side's moves come from a bot and not from the keyboard.
$terminal->bot_plays('black');
bot_move
Has the bot choose and play a move for the side to move. Returns the move.
$terminal->bot_move;
played
Records a move just played: puts it into words, keeps it among the recent moves, and asks for the board to be drawn. Returns the move.
$terminal->played($move);
name_of
What to call a side: You for the human's, its name otherwise.
$terminal->name_of('white');
narrate
A move in words, in the past tense.
$terminal->narrate($move); # 'Black moved f4 to g4, closed a mill and took your man on a1.'
read_line
Prints a prompt and reads a line, without its newline. Returns undef at the end of the input. Takes the prompt, or uses the side to move.
my $line = $terminal->read_line;
say
Prints a line. Returns the terminal.
$terminal->say('Taken back.');
clear
Clears the screen, when the input is a terminal. Returns the terminal.
$terminal->clear;
paint
Text wrapped in the colours named, or the text alone when colour is off.
$terminal->paint('Draw', 'mill');
ink_of
The name of the colour a side is written in.
$terminal->ink_of('white');
render
Clears the screen and draws the board and what goes under it.
$terminal->render;
glyphs
The characters the board is drawn with at the current settings, as a hashref.
$terminal->glyphs->{white};
marks
The marks to draw, as a hashref of point number to kind: those of the last move, with "highlight" on top.
$terminal->marks;
canvas
The board as rows of cells, before any character or colour is chosen.
$terminal->canvas;
board_lines
The board as an arrayref of lines ready to print.
print "$_\n" for @{ $terminal->board_lines };
aside
What stands beside the board, as an arrayref indexed by board row.
$terminal->aside;
mills_of
A side's closed mills, as an arrayref of strings such as a7-d7-g7.
$terminal->mills_of('white');
status_lines
What goes under the board, as an arrayref of lines.
$terminal->status_lines;
command
Acts on a line typed at the prompt. Returns true when it is time to stop.
$terminal->command('d2-d3');
play
Plays a move typed as notation, or says why not.
$terminal->play('d2');
play_number
Plays a move by its number in the moves list.
$terminal->play_number(3);
show_moves
Prints the legal moves, numbered.
$terminal->show_moves;
hint
What the bot would play for the side to move, as a hashref of move and a line to print.
$terminal->hint->{line};
show_hint
Prints the hint.
$terminal->show_hint;
take_back
Takes back the last move, and the reply to it when a bot made one.
$terminal->take_back;
save
Writes the game to a file.
$terminal->save('game.txt');
load
Reads a game from a file and carries on from where it stopped.
$terminal->load('game.txt');
set_level
Sets the strength of the bot.
$terminal->set_level(4);
toggle
Turns ascii or colour over.
$terminal->toggle('ascii');
offer_draw
Offers a draw for the human's side. A bot answers at once, taking it unless it thinks it is ahead.
$terminal->offer_draw;
answer_draw
Accepts or declines a draw that was offered.
$terminal->answer_draw('accept');
resign
Gives the game up for the human's side.
$terminal->resign;
quit
Asks whether to leave an unfinished game. Returns true to stop.
$terminal->quit;
help_lines
The help, as an arrayref of lines.
$terminal->help_lines;
show_help
Prints the help.
$terminal->show_help;
PACKAGE VARIABLES
%COMMAND-
The commands and what each does.
%GLYPH-
The characters for each way of drawing the board.
%INK,%GROUND-
The colours, as terminal codes, for what is written and what it stands on.
%BRACKET-
The pair of characters for each kind of mark.
%SEQUENCE,%CONTROL-
The names of the keys that arrive as an escape sequence or a control character.
%KEY-
The keys that stand for a command while choosing.
CONSTANTS
- PITCH
-
4, the columns from one file to the next.
- WIDTH
-
27, the columns of the board.
- ROWS
-
13, the rows of the board.
- RECENT
-
2, how many moves are kept in words.
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)