termenv

package module
v0.16.2 Latest Latest
Warning

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

Go to latest
Published: Oct 21, 2025 License: MIT Imports: 16 Imported by: 0

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, Ghostty, 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 supported since v0.11.0

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) + `\`
)

Variables

View Source
var ErrInvalidColor = errors.New("invalid color")

ErrInvalidColor gets returned when a color is invalid.

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

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

func ChangeScrollingRegion(top, bottom int)

ChangeScrollingRegion sets the scrolling region of the terminal.

Deprecated: please use termenv.Output instead.

func ClearLine deprecated

func ClearLine()

ClearLine clears the current line.

Deprecated: please use termenv.Output instead.

func ClearLineLeft deprecated

func ClearLineLeft()

ClearLineLeft clears the line to the left of the cursor.

Deprecated: please use termenv.Output instead.

func ClearLineRight deprecated

func ClearLineRight()

ClearLineRight clears the line to the right of the cursor.

Deprecated: please use termenv.Output instead.

func ClearLines deprecated

func ClearLines(n int)

ClearLines clears a given number of lines.

Deprecated: please use termenv.Output instead.

func ClearScreen deprecated

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

func Copy(str string)

Copy copies text to clipboard using OSC 52 escape sequence.

func CopyPrimary

func CopyPrimary(str string)

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

func CursorBack deprecated

func CursorBack(n int)

CursorBack moves the cursor backwards a given number of cells.

Deprecated: please use termenv.Output instead.

func CursorDown deprecated

func CursorDown(n int)

CursorDown moves the cursor down a given number of lines.

Deprecated: please use termenv.Output instead.

func CursorForward deprecated

func CursorForward(n int)

CursorForward moves the cursor up a given number of lines.

Deprecated: please use termenv.Output instead.

func CursorNextLine deprecated

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

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

func CursorUp(n int)

CursorUp moves the cursor up a given number of lines.

Deprecated: please use termenv.Output instead.

func DeleteLines deprecated

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

func DisableBracketedPaste()

DisableBracketedPaste disables bracketed paste.

Deprecated: please use termenv.Output instead.

func DisableMouse deprecated

func DisableMouse()

DisableMouse disables Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func DisableMouseAllMotion deprecated

func DisableMouseAllMotion()

DisableMouseAllMotion disables All Motion Mouse mode.

Deprecated: please use termenv.Output instead.

func DisableMouseCellMotion deprecated

func DisableMouseCellMotion()

DisableMouseCellMotion disables Cell Motion Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func DisableMouseHilite deprecated

func DisableMouseHilite()

DisableMouseHilite disables Hilite Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func DisableMousePress deprecated

func DisableMousePress()

DisableMousePress disables X10 mouse mode.

Deprecated: please use termenv.Output instead.

func EnableBracketedPaste deprecated

func EnableBracketedPaste()

EnableBracketedPaste enables bracketed paste.

Deprecated: please use termenv.Output instead.

func EnableMouse deprecated

func EnableMouse()

EnableMouse enables Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func EnableMouseAllMotion deprecated

func EnableMouseAllMotion()

EnableMouseAllMotion enables All Motion Mouse mode.

Deprecated: please use termenv.Output instead.

func EnableMouseCellMotion deprecated

func EnableMouseCellMotion()

EnableMouseCellMotion enables Cell Motion Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func EnableMouseHilite deprecated

func EnableMouseHilite()

EnableMouseHilite enables Hilite Mouse Tracking mode.

Deprecated: please use termenv.Output instead.

func EnableMousePress deprecated

func EnableMousePress()

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

Deprecated: please use termenv.Output instead.

func EnableVirtualTerminalProcessing

func EnableVirtualTerminalProcessing(o *Output) (restoreFunc func() error, err error)

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

func EnableWindowsANSIConsole

func EnableWindowsANSIConsole() (uint32, error)

EnableWindowsANSIConsole enables virtual terminal processing on Windows platforms. This allows the use of ANSI escape sequences in Windows console applications. Ensure this gets called before anything gets rendered with termenv.

Returns the original console mode and an error if one occurred.

func EnvNoColor

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

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

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

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

func MoveCursor(row int, column int)

MoveCursor moves the cursor to a given position.

Deprecated: please use termenv.Output instead.

func Notify

func Notify(title, body string)

Notify triggers a notification using OSC777.

func Reset deprecated

func Reset()

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

Deprecated: please use termenv.Output instead.

func RestoreCursorPosition deprecated

func RestoreCursorPosition()

RestoreCursorPosition restores a saved cursor position.

Deprecated: please use termenv.Output instead.

func RestoreScreen deprecated

func RestoreScreen()

RestoreScreen restores a previously saved screen state.

Deprecated: please use termenv.Output instead.

func RestoreWindowsConsole

func RestoreWindowsConsole(mode uint32) error

RestoreWindowsConsole restores the console mode to a previous state.

func SaveCursorPosition deprecated

func SaveCursorPosition()

SaveCursorPosition saves the cursor position.

Deprecated: please use termenv.Output instead.

func SaveScreen deprecated

func SaveScreen()

SaveScreen saves the screen state.

Deprecated: please use termenv.Output instead.

func SetBackgroundColor deprecated

func SetBackgroundColor(color Color)

SetBackgroundColor sets the default background color.

Deprecated: please use termenv.Output instead.

func SetCursorColor deprecated

func SetCursorColor(color Color)

SetCursorColor sets the cursor color.

Deprecated: please use termenv.Output instead.

func SetDefaultOutput

func SetDefaultOutput(o *Output)

SetDefaultOutput sets the default global output.

func SetForegroundColor deprecated

func SetForegroundColor(color Color)

SetForegroundColor sets the default foreground color.

Deprecated: please use termenv.Output instead.

func SetWindowTitle deprecated

func SetWindowTitle(title string)

SetWindowTitle sets the terminal window title.

Deprecated: please use termenv.Output instead.

func ShowCursor deprecated

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

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

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

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

Environ is an interface for getting environment variables.

type File deprecated

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

File represents a file descriptor.

Deprecated: Use *os.File instead.

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

func (c NoColor) String() string

type Output

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

Output is a terminal output.

func DefaultOutput

func DefaultOutput() *Output

DefaultOutput returns the default global output.

func NewOutput

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

NewOutput returns a new Output for the given writer.

func (Output) AltScreen

func (o Output) AltScreen()

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

func (*Output) BackgroundColor

func (o *Output) BackgroundColor() Color

BackgroundColor returns the terminal's default background color.

func (Output) ChangeScrollingRegion

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

ChangeScrollingRegion sets the scrolling region of the terminal.

func (Output) ClearLine

func (o Output) ClearLine()

ClearLine clears the current line.

func (Output) ClearLineLeft

func (o Output) ClearLineLeft()

ClearLineLeft clears the line to the left of the cursor.

func (Output) ClearLineRight

func (o Output) ClearLineRight()

ClearLineRight clears the line to the right of the cursor.

func (Output) ClearLines

func (o Output) ClearLines(n int)

ClearLines clears a given number of lines.

func (Output) ClearScreen

func (o Output) ClearScreen()

ClearScreen clears the visible portion of the terminal.

func (*Output) ColorProfile

func (o *Output) ColorProfile() Profile

func (Output) Copy

func (o Output) Copy(str string)

Copy copies text to clipboard using OSC 52 escape sequence.

func (Output) CopyPrimary

func (o Output) CopyPrimary(str string)

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

func (Output) CursorBack

func (o Output) CursorBack(n int)

CursorBack moves the cursor backwards a given number of cells.

func (Output) CursorDown

func (o Output) CursorDown(n int)

CursorDown moves the cursor down a given number of lines.

func (Output) CursorForward

func (o Output) CursorForward(n int)

CursorForward moves the cursor up a given number of lines.

func (Output) CursorNextLine

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

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

func (o Output) CursorUp(n int)

CursorUp moves the cursor up a given number of lines.

func (Output) DeleteLines

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

func (o Output) DisableBracketedPaste()

DisableBracketedPaste disables bracketed paste.

func (Output) DisableMouse

func (o Output) DisableMouse()

DisableMouse disables Mouse Tracking mode.

func (Output) DisableMouseAllMotion

func (o Output) DisableMouseAllMotion()

DisableMouseAllMotion disables All Motion Mouse mode.

func (Output) DisableMouseCellMotion

func (o Output) DisableMouseCellMotion()

DisableMouseCellMotion disables Cell Motion Mouse Tracking mode.

func (Output) DisableMouseExtendedMode

func (o Output) DisableMouseExtendedMode()

DisableMouseExtendedMotion disables Extended Mouse mode (SGR).

func (Output) DisableMouseHilite

func (o Output) DisableMouseHilite()

DisableMouseHilite disables Hilite Mouse Tracking mode.

func (Output) DisableMousePixelsMode

func (o Output) DisableMousePixelsMode()

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

func (Output) DisableMousePress

func (o Output) DisableMousePress()

DisableMousePress disables X10 mouse mode.

func (Output) EnableBracketedPaste

func (o Output) EnableBracketedPaste()

EnableBracketedPaste enables bracketed paste.

func (Output) EnableMouse

func (o Output) EnableMouse()

EnableMouse enables Mouse Tracking mode.

func (Output) EnableMouseAllMotion

func (o Output) EnableMouseAllMotion()

EnableMouseAllMotion enables All Motion Mouse mode.

func (Output) EnableMouseCellMotion

func (o Output) EnableMouseCellMotion()

EnableMouseCellMotion enables Cell Motion Mouse Tracking mode.

func (Output) EnableMouseExtendedMode

func (o Output) EnableMouseExtendedMode()

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

func (Output) EnableMouseHilite

func (o Output) EnableMouseHilite()

EnableMouseHilite enables Hilite Mouse Tracking mode.

func (Output) EnableMousePixelsMode

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

func (o Output) EnableMousePress()

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

func (*Output) EnvColorProfile

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

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

func (o Output) ExitAltScreen()

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

func (*Output) ForegroundColor

func (o *Output) ForegroundColor() Color

ForegroundColor returns the terminal's default foreground color.

func (*Output) HasDarkBackground

func (o *Output) HasDarkBackground() bool

HasDarkBackground returns whether terminal uses a dark-ish background.

func (Output) HideCursor

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

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

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

MoveCursor moves the cursor to a given position.

func (*Output) Notify

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

Notify triggers a notification using OSC777.

func (Output) Reset

func (o Output) Reset()

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

func (Output) RestoreCursorPosition

func (o Output) RestoreCursorPosition()

RestoreCursorPosition restores a saved cursor position.

func (Output) RestoreScreen

func (o Output) RestoreScreen()

RestoreScreen restores a previously saved screen state.

func (Output) SaveCursorPosition

func (o Output) SaveCursorPosition()

SaveCursorPosition saves the cursor position.

func (Output) SaveScreen

func (o Output) SaveScreen()

SaveScreen saves the screen state.

func (Output) SetBackgroundColor

func (o Output) SetBackgroundColor(color Color)

SetBackgroundColor sets the default background color.

func (Output) SetCursorColor

func (o Output) SetCursorColor(color Color)

SetCursorColor sets the cursor color.

func (Output) SetForegroundColor

func (o Output) SetForegroundColor(color Color)

SetForegroundColor sets the default foreground color.

func (Output) SetWindowTitle

func (o Output) SetWindowTitle(title string)

SetWindowTitle sets the terminal window title.

func (Output) ShowCursor

func (o Output) ShowCursor()

ShowCursor shows the cursor.

func (Output) TTY deprecated

func (o Output) TTY() File

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

Deprecated: Use Writer() instead.

func (Output) TemplateFuncs

func (o Output) TemplateFuncs() template.FuncMap

TemplateFuncs returns template helpers for the given output.

func (Output) Write

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

func (Output) WriteString

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

WriteString writes the given string to the output.

func (Output) Writer

func (o Output) Writer() io.Writer

Writer returns the underlying writer. This may be of type io.Writer, io.ReadWriter, or *os.File.

type OutputOption

type OutputOption = func(*Output)

OutputOption sets an option on Output.

func WithColorCache

func WithColorCache(v bool) OutputOption

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

func WithEnvironment

func WithEnvironment(environ Environ) OutputOption

WithEnvironment returns a new OutputOption for the given environment.

func WithProfile

func WithProfile(profile Profile) OutputOption

WithProfile returns a new OutputOption for the given profile.

func WithTTY

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

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

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

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

FromColor creates a Color from a color.Color.

func (Profile) Name

func (p Profile) Name() string

Name returns the profile name as a string.

func (Profile) String

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

func (t Style) StyledWithoutReset(s string) string

Styled renders s with all applied styles, but no trailing reset

func (Style) Underline

func (t Style) Underline() Style

Underline enables underline rendering.

func (Style) Width

func (t Style) Width() int

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

Directories

Path Synopsis
examples
color-chart command
hello-world command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL