termenv

package module
v0.15.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 26, 2023 License: MIT Imports: 16 Imported by: 795

README

termenv Logo
Latest Release GoDoc Build Status Coverage Status Go ReportCard
Example terminal output

termenv lets you safely use advanced styling options on the terminal. It gathers information about the terminal environment in terms of its ANSI & color support and offers you convenient methods to colorize and style your output, without you having to deal with all kinds of weird ANSI escape sequences and color conversions.

Features

  • RGB/TrueColor support
  • Detects the supported color range of your terminal
  • Automatically converts colors to the best matching, available colors
  • Terminal theme (light/dark) detection
  • Chainable syntax
  • Nested styles

Installation

go get github.com/muesli/termenv

Usage

output := termenv.NewOutput(os.Stdout)

termenv queries the terminal's capabilities it is running in, so you can safely use advanced features, like RGB colors or ANSI styles. output.Profile returns the supported profile:

  • termenv.Ascii - no ANSI support detected, ASCII only
  • termenv.ANSI - 16 color ANSI support
  • termenv.ANSI256 - Extended 256 color ANSI support
  • termenv.TrueColor - RGB/TrueColor support

Alternatively, you can use termenv.EnvColorProfile which evaluates the terminal like ColorProfile, but also respects the NO_COLOR and CLICOLOR_FORCE environment variables.

You can also query the terminal for its color scheme, so you know whether your app is running in a light- or dark-themed environment:

// Returns terminal's foreground color
color := output.ForegroundColor()

// Returns terminal's background color
color := output.BackgroundColor()

// Returns whether terminal uses a dark-ish background
darkTheme := output.HasDarkBackground()

Manual Profile Selection

If you don't want to rely on the automatic detection, you can manually select the profile you want to use:

output := termenv.NewOutput(os.Stdout, termenv.WithProfile(termenv.TrueColor))

Colors

termenv supports multiple color profiles: Ascii (black & white only), ANSI (16 colors), ANSI Extended (256 colors), and TrueColor (24-bit RGB). Colors will automatically be degraded to the best matching available color in the desired profile:

TrueColor => ANSI 256 Colors => ANSI 16 Colors => Ascii

s := output.String("Hello World")

// Supports hex values
// Will automatically degrade colors on terminals not supporting RGB
s.Foreground(output.Color("#abcdef"))
// but also supports ANSI colors (0-255)
s.Background(output.Color("69"))
// ...or the color.Color interface
s.Foreground(output.FromColor(color.RGBA{255, 128, 0, 255}))

// Combine fore- & background colors
s.Foreground(output.Color("#ffffff")).Background(output.Color("#0000ff"))

// Supports the fmt.Stringer interface
fmt.Println(s)

Styles

You can use a chainable syntax to compose your own styles:

s := output.String("foobar")

// Text styles
s.Bold()
s.Faint()
s.Italic()
s.CrossOut()
s.Underline()
s.Overline()

// Reverse swaps current fore- & background colors
s.Reverse()

// Blinking text
s.Blink()

// Combine multiple options
s.Bold().Underline()

Template Helpers

termenv provides a set of helper functions to style your Go templates:

// load template helpers
f := output.TemplateFuncs()
tpl := template.New("tpl").Funcs(f)

// apply bold style in a template
bold := `{{ Bold "Hello World" }}`

// examples for colorized templates
col := `{{ Color "#ff0000" "#0000ff" "Red on Blue" }}`
fg := `{{ Foreground "#ff0000" "Red Foreground" }}`
bg := `{{ Background "#0000ff" "Blue Background" }}`

// wrap styles
wrap := `{{ Bold (Underline "Hello World") }}`

// parse and render
tpl, err = tpl.Parse(bold)

var buf bytes.Buffer
tpl.Execute(&buf, nil)
fmt.Println(&buf)

Other available helper functions are: Faint, Italic, CrossOut, Underline, Overline, Reverse, and Blink.

Positioning

// Move the cursor to a given position
output.MoveCursor(row, column)

// Save the cursor position
output.SaveCursorPosition()

// Restore a saved cursor position
output.RestoreCursorPosition()

// Move the cursor up a given number of lines
output.CursorUp(n)

// Move the cursor down a given number of lines
output.CursorDown(n)

// Move the cursor up a given number of lines
output.CursorForward(n)

// Move the cursor backwards a given number of cells
output.CursorBack(n)

// Move the cursor down a given number of lines and place it at the beginning
// of the line
output.CursorNextLine(n)

// Move the cursor up a given number of lines and place it at the beginning of
// the line
output.CursorPrevLine(n)

Screen

// Reset the terminal to its default style, removing any active styles
output.Reset()

// RestoreScreen restores a previously saved screen state
output.RestoreScreen()

// SaveScreen saves the screen state
output.SaveScreen()

// Switch to the altscreen. The former view can be restored with ExitAltScreen()
output.AltScreen()

// Exit the altscreen and return to the former terminal view
output.ExitAltScreen()

// Clear the visible portion of the terminal
output.ClearScreen()

// Clear the current line
output.ClearLine()

// Clear a given number of lines
output.ClearLines(n)

// Set the scrolling region of the terminal
output.ChangeScrollingRegion(top, bottom)

