1 Utilities

8.16.0.4

1 Utilities🔗ℹ

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

These modules provide low-level helpers commonly used in various layers of the terminal support infrastructure.

1.1 Generic Buffered Reader🔗ℹ

A small layer on top of input-port? that allows for acknowleging the input read or making a rollback if not enough data to decode certain sequence was available. This is needed to properly implement non-blocking I/O in make-input-port arguments without having to run multiple threads.

This module is used in both tui/term/nvt-input-port and tui/term/vt-input-port for handling non-blocking input.

procedure
(make-gen-buf-reader [in initial-size reader]) → gen-buf-reader?
  in : input-port? = (current-input-port)
  initial-size : exact-nonnegative-integer? = 8
  reader : (-> input-port? any/c) = read-char

Creates a new gen-buf-reader? with given reader procedure. When reading data (typically bytes or characters) from the underlying input port in a buffer of initial-size is filled first. If the buffer size is not enough at any point, it is always doubled. The buffer is never shrunk.

The application uses read-gen-buf to read required data from the port and when it successfully decoded its sequence, it can ack-gen-buf to remove processed data from the buffer. If there was any further data already buffered, it is moved to the beginning of the buffer.

If the application did not decode the sequence in question and no more data is available - or for any other reason - it should rollback-gen-buffer to allow re-trying reading the sequence later on.

The default for the reader argument makes this equivalent to make-char-buf-reader.

procedure
(gen-buf-reader? v) → boolean?
v : any/c

A predicate returning #t if given v is a generic buffered reader of any kind.

procedure
(make-char-buf-reader in [initial-size]) → gen-buf-reader?
in : input-port?
initial-size : exact-nonnegative-integer? = 8

Creates a generic buffered reader with read-char as the reader.

procedure
(make-byte-buf-reader in [initial-size]) → gen-buf-reader?
in : input-port?
initial-size : exact-nonnegative-integer? = 8

Creates a generic buffered reader with read-byte as the reader.

procedure
(read-gen-buf gbr) → any/c
gbr : gen-buf-reader?

Reads a single value from the buffered reader returning whatever its internal reader has put in the buffer. If no data is available yet, it returns #f. If the input has ended, it returns eof.

This is different behaviour than what read-byte and read-char have. This procedure returns the eof value if and only if no more data can be retrieved from the underlying port. In case of temporary data unavailability #f is returned and not eof - unlike the aforementioned procedures.

procedure
(ack-gen-buf gbr) → void?
gbr : gen-buf-reader?

Acknowledges all the bytes read so far using read-gen-buf from given gbr. The next read-gen-buf would return whatever follows.

procedure
(rollback-gen-buf gbr) → void?
gbr : gen-buf-reader?

Rolls given gbr back. The next read-gen-buf would return whatever was in the internal buffer as if the previous reads (since last ack-gen-buf) never happened.

procedure
(gen-buf-reader-eof? gbr) → boolean?
gbr : gen-buf-reader?

Returns #t if there is no further data available in the underlying input port of given gbr.

procedure
(gen-buf-reader-non-empty? gbr) → boolean?
gbr : gen-buf-reader?

Returns #t if there is some data available in the internal buffer of given gbr.

procedure
(gen-buf-reader-empty? gbr) → boolean?
gbr : gen-buf-reader?

Returns #t if the internal buffer of gbr is empty.

1.2 Byteslices🔗ℹ

(require tui/term/byteslice)

package: tui-term

This module implements support for read-only slices of bytes? values. It is used primarily for implementing efficient NVT encoding in tui/term/nvt-encoder.

procedure
(byteslice? v) → boolean?
v : any/c

A predicate returning #t if given value v is byteslice.

procedure
(make-byteslice b/s [start end]) → byteslice?
  b/s : (or/c bytes? byteslice?)
  start : exact-nonnegative-integer? = 0
  end : (or/c #f exact-nonnegative-integer?) = #f

Creates new byteslice value from given bytes or byteslice value. If no end argument is provided the rest of the input argument b/s is used.

procedure
(write-byteslice bs [out]) → void?
bs : (or/c bytes? byteslice?)
out : output-port? = (current-output-port)

Uses write-bytes on the byteslice bs data and writes the part starting at start (inclusive) and ending at end (exclusive).

When given a bytes? value, it is passed directly to write-bytes.

procedure
(write-byteslices bss [out]) → void?
bss : (listof (or/ bytes? byteslice?))
out : output-port? = (current-output-port)

Performs write-byteslice on all elements of bss to the out port given.

procedure
(byteslice-ref bs idx) → byte?
bs : byteslice?
idx : exact-nonnegative-integer?

Uses bytes-ref on the underlying data adjusting for start offset.

procedure
(byteslice-length bs) → nonnegative-integer?
bs : byteslice?

Returns the actual number of bytes in given byteslice bs.

1.3 Thread-Safe Queues🔗ℹ

(require tui/term/tqueue)

package: tui-term

This module wraps data/queue with thread-safety and synchronizable events.

procedure
(tqueue? v) → boolean?
v : any/c

Returns #t if given value v

procedure
(make-tqueue) → tqueue?

Creates an empty tqueue?.

procedure
(tqueue-enqueue! q v) → void?
q : tqueue?
v : any/c

Enqueues given value v into the queue q and increments the internal semaphore counter.

procedure
(tqueue-dequeue! q) → any/c
q : tqueue?

Dequeues next value from the queue q after decrementing the internal semaphore counter and returns the value retrieved.

If there are no values queued, it blocks until the queue is ready.

procedure
(tqueue-evt q) → evt?
q : tqueue?

Returns a synchronizable event that is ready for synchronization when the given queue q is non-empty.

procedure
(tqueue-length q) → exact-nonnegative-integer?
q : tqueue?

Returns the number of elements in given queue q.

procedure
(tqueue-empty? q) → boolean?
q : tqueue?

Returns #t if given queue q contains no elements.

procedure
(tqueue-non-empty? q) → boolean?
q : tqueue?

Returns #t if given queue q contains at least one element.

procedure
(tqueue-peek q) → any/c
q : tqueue?

If given queue q is empty, this procedure returns #f. If non-empty, the first element in the queue is returned but it is NOT removed from the queue.

1.4 Bytes Buffer🔗ℹ

(require tui/term/bytes-buffer)

package: tui-term

This module provides a thin glue layer used by tui/term/tty-input-port to use special procedure for reading keyboard input and providing it as stream of bytes for the next layer.

procedure
(make-bytes-buffer [initial-size]) → bytes-buffer?
initial-size : exact-positive-integer? = 8

Creates a bytes buffer of given initial size. If more data is written in the buffer than available capacity, it is always reallocated double the size. All the operations are protected by internal semaphore and are therefore thread-safe.

procedure
(bytes-buffer? v) → boolean?
v : any/c

A predicate returning #t if given value v is a bytes buffer.

procedure
(bytes-buffer-write-char! bb ch) → void?
bb : bytes-buffer?
ch : char?

Writes bytes corresponding to the UTF-8 representation of given character ch into the buffer bb reallocating the internal mutable bytes vector if necessary.

procedure
(bytes-buffer-read-bytes! bb bs [peek?])
→ nonnegative-exact-integer?
  bb : bytes-buffer?
  bs : bytes?
  peek? : boolean? = #f

Reads bytes from given bb buffer into the bs bytes up to whatever is available in the buffer or whatever fits in the target bytes. Updates buffer contents accordingly and returns the number of bytes stored in the output mutable bytes.

Tries to read as many bytes from given bytes-buffer? bb into bytes? bb. Returns the number of bytes read.

If peek? is #t the bytes are retained in the buffer - they are removed otherwise.

procedure
(bytes-buffer-peek-bytes! bb bs) → nonnegative-exact-integer
bb : bytes-buffer?
bs : bytes?

Uses bytes-buffer-read-bytes! with peek? argument set to #t to peek the bytes awaiting in the underlying buffer.

1.5 Term Struct🔗ℹ

(require tui/term/term-struct)

package: tui-term

This module defines the data structure representing the terminal.

struct
(struct tterm (in out size ttype phook))
  in : input-port?
  out : output-port?
  size : (box/c (list/c fixnum? fixnum?))
  ttype : (box/c string?)
  phook : (or/c #f procedure?)

Structure representing interactive terminal. It includes the actual in and out ports as well as boxes with size and terminal type ttype.

Typically the ports are custom ports implementing the specifics of given terminal connection like NVT or local TTY.

The phook field may contain platform hook procedure. Currently only on the Windows platform this hook is present for local terminals.

parameter
(current-term) → (or/c tterm? #f)
(current-term term) → void?
term : (or/c tterm? #f)
= #f

A parameter holding the current terminal struct.

procedure
(run-current-term-platform-hook arg ...) → any/c
arg : any/c

If there is any platform hook registered within (current-term) it is run with any arguments given as its arguments and its result is returned.

procedure
(current-term-size)
→
nonnegative-integer? nonnegative-integer?

Returns the number of columns and number of rows (width and height) of the (current-term).

1.6 Term Syntax🔗ℹ

(require tui/term/term-syntax)

package: tui-term

Some infrastructure to make the terminal easy to use - including current terminal parameter and with-term syntax that handles I/O redirection to/from the terminal transparently.

syntax
(with-term term expr ...)

Syntax form that parameterizes not only the current-term but also current-input-port and current-output-port accordingly.

1	Utilities
2	Virtual Terminal
3	Network Virtual Terminal
4	Tele TYpe Terminal

1.1	Generic Buffered Reader
1.2	Byteslices
1.3	Thread-Safe Queues
1.4	Bytes Buffer
1.5	Term Struct
1.6	Term Syntax