15 RRLL: Terminal I/O

8.10

contents ← prev up next →

15 RRLL: Terminal I/O

Dominik Pantůček <dominik.pantucek@trustica.cz>

Racket Rogue-Like Library: Local and Network Virtual Terminal

Unified interface for local and network virtual terminals.

(require rrll/term)

package: rrll-term

This module provides all bindings from rrll/term/private/ansi-output.

It provides make-tty from rrll/term/private/tty, make-nvt and nvt-tcp-accet from rrll/term/private/nvt and term-resize? and struct term-size bindings from rrll/term/private/size.

syntax
(with-term term body ...)

Uses parameterize on current-input-port, current-output-port and current-term and sets them to term. The body ... expressions are evaluated within the new context.

The current-term parameter is internal to this module only.

procedure
(get-term-size [term]) →
(or/c fixnum? #f) (or/c fixnum? #f)
term : term-base? = (current-term)

Returns the size in character cells of the currently used terminal.

procedure
(enable-term-read-resize! [term]) → void?
term : term-base? = (current-term)

Enables returning terminal resize events with read.

procedure
(disable-term-read-resize! [term]) → void?
term : term-base? = (current-term)

Disables returning terminal resize events with read.

procedure
(get-mouse-pos [term]) →
(or/c fixnum? #f) (or/c fixnum? #f)
term : term-base? = (current-term)

Returns current mouse position if known - #fs otherwise.

procedure
(get-term-width [term]) → fixnum?
term : term-base? = (current-term)

Returns the number of columns of given terminal.

procedure
(get-term-height [term]) → fixnum?
term : term-base? = (current-term)

Returns the number of lines of given terminal.

15.1 ANSI Terminal Output

(require rrll/term/private/ansi-output)

package: rrll-term

This module contains various utility functions for directly altering the state of connected ANSI terminal.

procedure
(hide-cursor out) → void?
out : (current-output-port)

Hides the terminal text cursor.

procedure
(show-cursor out) → void?
out : (current-output-port)

Shows the terminal text cursor.

procedure
(clrscr out) → void?
out : (current-output-port)

Clears the terminal screen.

procedure
(gotoxy x y out) → void?
  x : fixnum?
  y : fixnum?
  out : (current-output-port)

Moves the cursor at specified location. The upper left corner has both coordinates 0.

procedure
(enable-alternate-screen out) → void?
out : (current-output-port)

Switches the terminal to alternate screen.

procedure
(disable-alternate-screen out) → void?
out : (current-output-port)

Switches the terminal back to normal screen.

procedure
(enable-mouse out) → void?
out : (current-output-port)

Turns on mouse events reporting.

procedure
(disable-mouse out) → void?
out : (current-output-port)

Turns off mouse events reporting.

procedure
(set-window-title title out) → void?
title : string?
out : (current-output-port)

Sets terminal window title to given string.

15.2 TTY

(require rrll/term/private/tty)

package: rrll-term

Local terminal representation.

procedure
(make-tty [ in
out
#:size-poll-interval size-poll-interval]) → tty?
  in : input-port? = (current-input-port)
  out : output-port? = (current-output-port)
  size-poll-interval : fixnum? = 1

Creates new TTY terminal from given input and output ports and sets it to raw input mode. Currently can work only with the terminal the program was started with - as the underlying term/termios operations are performed on fixed port descriptor numbers.

Because lack of support for signals (especially SIGWINCH), the terminal is periodically queried for any size changes and the interval between these polls can be set using size-poll-interval.

15.3 NVT - TELNET

(require rrll/term/private/nvt)

package: rrll-term

Network virtual terminal representation.

procedure
(make-nvt in out) → nvt?
in : input-port?
out : output-port?

Creates a new NVT from provided ports and negotiates raw input and output mode.

procedure
(nvt-tcp-accept tcp-listen-socket) → nvt?
tcp-listen-socket : tcp-listener?

Performs tcp-accept and creates new NVT from the ports returned.

15.4 NVT Options Storage

(require rrll/term/private/nvt-options)

package: rrll-term

Handling of NVT options on both sides of the connection.

value
nvt-code-names : hash?

The following NVT codes are provided:

IAC		#xff
DONT		#xfe
DO		#xfd
WONT		#xfc
WILL		#xfb
SB		#xfa
GA		#xf9
EL		#xf8
EC		#xf7
AYT		#xf6
AO		#xf5
IP		#xf4
BRK		#xf3
DM		#xf2
NOP		#xf1
SE		#xf0
LINEMODE		#x22
NAWS		#x1f
TTYPE		#x18
SGA		#x3
ECHO		#x1
BINARY		#x0

procedure
(set-nvt-option options action option) → hash?
  options : hash?
  action : byte?
  option : byte?

Maps given option to symbolic name and in options it sets given key to #t or #f based on action interpretation.

procedure
(set-nvt-option! options action option) → void?
  options : hash?
  action : byte?
  option : byte?

Like set-nvt-option but modifies options in place.

procedure
(format-nvt-options options) → string?
options : hash?

Returns human-readable version of NVT options stored in options hash. It performs the binary to text mapping using nvt-code-names lookup table.

procedure
(nvt-option-bytes action option) → bytes?
action : byte?
option : byte?

Returns a 3-byte sequence that can be sent directly to the remote NVT.

15.5 Terminal Size and Resize Reporting

(require rrll/term/private/size)

package: rrll-term

This module unifies size and resize reporting for any terminal implementation.

struct
(struct term-size (columns lines))
columns : fixnum?
lines : fixnum?

Stores the rectangular dimensions of terminal screen.

struct
(struct term-resize term-size ())

The same as term-size but used in input streams.

15.6 Terminal Base

(require rrll/term/private/base)

package: rrll-term

Provides basic facilities to implement a terminal backend.

struct
(struct term-base ( in
out
[size #:mutable]
[read-size? #:mutable]
mouse))
  in : input-port?
  out : output-port?
  size : (or/c #f term-size?)
  read-size? : boolean?
  mouse : mouse-status?

All terminals must be derived from this structs. Provides unified resizing and mouse reporting.

procedure
(do-term-resize! tb new-columns new-lines) → void?
  tb : term-base?
  new-columns : fixnum?
  new-lines : fixnum?

Performs terminal resize - if anything changed. If the resize took place and the terminal’s read-size? is #t, queues resize event in its input port.

15.7 Terminal Resources Garbage Collection

(require rrll/term/private/cleanup)

package: rrll-term

This module runs a thread that performs cleanup after garbage collected terminals.

value
term-will-executor : will-executor?

All terminals must register with this executor to ensure release of their resources upon garbage collection.

15.8 Foreign Function Interface Struct Size Detection

(require rrll/term/private/ffi-struct-size)
	package: rrll-term

This module is used by rrll/term/private/termios and rrll/term/private/tiocgwinsz to allocate memory properly.

procedure
(ffi-detect-struct-size procs [size]) → fixnum?
procs : (listof (-> cpointer? any/c))
size : fixnum? = 1024

Detects size of buffer by filling it with 0’s and 255’s and for both cases checking difference after running each of procs. The maximum offset detected + 1 is returned.

procedure
(cached-ffi-detect-struct-size procs [size]) → fixnum?
procs : (listof (-> cpointer? any/c))
size : fixnum? = 1024

Cached (lazy-evaluated) version of ffi-detect-struct-size.

15.9 Low-Level Termios Interface

(require rrll/term/private/termios)

package: rrll-term

This module allows direct manipulation of program TTY descriptors. It is used by rrll/term/private/tty to put the terminal into a raw mode.

procedure
(termios? termios) → boolean?
termios : any/c

Returns true if given termios is termios wrapped structure.

procedure
(termios-get) → termios?

Shorthand for getting current struct termios with memory allocation.

procedure
(termios-load termios) → void?
termios : termios?

Loads struct termios on stdin from given buffer.

procedure
(termios-copy termios) → termios?
termios : termios?

Creates copy of given struct termios.

procedure
(termios-make-raw! termios) → void?
termios : termios?

Sets given struct termios up to make it a raw terminal device.

15.10 TTY Window Size I/O Control

(require rrll/term/private/tiocgwinsz)

package: rrll-term

procedure
(tiocgwinsz) →
fixnum? fixnum?

Uses ioctl on system terminal to get window structure and extracts its size in character cells.

Falls back to 80x24.

15.11 Queue Input Port

(require rrll/term/private/queue-port)

package: rrll-term

An implementation of input port with queue-like semantics of adding more data to it.

procedure
(make-queue-port [name]) → input-port?
name : symbol? = 'queue-port

Creates new empty queue port.

procedure
(queue-port-post! qp v) → void?
qp : queue-port?
v : any/c

Adds a value to given queue port queue.

15.12 NVT Input Port

(require rrll/term/private/iac-input-port)
	package: rrll-term

Handles incoming NVT IAC codes.

procedure
(make-iac-input-port in iac-handler) → input-port?
in : input-port?
iac-handler : procedure?

Creates an IAC input port from given port. All IAC codes are captured and passed on to given iac-handler. Other data is passed on unchanged.

procedure
(nvt-iac-handler in options [sb-handler]) → void?
  in : input-port?
  options : hash?
  sb-handler : procedure? = void

Reasonable implementation of NVT IAC handler that allows passing IAC subnegotiations to sb-handler for further processing.

15.13 ANSI Input Port

(require rrll/term/private/ansi-input-port)
	package: rrll-term

Implementation of ANSI input decoding on top of another input port.

procedure
(make-ansi-input-port in
[ queue-port
#:mouse-status mouse-status])
→ input-port?
  in : input-port?
  queue-port : (or/c queue-port? #f) = #f
  mouse-status : (or/c mouse-status? #f) = #f

Creates ANSI input decoding port. If no queue-port is given, it creates a new one. Existing is needed by one terminal implementation.

Both the original port and mouse-status struct for mouse reporting are held in weak boxes.

15.14 Mouse Input

(require rrll/term/private/mouse)

package: rrll-term

This module is used by rrll/term/private/ansi-input-port to store the results of mouse tracking.

struct
(struct mouse-status (x y b1 b2 b3))
  x : fixnum?
  y : fixnum?
  b1 : boolean?
  b2 : boolean?
  b3 : boolean?

Storage for mouse position and status of its three buttons.

procedure
(make-mouse-status) → mouse-status?

Creates empty mouse status - a helper procedure so that the creator doesn’t need to know the exact contents of the struct.

contents ← prev up next →

1	RRLL: Actor Basic 2.0
2	RRLL: ANSI Buffers
3	RRLL: Abuf Canvas
4	RRLL: Canvas
5	RRLL: Rendering Canvas
6	RRLL: Color Support
7	RRLL: Single-Channel Flomaps
8	RRLL: Futures
9	RRLL: Functional Grids
10	RRLL: Helpers
11	RRLL: Math
12	RRLL: Mutable Future Queue
13	RRLL: Rasterizer
14	RRLL: Renderer
15	RRLL: Terminal I/ O
16	RRLL: Ticker
17	RRLL: Unsafe

15.1	ANSI Terminal Output
15.2	TTY
15.3	NVT - TELNET
15.4	NVT Options Storage
15.5	Terminal Size and Resize Reporting
15.6	Terminal Base
15.7	Terminal Resources Garbage Collection
15.8	Foreign Function Interface Struct Size Detection
15.9	Low-Level Termios Interface
15.10	TTY Window Size I/ O Control
15.11	Queue Input Port
15.12	NVT Input Port
15.13	ANSI Input Port
15.14	Mouse Input