term #

Description

The term module is designed to provide the building blocks for building very simple TUI apps. For more complex apps, you should really look at the term.ui module, as it includes terminal events, is easier to use and is much more performant for large draws.

Usage

You can use the term module to either color the output on a terminal or to decide on where to put the output in your terminal.

For example let's make a simple program which prints colored text in the middle of the terminal.

import term
import os

fn main() {
    term.clear() // clears the content in the terminal
    width, height := term.get_terminal_size() // get the size of the terminal
    term.set_cursor_position(x: width / 2, y: height / 2) // now we point the cursor to the middle of  the terminal
    println(term.strikethrough(term.bright_green('hello world'))) // Print green text
    term.set_cursor_position(x: 0, y: height) // Sets the position of the cursor to the bottom of the terminal
    // Keep prompting until the user presses the q key
    for {
        if var := os.input_opt('press q to quit: ') {
            if var != 'q' {
                continue
            }
            break
        }
        println('')
        break
    }
    println('Goodbye.')
}

This simple program covers many of the principal aspects of the term module.

API

Here are some of the main functions of the term module:

import term

// returns the height and the width of the terminal
width, height := term.get_terminal_size()
println('width: ${width}, height: ${height}')
// returns the string as green text to be printed on stdout
term.ok_message('cool')
// returns the string as red text to be printed on stdout
term.fail_message('oh, no')
// returns the string as yellow text to be printed on stdout
term.warn_message('be warned')
// clears the entire terminal and leaves a blank one
term.clear()

// Set the color output of the output.
// The available colors are:
// black, white, blue, yellow,
// green, red, cyan, magenta,
// bright_black, bright_white, bright_blue, bright_yellow,
// bright_green, bright_red, bright_cyan, bright_magenta,
term.yellow('submarine')

// transforms the given string into bold text
term.bold('and beautiful')
// puts a strikethrough into the given string
term.strikethrough('the core of the problem')
// underlines the given string
term.underline('important')
// colors the background of the output following the given color
// the available colors are: black, blue, yellow, green, cyan, gray
term.bg_green('field')
// sets the position of the cursor at a given place in the terminal
term.set_cursor_position(x: 5, y: 10)
// moves the cursor up
term.cursor_up(1)
// moves the cursor down
term.cursor_down(1)
// moves the cursor to the right
term.cursor_forward(2)
// moves the cursor to the left
term.cursor_back(2)
// hides the cursor
term.hide_cursor()
// shows the cursor
term.show_cursor()

fn bg_black(msg string) string

bg_black formats the msg in black background.

fn bg_blue(msg string) string

bg_blue formats the msg in blue background.

fn bg_cyan(msg string) string

bg_cyan formats the msg in cyan background.

fn bg_green(msg string) string

bg_green formats the msg in green background.

fn bg_hex(hex int, msg string) string

hex returns the msg with the background in the specified hex color. For example, bg_rgb(255, 'hi') returns the 'hi' string in a background of blue color, which is (0, 0, 255) in RGB.

fn bg_magenta(msg string) string

bg_magenta formats the msg in magenta background.

fn bg_red(msg string) string

bg_red formats the msg in red background.

fn bg_rgb(r int, g int, b int, msg string) string

bg_rgb returns the msg with the background in the specified RGB color. For example, bg_rgb(255, 0, 0, 'hi') returns the text 'hi' in red color.

fn bg_white(msg string) string

bg_white formats the msg in white background.

fn bg_yellow(msg string) string

bg_yellow formats the msg in yellow background.

fn black(msg string) string

black formats the msg in black.

fn blue(msg string) string

blue formats the msg in blue.

fn bold(msg string) string

bold returns the given msg in bold.

fn bright_bg_black(msg string) string

bright_bg_black formats the msg in bright black background.

fn bright_bg_blue(msg string) string

bright_bg_blue formats the msg in bright blue background.

fn bright_bg_cyan(msg string) string

bright_bg_cyan formats the msg in bright cyan background.

fn bright_bg_green(msg string) string

bright_bg_green formats the msg in bright green background.

fn bright_bg_magenta(msg string) string

bright_bg_magenta formats the msg in bright magenta background.

fn bright_bg_red(msg string) string

bright_bg_red formats the msg in bright red background.

fn bright_bg_white(msg string) string

bright_bg_white formats the msg in bright white background.

fn bright_bg_yellow(msg string) string

bright_bg_yellow formats the msg in bright yellow background.

fn bright_black(msg string) string

bright_black formats the msg in bright black.

fn bright_blue(msg string) string

bright_blue formats the msg in bright blue.

fn bright_cyan(msg string) string

bright_cyan formats the msg in bright cyan.

fn bright_green(msg string) string

bright_green formats the msg in bright green.

fn bright_magenta(msg string) string

bright_magenta formats the msg in bright magenta.

fn bright_red(msg string) string

bright_red formats the msg in bright red.

fn bright_white(msg string) string

