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 functions you should be aware of in the term module:

import term

// returns the height and the width of the terminal
width, height := term.get_terminal_size()
// 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()
// colors the output of the output, the available colors are:
// black,blue,yellow,green,cyan,gray,bright_blue,bright_green,bright_red,bright_black,bright_cyan
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()
// moves the cursor down
term.cursor_down()
// moves the cursor to the right
term.cursor_forward()
// moves the cursor to the left
term.cursor_back()
// shows the cursor
term.show_cursor()
// hides the cursor
term.hide_cursor()

fn bg_black(msg string) string

fn bg_blue(msg string) string

fn bg_cyan(msg string) string

fn bg_green(msg string) string

fn bg_hex(hex int, msg string) string

fn bg_magenta(msg string) string

fn bg_red(msg string) string

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

fn bg_white(msg string) string

fn bg_yellow(msg string) string

fn black(msg string) string

fn blue(msg string) string

fn bold(msg string) string

fn bright_bg_black(msg string) string

fn bright_bg_blue(msg string) string

fn bright_bg_cyan(msg string) string

fn bright_bg_green(msg string) string

fn bright_bg_magenta(msg string) string

fn bright_bg_red(msg string) string

fn bright_bg_white(msg string) string

fn bright_bg_yellow(msg string) string

fn bright_black(msg string) string

fn bright_blue(msg string) string

fn bright_cyan(msg string) string

fn bright_green(msg string) string

fn bright_magenta(msg string) string

fn bright_red(msg string) string

fn bright_white(msg string) string

fn bright_yellow(msg string) string

fn can_show_color_on_stderr() bool

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

fn can_show_color_on_stdout() bool

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

fn clear()

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, only if colored stdout is supported by the terminal.

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

fn cursor_back(n int)

fn cursor_down(n int)

fn cursor_forward(n int)

fn cursor_up(n int)

fn cyan(msg string) string

fn dim(msg string) string

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

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

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

fn erase_clear()

clears entire screen and returns cursor to top left-corner

fn erase_del_clear()

fn erase_display(t string)

type: 0 -> current cursor position to end of the screen type: 1 -> current cursor position to beginning of the screen type: 2 -> clears entire screen type: 3 -> clears entire screen and also delete scrollback buffer

fn erase_line(t string)

type: 0 -> current cursor position to end of the line type: 1 -> current cursor position to beginning of the line type: 2 -> clears entire line Note: Cursor position does not change

fn erase_line_clear()

fn erase_line_tobeg()

fn erase_line_toend()

fn erase_tobeg()

fn erase_toend()

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

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

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 colums and rows of terminal window.

fn gray(msg string) string

fn green(msg string) string

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

fn hidden(msg string) string

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

fn italic(msg string) string

fn magenta(msg string) string

fn move(n int, direction string)

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 red(msg string) string

fn reset(msg string) string

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

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_terminal_title(title string) bool

set_terminal_title change the terminal title

fn show_cursor()

Will make cursor appear if not visible

fn strikethrough(msg string) string

fn strip_ansi(text string) string

strip_ansi removes any ANSI sequences in the text

fn underline(msg string) string

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

fn yellow(msg string) string

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 Coord {
pub mut:
	x int
	y int
}

Coord - used by term.get_cursor_position and term.set_cursor_position