term

README

Go 1.18+ Terminal Escapes, Color, Size

• VT100 Terminal ANSI Escapes
• Terminal Size
• AttrOn/AttrOff
• IsInteractive/SetInteractive
• EmphFromLess

Documentation

Index

• Variables
• func AttrOff()
• func AttrOn()
• func DetectInteractive() bool
• func EmphFromLess()
• func IsInteractive() bool
• func Prompt(form string, args ...any) string
• func PromptHidden(form string, args ...any) string
• func Read() string
• func ReadHidden() string
• func SetInteractive(to bool)
• func StripNonPrint(s string) string
• func WinSizeUpdate()
• type WinSizeStruct

Examples

• EmphFromLess
• StripNonPrint

Variables

var (
	Reset      string
	Bright     string
	Bold       string
	Dim        string
	Italic     string
	Under      string
	Blink      string
	BlinkF     string
	Reverse    string
	Hidden     string
	Strike     string
	BoldItalic string
	Black      string
	Red        string
	Green      string
	Yellow     string
	Blue       string
	Magenta    string
	Cyan       string
	White      string
	BBlack     string
	BRed       string
	BGreen     string
	BYellow    string
	BBlue      string
	BMagenta   string
	BCyan      string
	BWhite     string
	HBlack     string
	HRed       string
	HGreen     string
	HYellow    string
	HBlue      string
	HMagenta   string
	HCyan      string
	HWhite     string
	BHBlack    string
	BHRed      string
	BHGreen    string
	BHYellow   string
	BHBlue     string
	BHMagenta  string
	BHCyan     string
	BHWhite    string
	X          string
	B          string
	I          string
	U          string
	BI         string
)

var AttrAreOn bool

AttrAreOn contains the state of the last AttrOn/AttrOff call.

Functions

func AttrOff

func AttrOff()

AttrOff sets all the terminal attributes to zero values (empty strings). Note that this does not affect anything in the esc subpackage (which contains the constants from the VT100 specification). Sets the AttrAreOn bool to false.

func AttrOn

func AttrOn()

AttrOn sets all the terminal attributes to zero values (empty strings). Note that this does not affect anything in the esc subpackage (which contains the constants from the VT100 specification). Sets the AttrAreOn bool to true.

func DetectInteractive

func DetectInteractive() bool

DetectInteractive returns true if the output is to an interactive terminal (not piped in any way).

func EmphFromLess

func EmphFromLess()

EmphFromLess sets Italic, Bold, BoldItalic, and Under from the LESS_TERMCAP_us, _md, _mb, and _us environment variables respectively. This is a long used way to provide color to UNIX man pages dating back to initial color terminals. UNIX users frequently set these to provide color to man pages and more. Observes AttrAreOn and will simply return if set to false. EmphFromLess is called at package init() time automatically.

Example

package main

import (
	"fmt"
	"os"

	"github.com/rwxrob/term"
	"github.com/rwxrob/term/esc"
)

func main() {

	/*
	   export LESS_TERMCAP_mb="�[35m" # magenta
	   export LESS_TERMCAP_md="�[33m" # yellow
	   export LESS_TERMCAP_me="" # "�0m"
	   export LESS_TERMCAP_se="" # "�0m"
	   export LESS_TERMCAP_so="�[34m" # blue
	   export LESS_TERMCAP_ue="" # "�0m"
	   export LESS_TERMCAP_us="�[4m"  # underline
	*/

	os.Setenv("LESS_TERMCAP_mb", esc.Magenta)
	os.Setenv("LESS_TERMCAP_md", esc.Yellow)
	os.Setenv("LESS_TERMCAP_me", esc.Reset)
	os.Setenv("LESS_TERMCAP_se", esc.Reset)
	os.Setenv("LESS_TERMCAP_so", esc.Blue)
	os.Setenv("LESS_TERMCAP_ue", esc.Reset)
	os.Setenv("LESS_TERMCAP_us", esc.Under)

	term.EmphFromLess()

	fmt.Printf("%q\n", term.Italic+"italic"+term.Reset)
	fmt.Printf("%q\n", term.Bold+"bold"+term.Reset)
	fmt.Printf("%q\n", term.BoldItalic+"bolditalic"+term.Reset)
	fmt.Printf("%q\n", term.Under+"under"+term.Reset)

}

Output:

"\x1b[4mitalic\x1b[0m"
"\x1b[33mbold\x1b[0m"
"\x1b[35mbolditalic\x1b[0m"
"\x1b[4munder\x1b[0m"

func IsInteractive

func IsInteractive() bool

IsInteractive returns the internal interactive state set by SetInteractive. The default is that returned by DetectInteractive set at init() time.

func Prompt

func Prompt(form string, args ...any) string

Prompt prints the given message if the terminal IsInteractive and reads the string by calling Read. The argument signature is identical and passed to to fmt.Printf().

func PromptHidden

func PromptHidden(form string, args ...any) string

PromptHidden prints the given message if the terminal IsInteractive and reads the string by calling ReadHidden (which does not echo to the screen). The argument signature is identical and passed to to fmt.Printf().

func Read

func Read() string

Read reads a single line of input and chomps the \r?\n. Also see ReadHidden.

func ReadHidden

func ReadHidden() string

ReadHidden disables the cursor and echoing to the screen and reads a single line of input. Leading and trailing whitespace are removed. Also see Read.

func SetInteractive

func SetInteractive(to bool)

SetInteractive forces the interactive internal state affecting output including calling AttrOn (true) or AttrOff (false).

func StripNonPrint

func StripNonPrint(s string) string

StripNonPrint remove non-printable runes, e.g. control characters in a string that is meant for consumption by terminals that support control characters.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/term"
	"github.com/rwxrob/term/esc"
)

func main() {
	some := esc.Bold + "not bold" + esc.Reset
	fmt.Println(term.StripNonPrint(some))
	// Output;
	// not bold
}

func WinSizeUpdate

func WinSizeUpdate()

Types

type WinSizeStruct

type WinSizeStruct struct {
	Row, Col       uint16
	Xpixel, Ypixel uint16
}

WinSizeStruct is the exact struct used by the ioctl system library.

var WinSize WinSizeStruct

WinSize is 80x24 by default but is detected and set to a more accurate value at init() time on systems that support ioctl (currently) and can be updated with WinSizeUpdate on systems that support it. This value can be overriden by those wishing a more consistent value or who prefer not to fill the screen completely when displaying help and usage information.