YOLK --- ansi escapes for CHICKEN -*- text -*-

yes there's already ansi-escape-sequences[1]. consider this NIH ;) this library
is based on the information a gist by fnky[2]. at some point i should base it
instead on xterm's manual[3].

Unless otherwise stated, all procedures and variables in this library are
strings or return strings ready for `display'.

INSTALLATION.

Run `chicken-install' in this directory or `make install', which will run it for
you. You can also run `make clean' to clean the folder of build artifacts.

MODULES.

(yolk common) --- common functionality

Procedures.

- (esc . xs)

Return a string consisting of XS, converted to strings, prepended by ESC.

- (csi . xs)

Convenience function to escape XS using the csi code (ESC "[").

- (dcs . xs)

Convenience function to escape XS using the dcs code (ESC "P").

- (ocs . xs)

Convenience function to escape XS using the ocs code (ESC "]").

- (parameter-assert predicate error-message)

Convenience function. Returns a function that runs PREDICATE on its argument and
returns the argument if PREDICATE passes, or errors if not. I use this for
parameters.

Syntax.

- (define-esc-alt-wrapper wrapper-proc-name param-name (default-proc args ...))

Many terminal behaviors have multiple escape sequences that might work. This
macro defines a parameter named PARAM-NAME and a procedure named
WRAPPER-PROC-NAME that will call PARAM-NAME with ARGS ... . The user can change
which procedure to call by calling (PARAM-NAME new-proc).

(yolk attrs) --- text attributes

-- (prop? x)

Returns X if X is a text property (non-color); otherwise returns #f.

-- (color? x)

Returns X if X is a terminal color name; otherwise returns #f.

-- (attrs as)

AS is a list of attributes, each of one of the following forms:

- [number] -- returned directly
- [color], (fg [color]), (fg . [color]) -- set the foreground to [color]
- (bg [color]), (bg . [color]) -- set the background to [color]
- [property], (set [property]), (set . [property]) -- turn [property] on
- (reset [property]), (reset . [property]) -- turn [property] off
- 'reset -- reset the text attributes

Anything else is an error.  `attrs' returns a string ready to be displayed on the terminal.

-- (with-attrs as str)

Print STR prepended with AS and followed by (attrs 'reset).

(yolk cursor) --- cursor movement

Variables.

-- cursor-home

Move the cursor to the top-left corner (0,0). NOTE: This and the move commands
might be revised later.

Procedures.

-- (cursor-move x y)

Move cursor to X, Y, counting from the top-left corner of the screen.
cursor-move is an esc-alt-wrapper that defaults to cursor-move/H ("^[[Y;XH").

-- (cursor-up n)
-- (cursor-down n)
-- (cursor-right n)
-- (cursor-left n)

Move cursor up, down, left, or right by N spaces.

-- (cursor-up-bol n)
-- (cursor-down-bol n)

Move cursor up or down by N lines, to the beginning of the given line.

-- (cursor-move-column n)

Move cursor to column N.

-- (cursor-save)
-- (cursor-restore)

Save or restore the cursor's position on the screen. These variables are
parameters defaulting to the DEC escapes. You can set them to the SCO escapes
using (cursor-save cursor-save/sco), for example.

(yolk erase) --- erasing the screen

Variables.

-- erase-screen-down
-- erase-screen-up
-- erase-screen
-- erase-saved-lines

These erase portions of the entire screen.

-- erase-line-right
-- erase-line-left
-- erase-line

These erase portions of the current line.

-- erase-line-and-return

Convenience function to return the cursor to the beginning of the line after
erasing it.

(yolk xterm) --- xterm-specific escape sequences

Variables.

-- invisible-cursor
-- visible-cursor

Make the cursor invisible or visible.

-- save-screen
-- restore-screen

Save or restore the screen's state.

-- alt-buffer-enable
-- alt-buffer-disable

Enable or disable the "alternate buffer."

REFERENCES.

[1]: http://wiki.call-cc.org/eggref/5/ansi-escape-sequences
[2]: https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797
[3]: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html

- https://xn--rpa.cc/irl/term.html
- (man "console_codes")