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 exitprocs.addExitProc(resetAttributes) to restore the defaults. Similarly, if you hide the cursor, make sure to unhide it with showCursor before quitting.

Progress bar

Basic progress bar example:

Example: cmd: -r:off

import pure/terminal
import std/[os, strutils]

for i in 0..100:
  stdout.styledWriteLine(fgRed, "0% ", fgWhite, '#'.repeat i, if i > 50: fgGreen else: fgYellow, "\t", $i , "%")
  sleep 42
  cursorUp 1
  eraseLine()

stdout.resetAttributes()

Playing with colorful and styled text

Procs like styledWriteLine, styledEcho etc. have a temporary effect on text parameters. Style parameters only affect the text parameter right after them. After being called, these procs will reset the default style of the terminal. While setBackGroundColor, setForeGroundColor etc. have a lasting influence on the terminal, you can use resetAttributes to reset the default style of the terminal.

Example: cmd: -r:off

import pure/terminal
stdout.styledWriteLine({styleBright, styleBlink, styleUnderscore}, "styled text ")
stdout.styledWriteLine(fgRed, "red text ")
stdout.styledWriteLine(fgWhite, bgRed, "white text in red background")
stdout.styledWriteLine(" ordinary text without style ")

stdout.setBackGroundColor(bgCyan, true)
stdout.setForeGroundColor(fgBlue)
stdout.write("blue text in cyan background")
stdout.resetAttributes()

# You can specify multiple text parameters. Style parameters
# only affect the text parameter right after them.
styledEcho styleBright, fgGreen, "[PASS]", resetStyle, fgGreen, " Yay!"

stdout.styledWriteLine(fgRed, "red text ", styleBright, "bold red", fgDefault, " bold text")

Imports

macros, strformat, strutils, colors, termios, posix, os, parseutils

Types

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. Source Edit
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. Source Edit
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. Source Edit
TerminalCmd = enum resetStyle, ## reset attributes fgColor, ## set foreground's true color bgColor ## set background's true color: commands that can be expressed as arguments Source Edit

Consts

ansiResetCode = "\e[0m": Source Edit

Procs

proc ansiBackgroundColorCode(color: Color): string {....raises: [ValueError], tags: [].}: Source Edit
proc ansiForegroundColorCode(color: Color): string {....raises: [ValueError], tags: [].}: Source Edit
proc ansiForegroundColorCode(fg: ForegroundColor; bright = false): string {. ...raises: [ValueError], tags: [].}: Source Edit
proc ansiStyleCode(style: int): string {....raises: [ValueError], tags: [].}: Source Edit
proc cursorBackward(f: File; count = 1) {....raises: [IOError, ValueError], tags: [WriteIOEffect].}: Moves the cursor backward by count columns.
Example: cmd: -r:off

stdout.cursorBackward(2) write(stdout, "Hello World!") # anything written at that location will be erased/replaced with this
Source Edit
proc cursorDown(f: File; count = 1) {....raises: [IOError, ValueError], tags: [WriteIOEffect].}: Moves the cursor down by count rows.
Example: cmd: -r:off

stdout.cursorDown(2) write(stdout, "Hello World!") # anything written at that location will be erased/replaced with this
Source Edit
proc cursorForward(f: File; count = 1) {....raises: [IOError, ValueError], tags: [WriteIOEffect].}: Moves the cursor forward by count columns.
Example: cmd: -r:off

stdout.cursorForward(2) write(stdout, "Hello World!") # anything written at that location will be erased/replaced with this
Source Edit
proc cursorUp(f: File; count = 1) {....raises: [IOError], tags: [WriteIOEffect].}: Moves the cursor up by count rows.
Example: cmd: -r:off

stdout.cursorUp(2) write(stdout, "Hello World!") # anything written at that location will be erased/replaced with this
Source Edit
proc disableTrueColors() {....raises: [], tags: [RootEffect].}: Disables true color. Source Edit
proc enableTrueColors() {....raises: [], tags: [RootEffect, ReadEnvEffect].}: Enables true color. Source Edit
proc eraseLine(f: File) {....raises: [IOError, ValueError], tags: [WriteIOEffect].}: Erases the entire current line.
Example: cmd: -r:off

