NAME

Game::Cribbage::Terminal - the cribbage board on a terminal

VERSION

Version 0.17

SYNOPSIS

my $t = Game::Cribbage::Terminal->new;
my $status = $t->start;          # RETURNS the exit status; never exits

Game::Cribbage::Terminal->new(picking => 0)->start;   # type numbers

DESCRIPTION

Everything that knows about a screen, and nothing that knows about the rules: those are Game::Cribbage::Board's. in and out are read-write properties defaulting to STDIN and STDOUT, so a test can hand it a pair of handles and read back exactly what it drew.

start returns and never calls exit. Its return value is the exit status bin/cribbage should use: 0 if you won or quit, 1 if you lost.

PROPERTIES

The following properties are defined in Game::Cribbage::Terminal

board

Property to store the current Game::Cribbage::Board

$game->board;

dealer

Property to store a boolean of whether the current player is the dealer for the current round. If true they are.

$game->dealer;

crib_set

Property to store a boolean of whether the current plays crib is set.

$game->crib_set;

starter_card

Property to store the starter card for the current play.

$game->starter_card;.

FUNCTIONS

The following functions are defined in Game::Cribbage::Terminal

	my $game = Game::Cribbage->new;

	$game->clear_screen;

        $game->print_header("Welcome to terminal Cribbage");

        $game->print_footer("Insert name: ");

        my $name = <STDIN>;

        chomp($name);

        my $board = Game::Cribbage::Board->new();

        $board->add_player(name => 'Bot');
        $board->add_player(name => $name);

        $board->start_game();
/split
        $game->board($board);

	$game->clear_screen;

	$game->reset_cursor();

	$game->split_cards();

	$game->init_draw();

run

exit Game::Cribbage::Terminal->run(@ARGV);

The whole command line program as a class method: parses the options bin/cribbage documents, builds the terminal, plays, and returns the exit status rather than calling exit: 0 if you won or quit, 1 if you lost, 2 for a bad option, with the usage on STDERR. --help prints the usage on STDOUT and returns 0. 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 and off a terminal.

start

Start a new terminal cribbage game. This function setups the Game::Cribbage::Board setting the players and starting the game. It will then call init_game.

$game->start();

init_game

Initialise a new terminal game, clearing the welcome start screen, calling split_cards and then init_draw.

$game->init_game();

init_draw

This is where the main terminal game loop happens. For each new round/draw this function is called recursively. Cards are drawn, discarded and the starter card is set. Hands are played until no cards are left, scores are calculated and we repeat..

$game->init_draw();

end_hands

When all cards have been used in the current draw/round then this end_hands function should be called. It handles the ending of the round and will render to the terminal an overview of the round/draw including all cards and the relevant scores.

$game->end_hands();

play_hand

Contains the logic needed to handle the play of the players hand, aka placing a card or calling go because you cannot play a card.

$game->play_hand();.

split_cards

Contains the logic needed to decide which player goes first as the dealer.

$game->split_cards();

draw_cards

Contains the logic needed to draw player cards so they can then decide which two to discard.

$game->draw_cards();

discard_cards

Contains the logic neeeded to discard two cards from the players and bots hands into the crib.

$game->discard_cards();

starter

Contains the logic needed to select the starter card for the current draw.

$game->starter();

render_card

Contians the logic needed to render a card to the terminal.

$game->render_card($card, $row, $col);

render_opponent_cards

Contains the logic needed to render the opponents cards to the terminal. AKA face down at the top of the screen.

$game->render_opponent_cards($num);

render_player_cards

Contains the logic needed to render the players cards to the terminal. AKA face up at the bottom of the screen.

$game->render_player_cards($cards, $row, $col, $all);

render_run_play

Contains the logic needed to render the current plays run cards. AKA the cards that have been played for the current play in the middle of the screen.

$game->render_run_play;

show_face_down_split

Utility function to render face down cards to the terminal.

$game->show_face_down_split($num, $vertical);

draw_background

Utility function to draw the basic cribbage game, this function calls draw_dealer, draw_crib, draw_starter and reset_cursor. It will render the green background, dealer, crib and starter card to the terminal.

$game->draw_background();

draw_starter

Utility function to draw the starter card to the terminal. If no starter card is set then nothing will be drawn.

$game->draw_starter();

draw_crib

Utility function to draw the crib to the terminal, depending on who is the dealer.

$game->draw_crib();

draw_go

Utitlity function to draw GO to the terminal.

$game->draw_go();

draw_dealer

Utility function to draw the text "Dealer" to the terminal, this will be against the player who is currently the dealer.

$game->draw_dealer();.

draw_scores

Utility function to draw the current scores to the terminal.

