For Gauche 0.9.5


Next: , Previous: , Up: Library modules - Utilities   [Contents][Index]

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.

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-console console 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: putch console char

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

Generic function: putstr console string

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

Generic function: beep console

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

Generic function: getch 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 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.

A symbol

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).

A list of symbol 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 (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-position console

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

Generic function: move-cursor-to console row column

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

Generic function: reset-terminal console

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

Generic function: clear-screen console

Clear entire screen.

Generic function: clear-to-eol console

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

Generic function: clear-to-eos console

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

Generic function: hide-cursor console
Generic function: show-cursor console

Hide/show the cursor.

Generic function: cursor-down/scroll-up 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.

Generic function: cursor-up/scroll-down 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.

Generic function: query-screen-size 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.

Generic function: set-character-attribute console spec

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

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.

Generic function: reset-character-attribute console

Reset character attributes to the default.

Generic function: with-character-attribute console attrs thunk

Sets the console’s attributes to attrs and calls thunk, then restores the attributes. Even if thunk throws an error, attributes are restored.

Note: You should be able to nest this, but currently nesting isn’t working.


Next: , Previous: , Up: Library modules - Utilities   [Contents][Index]