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