write(stdout, "never mind") stdout.eraseLine() # nothing will be printed on the screen
Source Edit
proc eraseScreen(f: File) {....raises: [IOError], tags: [WriteIOEffect].}: Erases the screen with the background colour and moves the cursor to home. Source Edit
proc getch(): char {....raises: [IOError, EOFError], tags: [ReadIOEffect].}: Reads a single character from the terminal, blocking until it is entered. The character is not printed to the terminal. Source Edit
proc hideCursor(f: File) {....raises: [IOError], tags: [WriteIOEffect].}: Hides the cursor. Source Edit
proc isatty(f: File): bool {....raises: [], tags: [].}: Returns true if f is associated with a terminal device. Source Edit
proc isTrueColorSupported(): bool {....raises: [], tags: [RootEffect].}: Returns true if a terminal supports true color. Source Edit
proc readPasswordFromStdin(prompt = "password: "): string {....raises: [IOError], tags: [ReadIOEffect, WriteIOEffect].}: Reads a password from stdin without printing it. Source Edit
proc readPasswordFromStdin(prompt: string; password: var string): bool {. ...tags: [ReadIOEffect, WriteIOEffect], raises: [IOError].}: Source Edit
proc resetAttributes() {.noconv, ...raises: [IOError], tags: [WriteIOEffect].}: Resets all attributes on stdout. It is advisable to register this as a quit proc with exitprocs.addExitProc(resetAttributes). Source Edit
proc resetAttributes(f: File) {....raises: [IOError], tags: [WriteIOEffect].}: Resets all attributes. Source Edit
proc setBackgroundColor(f: File; bg: BackgroundColor; bright = false) {. ...raises: [IOError, ValueError], tags: [WriteIOEffect].}: Sets the terminal's background color. Source Edit
proc setBackgroundColor(f: File; color: Color) {....raises: [IOError, ValueError], tags: [RootEffect, WriteIOEffect].}: Sets the terminal's background true color. Source Edit
proc setCursorPos(f: File; x, y: int) {....raises: [IOError, ValueError], tags: [WriteIOEffect].}: 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: [IOError, ValueError], tags: [WriteIOEffect].}: Sets the terminal's cursor to the x position. The y position is not changed. Source Edit
proc setForegroundColor(f: File; color: Color) {....raises: [IOError, ValueError], tags: [RootEffect, WriteIOEffect].}: Sets the terminal's foreground true color. Source Edit
proc setForegroundColor(f: File; fg: ForegroundColor; bright = false) {. ...raises: [IOError, ValueError], tags: [WriteIOEffect].}: Sets the terminal's foreground color. Source Edit
proc setStyle(f: File; style: set[Style]) {....raises: [IOError, ValueError], tags: [WriteIOEffect].}: Sets the terminal style. Source Edit
proc showCursor(f: File) {....raises: [IOError], tags: [WriteIOEffect].}: Shows the cursor. Source Edit
proc terminalHeight(): int {....raises: [ValueError], tags: [ReadEnvEffect].}: Returns some reasonable terminal height from either standard file descriptors, controlling terminal, environment variables or tradition. Zero is returned if the height could not be determined. Source Edit
proc terminalHeightIoctl(fds: openArray[int]): int {....raises: [], tags: [].}: Returns terminal height from first fd that supports the ioctl. Source Edit
proc terminalSize(): tuple[w, h: int] {....raises: [ValueError], tags: [ReadEnvEffect].}: Returns the terminal width and height as a tuple. Internally calls terminalWidth and terminalHeight, so the same assumptions apply. Source Edit
proc terminalWidth(): int {....raises: [ValueError], tags: [ReadEnvEffect].}: Returns some reasonable terminal width from either standard file descriptors, controlling terminal, environment variables or tradition. Source Edit
proc terminalWidthIoctl(fds: openArray[int]): int {....raises: [], tags: [].}: Returns terminal width from first fd that supports the ioctl. Source Edit
proc writeStyled(txt: string; style: set[Style] = {styleBright}) {. ...raises: [IOError, ValueError], tags: [WriteIOEffect].}: Writes the text txt in a given style to stdout. Source Edit

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: cmd: -r:off

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

Templates

template ansiBackgroundColorCode(color: static[Color]): string: Source Edit
template ansiForegroundColorCode(color: static[Color]): string: Source Edit
template ansiForegroundColorCode(fg: static[ForegroundColor]; bright: static[bool] = false): string: Source Edit
template ansiStyleCode(style: static[Style]): string: Source Edit
template ansiStyleCode(style: Style): string: Source Edit
template cursorBackward(count = 1): Source Edit
template cursorDown(count = 1): Source Edit
template cursorForward(count = 1): Source Edit
template cursorUp(count = 1): Source Edit
template eraseLine(): Source Edit
template eraseScreen(): Source Edit
template hideCursor(): Source Edit
template setBackgroundColor(bg: BackgroundColor; bright = false): Source Edit
template setBackgroundColor(color: Color): Source Edit
template setCursorPos(x, y: int): Source Edit
template setCursorXPos(x: int): Source Edit
template setForegroundColor(color: Color): Source Edit
template setForegroundColor(fg: ForegroundColor; bright = false): Source Edit
template setStyle(style: set[Style]): Source Edit
template showCursor(): Source Edit
template styledEcho(args: varargs[untyped]): Echoes styles arguments to stdout using styledWriteLine. Source Edit
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)
Source Edit