Wasite

Wasite is the WASI Terminal Environment API standard. It defines a set of environment variables and stdin/stdout parsing rules for interfacing with a generic terminal. It is not developed by the same people as WASI, and may conflict with WASI's future goals (future WASI features may deprecate Wasite features). Wasite's only purpose is to extend WASI to make it possible to write interactive terminal applications using WASI today.

Wasite aims to stay as close as possible to what you might expect to find on a standard POSIX-like terminal for environment variables and parsing of stdin and stdout. Wasite uses a subset of the ANSI escape sequences.

This document is the official specification for Wasite.

Environment Variables

The following environment variables must be exported by Wasite-compliant terminal emulators (writes can be ignored to deny permissions without forfeiting compliance):

R: `LINES` (Since v0.1.0)

The number of lines in the terminal view.

R: `COLUMNS` (Since v0.1.0)

The number of columns in the terminal view.

R/W: `LINE` (Since v0.1.0)

The line number of the cursor position (non-zero)

R/W: `COLUMN` (Since v0.1.0)

The column number of the cursor position (non-zero)

R/W: `SCREEN` (Since v0.1.0)

The screen number within the terminal. Default is 0.

Non-default (alternate) screens are only the size of the display; They do not scroll.

R/W: `TITLE` (Since v0.1.0)

The title of the window.

R/W: `USER` (Since v0.1.0)

The username of the current user.

R/W: `HOSTNAME` (Since v0.1.0)

The hostname of the host device.

R/W: `NAME` (Since v0.1.0)

The pretty name of the host device.

R/W: `TZ` (Since v0.1.0)

The IANA TZDB identifier for the timezone (ex: America/New_York)

R/W: `LANGS` (Since v0.1.0)

The display language using two letter language code (ISO 639-1) followed by an underscore and a two letter region code (ISO 3166-1 alpha-2). (ex: en_US)

Multiple languages/dialects can be specified in order of preference, separated by semicolons.

R/W: `RAW` (Since v0.1.0)

This mode can be switched on and off. Default is 0; 1 to enable.

Enabling changes:

Stdout/Stdin is not written to the screen
Stdin is not buffered until newline
All keyboard shortcuts are intercepted
Stdout does not move the cursor on newline characters

Standard Output

