about summary refs log tree commit diff stats
path: root/readme
blob: baa3bbc83d9f608c3839d74d5ad485183f69500a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
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.

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