// Insert the given number of lines at the top of the scrollable region, pushing
// lines below down
output.InsertLines(n)

// Delete the given number of lines, pulling any lines in the scrollable region
// below up
output.DeleteLines(n)

Session

// SetWindowTitle sets the terminal window title
output.SetWindowTitle(title)

// SetForegroundColor sets the default foreground color
output.SetForegroundColor(color)

// SetBackgroundColor sets the default background color
output.SetBackgroundColor(color)

// SetCursorColor sets the cursor color
output.SetCursorColor(color)

// Hide the cursor
output.HideCursor()

// Show the cursor
output.ShowCursor()

// Copy to clipboard
output.Copy(message)

// Copy to primary clipboard (X11)
output.CopyPrimary(message)

// Trigger notification
output.Notify(title, body)

Mouse

// Enable X10 mouse mode, only button press events are sent
output.EnableMousePress()

// Disable X10 mouse mode
output.DisableMousePress()

// Enable Mouse Tracking mode
output.EnableMouse()

// Disable Mouse Tracking mode
output.DisableMouse()

// Enable Hilite Mouse Tracking mode
output.EnableMouseHilite()

// Disable Hilite Mouse Tracking mode
output.DisableMouseHilite()

// Enable Cell Motion Mouse Tracking mode
output.EnableMouseCellMotion()

// Disable Cell Motion Mouse Tracking mode
output.DisableMouseCellMotion()

// Enable All Motion Mouse mode
output.EnableMouseAllMotion()

// Disable All Motion Mouse mode
output.DisableMouseAllMotion()

Bracketed Paste

// Enables bracketed paste mode
termenv.EnableBracketedPaste()

// Disables bracketed paste mode
termenv.DisableBracketedPaste()

Terminal Feature Support

Color Support

  • 24-bit (RGB): alacritty, foot, iTerm, kitty, Konsole, st, tmux, vte-based, wezterm, Windows Terminal
  • 8-bit (256): rxvt, screen, xterm, Apple Terminal
  • 4-bit (16): Linux Console

Control Sequences

Click to show feature matrix
Terminal Query Color Scheme Query Cursor Position Set Window Title Change Cursor Color Change Default Foreground Setting Change Default Background Setting Bracketed Paste Extended Mouse (SGR) Pixels Mouse (SGR-Pixels)
alacritty ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌
foot ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
kitty ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Konsole ✅ ✅ ✅ ❌ ✅ ✅ ✅ ✅ ❌
rxvt ❌ ✅ ✅ ✅ ✅ ✅ ✅ ❌ ❌
urxvt ❌ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌
screen ⛔[^mux] ✅ ✅ ❌ ❌ ✅ ❌ ❌ ❌
st ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌
tmux ⛔[^mux] ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌
vte-based[^vte] ✅ ✅ ✅ ✅ ✅ ❌ ✅ ✅ ❌
wezterm ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
xterm ✅ ✅ ✅ ❌ ❌ ❌ ✅ ✅ ❌
Linux Console ❌ ✅ ⛔ ❌ ❌ ❌ ❌ ❌ ❌
Apple Terminal ✅ ✅ ✅ ❌ ✅ ✅ ✅ ✅ ❌
iTerm ✅ ✅ ✅ ❌ ❌ ❌ ✅ ✅ ❌
Windows cmd ❌ ✅ ✅ ✅ ✅ ✅ ❌ ❌ ❌
Windows Terminal ❌ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌

[^vte]: This covers all vte-based terminals, including Gnome Terminal, guake, Pantheon Terminal, Terminator, Tilix, XFCE Terminal. [^mux]: Unavailable as multiplexers (like tmux or screen) can be connected to multiple terminals (with different color settings) at the same time.

You can help improve this list! Check out how to and open an issue or pull request.

System Commands

Click to show feature matrix
Terminal Copy to Clipboard (OSC52) Hyperlinks (OSC8) Notifications (OSC777)
alacritty ✅ ❌[^alacritty] ❌
foot ✅ ✅ ✅
kitty ✅ ✅ ✅
Konsole ❌[^konsole] ✅ ❌
rxvt ❌ ❌ ❌
urxvt ✅[^urxvt] ❌ ✅
screen ✅ ❌[^screen] ❌
st ✅ ❌ ❌
tmux ✅ ❌[^tmux] ❌
vte-based[^vte] ❌[^vte] ✅ ❌
wezterm ✅ ✅ ❌
xterm ✅ ❌ ❌
Linux Console ⛔ ⛔ ❌
Apple Terminal ✅[^apple] ❌ ❌
iTerm ✅ ✅ ❌
Windows cmd ❌ ❌ ❌
Windows Terminal ✅ ✅ ❌

[^vte]: This covers all vte-based terminals, including Gnome Terminal, guake, Pantheon Terminal, Terminator, Tilix, XFCE Terminal. OSC52 is not supported, see issue#2495. [^urxvt]: Workaround for urxvt not supporting OSC52. See this for more information. [^konsole]: OSC52 is not supported, for more info see bug#372116. [^apple]: OSC52 works with a workaround. [^tmux]: OSC8 is not supported, for more info see issue#911. [^screen]: OSC8 is not supported, for more info see bug#50952. [^alacritty]: OSC8 is not supported, for more info see issue#922.

