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, strformat, strutils, colors, tables, winlean, winlean, os, unicode, os

Types

Style = enum
  styleBright = 1,              ## bright text
  styleDim,                   ## dim text
  styleItalic,                ## italic (or reverse on terminals not supporting)
  styleUnderscore,            ## underscored text
  styleBlink,                 ## blinking/bold text
  styleBlinkRapid,            ## rapid blinking/bold text (not widely supported)
  styleReverse,               ## reverse
  styleHidden,                ## hidden text
  styleStrikethrough          ## strikethrough

different styles for text output

ForegroundColor = enum
  fgBlack = 30,                 ## black
  fgRed,                      ## red
  fgGreen,                    ## green
  fgYellow,                   ## yellow
  fgBlue,                     ## blue
  fgMagenta,                  ## magenta
  fgCyan,                     ## cyan
  fgWhite,                    ## white
  fg8Bit,                     ## 256-color (not supported, see ``enableTrueColors`` instead.)
  fgDefault                   ## default terminal foreground color

terminal's foreground colors

BackgroundColor = enum
  bgBlack = 40,                 ## black
  bgRed,                      ## red
  bgGreen,                    ## green
  bgYellow,                   ## yellow
  bgBlue,                     ## blue
  bgMagenta,                  ## magenta
  bgCyan,                     ## cyan
  bgWhite,                    ## white
  bg8Bit,                     ## 256-color (not supported, see ``enableTrueColors`` instead.)
  bgDefault                   ## default terminal background color

terminal's background colors

TerminalCmd = enum
  resetStyle,                 ## reset attributes
  fgColor,                    ## set foreground's true color
  bgColor                     ## set background's true color

commands that can be expressed as arguments

Consts

ansiResetCode = "\e[0m"

Procs

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

iterates over each item of a.

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

iterates over each item of a.

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

"is greater" operator. This is the same as y < x.

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

"is greater" operator. This is the same as y < x.

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: [Exception, OSError], tags: [RootEffect].}

Hides the cursor.

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

Shows the cursor.

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

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: [Exception, OSError], tags: [RootEffect].}

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

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

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: [Exception, OSError], tags: [RootEffect].}

Moves the cursor up by count rows.

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

Moves the cursor down by count rows.

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

Moves the cursor forward by count columns.

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

Moves the cursor backward by count columns.

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

Erases the entire current line.

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

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

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

Resets all attributes.

proc ansiStyleCode(style: int): string {...}{.raises: [], tags: [].}

An alias for &.

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

Sets the terminal style.

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

Writes the text txt in a given style to stdout.

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

Sets the terminal's foreground color.

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

Sets the terminal's background color.

proc ansiForegroundColorCode(fg: ForegroundColor; bright = false): string {...}{.raises: [],
    tags: [].}

proc ansiForegroundColorCode(color: Color): string {...}{.raises: [], tags: [].}

An alias for &.

proc ansiBackgroundColorCode(color: Color): string {...}{.raises: [], tags: [].}

An alias for &.

proc setForegroundColor(f: File; color: Color) {...}{.raises: [Exception, IOError],
    tags: [RootEffect, WriteIOEffect].}

Sets the terminal's foreground true color.

proc setBackgroundColor(f: File; color: Color) {...}{.raises: [Exception, IOError],
    tags: [RootEffect, WriteIOEffect].}

Sets the terminal's background true color.

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

Returns true if f is associated with a terminal device.

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.

proc readPasswordFromStdin(prompt: string; password: var TaintedString): bool {...}{.
    tags: [ReadIOEffect, WriteIOEffect], raises: [IOError].}

Reads a password from stdin without printing it. password must not be nil! Returns false if the end of the file has been reached, true otherwise.

proc readPasswordFromStdin(prompt = "password: "): TaintedString {...}{.raises: [IOError],
    tags: [ReadIOEffect, WriteIOEffect].}

Reads a password from stdin without printing it.

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

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

proc isTrueColorSupported(): bool {...}{.raises: [Exception], tags: [RootEffect].}

Returns true if a terminal supports true color.

proc enableTrueColors() {...}{.raises: [Exception], tags: [RootEffect, ReadEnvEffect].}

Enable true color.

proc disableTrueColors() {...}{.raises: [Exception], tags: [RootEffect, ReadEnvEffect].}

Disable true color.

Macros

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

Similar to write, 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:

stdout.styledWrite(fgRed, "red text ")
stdout.styledWrite(fgGreen, "green text")

Templates

template ansiStyleCode(style: Style): string

template ansiStyleCode(style: static[Style]): string

template ansiForegroundColorCode(fg: static[ForegroundColor];
                                bright: static[bool] = false): string

template ansiForegroundColorCode(color: static[Color]): string

template ansiBackgroundColorCode(color: static[Color]): string

template styledWriteLine(f: File; args: varargs[untyped])

Calls styledWrite and appends a newline at the end.

Example:

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

template styledEcho(args: varargs[untyped])

Echoes styles arguments to stdout using styledWriteLine.

template hideCursor()

template showCursor()

template setCursorPos(x, y: int)

template setCursorXPos(x: int)

template setCursorYPos(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)

template setForegroundColor(color: Color)

template setBackgroundColor(color: Color)