# terminal

> Terminal/TUI control — raw mode, key reading, size, and ANSI colors, cursor, and screen sequences.

# terminal

Build terminal UIs: query the terminal, switch stdin to raw mode, read individual keystrokes, and generate ANSI escape sequences for color, cursor, and screen control. Import it with `import terminal`.

## State and input

| Function | Signature | Description |
| --- | --- | --- |
| `isatty` | `terminal.isatty() → bool` | Whether stdout is a terminal |
| `size` | `terminal.size() → object` | Terminal dimensions as `{cols, rows}` (defaults to 80x24 if unavailable) |
| `rawMode` | `terminal.rawMode() → int` | Switch stdin to raw mode (no echo, no line buffering); returns a state handle, or `-1` on error |
| `restoreMode` | `terminal.restoreMode(handle: int) → bool` | Restore the mode saved by `rawMode` |
| `readKey` | `terminal.readKey() → string` | Read one keystroke; returns a key name (see below) or a single printable character |
| `write` | `terminal.write(s: string) → bool` | Unbuffered write to stdout with no trailing newline — use for mid-frame ANSI sequences |
| `flush` | `terminal.flush() → void` | Flush pending stdout output |

`readKey` returns names like `up`, `down`, `left`, `right`, `enter`, `tab`, `esc`, `backspace`, `home`, `end`, `pageup`, `pagedown`, `insert`, `delete`, `f1`–`f12`, and `ctrl+a`–`ctrl+z`.

## Cursor and screen

These return ANSI escape-sequence strings to pass to `terminal.write`.

| Function | Signature | Description |
| --- | --- | --- |
| `clear` | `terminal.clear() → string` | Clear screen and home the cursor |
| `clearLine` | `terminal.clearLine() → string` | Clear the entire current line |
| `clearRight` | `terminal.clearRight() → string` | Clear from cursor to end of line |
| `hideCursor` | `terminal.hideCursor() → string` | Hide the cursor |
| `showCursor` | `terminal.showCursor() → string` | Show the cursor |
| `altScreen` | `terminal.altScreen() → string` | Enter the alternate screen buffer |
| `mainScreen` | `terminal.mainScreen() → string` | Leave the alternate screen buffer |
| `saveCursor` | `terminal.saveCursor() → string` | Save the cursor position |
| `loadCursor` | `terminal.loadCursor() → string` | Restore the saved cursor position |
| `moveTo` | `terminal.moveTo(row: int, col: int) → string` | Move cursor to a 1-indexed position |

## Styling and color

| Function | Signature | Description |
| --- | --- | --- |
| `reset` | `terminal.reset() → string` | Reset all attributes |
| `bold` | `terminal.bold() → string` | Bold |
| `dim` | `terminal.dim() → string` | Dim |
| `italic` | `terminal.italic() → string` | Italic |
| `underline` | `terminal.underline() → string` | Underline |
| `reverse` | `terminal.reverse() → string` | Reverse video |
| `color` | `terminal.color(name: string) → string` | Foreground color by name (`red`, `green`, …, `brightblue`, `default`) or a `"0"`–`"255"` string for 256-color |
| `bg` | `terminal.bg(name: string) → string` | Background color, same names |
| `rgb` | `terminal.rgb(r: int, g: int, b: int) → string` | 24-bit truecolor foreground |
| `bgRgb` | `terminal.bgRgb(r: int, g: int, b: int) → string` | 24-bit truecolor background |

## Example

```goost
import terminal

// switch to raw mode and read keys until Esc
let st = terminal.rawMode()
terminal.write(terminal.clear())

let running = true
while running {
  let key = terminal.readKey()
  if key == "esc" {
    running = false
  } else {
    // print the key in green at the top-left
    terminal.write(terminal.moveTo(1, 1) + terminal.clearLine())
    terminal.write(terminal.color("green") + "key: " + key + terminal.reset())
    terminal.flush()
  }
}

terminal.restoreMode(st)
```