bright_white formats the msg in bright white.

fn bright_yellow(msg string) string

bright_yellow formats the msg in bright yellow.

fn can_show_color_on_stderr() bool

can_show_color_on_stderr returns true, if colors are allowed in stderr. It returns false otherwise.

fn can_show_color_on_stdout() bool

can_show_color_on_stdout returns true, if colors are allowed in stdout. It returns false otherwise.

fn clear() bool

clear clears current terminal screen.

fn clear_previous_line()

clear_previous_line - useful for progressbars. It moves the cursor to start of line, then 1 line above, then erases the line. In effect the next println will overwrite the previous content.

fn colorize(cfn fn (string) string, s string) string

colorize returns a colored string by running the specified cfn over the message s, but only if colored stdout is supported by the terminal.

term.colorize(term.yellow, 'the message')

fn cursor_back(n int)

cursor_back moves the cursor back n characters.

fn cursor_down(n int)

cursor_down moves the cursor down n lines.

fn cursor_forward(n int)

cursor_forward moves the cursor forward n character positions.

fn cursor_up(n int)

cursor_up moves the cursor up n lines.

fn cyan(msg string) string

cyan formats the msg in cyan.

fn dim(msg string) string

dim returns the dimmed msg.

fn ecolorize(cfn fn (string) string, s string) string

ecolorize returns a colored string by running the specified cfn over the message s, but only if colored stderr is supported by the terminal.

term.ecolorize(term.bright_red, 'the message')

fn enable_echo(enable bool)

enable_echo enable/disable echo input characters.

fn erase_clear()

erase_clear clears the entire terminal window and returns the cursor to the top left corner.

fn erase_del_clear()

erase_del_clear erases saved lines.

fn erase_display(t string)

erase_display erases display characters based on the given parameter, t. t can be of the following values in string: 0: current cursor position to end of the terminal window. 1: current cursor position to beginning of the terminal window. 2: clears the entire terminal window. 3: clears the entire terminal window and also deletes the scrollback buffer.

fn erase_line(t string)

erase_line erases the current line based on the given parameter, t. t can be of the following values in string: 0: current cursor position to the end of the line. 1: current cursor position to the beginning of the line. 2: clears the entire line.

Note: Cursor position does not change.

fn erase_line_clear()

erase_line_clear erases the entire line.

fn erase_line_tobeg()

erase_line_tobeg erases from the start of the line to the cursor position.

fn erase_line_toend()

erase_line_toend erases from the cursor position to the end of the line.

fn erase_tobeg()

erase_tobeg erases from the cursor to the beginning of the terminal window.

fn erase_toend()

erase_to_end erases from the cursor to the end of the terminal window.

fn fail_message(s string) string

fail_message returns a colored string with red color. If colors are not allowed, returns a given string.

fn failed(s string) string

failed returns a bold white on red version of the string s. If colors are not allowed, returns the string s

fn format(msg string, open string, close string) string

format returns ANSI escape coded msg formatted with a preceding open and a succeeding close. For instance, format('hi', '9', '29') returns '\x1b[9mhi\x1b[29m', or 'hi' with strikethrough, where '\x1b[9m' represents crossed out/strikethrough text and '\x1b[29m' turns off strikethrough.

fn format_esc(code string) string

format_esc produces an ANSI escape code, for selecting the graphics rendition of the following text. Each of the attributes that can be passed in code, separated by ;, will be in effect, until the terminal encounters another SGR ANSI escape code. For more details about the different codes, and their meaning, see: https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters

fn format_rgb(r int, g int, b int, msg string, open string, close string) string

format_rgb returns ANSI escape coded msg formatted with a preceding open, a succeeding close and the provided RGB colors r, g, and b.

fn get_cursor_position() !Coord

get_cursor_position returns a Coord containing the current cursor position.

fn get_terminal_size() (int, int)

get_terminal_size returns a number of columns and rows of terminal window.

fn graphics_num_colors() u16

graphics_num_colors returns the number of color registers the terminal graphic attribute is set to use. This can be useful to know if the terminal is configured to support Sixel graphics.

See "CSI ? Pi ; Pa ; Pv S" from https://invisible-island.net/xterm/ctlseqs/ctlseqs.html

fn gray(msg string) string

gray formats the msg in gray (equivalent to bright_black).

fn green(msg string) string

green formats the msg in green.

fn h_divider(divider string) string

h_divider returns a horizontal divider line with a dynamic width, that depends on the current terminal settings. If an empty string is passed in, print enough spaces to make a new line.

fn header(text string, divider string) string

header returns a horizontal divider line with a centered text in the middle. e.g: term.header('TEXT', '=') =============== TEXT ===============

fn header_left(text string, divider string) string

header_left returns a horizontal divider line with a title text on the left. e.g: term.header_left('TITLE', '=') ==== TITLE =========================

fn hex(hex int, msg string) string

hex returns the msg with the foreground in the specified hex color. For example, rgb(255, 'hi') returns the 'hi' string in blue color, which is (0, 0, 255) in RGB.

