text.console - Text terminal control ¶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.
{text.console}
Represents a vt100-compatible terminal. An instance of this class
can be passed to the “console” argument of the following generic
functions.
<vt100>: iport ¶Input port connected to the terminal. The default value is the standard input port.
<vt100>: oport ¶Output port connected to the terminal. The default value is the standard output port.
<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).
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.
has-windows-console? returns true, create <windows-console>
instance.
You don’t need cond-expand; has-windows-console? returns
#f on non-Windows platforms.
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.)
The following procedure packages this flow.
{text.console}
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.
{text.console}
Given the string value of the environment variable TERM,
returns #t if the terminal can be handled by <vt100> console,
#f otherwise.
{text.console}
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. See gauche.termios - Terminal control, for the details.)
If proc raises an unhandled error, this generic function resets the terminal mode before returning. It does not clear the screen.
{text.console}
Display a character at the current cursor position, and
move the current cursor position.
{text.console}
Display a string from the current cursor position, and
move the current cursor position.
{text.console}
Ring the beep, or flash the screen (visible bell) if possible.
{text.console}
Fetch a keypress from the console. This blocks until
any key is pressed.
The return value may be one of the following values:
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 a special key; the following keys are supported:
KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT,
KEY_HOME, KEY_END, KEY_INS, KEY_DEL,
KEY_PGDN, KEY_PGUP, KEY_F1, KEY_F2,
KEY_F3, KEY_F4, KEY_F5, KEY_F6,
KEY_F7, KEY_F8, KEY_F9, KEY_F10,
KEY_F11, KEY_F12.
(Note: DELETE key is usually mapped to #\x7f, but it depends on
the terminal).
ALT and a character.Indicates the character key is pressed with Alt key. For example,
if the user presses Alt-a, (ALT #\a) is returned.
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.
{text.console}
Returns true if there’s a key sequence to be read in the console’s
input.
{text.console}
Returns two values, the current cursor’s x and y position.
The top-left corner is (0,0).
{text.console}
Move cursor to the specified position. The top-left corner is (0,0).
{text.console}
Reset terminal. Usually this sets the
character attributes to the default,
clears the screen, and moves the cursor to (0, 0).
{text.console}
Clear entire screen.
{text.console}
Clear characters from the current cursor position to the
end of the line.
{text.console}
Clear characters from the current cursor position to the
end of the screen.
{text.console}
Hide/show the cursor.
{text.console}
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.
{text.console}
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.
{text.console}
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.
{text.console}
Set the console so that the subsequent characters will be written
with attributes specified by attr.
The character attributes spec is a list in the following format:
(<fgcolor> [<bgcolor> . <option> ...])
where:
<fgcolor> : <color> | #f ; #f means default <bgcolor> : <color> | #f <color> : black | red | green | yellow | blue | magenta | cyan | white <option> : bright | reverse | underscore
For example, you can set characters to be written in red with black background and underscore, you can call:
(set-character-attribute con '(red black underscore))
That the options may seem rather limited in the age of full-color bitmap displays. That’s what it used to be, young lads.
{text.console}
Reset character attributes to the default.
{text.console}
Sets the console’s attributes to attr and calls thunk,
then resets the attributes. Even if thunk throws an error,
attributes are reset.
See set-character-attribute above for the form of attr.
Note: You should be able to nest this, but currently nesting
isn’t working. The end of innermost with-character-attribute
resets the attributes.