term

README

Go 1.18+ Terminal Escapes, Color, Size

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

Documentation

Overview

Package term provides traditional terminal escapes and interactions including an Prompter/Responder specification for Expect-like, line-based APIs, communications, and user interfaces.

Index

• Variables
• func AttrOff()
• func AttrOn()
• func DetectInteractive() bool
• func EmphFromLess()
• func IsAttrOn() bool
• func IsInteractive() bool
• func Print(a ...any) (int, error)
• func Printf(format string, a ...any) (int, error)
• func Prompt(form string, args ...any) string
• func PromptHidden(form string, args ...any) string
• func REPL(prompt, respond InOutFunc)
• func Read() string
• func ReadHidden() string
• func SetInteractive(to bool)
• func StripNonPrint(s string) string
• func WinSizeUpdate()
• type InOutFunc
• type WinSizeStruct

Examples

• EmphFromLess
• REPL
• 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 TrapPanic = func() {
	if r := recover(); r != nil {
		log.Println(r)
		os.Exit(1)
	}
}

TrapPanic recovers from any panic and more gracefully displays the panic by logging it before exiting. See log package for ways to alter the output of the embedded log.Println function.

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 IsAttrOn

func IsAttrOn() bool

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

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 Print

func Print(a ...any) (int, error)

Print calls Println if IsInteractive, otherwise, Print. This works better with applications that would otherwise need to trim the tailing line return to set that as values for shell variables.

func Printf

func Printf(format string, a ...any) (int, error)

Printf calls fmt.Printf directly but adds a line return if IsInteractive.

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 as that passed 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 REPL

func REPL(prompt, respond InOutFunc)

REPL starts a rudimentary, functional, read-evaluate print loop passing each line of prompted input to the respond function as it is entered, printing the response, and then prompting for another. No tab-completion is supported or planned. In this way, a REPL can be used to connect prompt and respond functions by passing input/output back and forth.

The output from the prompt function will be printed directly to the terminal before prompting for more input. Most prompt function implementations will print a preceding line return. Prompt function implementations must state explicitly any terminal requirements (plain text, markup, VT100 compatible, etc.)

Response functions can be useful for encapsulating bots and other intelligent responders to any terminal input. In theory, one respond function can be connected to another. In that sense, respond functions are a rudimentary, single-line replacement for other API interactions (such as rest).

Either prompt or respond functions may use panic or os.Exit to end the program, but panic is generally preferred since the REPL (or other caller) can trap it and exit gracefully. Panics within a REPL are generally sent directly to the user and therefore may break the all-lowercase convention normally observed for panic messages.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/term"
)

func main() {
	defer term.TrapPanic()

	// both are enclosed in prompt/respond functions
	var history []string
	hcount := 1

	prompt := func(_ string) string {
		if hcount > 3 {
			panic("All done.")
		}
		return fmt.Sprintf("%v> ", hcount)
	}

	respond := func(in string) string {
		hcount++
		history = append(history, in)
		return "okay"
	}

	term.REPL(prompt, respond)
}

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()

WinSizeUpdate makes a SYS_IOCTL syscall to get the information for the current terminal. This returns nothing but zeros unless the terminal is interactive (standard output is a terminal). Consider gdamore/tcell if more reliable dimensions are needed.

Types

type InOutFunc

type InOutFunc func(in string) string

InOutFunc is a function that takes input as a string and simply responds based on that input.

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.