# std/terminal

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

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 std/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 std/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, syncio, assertions, 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: [], tags: [],
        forbids: [].}

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  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], tags: [WriteIOEffect],
                                          forbids: [].}

  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],
        tags: [WriteIOEffect], forbids: [].}

  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],
                                        forbids: [].}

  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], forbids: [].}

  Disables true color. Source Edit

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

  Enables true color. Source Edit

    proc eraseLine(f: File) {....raises: [IOError], tags: [WriteIOEffect], forbids: [].}

  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],
                                forbids: [].}

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

    proc getch(): char {....raises: [IOError, EOFError], tags: [ReadIOEffect],
                         forbids: [].}

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

    proc getCursorPos(): tuple[x, y: int] {....raises: [ValueError, IOError],
                                            tags: [WriteIOEffect, ReadIOEffect],
                                            forbids: [].}

  Returns cursor position (x, y) writes to stdout and expects the terminal to respond via stdin Source Edit

    proc hideCursor(f: File) {....raises: [IOError], tags: [WriteIOEffect], forbids: [].}

  Hides the cursor. Source Edit

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

  Returns true if `f` is associated with a terminal device. Source Edit

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

  Returns true if a terminal supports true color. Source Edit

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

  Reads a password from stdin without printing it. Source Edit

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

  Source Edit

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

  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],
                                    forbids: [].}

  Resets all attributes. Source Edit

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

  Sets the terminal's background color. Source Edit

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

  Sets the terminal's background true color. Source Edit

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

  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], tags: [WriteIOEffect],
                                          forbids: [].}

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

  Sets the terminal's foreground true color. Source Edit

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

  Sets the terminal's foreground color. Source Edit

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

  Sets the terminal style. Source Edit

    proc showCursor(f: File) {....raises: [IOError], tags: [WriteIOEffect], forbids: [].}

  Shows the cursor. Source Edit

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

  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: [],
        forbids: [].}

  Returns terminal height from first fd that supports the ioctl. Source Edit

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

  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: [], tags: [ReadEnvEffect], forbids: [].}

  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: [],
        forbids: [].}

  Returns terminal width from first fd that supports the ioctl. Source Edit

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

  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