NAME
Game::Terminal::Kit::Keys - one key at a time, by name
VERSION
Version 0.05
SYNOPSIS
use Game::Terminal::Kit::Keys;
my $keys = Game::Terminal::Kit::Keys->new;
$keys->enter_raw or die "no keys here\n";
while (defined(my $key = $keys->read_key)) {
last if $key eq 'q' || $key eq 'escape';
move(-1) if $key eq 'up';
move(+1) if $key eq 'down';
}
$keys->leave_raw;DESCRIPTION
The keyboard of a terminal game. It puts the terminal in a mode where a key arrives as it is pressed, reads one key, and gives it a name: up for the up arrow whichever of its spellings the terminal sent, enter for return or line feed, the character itself for anything printable.
Term::ReadKey is used when it is installed and is never required. Without it, or off a terminal, "keys_available" is false and a game falls back to whole lines with "read_line".
The names
enter, tab, back_tab, backspace, delete, insert, up, down, left, right, home, end, page_up, page_down, interrupt for control-C, eof for control-D, escape for the escape key alone, and unknown for an escape sequence that is none of the above, such as an arrow with a modifier held. Space is a space.
The mode is one in which control-C still raises SIGINT, so interrupt is seen only from a "keysource".
Waiting
"read_key" with no argument waits for a key. With a number of seconds it waits that long and returns undef if none came, which is how a game that moves on its own reads the keyboard between frames. With zero it does not wait at all.
Testing
Give keysource a code reference and no terminal is touched: it is called for each character with the wait as its argument, and returns the character or undef for none. Real escape sequences go through it a character at a time, so a test types "\e[B\r" for down then enter.
ATTRIBUTES
in
The handle keys and lines are read from. STDIN by default.
raw
True between "enter_raw" and "leave_raw".
keysource
A code reference standing in for the keyboard; see "Testing".
pending
Characters read and put back, an array reference, next first.
sleeper
A code reference called with a number of seconds when a wait was asked for and there is no keyboard to wait on. It sleeps by default.
sequence_wait
How long, in seconds, to wait for the rest of an escape sequence before deciding the escape key was pressed on its own. 0.05 by default.
METHODS
names
Every name "read_key" can return for a key that is not printable, sorted.
keys_available
True when single keys can be read: there is a "keysource", or "in" is a terminal and Term::ReadKey loads.
enter_raw
leave_raw
enter_raw starts reading a key at a time and returns the object, or undef when keys are not available. leave_raw gives the terminal back as it was. Either may be called twice. Call leave_raw on every way out, a signal included; Game::Terminal::Kit::Run does.
read_key
my $key = $keys->read_key; # wait for one
my $key = $keys->read_key(0.1); # or undef after a tenth of a secondOne key, as a name or a character; undef when the wait ran out or the input ended.
read_char
read_sequence
unread
read_char returns the next raw character, taking the same wait as "read_key". read_sequence reads what follows an escape character and names it. unread puts characters back to be read next. "read_key" is built from the three.
read_line
my $text = $keys->read_line('Your move: ', \*STDOUT);Leaves key-at-a-time mode, prints the prompt to the handle given if both are given, reads a line, and goes back to key-at-a-time mode if it was in it. The line comes back without the space around it; undef at the end of input.
SEE ALSO
Game::Terminal::Kit, Game::Terminal::Kit::Screen, Term::ReadKey.
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)