12.48 text.console - Text terminal control

Module: text.console

This module provides a simple interface for character terminal control.
Currently we support vt100 compatible terminals and Windows
console.

This module doesn’t depend on external library such as curses
and works with Gauche alone, but
what it can do is limited; for example, you can’t get an event
when shift key alone is pressed. For finer controls, you need
some extension libraries.

For an example of the features in this module, see
snake.scm in the examples directory of Gauche source distribution.

Console objects

Class: <vt100>

Represents a vt100-compatible terminal. An instance of this class
can be passed to the “console” argument of the following generic
functions.

Instance Variable of <vt100>: iport

Input port connected to the terminal. The default value is
the standard input port.

Instance Variable of <vt100>: oport

Output port connected to the terminal. The default value is
the standard output port.

Instance Variable of <vt100>: input-delay

The terminal send back special keys encoded in an input escape sequence.
In order to distinguish such keys from the actual ESC key, we time the
input—if the subsequent input doesn’t come within input-delay
microseconds, we interpret the input as individual keystroke, rather
than a part of an escape sequence. The default value is 1000 (1ms).

Class: <windows-console>

Represents Windows console. This class is defined on all platforms,
but its useful methods are only available on Windows-native runtime.

It doesn’t have public slots.

The application has to check the runtime to see what kind of console
is available. A suggested flow is as follows.

Check the environment variable TERM. If it is set and
satisfies vt100-compatible?, you can create
<vt100> instance.
(Note: It is possible that you end up using <vt100> console
on Windows; e.g. gosh running on MSYS shell.)

Otherwise, console isn’t available.

The following procedure packages this flow.

Function: make-default-console:key if-not-available

Determines a suitable console class of the running process and
returns its instance.

If no suitable console is available, the behavior depends on the
if-not-available keyword argument. If it is :error,
which is default, an error is signalled. If it is #f,
the procedure returns #f.

Function: vt100-compatible?string

Given the string value of the environment variable TERM,
returns #t if the terminal can be handled by <vt100> console,
#f otherwise.

Console control

Generic function: call-with-consoleconsole proc :key mode

Takes over the control of the console, and calls proc with
console as the only argument. The console is set to
the mode, which must be a symbol with-terminal-mode
accepts: raw, rare or cooked. By default
the console is set to rare mode, which turn off the echoing
and passes most of keystrokes to the program, but it intercepts
terminal controls (like Ctrl-C for interrupt and
Ctrl-Z for suspend; the actual key depends on terminal
settings, though.)

If proc raises an unhandled error, this generic function
resets the terminal mode before returning. It does not clear
the screen.

Generic function: putchconsole char

Display a character at the current cursor position, and
move the current cursor position.

Generic function: putstrconsole string

Display a string from the current cursor position, and
move the current cursor position.

Generic function: beepconsole

Ring the beep, or flash the screen (visible bell) if possible.

Generic function: getchconsole

Fetch a keypress from the console. This blocks until
any key is pressed.

The return value may be one of the following values:

A character

A key for the character is pressed. It may be a control code
if the control key is pressed with the key; that is, if the user
presses Ctrl-A, #\x01 will be returned.

Indicates the character key is pressed with Alt key. For example,
if the user presses Alt-a, (ALT #\a) is returned (assuming
CAPSLOCK is off).

EOF

Indicates the input is closed somehow.

Modifier keys except ALT are not treated separately but
included in the returned keycode. Assuming CAPSLOCK is off,
if the user press a, Shift+a, and Ctrl+a,
the returned value is #\a, #\A and #\x01, respectively.
Ctrl+Shift+a can’t be distinguished from
Ctrl+a. ALT+a, ALT+Shift+a,
and ALT+Ctrl+a will be (ALT #\a),
(ALT #\A) and (ALT #\x01), respectively.

Generic function: chready?console

Returns true if there’s a key sequence to be read in the console’s
input.

Generic function: query-cursor-positionconsole

Returns two values, the current cursor’s x and y position.
The top-left corner is (0,0).

Generic function: move-cursor-toconsole row column

Move cursor to the specified position. The top-left corner is (0,0).

Generic function: reset-terminalconsole

Reset terminal. Usually this sets the
character attributes to the default,
clears the screen, and moves the cursor to (0, 0).

Generic function: clear-screenconsole

Clear entire screen.

Generic function: clear-to-eolconsole

Clear characters from the current cursor position to the
end of the line.

Generic function: clear-to-eosconsole

Clear characters from the current cursor position to the
end of the screen.

Generic function: hide-cursorconsole

Generic function: show-cursorconsole

Hide/show the cursor.

Generic function: cursor-down/scroll-upconsole

If the cursor is at the bottom line of the screen,
scroll up the contents and clear the bottom line; the cursor stays
the same position. If the cursor is not at the bottom line of
the screen, move the cursor down.

Generic function: cursor-up/scroll-downconsole

If the cursor is at the top line of the screen,
scroll down the contents and clear the top line; the cursor stays
the same position. If the cursor is not at the top line of
the screen, move the cursor up.

Generic function: query-screen-sizeconsole

Returns two values, the width and height of the screen.

Note: This may affect what’s shown in the console.
It is recommended that you only call this before redrawing
the entire screen and save the result.

Generic function: set-character-attributeconsole spec

Set the console so that the subsequent characters will be written
with attributes specified by spec.