fn hidden(msg string) string

hidden hides the given msg.

fn hide_cursor()

Will make cursor invisible

fn highlight_command(command string) string

highlight_command highlights the command with an on-brand background to make CLI commands immediately recognizable.

fn inverse(msg string) string

inverse inverses the given msg.

fn italic(msg string) string

italic returns the given msg in italic.

fn key_pressed(params KeyPressedParams) i64

key_pressed gives back a single character, read from the standard input. It returns -1 on error or no character in non-blocking mode

fn magenta(msg string) string

magenta formats the msg in magenta.

fn move(n int, direction string)

move the cursor relative to its current position. n is number of cells. direction: A is up / North direction: B is down / South direction: C is forward / East direction: D is backward / West

fn ok_message(s string) string

ok_message returns a colored string with green color. If colors are not allowed, returns a given string.

fn rapid_blink(msg string) string

rapid_blink will surround the msg with ANSI escape codes for blinking (over 150 times per minute). Note that unlike slow_blink, this is not very widely supported.

fn red(msg string) string

red formats the msg in red.

fn reset(msg string) string

reset resets all formatting for msg.

fn rgb(r int, g int, b int, msg string) string

rbg returns the msg with the foreground in the specified RGB color For example, rgb(0, 255, 0, 'hi') returns the 'hi' string in lime color.

fn set_cursor_position(c Coord)

Sources for ANSI Control Sequences https://github.com/RajeshPatkarInstitute/Panim https://www.gnu.org/software/screen/manual/html_node/Control-Sequences.html https://en.wikipedia.org/wiki/ANSI_escape_code Support for Windows https://en.wikipedia.org/wiki/ANSI.SYS #include <windows.h> C.SetConsoleMode(C.ENABLE_VIRTUAL_TERMINAL_INPUT) Setting cursor to the given position x is the x coordinate y is the y coordinate

fn set_tab_title(title string) bool

set_tab_title changes the terminal tab title, for terminal emulators like Konsole, that support several tabs.

fn set_terminal_title(title string) bool

set_terminal_title change the terminal title (usually that is the containing terminal window title).

fn show_cursor()

show_cursor makes the cursor appear if it was not visible.

fn slow_blink(msg string) string

slow_blink will surround the msg with ANSI escape codes for blinking (less than 150 times per minute).

fn strikethrough(msg string) string

strikethrough returns the given msg in strikethrough.

fn strip_ansi(text string) string

strip_ansi removes any ANSI sequences in the text.

fn supports_sixel() bool

supports_sixel returns true if the terminal supports Sixel graphics

For more info on the sixel format: See https://en.wikipedia.org/wiki/Sixel See https://www.digiater.nl/openvms/decus/vax90b1/krypton-nasa/all-about-sixels.text For more info on terminal support: See https://www.arewesixelyet.com

fn underline(msg string) string

underline returns the underlined msg.

fn utf8_getchar() ?rune

utf8_getchar returns an utf8 rune from standard input.

fn utf8_len(c u8) int

utf8_len calculates the length of a utf8 rune to read, according to its first byte.

fn warn_message(s string) string

warn_message returns a colored string with yellow color. If colors are not allowed, returns a given string.

fn white(msg string) string

white formats the msg in white.

fn write_color(mut b strings.Builder, s string, config ColorConfig)

write_color appends the ANSI colorful string s to the buffer.

fn writeln_color(mut b strings.Builder, s string, color ColorConfig)

writeln_color appends the ANSI colorful string s, and then a newline character.

fn yellow(msg string) string

yellow formats the msg in yellow.

enum BgColor {
	black   = 40
	red     = 41
	green   = 42
	yellow  = 43
	blue    = 44
	magenta = 45
	cyan    = 46
	white   = 47
}

enum FgColor {
	black   = 30
	red     = 31
	green   = 32
	yellow  = 33
	blue    = 34
	magenta = 35
	cyan    = 36
	white   = 37
}

enum TextStyle {
	bold      = 1
	dim       = 2
	italic    = 3
	underline = 4
	blink     = 5
	reverse   = 7
}

struct C.termios {
mut:
	c_iflag int
	c_oflag int
	c_cflag int
	c_lflag int
	//	c_line  byte
	c_cc [10]int
}

struct C.winsize {
pub:
	ws_row    u16
	ws_col    u16
	ws_xpixel u16
	ws_ypixel u16
}

struct ColorConfig {
pub mut:
	styles []TextStyle
	fg     ?FgColor
	bg     ?BgColor
	custom string
}

struct Coord {
pub mut:
	x int
	y int
}

Coord - used by term.get_cursor_position and term.set_cursor_position.

struct KeyPressedParams {
pub mut:
	blocking bool // whether to wait for a pressed key
	echo     bool // whether to output the pressed key to stdout
}

KeyPressedParams contains the optional parameters that you can pass to key_pressed.