/ 
Game-Checkers-0.01
/ Game::Checkers::Terminal

NAME

Game::Checkers::Terminal - the game at a prompt

VERSION

Version 0.01

SYNOPSIS

use Game::Checkers;
use Game::Checkers::Bot;
use Game::Checkers::Terminal;

Game::Checkers::Terminal->new(
	game  => Game::Checkers->new,
	bot   => Game::Checkers::Bot->new(level => 3),
	human => 'black',
)->start;

DESCRIPTION

Everything in this distribution that reads a handle or writes to one is here. Game::Checkers and the modules under it do no input and no output at all, and nothing in the engine loads this module: the checkers script does.

The handles are properties. in and out default to STDIN and STDOUT, and a test hands it two in memory filehandles and plays a whole game in process, which is the reason for the split.

start returns the Game::Checkers::Result and never calls exit, so the script owns the exit status.

The board

    a   b   c   d   e   f   g   h
  +---+---+---+---+---+---+---+---+
8 |   | b |   | b |   | b |   | b |  Black 12  (0 kings)
  +---+---+---+---+---+---+---+---+
7 | b |   | b |   | b |   | b |   |  White 12  (0 kings)
  +---+---+---+---+---+---+---+---+
6 |   | b |   | b |   | b |   | b |
  +---+---+---+---+---+---+---+---+
5 | . |   | . |   | . |   | . |   |
  ...

Pieces are the Unicode draughts symbols, or b, B, w and W with "ascii". An empty playing square is a dot: half the board is never played on and the dots are what say which half. Colour is on only when the input is a terminal and NO_COLOR is unset.

Moves and the commands

A move is written as the squares it is on, read off the letters and numbers round the edge: a3-b4 to slide and c3xe5xg7 to jump, with the whole path for a multiple jump. Numeric notation is still accepted, because Game::Checkers::Notation reads both, but nothing here prints it: a saved game is PDN, which is numeric, and the board is not.

A bare number plays that move from the moves list. Everything else is a command: help, moves, hint, board, fen, undo, save FILE, load FILE, level N, flip, ascii, draw, resign and quit. An unknown word is answered and the prompt comes back: the loop never dies on what somebody types, which is what Game::Checkers::Error is for.

The board is drawn again when something changes it, and not otherwise. A list of moves, a hint or a refusal stays on the screen with the prompt under it, rather than being cleared away, or pushed off the top, by a board that is exactly the one already drawn.

End of file on in is a clean quit, so echo | checkers ends instead of spinning.

PROPERTIES

game

Read and write Game::Checkers, a new game by default.

$terminal->game;

bot

Read and write Game::Checkers::Bot, or undef for two people at one keyboard.

$terminal->bot;

human

Read and write string: black or white for a game against the bot, both for hotseat, none to watch two bots play.

$terminal->human;

in, out

Read and write filehandles, STDIN and STDOUT by default. out is given a UTF-8 layer unless "ascii" is set.

$terminal->out;

interactive

Read and write boolean, true when in is a terminal. It decides whether the screen is cleared between moves, so a captured transcript stays readable.

$terminal->interactive;

colour

Read and write boolean. Defaults to on when the session is interactive and NO_COLOR is unset.

$terminal->colour;

ascii

Read and write boolean: letters instead of the Unicode symbols.

$terminal->ascii;

redraw

Read and write boolean: whether the board wants drawing again. "render" clears it and a move, an undo, a load or one of the switches sets it, so the loop only draws a board that has changed.

$terminal->redraw;

flip

Read and write boolean: draw the board from White's side. The square names do not change, because they name the board and not the view of it.

$terminal->flip;

FUNCTIONS

start

Runs the game to its end and returns the result.

my $result = $terminal->start;

render

Draws the board and the status block.

$terminal->render;

board_lines

The board as an arrayref of lines, without their newlines.

$terminal->board_lines;

status_lines

The lines under the board: the last move, whose turn it is and how many moves they have, any draw offer, and the result once there is one.

$terminal->status_lines;

aside

The two lines printed beside the top of the board, one a side, with the piece counts.

$terminal->aside;

cell

The three characters for one square of the board.

$terminal->cell($board, 0, 1);

paint

Wraps text in an ANSI colour, or returns it untouched when colour is off.

$terminal->paint('b', '1;36');

command

Handles one line of input, whether it is a move or a command. Returns true when the game should stop.

$terminal->command('f6-e5');

play

Plays a move written out, and prints why not when it is refused.

$terminal->play('f6-e5');

play_number

Plays a move by its place in the numbered list.

$terminal->play_number(3);

bot_plays

True when the given side belongs to the bot.

$terminal->bot_plays('white');

bot_move

Lets the bot play one move and announces it.

$terminal->bot_move;

read_line

Prints a prompt and reads one line from in, returning undef at end of file.

my $line = $terminal->read_line;

say

Prints one line to out.

$terminal->say('your move');

clear

Clears the screen, but only in an interactive session.

$terminal->clear;

show_moves, show_hint, show_help

The moves, hint and help commands.

$terminal->show_moves;

take_back

The undo command: your last move and the reply to it.

$terminal->take_back;

save, load

The save and load commands, which write and read PDN.

$terminal->save('game.pdn');

set_level

The level command.

$terminal->set_level(4);

toggle

Flips one of the rendering switches by name.

$terminal->toggle('flip');

offer_draw

The draw command. The bot answers from the score it recorded on its last move, taking the draw when it is not better than a third of a man ahead.

$terminal->offer_draw;

resign

The resign command.

$terminal->resign;

quit

The quit command, which asks first when a game is under way.

$terminal->quit;

AUTHOR

LNATION, <email at lnation.org>

BUGS

Please report any bugs or feature requests to bug-game-checkers at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Game-Checkers. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

perldoc Game::Checkers

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)