terminal

nimony/lib/std/terminal.nim

This module contains a few procedures to control the terminal (also called console). Styles and colors are written as ANSI escape sequences on every platform, so on Windows they need a terminal with virtual terminal processing (Windows Terminal, or Windows 10+ conhost after enableTrueColors). Cursor movement, erasing and the terminal size use the console API on Windows, like Nim's std/terminal.

True color (Color from std/colors) is off until enableTrueColors is called, as in Nim; ansiForegroundColorCode(Color) and ansiBackgroundColorCode(Color) always return the escape sequence.

Not ported: getch, readPasswordFromStdin, getCursorPos, setCursorYPos and writeStyled.

const fgPrefix: string
const bgPrefix: string
const ansiResetCode: string
const stylePrefix: string
type Style = HoleyEnum
func dollar`.Style(e: Style): string
type ForegroundColor = HoleyEnum
func dollar`.ForegroundColor(e: ForegroundColor): string
type BackgroundColor = HoleyEnum
func dollar`.BackgroundColor(e: BackgroundColor): string

type TerminalCmd = enum
  resetStyle = (0, "resetStyle")
  fgColor = (1, "fgColor")
  bgColor = (2, "bgColor")

func dollar`.TerminalCmd(e: TerminalCmd): string
proc ansiStyleCode(style: int64): string
proc ansiStyleCode(style: Style): string
proc ansiForegroundColorCode(fg: ForegroundColor; bright: bool): string
proc ansiBackgroundColorCode(bg: BackgroundColor; bright: bool): string
proc ansiForegroundColorCode(color: Color): string
The escape sequence that sets the foreground to the true color color: \e[38;2;R;G;Bm.
proc ansiBackgroundColorCode(color: Color): string
The escape sequence that sets the background to the true color color: \e[48;2;R;G;Bm.
proc resetAttributes(f: ref FileObj)
Resets all attributes.
proc setStyle(f: ref FileObj; style: Style)
Sets a single terminal style attribute.
proc setStyle(f: ref FileObj; style: set[Style])
Sets the terminal style.
proc setForegroundColor(f: ref FileObj; fg: ForegroundColor; bright: bool)
Sets the terminal's foreground color.
proc setBackgroundColor(f: ref FileObj; bg: BackgroundColor; bright: bool)
Sets the terminal's background color.
proc isatty(f: ref FileObj): bool
Returns true if f is associated with a terminal device.
proc terminalWidth(): int64
Returns the terminal width in columns: the COLUMNS environment variable if set, else the size of the terminal attached to a standard stream (or, on POSIX, of the controlling terminal), else 80.
proc terminalHeight(): int64
Returns the terminal height in rows: the LINES environment variable if set, else the size of the terminal attached to a standard stream (or, on POSIX, of the controlling terminal), else 24. (Nim returns 0 instead.)
proc terminalSize(): tuple[w: int64, h: int64]
Returns the terminal width and height as a tuple. Internally calls terminalWidth and terminalHeight, so the same assumptions apply.
proc hideCursor(f: ref FileObj)
Hides the cursor.
proc showCursor(f: ref FileObj)
Shows the cursor.
proc setCursorPos(f: ref FileObj; x: int64; y: int64)
Sets the terminal's cursor to the (x,y) position. (0,0) is the upper left of the screen.
proc setCursorXPos(f: ref FileObj; x: int64)
Sets the terminal's cursor to the x position. The y position is not changed.
proc cursorUp(f: ref FileObj; count: int64)
Moves the cursor up by count rows.
proc cursorDown(f: ref FileObj; count: int64)
Moves the cursor down by count rows.
proc cursorForward(f: ref FileObj; count: int64)
Moves the cursor forward by count columns.
proc cursorBackward(f: ref FileObj; count: int64)
Moves the cursor backward by count columns.
proc eraseLine(f: ref FileObj)
Erases the entire current line and moves the cursor to its start.
proc eraseScreen(f: ref FileObj)
Erases the screen with the background colour and moves the cursor to home.
proc isTrueColorSupported(): bool
Returns true if a terminal supports true color. Only known after enableTrueColors was called (on the current thread).
proc enableTrueColors()
Enables true color if the terminal supports it: on POSIX when COLORTERM is truecolor or 24bit; on Windows when ANSICON is active or the console accepts virtual terminal processing, which this turns on for stdout.
proc disableTrueColors()
Disables true color: setForegroundColor(f, Color) and friends write nothing afterwards. (Unlike Nim, the Windows console mode is left alone, since the styles of this module are ANSI sequences there too.)
proc setForegroundColor(f: ref FileObj; color: Color)
Sets the terminal's foreground true color, if true color is enabled.
proc setBackgroundColor(f: ref FileObj; color: Color)
Sets the terminal's background true color, if true color is enabled.
proc styledEchoProcessArg(f: ref FileObj; s: string)
proc styledEchoProcessArg(f: ref FileObj; c: char)
proc styledEchoProcessArg(f: ref FileObj; style: Style)
proc styledEchoProcessArg(f: ref FileObj; style: set[Style])
proc styledEchoProcessArg(f: ref FileObj; color: ForegroundColor)
proc styledEchoProcessArg(f: ref FileObj; color: BackgroundColor)
proc styledEchoProcessArg(f: ref FileObj; color: Color)
Sets the foreground or background true color, whichever the last fgColor/bgColor argument selected (background by default, as in Nim).
proc styledEchoProcessArg(f: ref FileObj; cmd: TerminalCmd)
template styledWrite(f: ref FileObj; vanon: varargs)
Similar to write, but treating terminal style arguments specially. When an argument is Style, set[Style], ForegroundColor, BackgroundColor, Color or TerminalCmd the corresponding terminal style proc is called instead of writing the value directly.
template styledWriteLine(f: ref FileObj; vanon: varargs)
Calls styledWrite and appends a newline at the end.
template hideCursor()
template showCursor()
template setCursorPos(x: int64; y: int64)
template setCursorXPos(x: int64)
template cursorUp(count: int64)
template cursorDown(count: int64)
template cursorForward(count: int64)
template cursorBackward(count: int64)
template eraseLine()
template eraseScreen()
template setStyle(style: set[Style])
template setForegroundColor(fg: ForegroundColor; bright: bool)
template setBackgroundColor(bg: BackgroundColor; bright: bool)
template setForegroundColor(color: Color)
template setBackgroundColor(color: Color)
proc resetAttributes()
Resets all attributes on stdout.