std/terminal (original) (raw)
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()
styledEcho styleBright, fgGreen, "[PASS]", resetStyle, fgGreen, " Yay!"
stdout.styledWriteLine(fgRed, "red text ", styleBright, "bold red", fgDefault, " bold text")
Types
BackgroundColor = enum
bgBlack = 40,
bgRed,
bgGreen,
bgYellow,
bgBlue,
bgMagenta,
bgCyan,
bgWhite,
bg8Bit,
bgDefault
Terminal's background colors.Source Edit
ForegroundColor = enum
fgBlack = 30,
fgRed,
fgGreen,
fgYellow,
fgBlue,
fgMagenta,
fgCyan,
fgWhite,
fg8Bit,
fgDefault
Terminal's foreground colors.Source Edit
Style = enum
styleBright = 1,
styleDim,
styleItalic,
styleUnderscore,
styleBlink,
styleBlinkRapid,
styleReverse,
styleHidden,
styleStrikethrough
Different styles for text output.Source Edit
Procs
proc cursorBackward(f: File; count = 1) {....raises: [OSError], tags: [RootEffect], forbids: [].}
Moves the cursor backward by count columns.
Example: cmd: -r:off
stdout.cursorBackward(2) write(stdout, "Hello World!")
proc cursorDown(f: File; count = 1) {....raises: [OSError], tags: [RootEffect], forbids: [].}
Moves the cursor down by count rows.
Example: cmd: -r:off
stdout.cursorDown(2) write(stdout, "Hello World!")
proc cursorForward(f: File; count = 1) {....raises: [OSError], tags: [RootEffect], forbids: [].}
Moves the cursor forward by count columns.
Example: cmd: -r:off
stdout.cursorForward(2) write(stdout, "Hello World!")
proc cursorUp(f: File; count = 1) {....raises: [OSError], tags: [RootEffect], forbids: [].}
Moves the cursor up by count rows.
Example: cmd: -r:off
stdout.cursorUp(2) write(stdout, "Hello World!")
proc disableTrueColors() {....raises: [], tags: [RootEffect, ReadEnvEffect], forbids: [].}
Disables true color.Source Edit
proc enableTrueColors() {....raises: [], tags: [RootEffect, ReadEnvEffect], forbids: [].}
Enables true color.Source Edit
proc eraseLine(f: File) {....raises: [OSError], tags: [RootEffect], forbids: [].}
Erases the entire current line.
Example: cmd: -r:off
write(stdout, "never mind") stdout.eraseLine()
proc eraseScreen(f: File) {....raises: [OSError], tags: [RootEffect], forbids: [].}
Erases the screen with the background colour and moves the cursor to home.Source Edit
proc getch(): char {....raises: [], tags: [], forbids: [].}
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: [OSError], tags: [RootEffect], forbids: [].}
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: [].}
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.Source Edit
proc resetAttributes() {.noconv, ...raises: [], tags: [RootEffect], 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: [], tags: [RootEffect], forbids: [].}
Resets all attributes.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: [OSError], tags: [RootEffect], 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: [OSError], tags: [RootEffect], forbids: [].}
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: [RootEffect], forbids: [].}
Sets the terminal's cursor to the y position. The x position is not changed. .. warning:: This is not supported on UNIX Edit
proc setForegroundColor(f: File; color: Color) {....raises: [IOError], tags: [RootEffect, WriteIOEffect], forbids: [].}
Sets the terminal's foreground true color.Source Edit
proc setStyle(f: File; style: set[Style]) {....raises: [], tags: [RootEffect], forbids: [].}
Sets the terminal style.Source Edit
proc showCursor(f: File) {....raises: [OSError], tags: [RootEffect], forbids: [].}
proc terminalHeight(): int {....raises: [], tags: [], forbids: [].}
Returns the terminal height in rows.Source Edit
proc terminalSize(): tuple[w, h: int] {....raises: [], tags: [], 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: [], forbids: [].}
Returns the terminal width in columns.Source Edit
proc writeStyled(txt: string; style: set[Style] = {styleBright}) {. ...raises: [IOError], tags: [RootEffect, 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")
Templates
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)