Platform Support

termenv works on Unix systems (like Linux, macOS, or BSD) and Windows. While terminal applications on Unix support ANSI styling out-of-the-box, on Windows you need to enable ANSI processing in your application first:

    restoreConsole, err := termenv.EnableVirtualTerminalProcessing(termenv.DefaultOutput())
    if err != nil {
        panic(err)
    }
    defer restoreConsole()

The above code is safe to include on non-Windows systems or when os.Stdout does not refer to a terminal (e.g. in tests).

Color Chart

ANSI color chart

You can find the source code used to create this chart in termenv's examples.

  • reflow - ANSI-aware text operations
  • Lip Gloss - style definitions for nice terminal layouts 👄
  • ansi - ANSI sequence helpers

termenv in the Wild

Need some inspiration or just want to see how others are using termenv? Check out these projects:

  • Bubble Tea - a powerful little TUI framework 🏗
  • Glamour - stylesheet-based markdown rendering for your CLI apps 💇🏻‍♀️
  • Glow - a markdown renderer for the command-line 💅🏻
  • duf - Disk Usage/Free Utility - a better 'df' alternative
  • gitty - contextual information about your git projects
  • slides - terminal-based presentation tool

Feedback

Got some feedback or suggestions? Please open an issue or drop me a note!

License

MIT

Documentation

Index

Constants

View Source 
const (
	Foreground = "38"
	Background = "48"
)

Foreground and Background sequence codes

View Source 
const (
	// TrueColor, 24-bit color profile
	TrueColor = Profile(iota)
	// ANSI256, 8-bit color profile
	ANSI256
	// ANSI, 4-bit color profile
	ANSI
	// Ascii, uncolored profile
	Ascii //nolint:revive
)
View Source 
const (
	// Cursor positioning.
	CursorUpSeq              = "%dA"
	CursorDownSeq            = "%dB"
	CursorForwardSeq         = "%dC"
	CursorBackSeq            = "%dD"
	CursorNextLineSeq        = "%dE"
	CursorPreviousLineSeq    = "%dF"
	CursorHorizontalSeq      = "%dG"
	CursorPositionSeq        = "%d;%dH"
	EraseDisplaySeq          = "%dJ"
	EraseLineSeq             = "%dK"
	ScrollUpSeq              = "%dS"
	ScrollDownSeq            = "%dT"
	SaveCursorPositionSeq    = "s"
	RestoreCursorPositionSeq = "u"
	ChangeScrollingRegionSeq = "%d;%dr"
	InsertLineSeq            = "%dL"
	DeleteLineSeq            = "%dM"

	// Explicit values for EraseLineSeq.
	EraseLineRightSeq  = "0K"
	EraseLineLeftSeq   = "1K"
	EraseEntireLineSeq = "2K"

	// Mouse.
	EnableMousePressSeq         = "?9h" // press only (X10)
	DisableMousePressSeq        = "?9l"
	EnableMouseSeq              = "?1000h" // press, release, wheel
	DisableMouseSeq             = "?1000l"
	EnableMouseHiliteSeq        = "?1001h" // highlight
	DisableMouseHiliteSeq       = "?1001l"
	EnableMouseCellMotionSeq    = "?1002h" // press, release, move on pressed, wheel
	DisableMouseCellMotionSeq   = "?1002l"
	EnableMouseAllMotionSeq     = "?1003h" // press, release, move, wheel
	DisableMouseAllMotionSeq    = "?1003l"
	EnableMouseExtendedModeSeq  = "?1006h" // press, release, move, wheel, extended coordinates
	DisableMouseExtendedModeSeq = "?1006l"
	EnableMousePixelsModeSeq    = "?1016h" // press, release, move, wheel, extended pixel coordinates
	DisableMousePixelsModeSeq   = "?1016l"

	// Screen.
	RestoreScreenSeq = "?47l"
	SaveScreenSeq    = "?47h"
	AltScreenSeq     = "?1049h"
	ExitAltScreenSeq = "?1049l"

	// Bracketed paste.
	// https://en.wikipedia.org/wiki/Bracketed-paste
	EnableBracketedPasteSeq  = "?2004h"
	DisableBracketedPasteSeq = "?2004l"
	StartBracketedPasteSeq   = "200~"
	EndBracketedPasteSeq     = "201~"

	// Session.
	SetWindowTitleSeq     = "2;%s" + string(BEL)
	SetForegroundColorSeq = "10;%s" + string(BEL)
	SetBackgroundColorSeq = "11;%s" + string(BEL)
	SetCursorColorSeq     = "12;%s" + string(BEL)
	ShowCursorSeq         = "?25h"
	HideCursorSeq         = "?25l"
)

Sequence definitions.

View Source 
const (
	ResetSeq     = "0"
	BoldSeq      = "1"
	FaintSeq     = "2"
	ItalicSeq    = "3"
	UnderlineSeq = "4"
	BlinkSeq     = "5"
	ReverseSeq   = "7"
	CrossOutSeq  = "9"
	OverlineSeq  = "53"
)

Sequence definitions.

