Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

USER (Since v0.1.0)

The username of the current user.

HOSTNAME (Since v0.1.0)

The hostname of the host device.

NAME (Since v0.1.0)

The pretty name of the host device.

TZ (Since v0.1.0)

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

LANGS (Since v1.0.0)

The display language using two letter language code (ISO 639-1) followed by a forward slash 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 colons.

Key / value pairs can specify languages for specific contexts:

  • Collation: Sorting
  • CharClass: How characters should be classified
  • Monetary: Kind of money
  • Message: Messages
  • Numeric: Thousands separator, number system
  • Time: Displaying date and time

So, for a preference of American English, falling back to Mexican Spanish if not available, and a preference of pound sterlings for money:

Monetary=en/GB:en/US:es/MX

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
  • SOH \x01 (Since v1.0.0): Set title (start)
  • STX \x02 (Since v1.0.0): Turn off RAW mode
  • ETX \x03 (Since v1.0.0): Turn on RAW mode
  • EOT \x04 (Since v1.0.0): Set title (end)
  • ENQ \x05 (Since v1.0.0): Print “column/columns;line/lines” to stdin (skips buffer)
  • ACK \x06 (Since v1.0.0): Remove “column/columns;line/lines” from stdin
  • 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
  • SO \x0E (Since v1.0.0): Alternate screen off - Go to shell prompt
  • SI \x0F (Since v1.0.0): Alternate screen on

Raw Mode

This mode can be switched on and off. Default is off.

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