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.

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   Source
ForegroundColor = enum
  fgBlack = 30,                 ## black
  fgRed,                      ## red
  fgGreen,                    ## green
  fgYellow,                   ## yellow
  fgBlue,                     ## blue
  fgMagenta,                  ## magenta
  fgCyan,                     ## cyan
  fgWhite                     ## white
terminal's foreground colors   Source
BackgroundColor = enum
  bgBlack = 40,                 ## black
  bgRed,                      ## red
  bgGreen,                    ## green
  bgYellow,                   ## yellow
  bgBlue,                     ## blue
  bgMagenta,                  ## magenta
  bgCyan,                     ## cyan
  bgWhite                     ## white
terminal's background colors   Source
TerminalCmd = enum
  resetStyle                  ## reset attributes
commands that can be expressed as arguments   Source

Procs

proc setCursorPos(f: File; x, y: int) {.raises: [IOError], tags: [WriteIOEffect].}
Sets the terminal's cursor to the (x,y) position. (0,0) is the upper left of the screen.   Source
proc setCursorXPos(f: File; x: int) {.raises: [IOError], tags: [WriteIOEffect].}
Sets the terminal's cursor to the x position. The y position is not changed.   Source
proc cursorUp(f: File; count = 1) {.raises: [IOError], tags: [WriteIOEffect].}
Moves the cursor up by count rows.   Source
proc cursorDown(f: File; count = 1) {.raises: [IOError], tags: [WriteIOEffect].}
Moves the cursor down by count rows.   Source
proc cursorForward(f: File; count = 1) {.raises: [IOError], tags: [WriteIOEffect].}
Moves the cursor forward by count columns.   Source
proc cursorBackward(f: File; count = 1) {.raises: [IOError], tags: [WriteIOEffect].}
Moves the cursor backward by count columns.   Source
proc eraseLine(f: File) {.raises: [IOError], tags: [WriteIOEffect].}
Erases the entire current line.   Source
proc eraseScreen(f: File) {.raises: [IOError], tags: [WriteIOEffect].}
Erases the screen with the background colour and moves the cursor to home.   Source
proc resetAttributes(f: File) {.raises: [IOError], tags: [WriteIOEffect].}
Resets all attributes.   Source
proc setStyle(f: File; style: set[Style]) {.raises: [IOError], tags: [WriteIOEffect].}
Sets the terminal style.   Source
proc writeStyled(txt: string; style: set[Style] = {styleBright}) {.raises: [IOError],
    tags: [WriteIOEffect].}
Writes the text txt in a given style to stdout.   Source
proc setForegroundColor(f: File; fg: ForegroundColor; bright = false) {.
    raises: [IOError], tags: [WriteIOEffect].}
Sets the terminal's foreground color.   Source
proc setBackgroundColor(f: File; bg: BackgroundColor; bright = false) {.
    raises: [IOError], tags: [WriteIOEffect].}
Sets the terminal's background color.   Source
proc isatty(f: File): bool {.raises: [], tags: [].}
Returns true if f is associated with a terminal device.   Source
proc getch(): char {.raises: [], tags: [].}
Read a single character from the terminal, blocking until it is entered. The character is not printed to the terminal. This is not available for Windows.   Source
proc resetAttributes() {.noconv, raises: [IOError], tags: [WriteIOEffect].}
Resets all attributes on stdout. It is advisable to register this as a quit proc with system.addQuitProc(resetAttributes).   Source

Macros

macro styledWriteLine(f: File; m: varargs[expr]): stmt

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) =
  styleWriteLine(stderr, fgRed, "Error: ", resetStyle, msg)
  Source

Templates

template styledEcho(args: varargs[expr]): expr
Echoes styles arguments to stdout using styledWriteLine.   Source
template setCursorPos(x, y: int)
  Source
template setCursorXPos(x: int)
  Source
template cursorUp(count = 1)
  Source
template cursorDown(count = 1)
  Source
template cursorForward(count = 1)
  Source
template cursorBackward(count = 1)
  Source
template eraseLine()
  Source
template eraseScreen()
  Source
template setStyle(style: set[Style])
  Source
template setForegroundColor(fg: ForegroundColor; bright = false)
  Source
template setBackgroundColor(bg: BackgroundColor; bright = false)
  Source