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.

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

Procs

proc terminalWidthIoctl(handles: openArray[Handle]): int {.
raises: [], tags: []
.}
  Source Edit
proc terminalHeightIoctl(handles: openArray[Handle]): int {.
raises: [], tags: []
.}
  Source Edit
proc terminalWidth(): int {.
raises: [], tags: []
.}
  Source Edit
proc terminalHeight(): int {.
raises: [], tags: []
.}
  Source Edit
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.   Source Edit
proc hideCursor(f: File) {.
raises: [OSError], tags: []
.}
Hides the cursor.   Source Edit
proc showCursor(f: File) {.
raises: [OSError], tags: []
.}
Shows the cursor.   Source Edit
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.   Source Edit
proc setCursorXPos(f: File; x: int) {.
raises: [OSError], tags: []
.}
Sets the terminal's cursor to the x position. The y position is not changed.   Source Edit
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!   Source Edit
proc cursorUp(f: File; count = 1) {.
raises: [OSError], tags: []
.}
Moves the cursor up by count rows.   Source Edit
proc cursorDown(f: File; count = 1) {.
raises: [OSError], tags: []
.}
Moves the cursor down by count rows.   Source Edit
proc cursorForward(f: File; count = 1) {.
raises: [OSError], tags: []
.}
Moves the cursor forward by count columns.   Source Edit
proc cursorBackward(f: File; count = 1) {.
raises: [OSError], tags: []
.}
Moves the cursor backward by count columns.   Source Edit
proc eraseLine(f: File) {.
raises: [OSError], tags: []
.}
Erases the entire current line.   Source Edit
proc eraseScreen(f: File) {.
raises: [OSError], tags: []
.}
Erases the screen with the background colour and moves the cursor to home.   Source Edit
proc resetAttributes(f: File) {.
raises: [], tags: []
.}
Resets all attributes.   Source Edit
proc setStyle(f: File; style: set[Style]) {.
raises: [], tags: []
.}
Sets the terminal style.   Source Edit
proc writeStyled(txt: string; style: set[Style] = {styleBright}) {.
raises: [IOError], tags: [WriteIOEffect]
.}
Writes the text txt in a given style to stdout.   Source Edit
proc setForegroundColor(f: File; fg: ForegroundColor; bright = false) {.
raises: [], tags: []
.}
Sets the terminal's foreground color.   Source Edit
proc setBackgroundColor(f: File; bg: BackgroundColor; bright = false) {.
raises: [], tags: []
.}
Sets the terminal's background color.   Source Edit
proc isatty(f: File): bool {.
raises: [], tags: []
.}
Returns true if f is associated with a terminal device.   Source Edit
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.   Source Edit
proc resetAttributes() {.
noconv, raises: [], tags: []
.}
Resets all attributes on stdout. It is advisable to register this as a quit proc with system.addQuitProc(resetAttributes).   Source Edit

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)
  Source Edit
macro styledEcho(args: varargs[untyped]): untyped
Echoes styles arguments to stdout using styledWriteLine.   Source Edit

Templates

template hideCursor()
  Source Edit
template showCursor()
  Source Edit
template setCursorPos(x, y: int)
  Source Edit
template setCursorXPos(x: int)
  Source Edit
template cursorUp(count = 1)
  Source Edit
template cursorDown(count = 1)
  Source Edit
template cursorForward(count = 1)
  Source Edit
template cursorBackward(count = 1)
  Source Edit
template eraseLine()
  Source Edit
template eraseScreen()
  Source Edit
template setStyle(style: set[Style])
  Source Edit
template setForegroundColor(fg: ForegroundColor; bright = false)
  Source Edit
template setBackgroundColor(bg: BackgroundColor; bright = false)
  Source Edit