View Source 
const (
	// Escape character
	ESC = '\x1b'
	// Bell
	BEL = '\a'
	// Control Sequence Introducer
	CSI = string(ESC) + "["
	// Operating System Command
	OSC = string(ESC) + "]"
	// String Terminator
	ST = string(ESC) + `\`
)
View Source 
const (
	// timeout for OSC queries
	OSCTimeout = 5 * time.Second
)

Variables

View Source 
var (
	// ErrInvalidColor gets returned when a color is invalid.
	ErrInvalidColor = errors.New("invalid color")
)
View Source 
var (
	// ErrStatusReport gets returned when the terminal can't be queried.
	ErrStatusReport = errors.New("unable to retrieve status report")
)

Functions

func AltScreen deprecated added in v0.5.0 

func AltScreen()

AltScreen switches to the alternate screen buffer. The former view can be restored with ExitAltScreen().

Deprecated: please use termenv.Output instead.

func ChangeScrollingRegion deprecated added in v0.6.0 

func ChangeScrollingRegion(top, bottom int)

ChangeScrollingRegion sets the scrolling region of the terminal.

Deprecated: please use termenv.Output instead.

func ClearLine deprecated added in v0.5.0 

func ClearLine()

ClearLine clears the current line.

Deprecated: please use termenv.Output instead.

func ClearLineLeft deprecated added in v0.9.0 

func ClearLineLeft()

ClearLineLeft clears the line to the left of the cursor.

Deprecated: please use termenv.Output instead.

func ClearLineRight deprecated added in v0.9.0 

func ClearLineRight()

ClearLineRight clears the line to the right of the cursor.

Deprecated: please use termenv.Output instead.

func ClearLines deprecated added in v0.5.0 

func ClearLines(n int)

ClearLines clears a given number of lines.

Deprecated: please use termenv.Output instead.

func ClearScreen deprecated added in v0.5.0 

func ClearScreen()

ClearScreen clears the visible portion of the terminal.

Deprecated: please use termenv.Output instead.

func ConvertToRGB 

func ConvertToRGB(c Color) colorful.Color

ConvertToRGB converts a Color to a colorful.Color.

func Copy added in v0.13.0 

func Copy(str string)

Copy copies text to clipboard using OSC 52 escape sequence.

func CopyPrimary added in v0.14.0 

func CopyPrimary(str string)

CopyPrimary copies text to primary clipboard (X11) using OSC 52 escape sequence.

func CursorBack deprecated added in v0.6.0 

func CursorBack(n int)

CursorBack moves the cursor backwards a given number of cells.

Deprecated: please use termenv.Output instead.

func CursorDown deprecated added in v0.5.2 

func CursorDown(n int)

CursorDown moves the cursor down a given number of lines.

Deprecated: please use termenv.Output instead.

func CursorForward deprecated added in v0.6.0 

func CursorForward(n int)

CursorForward moves the cursor up a given number of lines.

Deprecated: please use termenv.Output instead.

func CursorNextLine deprecated added in v0.5.0 

func CursorNextLine(n int)

CursorNextLine moves the cursor down a given number of lines and places it at the beginning of the line.

Deprecated: please use termenv.Output instead.

func CursorPrevLine deprecated added in v0.5.0 

func CursorPrevLine(n int)

CursorPrevLine moves the cursor up a given number of lines and places it at the beginning of the line.

Deprecated: please use termenv.Output instead.

func CursorUp deprecated added in v0.5.2 

func CursorUp(n int)

CursorUp moves the cursor up a given number of lines.

Deprecated: please use termenv.Output instead.

func DeleteLines deprecated added in v0.6.0 

func DeleteLines(n int)

DeleteLines deletes the given number of lines, pulling any lines in the scrollable region below up.

Deprecated: please use termenv.Output instead.

func DisableBracketedPaste deprecated added in v0.13.0 

func DisableBracketedPaste()

DisableBracketedPaste disables bracketed paste.

Deprecated: please use termenv.Output instead.

func DisableMouse deprecated added in v0.6.0 

func DisableMouse()

DisableMouse disables Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func DisableMouseAllMotion deprecated added in v0.6.0 

func DisableMouseAllMotion()

DisableMouseAllMotion disables All Motion Mouse mode.

Deprecated: please use termenv.Output instead.

func DisableMouseCellMotion deprecated added in v0.6.0 

func DisableMouseCellMotion()

DisableMouseCellMotion disables Cell Motion Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func DisableMouseHilite deprecated added in v0.6.0 

func DisableMouseHilite()

DisableMouseHilite disables Hilite Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func DisableMousePress deprecated added in v0.6.0 

func DisableMousePress()

DisableMousePress disables X10 mouse mode.

Deprecated: please use termenv.Output instead.

func EnableBracketedPaste deprecated added in v0.13.0 

func EnableBracketedPaste()

EnableBracketedPaste enables bracketed paste.

Deprecated: please use termenv.Output instead.

func EnableMouse deprecated added in v0.6.0 

func EnableMouse()

EnableMouse enables Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func EnableMouseAllMotion deprecated added in v0.6.0 

func EnableMouseAllMotion()

EnableMouseAllMotion enables All Motion Mouse mode.

Deprecated: please use termenv.Output instead.

func EnableMouseCellMotion deprecated added in v0.6.0 

func EnableMouseCellMotion()

EnableMouseCellMotion enables Cell Motion Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func EnableMouseHilite deprecated added in v0.6.0 

func EnableMouseHilite()

EnableMouseHilite enables Hilite Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func EnableMousePress deprecated added in v0.6.0 

func EnableMousePress()

EnableMousePress enables X10 mouse mode. Button press events are sent only.

Deprecated: please use termenv.Output instead.

func EnableVirtualTerminalProcessing added in v0.13.0 

func EnableVirtualTerminalProcessing(_ io.Writer) (func() error, error)

EnableVirtualTerminalProcessing enables virtual terminal processing on Windows for w and returns a function that restores w to its previous state. On non-Windows platforms, or if w does not refer to a terminal, then it returns a non-nil no-op function and no error.

func EnvNoColor added in v0.7.2 

func EnvNoColor() bool

EnvNoColor returns true if the environment variables explicitly disable color output by setting NO_COLOR (https://no-color.org/) or CLICOLOR/CLICOLOR_FORCE (https://bixense.com/clicolors/) If NO_COLOR is set, this will return true, ignoring CLICOLOR/CLICOLOR_FORCE If CLICOLOR=="0", it will be true only if CLICOLOR_FORCE is also "0" or is unset.

func ExitAltScreen deprecated added in v0.5.0 

func ExitAltScreen()

ExitAltScreen exits the alternate screen buffer and returns to the former terminal view.

Deprecated: please use termenv.Output instead.

func HasDarkBackground 

func HasDarkBackground() bool

HasDarkBackground returns whether terminal uses a dark-ish background.

func HideCursor deprecated added in v0.5.0 

func HideCursor()

HideCursor hides the cursor.

Deprecated: please use termenv.Output instead. 

func Hyperlink(link, name string) string

Hyperlink creates a hyperlink using OSC8.

func InsertLines deprecated added in v0.6.0 

func InsertLines(n int)

InsertLines inserts the given number of lines at the top of the scrollable region, pushing lines below down.

Deprecated: please use termenv.Output instead.

func MoveCursor deprecated added in v0.5.0 

func MoveCursor(row int, column int)

MoveCursor moves the cursor to a given position.

Deprecated: please use termenv.Output instead.

func Notify added in v0.14.0 

func Notify(title, body string)

Notify triggers a notification using OSC777.

func Reset deprecated added in v0.5.1 

func Reset()

Reset the terminal to its default style, removing any active styles.

Deprecated: please use termenv.Output instead.

func RestoreCursorPosition deprecated added in v0.6.0 

func RestoreCursorPosition()

RestoreCursorPosition restores a saved cursor position.

Deprecated: please use termenv.Output instead.

func RestoreScreen deprecated added in v0.11.0 

func RestoreScreen()

RestoreScreen restores a previously saved screen state.

Deprecated: please use termenv.Output instead.

func SaveCursorPosition deprecated added in v0.6.0 

func SaveCursorPosition()

SaveCursorPosition saves the cursor position.

Deprecated: please use termenv.Output instead.

func SaveScreen deprecated added in v0.11.0 

func SaveScreen()

SaveScreen saves the screen state.

Deprecated: please use termenv.Output instead.

func SetBackgroundColor deprecated added in v0.11.0 

func SetBackgroundColor(color Color)

SetBackgroundColor sets the default background color.

Deprecated: please use termenv.Output instead.

func SetCursorColor deprecated added in v0.11.0 

func SetCursorColor(color Color)

SetCursorColor sets the cursor color.

Deprecated: please use termenv.Output instead.

func SetDefaultOutput added in v0.15.0 

func SetDefaultOutput(o *Output)

SetDefaultOutput sets the default global output.

func SetForegroundColor deprecated added in v0.11.0 

func SetForegroundColor(color Color)

SetForegroundColor sets the default foreground color.

Deprecated: please use termenv.Output instead.

func SetWindowTitle deprecated added in v0.11.0 

func SetWindowTitle(title string)

SetWindowTitle sets the terminal window title.

Deprecated: please use termenv.Output instead.

func ShowCursor deprecated added in v0.5.0 

func ShowCursor()

ShowCursor shows the cursor.

Deprecated: please use termenv.Output instead.

func TemplateFuncs 

func TemplateFuncs(p Profile) template.FuncMap

TemplateFuncs contains a few useful template helpers.

Types

type ANSI256Color 

type ANSI256Color int

ANSI256Color is a color (16-255) as defined by the ANSI Standard.

func (ANSI256Color) Sequence 

func (c ANSI256Color) Sequence(bg bool) string

Sequence returns the ANSI Sequence for the color.

func (ANSI256Color) String added in v0.10.0 

func (c ANSI256Color) String() string

type ANSIColor 

type ANSIColor int

ANSIColor is a color (0-15) as defined by the ANSI Standard. 

const (
	ANSIBlack ANSIColor = iota
	ANSIRed
	ANSIGreen
	ANSIYellow
	ANSIBlue
	ANSIMagenta
	ANSICyan
	ANSIWhite
	ANSIBrightBlack
	ANSIBrightRed
	ANSIBrightGreen
	ANSIBrightYellow
	ANSIBrightBlue
	ANSIBrightMagenta
	ANSIBrightCyan
	ANSIBrightWhite
)

ANSI color codes

func (ANSIColor) Sequence 

func (c ANSIColor) Sequence(bg bool) string

Sequence returns the ANSI Sequence for the color.

func (ANSIColor) String added in v0.10.0 

func (c ANSIColor) String() string

type Color 

type Color interface {
	// Sequence returns the ANSI Sequence for the color.
	Sequence(bg bool) string
}

Color is an interface implemented by all colors that can be converted to an ANSI sequence.

func BackgroundColor 

func BackgroundColor() Color

BackgroundColor returns the terminal's default background color.

func ForegroundColor 

func ForegroundColor() Color

ForegroundColor returns the terminal's default foreground color.

type Environ added in v0.13.0 

type Environ interface {
	Environ() []string
	Getenv(string) string
}

Environ is an interface for getting environment variables.

type File added in v0.13.0 

type File interface {
	io.ReadWriter
	Fd() uintptr
}

File represents a file descriptor.

type NoColor 

type NoColor struct{}

NoColor is a nop for terminals that don't support colors.

func (NoColor) Sequence 

func (c NoColor) Sequence(_ bool) string

Sequence returns the ANSI Sequence for the color.

func (NoColor) String added in v0.10.0 

func (c NoColor) String() string

type Output added in v0.13.0 

type Output struct {
	Profile
	// contains filtered or unexported fields
}

Output is a terminal output.

func DefaultOutput added in v0.13.0 

func DefaultOutput() *Output

DefaultOutput returns the default global output.

func NewOutput added in v0.13.0 

func NewOutput(tty io.Writer, opts ...OutputOption) *Output

NewOutput returns a new Output for the given file descriptor.

func (Output) AltScreen added in v0.13.0 

func (o Output) AltScreen()

AltScreen switches to the alternate screen buffer. The former view can be restored with ExitAltScreen().

func (*Output) BackgroundColor added in v0.13.0 

func (o *Output) BackgroundColor() Color

BackgroundColor returns the terminal's default background color.

func (Output) ChangeScrollingRegion added in v0.13.0 

func (o Output) ChangeScrollingRegion(top, bottom int)

ChangeScrollingRegion sets the scrolling region of the terminal.

func (Output) ClearLine added in v0.13.0 

func (o Output) ClearLine()

ClearLine clears the current line.

func (Output) ClearLineLeft added in v0.13.0 

func (o Output) ClearLineLeft()

ClearLineLeft clears the line to the left of the cursor.

func (Output) ClearLineRight added in v0.13.0 

func (o Output) ClearLineRight()

ClearLineRight clears the line to the right of the cursor.

func (Output) ClearLines added in v0.13.0 

func (o Output) ClearLines(n int)

ClearLines clears a given number of lines.

func (Output) ClearScreen added in v0.13.0 

func (o Output) ClearScreen()

ClearScreen clears the visible portion of the terminal.

func (*Output) ColorProfile added in v0.13.0 

func (o *Output) ColorProfile() Profile

ColorProfile returns the supported color profile: Ascii, ANSI, ANSI256, or TrueColor.

func (Output) Copy added in v0.13.0 

func (o Output) Copy(str string)

Copy copies text to clipboard using OSC 52 escape sequence.

func (Output) CopyPrimary added in v0.14.0 

func (o Output) CopyPrimary(str string)

CopyPrimary copies text to primary clipboard (X11) using OSC 52 escape sequence.

func (Output) CursorBack added in v0.13.0 

func (o Output) CursorBack(n int)

CursorBack moves the cursor backwards a given number of cells.

func (Output) CursorDown added in v0.13.0 

func (o Output) CursorDown(n int)

CursorDown moves the cursor down a given number of lines.

func (Output) CursorForward added in v0.13.0 

func (o Output) CursorForward(n int)

CursorForward moves the cursor up a given number of lines.

func (Output) CursorNextLine added in v0.13.0 

func (o Output) CursorNextLine(n int)

CursorNextLine moves the cursor down a given number of lines and places it at the beginning of the line.

func (Output) CursorPrevLine added in v0.13.0 

func (o Output) CursorPrevLine(n int)

CursorPrevLine moves the cursor up a given number of lines and places it at the beginning of the line.

func (Output) CursorUp added in v0.13.0 

func (o Output) CursorUp(n int)

CursorUp moves the cursor up a given number of lines.

func (Output) DeleteLines added in v0.13.0 

func (o Output) DeleteLines(n int)

DeleteLines deletes the given number of lines, pulling any lines in the scrollable region below up.

func (Output) DisableBracketedPaste added in v0.13.0 

func (o Output) DisableBracketedPaste()

DisableBracketedPaste disables bracketed paste.

func (Output) DisableMouse added in v0.13.0 

func (o Output) DisableMouse()

DisableMouse disables Mouse Tracking mode.

func (Output) DisableMouseAllMotion added in v0.13.0 

func (o Output) DisableMouseAllMotion()

DisableMouseAllMotion disables All Motion Mouse mode.

func (Output) DisableMouseCellMotion added in v0.13.0 

func (o Output) DisableMouseCellMotion()

DisableMouseCellMotion disables Cell Motion Mouse Tracking mode.

func (Output) DisableMouseExtendedMode added in v0.14.0 

func (o Output) DisableMouseExtendedMode()

DisableMouseExtendedMotion disables Extended Mouse mode (SGR).

func (Output) DisableMouseHilite added in v0.13.0 

func (o Output) DisableMouseHilite()

DisableMouseHilite disables Hilite Mouse Tracking mode.

func (Output) DisableMousePixelsMode added in v0.14.0 

func (o Output) DisableMousePixelsMode()

DisableMousePixelsMotion disables Pixel Motion Mouse mode (SGR-Pixels).

func (Output) DisableMousePress added in v0.13.0 

func (o Output) DisableMousePress()

DisableMousePress disables X10 mouse mode.

func (Output) EnableBracketedPaste added in v0.13.0 

func (o Output) EnableBracketedPaste()

EnableBracketedPaste enables bracketed paste.

func (Output) EnableMouse added in v0.13.0 

func (o Output) EnableMouse()

EnableMouse enables Mouse Tracking mode.

func (Output) EnableMouseAllMotion added in v0.13.0 

func (o Output) EnableMouseAllMotion()

EnableMouseAllMotion enables All Motion Mouse mode.

func (Output) EnableMouseCellMotion added in v0.13.0 

func (o Output) EnableMouseCellMotion()

EnableMouseCellMotion enables Cell Motion Mouse Tracking mode.

func (Output) EnableMouseExtendedMode added in v0.14.0 

func (o Output) EnableMouseExtendedMode()

EnableMouseExtendedMotion enables Extended Mouse mode (SGR). This should be enabled in conjunction with EnableMouseCellMotion, and EnableMouseAllMotion.

func (Output) EnableMouseHilite added in v0.13.0 

func (o Output) EnableMouseHilite()

EnableMouseHilite enables Hilite Mouse Tracking mode.

func (Output) EnableMousePixelsMode added in v0.14.0 

func (o Output) EnableMousePixelsMode()

EnableMousePixelsMotion enables Pixel Motion Mouse mode (SGR-Pixels). This should be enabled in conjunction with EnableMouseCellMotion, and EnableMouseAllMotion.

func (Output) EnableMousePress added in v0.13.0 

func (o Output) EnableMousePress()

EnableMousePress enables X10 mouse mode. Button press events are sent only.

func (*Output) EnvColorProfile added in v0.13.0 

func (o *Output) EnvColorProfile() Profile

EnvColorProfile returns the color profile based on environment variables set Supports NO_COLOR (https://no-color.org/) and CLICOLOR/CLICOLOR_FORCE (https://bixense.com/clicolors/) If none of these environment variables are set, this behaves the same as ColorProfile() It will return the Ascii color profile if EnvNoColor() returns true If the terminal does not support any colors, but CLICOLOR_FORCE is set and not "0" then the ANSI color profile will be returned.

func (*Output) EnvNoColor added in v0.13.0 

func (o *Output) EnvNoColor() bool

EnvNoColor returns true if the environment variables explicitly disable color output by setting NO_COLOR (https://no-color.org/) or CLICOLOR/CLICOLOR_FORCE (https://bixense.com/clicolors/) If NO_COLOR is set, this will return true, ignoring CLICOLOR/CLICOLOR_FORCE If CLICOLOR=="0", it will be true only if CLICOLOR_FORCE is also "0" or is unset.

func (Output) ExitAltScreen added in v0.13.0 

func (o Output) ExitAltScreen()

ExitAltScreen exits the alternate screen buffer and returns to the former terminal view.

func (*Output) ForegroundColor added in v0.13.0 

func (o *Output) ForegroundColor() Color

ForegroundColor returns the terminal's default foreground color.

func (*Output) HasDarkBackground added in v0.13.0 

func (o *Output) HasDarkBackground() bool

HasDarkBackground returns whether terminal uses a dark-ish background.

func (Output) HideCursor added in v0.13.0 

func (o Output) HideCursor()

HideCursor hides the cursor. 

func (o *Output) Hyperlink(link, name string) string

Hyperlink creates a hyperlink using OSC8.

func (Output) InsertLines added in v0.13.0 

func (o Output) InsertLines(n int)

InsertLines inserts the given number of lines at the top of the scrollable region, pushing lines below down.

func (Output) MoveCursor added in v0.13.0 

func (o Output) MoveCursor(row int, column int)

MoveCursor moves the cursor to a given position.

func (*Output) Notify added in v0.14.0 

func (o *Output) Notify(title, body string)

Notify triggers a notification using OSC777.

func (Output) Reset added in v0.13.0 

func (o Output) Reset()

Reset the terminal to its default style, removing any active styles.

func (Output) RestoreCursorPosition added in v0.13.0 

func (o Output) RestoreCursorPosition()

RestoreCursorPosition restores a saved cursor position.

func (Output) RestoreScreen added in v0.13.0 

func (o Output) RestoreScreen()

RestoreScreen restores a previously saved screen state.

func (Output) SaveCursorPosition added in v0.13.0 

func (o Output) SaveCursorPosition()

SaveCursorPosition saves the cursor position.

func (Output) SaveScreen added in v0.13.0 

func (o Output) SaveScreen()

SaveScreen saves the screen state.

func (Output) SetBackgroundColor added in v0.13.0 

func (o Output) SetBackgroundColor(color Color)

SetBackgroundColor sets the default background color.

func (Output) SetCursorColor added in v0.13.0 

func (o Output) SetCursorColor(color Color)

SetCursorColor sets the cursor color.

func (Output) SetForegroundColor added in v0.13.0 

func (o Output) SetForegroundColor(color Color)

SetForegroundColor sets the default foreground color.

func (Output) SetWindowTitle added in v0.13.0 

func (o Output) SetWindowTitle(title string)

SetWindowTitle sets the terminal window title.

func (Output) ShowCursor added in v0.13.0 

func (o Output) ShowCursor()

ShowCursor shows the cursor.

func (Output) TTY added in v0.13.0 

func (o Output) TTY() File

TTY returns the terminal's file descriptor. This may be nil if the output is not a terminal.

func (Output) TemplateFuncs added in v0.13.0 

func (o Output) TemplateFuncs() template.FuncMap

TemplateFuncs returns template helpers for the given output.

func (Output) Write added in v0.13.0 

func (o Output) Write(p []byte) (int, error)

func (Output) WriteString added in v0.13.0 

func (o Output) WriteString(s string) (int, error)

WriteString writes the given string to the output.

type OutputOption added in v0.14.0 

type OutputOption = func(*Output)

OutputOption sets an option on Output.

func WithColorCache added in v0.13.0 

func WithColorCache(v bool) OutputOption

WithColorCache returns a new OutputOption with fore- and background color values pre-fetched and cached.

func WithEnvironment added in v0.13.0 

func WithEnvironment(environ Environ) OutputOption

WithEnvironment returns a new OutputOption for the given environment.

func WithProfile added in v0.13.0 

func WithProfile(profile Profile) OutputOption

WithProfile returns a new OutputOption for the given profile.

func WithTTY added in v0.15.0 

func WithTTY(v bool) OutputOption

WithTTY returns a new OutputOption to assume whether or not the output is a TTY. This is useful when mocking console output.

func WithUnsafe added in v0.14.0 

func WithUnsafe() OutputOption

WithUnsafe returns a new OutputOption with unsafe mode enabled. Unsafe mode doesn't check whether or not the terminal is a TTY.

This option supersedes WithTTY.

This is useful when mocking console output and enforcing ANSI escape output e.g. on SSH sessions.

type Profile 

type Profile int

Profile is a color profile: Ascii, ANSI, ANSI256, or TrueColor.

func ColorProfile 

func ColorProfile() Profile

ColorProfile returns the supported color profile: Ascii, ANSI, ANSI256, or TrueColor.

func EnvColorProfile added in v0.7.2 

func EnvColorProfile() Profile

EnvColorProfile returns the color profile based on environment variables set Supports NO_COLOR (https://no-color.org/) and CLICOLOR/CLICOLOR_FORCE (https://bixense.com/clicolors/) If none of these environment variables are set, this behaves the same as ColorProfile() It will return the Ascii color profile if EnvNoColor() returns true If the terminal does not support any colors, but CLICOLOR_FORCE is set and not "0" then the ANSI color profile will be returned.

func (Profile) Color 

func (p Profile) Color(s string) Color

Color creates a Color from a string. Valid inputs are hex colors, as well as ANSI color codes (0-15, 16-255).

func (Profile) Convert 

func (p Profile) Convert(c Color) Color

Convert transforms a given Color to a Color supported within the Profile.

func (Profile) FromColor added in v0.8.0 

func (p Profile) FromColor(c color.Color) Color

FromColor creates a Color from a color.Color.

func (Profile) String added in v0.13.0 

func (p Profile) String(s ...string) Style

String returns a new Style.

type RGBColor 

type RGBColor string

RGBColor is a hex-encoded color, e.g. "#abcdef".

func (RGBColor) Sequence 

func (c RGBColor) Sequence(bg bool) string

Sequence returns the ANSI Sequence for the color.

type Style 

type Style struct {
	// contains filtered or unexported fields
}

Style is a string that various rendering styles can be applied to.

func String 

func String(s ...string) Style

String returns a new Style.

func (Style) Background 

func (t Style) Background(c Color) Style

Background sets a background color. 

func (t Style) Blink() Style

Blink enables blink mode.

func (Style) Bold 

func (t Style) Bold() Style

Bold enables bold rendering.

func (Style) CrossOut 

func (t Style) CrossOut() Style

CrossOut enables crossed-out rendering.

func (Style) Faint 

func (t Style) Faint() Style

Faint enables faint rendering.

func (Style) Foreground 

func (t Style) Foreground(c Color) Style

Foreground sets a foreground color.

func (Style) Italic 

func (t Style) Italic() Style

Italic enables italic rendering.

func (Style) Overline 

func (t Style) Overline() Style

Overline enables overline rendering.

func (Style) Reverse 

func (t Style) Reverse() Style

Reverse enables reverse color mode.

func (Style) String 

func (t Style) String() string

func (Style) Styled 

func (t Style) Styled(s string) string

Styled renders s with all applied styles.

func (Style) Underline 

func (t Style) Underline() Style

Underline enables underline rendering.

func (Style) Width added in v0.6.0 

func (t Style) Width() int

Width returns the width required to print all runes in Style.

Source Files

View all Source files

Directories

Path Synopsis
examples
color-chart
hello-world
ssh Module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.