Module terminal

This module contains a few procedures to control the terminal (also called console). On UNIX, the implementation simply uses ANSI escape sequences and does not depend on any other module, on Windows it uses the Windows API. Changing the style is permanent even after program termination! Use the code system.addQuitProc(resetAttributes) to restore the defaults. Similarly, if you hide the cursor, make sure to unhide it with showCursor before quitting.

Imports

macros, winlean, os

Types

Style = enum
  styleBright = 1,              ## bright text
  styleDim,                   ## dim text
  styleUnknown,               ## unknown
  styleUnderscore = 4,          ## underscored text
  styleBlink,                 ## blinking/bold text
  styleReverse = 7,             ## unknown
  styleHidden                 ## hidden text

different styles for text output

ForegroundColor = enum
  fgBlack = 30,                 ## black
  fgRed,                      ## red
  fgGreen,                    ## green
  fgYellow,                   ## yellow
  fgBlue,                     ## blue
  fgMagenta,                  ## magenta
  fgCyan,                     ## cyan
  fgWhite                     ## white

terminal's foreground colors

BackgroundColor = enum
  bgBlack = 40,                 ## black
  bgRed,                      ## red
  bgGreen,                    ## green
  bgYellow,                   ## yellow
  bgBlue,                     ## blue
  bgMagenta,                  ## magenta
  bgCyan,                     ## cyan
  bgWhite                     ## white

terminal's background colors

TerminalCmd = enum
  resetStyle                  ## reset attributes

commands that can be expressed as arguments

Procs

proc terminalWidthIoctl(handles: openArray[Handle]): int {.raises: [], tags: [].}

proc terminalHeightIoctl(handles: openArray[Handle]): int {.raises: [], tags: [].}

proc terminalWidth(): int {.raises: [], tags: [].}

proc terminalHeight(): int {.raises: [], tags: [].}

proc terminalSize(): tuple[w, h: int] {.raises: [], tags: [].}

Returns the terminal width and height as a tuple. Internally calls terminalWidth and terminalHeight, so the same assumptions apply.

proc hideCursor(f: File) {.raises: [OSError], tags: [].}

Hides the cursor.

proc showCursor(f: File) {.raises: [OSError], tags: [].}

Shows the cursor.

proc setCursorPos(f: File; x, y: int) {.raises: [OSError], tags: [].}

Sets the terminal's cursor to the (x,y) position. (0,0) is the upper left of the screen.

proc setCursorXPos(f: File; x: int) {.raises: [OSError], tags: [].}

Sets the terminal's cursor to the x position. The y position is not changed.

proc setCursorYPos(f: File; y: int) {.raises: [OSError], tags: [].}

Sets the terminal's cursor to the y position. The x position is not changed. Warning: This is not supported on UNIX!

proc cursorUp(f: File; count = 1) {.raises: [OSError], tags: [].}

Moves the cursor up by count rows.

proc cursorDown(f: File; count = 1) {.raises: [OSError], tags: [].}

Moves the cursor down by count rows.

proc cursorForward(f: File; count = 1) {.raises: [OSError], tags: [].}

Moves the cursor forward by count columns.

proc cursorBackward(f: File; count = 1) {.raises: [OSError], tags: [].}

Moves the cursor backward by count columns.

proc eraseLine(f: File) {.raises: [OSError], tags: [].}

Erases the entire current line.

proc eraseScreen(f: File) {.raises: [OSError], tags: [].}

Erases the screen with the background colour and moves the cursor to home.

proc resetAttributes(f: File) {.raises: [], tags: [].}

Resets all attributes.

proc setStyle(f: File; style: set[Style]) {.raises: [], tags: [].}

Sets the terminal style.

proc writeStyled(txt: string; style: set[Style] = {styleBright}) {.raises: [IOError],
    tags: [WriteIOEffect].}

Writes the text txt in a given style to stdout.

proc setForegroundColor(f: File; fg: ForegroundColor; bright = false) {.raises: [],
    tags: [].}

Sets the terminal's foreground color.

proc setBackgroundColor(f: File; bg: BackgroundColor; bright = false) {.raises: [],
    tags: [].}

Sets the terminal's background color.

proc isatty(f: File): bool {.raises: [], tags: [].}

Returns true if f is associated with a terminal device.

proc getch(): char {.raises: [AssertionError], tags: [].}

Read a single character from the terminal, blocking until it is entered. The character is not printed to the terminal.

proc resetAttributes() {.noconv, raises: [], tags: [].}

Resets all attributes on stdout. It is advisable to register this as a quit proc with system.addQuitProc(resetAttributes).

Macros

macro styledWriteLine(f: File; m: varargs[typed]): untyped

Similar to writeLine, but treating terminal style arguments specially. When some argument is Style, set[Style], ForegroundColor, BackgroundColor or TerminalCmd then it is not sent directly to f, but instead corresponding terminal style proc is called.

Example:

proc error(msg: string) =
  styledWriteLine(stderr, fgRed, "Error: ", resetStyle, msg)

macro styledEcho(args: varargs[untyped]): untyped

Echoes styles arguments to stdout using styledWriteLine.

Templates

template hideCursor()

template showCursor()

template setCursorPos(x, y: int)

template setCursorXPos(x: int)

template cursorUp(count = 1)

template cursorDown(count = 1)

template cursorForward(count = 1)

template cursorBackward(count = 1)

template eraseLine()

template eraseScreen()

template setStyle(style: set[Style])

template setForegroundColor(fg: ForegroundColor; bright = false)

template setBackgroundColor(bg: BackgroundColor; bright = false)