Sequences start with the escape character followed by a left bracket \x1B[ and end with m. The style options give you 8 colors for both background and foreground (bold may not change intensity). And 4 style attributes (thickness, italic, underline, inverted).

The following ANSI escape sequences must be supported by Wasite-compliant terminal emulators:

`\x1B[0m` (Since v0.1.0)

Disable all style attribute flags (doesn't include colors)

`\x1B[1m` (Since v0.1.0)

Set thickness style attribute flag to bold

`\x1B[2m` (Since v0.1.0)

Set thickness style attribute flag to thin

`\x1B[3m` (Since v0.1.0)

Enable italic style attribute flag

`\x1B[4m` (Since v0.1.0)

Enable underlined style attribute flag

`\x1B[7m` (Since v0.1.0)

Enable color inversion style attribute flag

`\x1B[22m` (Since v0.1.0)

Set thickness style attribute flag to regular

`\x1B[23m` (Since v0.1.0)

Disable italic style attribute flag

`\x1B[24m` (Since v0.1.0)

Disable underlined style attribute flag

`\x1B[27m` (Since v0.1.0)

Disable color inversion style attribute flag

`\x1B[30m` (Since v0.1.0)

Set foreground color to black

`\x1B[31m` (Since v0.1.0)

Set foreground color to red

`\x1B[32m` (Since v0.1.0)

Set foreground color to green

`\x1B[33m` (Since v0.1.0)

Set foreground color to yellow

`\x1B[34m` (Since v0.1.0)

Set foreground color to blue

`\x1B[35m` (Since v0.1.0)

Set foreground color to magenta

`\x1B[36m` (Since v0.1.0)

Set foreground color to cyan

`\x1B[37m` (Since v0.1.0)

Set foreground color to white

`\x1B[38;5;nm` (Since v0.1.0)

Set foreground to n from Color table.

`\x1B[38;2;r;g;bm` (Since v0.1.0)

Set 24-bit foreground color to r, g, b (decimal 0-255)

`\x1B[39m` (Since v0.1.0)

Reset foreground color to default

`\x1B[40m` (Since v0.1.0)

Set background color to black

`\x1B[41m` (Since v0.1.0)

Set background color to red

`\x1B[42m` (Since v0.1.0)

Set background color to green

`\x1B[43m` (Since v0.1.0)

Set background color to yellow

`\x1B[44m` (Since v0.1.0)

Set background color to blue

`\x1B[45m` (Since v0.1.0)

Set background color to magenta

`\x1B[46m` (Since v0.1.0)

Set background color to cyan

`\x1B[47m` (Since v0.1.0)

Set background color to white

`\x1B[48;5;nm` (Since v0.1.0)

Set background to n from Color table.

`\x1B[48;2;r;g;bm` (Since v0.1.0)

Set 24-bit background color to r, g, b (decimal 0-255)

`\x1B[49m` (Since v0.1.0)

Reset background color to default

`\x1B[90m` (Since v0.1.0)

Set foreground color to bright black

`\x1B[91m` (Since v0.1.0)

Set foreground color to bright red

`\x1B[92m` (Since v0.1.0)

Set foreground color to bright green

`\x1B[93m` (Since v0.1.0)

Set foreground color to bright yellow

`\x1B[94m` (Since v0.1.0)

Set foreground color to bright blue

`\x1B[95m` (Since v0.1.0)

Set foreground color to bright magenta

`\x1B[96m` (Since v0.1.0)

Set foreground color to bright cyan

`\x1B[97m` (Since v0.1.0)

Set foreground color to bright white

`\x1B[100m` (Since v0.1.0)

Set background color to bright black

`\x1B[101m` (Since v0.1.0)

Set background color to bright red

`\x1B[102m` (Since v0.1.0)

Set background color to bright green

`\x1B[103m` (Since v0.1.0)

Set background color to bright yellow

`\x1B[104m` (Since v0.1.0)

Set background color to bright blue

`\x1B[105m` (Since v0.1.0)

Set background color to bright magenta

`\x1B[106m` (Since v0.1.0)

Set background color to bright cyan

`\x1B[107m` (Since v0.1.0)

Set background color to bright white

Unicode special codepoints

NUL `\x00` (Since v0.1.0)

Clear screen

BEL `\x07` (Since v0.1.0)

Visual alert

BS `\x08` (Since v0.1.0)

Move cursor back one column

TAB `\x09` (Since v0.1.0)

Move cursor to the next tab stop (always every 8 columns)

LF `\x0A` (Since v0.1.0)

Clear until end of line, move cursor to the beginning of the next line

VT `\x0B` (Since v0.1.0)

Move cursor to the beginning of the next line without clearing

FF `\x0C` (Since v0.1.0)

Move cursor to next line, keeping same column

CR `\x0D` (Since v0.1.0)

Return cursor to start of line

Standard Input

Standard input takes UTF-8 text for user input, but can also transfer other formats (via piping). If raw mode is enabled, then ANSI escape sequences (matching closely what GNOME terminal produces for maximum compatibility) for additional events will be sent:

Non-Character Keys Escape Sequences (Since v0.1.0)

ANSI escape sequences always start with \x1B[.

Omit for Escape (just \x1B)
A: Up
B: Down
C: Right
D: Left
F: End
H: Home
OP: F1
OQ: F2
OR: F3
OS: F4
Z: Shift+Tab
0;c;lM: Mouse left click press c (column) and l (line)
0;c;lm: Mouse left click release c (column) and l (line)
1mA: Up (m modifier)
1mB: Down (m modifier)
1mC: Right (m modifier)
1mD: Left (m modifier)
1mF: End (m modifier)
1mH: Home (m modifier)
1mP: F1 (m modifier)
1mQ: F2 (m modifier)
1mR: F3 (m modifier)
1mS: F4 (m modifier)
1mZ: Shift+Tab (m modifier)
1;c;lM: Mouse middle click press c (column) and l (line)
1;c;lm: Mouse middle click release c (column) and l (line)
2m~: Insert (m modifier)
2;c;lM: Mouse right click press c (column) and l (line)
2;c;lm: Mouse right click release c (column) and l (line)
3m~: Delete (m modifier)
5m~: Page Up (m modifier)
6m~: Page Down (m modifier)
15m~: F5 (m modifier)
17m~: F6 (m modifier)
18m~: F7 (m modifier)
19m~: F8 (m modifier)
20m~: F9 (m modifier)
21m~: F10 (m modifier)
23m~: F11 (m modifier)
24m~: F12 (m modifier)
35;c;lM: Mouse move c (column) and l (line)

Modifiers (Since v0.1.0)

Modifiers always start with ;

Omit for None (empty)
;2: Shift
;3: Alt
;4: Shift + Alt
;5: Control
;6: Shift + Control
;7: Alt + Control
;8: Shift + Alt + Control