$game->draw_scores();

winner

Utility function to draw the winners screen to the terminal at the end of the game.

$game->winner();

clear_screen

Utility function to clear the terminal.

$game->clear_screen();

reset_cursor

Utility function to reset the terminal cursor position.

$game->reset_cursor();

set_cursor_vertical

Utiltiy function to set the vertical position of the terminal cursor.

$game->set_cursor_vertical($y);

set_cursor_horizontal

Utility function to set the horizontal position of the terminal cursor.

$game->set_cursor_horizontal($x);

say

Utility function to print text to the terminal.

$game->say("Hello World", $new_line, $indent, $color, $background);

Utility function to print the header to the terminal

$game->print_header("Print some header text");

Utility function to print the footer to the terminal

$game->print_footer("Print some footer text");

THE PICKER

With a terminal and Term::ReadKey, the two choices that decide a cribbage game are made with the arrow keys instead of by typing a number: the two cards that go to the crib, and the card you play into the count.

The cursor only ever stops on a card you can play. The set it walks comes from "playable_cards", which asks "test_card" in Game::Cribbage::Play about each card in turn, so a card that would take the count past 31 is never a stop and never has to be refused after the fact.

The marks are frames, not colours

Three things need marking at once while discarding, so there are three box frames: light for an ordinary card, double for the one under the cursor, and heavy for a card already chosen for the crib. A mark that is a colour is gone the moment the board is piped into a file, and the suits are already using colour to tell red from black.

The caption is the engine's

"card_line" reads "test_card_score" in Game::Cribbage::Play and reports what it says: the count the card takes you to, whether that is a fifteen or thirty-one, the pair or run it makes and what it pegs. Nothing about the score is worked out here, because a preview that does its own arithmetic is a second implementation of the rules that can disagree with the first.

KEYS AND INPUT

in

out

Read-write handles, defaulting to STDIN and STDOUT. Everything the terminal draws goes through out and every line it reads comes from in, so a test can drive a whole game with a pair of in-memory handles.

picking

Whether the arrow keys are offered. Set it false to type numbers instead; left unset it follows "keys_available".

colour

Whether the escapes that colour the screen are written. Set it either way; left unset it is off when NO_COLOR is set to anything, off when "out" is not a terminal, and on otherwise. The cursor movement that lays the screen out is not colour and is written regardless.

keys_available

Whether a key can be read at all: a keysource, or in being a terminal with Term::ReadKey installed. Term::ReadKey is a recommendation and not a prerequisite, so this is false on a perfectly good installation and the typed prompt is what that installation gets.

enter_raw

leave_raw

The cbreak mode round the picker. Cbreak and not raw, so an interrupt is still an interrupt. leave_raw is safe to call more than once and from a signal handler; "run" calls it from INT, TERM, HUP and after a die, because a program that leaves a terminal in cbreak leaves the shell unusable.

keysource

pending

raw

The seam a test drives the picker through, the pushback queue for an escape sequence that turned out not to be one, and the cbreak state. keysource is a coderef returning one character per call, which is what makes the escape sequence for an arrow key testable: the reader has to ask three times for one key.

read_char

read_key

read_sequence

One character, one named key, and the tail of an escape sequence. read_key returns 'up', 'enter', 'escape' and so on, or the character itself.

read_line

emit

One line in and whatever is handed to it out, both through "in" and "out". Nothing in this module may use print or <STDIN> directly: that is what made the terminal untestable before.

CHOOSING

playable_cards

my $can = $t->playable_cards('player2');    # [ 1, 3, 4 ]

The 1-based positions in that player's hand of the cards that can legally be played into the current count, asked of the engine one card at a time. Empty means a go.

card_line

$t->card_line('player2', 3);
# '7♦️ takes the count to 15 for fifteen, pegging 2'

The caption under the cursor, read from the engine.

pick_card

Runs the picker for one card and returns its 1-based position, or 'go', 'bot' or 'quit'.

pick_discards

Runs the picker for the crib and returns an arrayref of the two 1-based positions chosen, or 'bot' or 'quit'. Enter on a card that is already chosen puts it back.

random_index

my $i = $t->random_index($count);    # 0 .. $count - 1

Every draw this module makes goes through here: the bot's card at the low-card split and the bot's cut for the starter. It exists so a test can pin the draw, and a test must pin it here and not with local *CORE::GLOBAL::rand, which has to be in place before the calling code is compiled and so does nothing at all when a test file sets it after its own use line.

step

my $i = $t->step(\@items, $at, 'right');

The index the cursor lands on. Left and up go back, right, down and tab go on, and both wrap; home and end are the ends. The hand is drawn as one row, so left and up are the same key and so are right and down.

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.