Foreground and Background sequence codes
const (
Foreground = "38"
Background = "48"
)
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
)
Sequence definitions.
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.
const (
ResetSeq = "0"
BoldSeq = "1"
FaintSeq = "2"
ItalicSeq = "3"
UnderlineSeq = "4"
BlinkSeq = "5"
ReverseSeq = "7"
CrossOutSeq = "9"
OverlineSeq = "53"
)
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) + `\`
)
const (
// timeout for OSC queries
OSCTimeout = 5 * time.Second
)
var (
// ErrInvalidColor gets returned when a color is invalid.
ErrInvalidColor = errors.New("invalid color")
)
var (
// ErrStatusReport gets returned when the terminal can't be queried.
ErrStatusReport = errors.New("unable to retrieve status report")
)
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(top, bottom int)
ChangeScrollingRegion sets the scrolling region of the terminal.
Deprecated: please use termenv.Output instead.
func ClearLine()
ClearLine clears the current line.
Deprecated: please use termenv.Output instead.
func ClearLineLeft()
ClearLineLeft clears the line to the left of the cursor.
Deprecated: please use termenv.Output instead.
func ClearLineRight()
ClearLineRight clears the line to the right of the cursor.
Deprecated: please use termenv.Output instead.
func ClearLines(n int)
ClearLines clears a given number of lines.
Deprecated: please use termenv.Output instead.
func ClearScreen()
ClearScreen clears the visible portion of the terminal.
Deprecated: please use termenv.Output instead.
func ConvertToRGB(c Color) colorful.Color
ConvertToRGB converts a Color to a colorful.Color.
func Copy(str string)
Copy copies text to clipboard using OSC 52 escape sequence.
func CopyPrimary(str string)
CopyPrimary copies text to primary clipboard (X11) using OSC 52 escape sequence.
func CursorBack(n int)
CursorBack moves the cursor backwards a given number of cells.
Deprecated: please use termenv.Output instead.
func CursorDown(n int)
CursorDown moves the cursor down a given number of lines.
Deprecated: please use termenv.Output instead.
func CursorForward(n int)
CursorForward moves the cursor up a given number of lines.
Deprecated: please use termenv.Output instead.
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(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(n int)
CursorUp moves the cursor up a given number of lines.
Deprecated: please use termenv.Output instead.
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()
DisableBracketedPaste disables bracketed paste.
Deprecated: please use termenv.Output instead.
func DisableMouse()
DisableMouse disables Mouse Tracking mode.
Deprecated: please use termenv.Output instead.
func DisableMouseAllMotion()
DisableMouseAllMotion disables All Motion Mouse mode.
Deprecated: please use termenv.Output instead.
func DisableMouseCellMotion()
DisableMouseCellMotion disables Cell Motion Mouse Tracking mode.
Deprecated: please use termenv.Output instead.
func DisableMouseHilite()
DisableMouseHilite disables Hilite Mouse Tracking mode.
Deprecated: please use termenv.Output instead.
func DisableMousePress()
DisableMousePress disables X10 mouse mode.
Deprecated: please use termenv.Output instead.
func EnableBracketedPaste()
EnableBracketedPaste enables bracketed paste.
Deprecated: please use termenv.Output instead.
func EnableMouse()
EnableMouse enables Mouse Tracking mode.
Deprecated: please use termenv.Output instead.
func EnableMouseAllMotion()
EnableMouseAllMotion enables All Motion Mouse mode.
Deprecated: please use termenv.Output instead.
func EnableMouseCellMotion()
EnableMouseCellMotion enables Cell Motion Mouse Tracking mode.
Deprecated: please use termenv.Output instead.
func EnableMouseHilite()
EnableMouseHilite enables Hilite Mouse Tracking mode.
Deprecated: please use termenv.Output instead.
func EnableMousePress()
EnableMousePress enables X10 mouse mode. Button press events are sent only.
Deprecated: please use termenv.Output instead.
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() 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()
ExitAltScreen exits the alternate screen buffer and returns to the former terminal view.
Deprecated: please use termenv.Output instead.
func HasDarkBackground() bool
HasDarkBackground returns whether terminal uses a dark-ish background.
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(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(row int, column int)
MoveCursor moves the cursor to a given position.
Deprecated: please use termenv.Output instead.
func Notify(title, body string)
Notify triggers a notification using OSC777.
func Reset()
Reset the terminal to its default style, removing any active styles.
Deprecated: please use termenv.Output instead.
func RestoreCursorPosition()
RestoreCursorPosition restores a saved cursor position.
Deprecated: please use termenv.Output instead.
func RestoreScreen()
RestoreScreen restores a previously saved screen state.
Deprecated: please use termenv.Output instead.
func SaveCursorPosition()
SaveCursorPosition saves the cursor position.
Deprecated: please use termenv.Output instead.
func SaveScreen()
SaveScreen saves the screen state.
Deprecated: please use termenv.Output instead.
func SetBackgroundColor(color Color)
SetBackgroundColor sets the default background color.
Deprecated: please use termenv.Output instead.
func SetCursorColor(color Color)
SetCursorColor sets the cursor color.
Deprecated: please use termenv.Output instead.
func SetDefaultOutput(o *Output)
SetDefaultOutput sets the default global output.
func SetForegroundColor(color Color)
SetForegroundColor sets the default foreground color.
Deprecated: please use termenv.Output instead.
func SetWindowTitle(title string)
SetWindowTitle sets the terminal window title.
Deprecated: please use termenv.Output instead.
func ShowCursor()
ShowCursor shows the cursor.
Deprecated: please use termenv.Output instead.
func TemplateFuncs(p Profile) template.FuncMap
TemplateFuncs contains a few useful template helpers.
ANSI256Color is a color (16-255) as defined by the ANSI Standard.
type ANSI256Color int
func (c ANSI256Color) Sequence(bg bool) string
Sequence returns the ANSI Sequence for the color.
func (c ANSI256Color) String() string
ANSIColor is a color (0-15) as defined by the ANSI Standard.
type ANSIColor int
ANSI color codes
const (
ANSIBlack ANSIColor = iota
ANSIRed
ANSIGreen
ANSIYellow
ANSIBlue
ANSIMagenta
ANSICyan
ANSIWhite
ANSIBrightBlack
ANSIBrightRed
ANSIBrightGreen
ANSIBrightYellow
ANSIBrightBlue
ANSIBrightMagenta
ANSIBrightCyan
ANSIBrightWhite
)
func (c ANSIColor) Sequence(bg bool) string
Sequence returns the ANSI Sequence for the color.
func (c ANSIColor) String() string
Color is an interface implemented by all colors that can be converted to an ANSI sequence.
type Color interface {
// Sequence returns the ANSI Sequence for the color.
Sequence(bg bool) string
}
func BackgroundColor() Color
BackgroundColor returns the terminal's default background color.
func ForegroundColor() Color
ForegroundColor returns the terminal's default foreground color.
Environ is an interface for getting environment variables.
type Environ interface {
Environ() []string
Getenv(string) string
}
File represents a file descriptor.
type File interface {
io.ReadWriter
Fd() uintptr
}
NoColor is a nop for terminals that don't support colors.
type NoColor struct{}
func (c NoColor) Sequence(_ bool) string
Sequence returns the ANSI Sequence for the color.
func (c NoColor) String() string
Output is a terminal output.
type Output struct {
Profile
// contains filtered or unexported fields
}
func DefaultOutput() *Output
DefaultOutput returns the default global output.
func NewOutput(tty io.Writer, opts ...OutputOption) *Output
NewOutput returns a new Output for the given file descriptor.
func (o Output) AltScreen()
AltScreen switches to the alternate screen buffer. The former view can be restored with ExitAltScreen().
func (o *Output) BackgroundColor() Color
BackgroundColor returns the terminal's default background color.
func (o Output) ChangeScrollingRegion(top, bottom int)
ChangeScrollingRegion sets the scrolling region of the terminal.
func (o Output) ClearLine()
ClearLine clears the current line.
func (o Output) ClearLineLeft()
ClearLineLeft clears the line to the left of the cursor.
func (o Output) ClearLineRight()
ClearLineRight clears the line to the right of the cursor.
func (o Output) ClearLines(n int)
ClearLines clears a given number of lines.
func (o Output) ClearScreen()
ClearScreen clears the visible portion of the terminal.
func (o *Output) ColorProfile() Profile
ColorProfile returns the supported color profile: Ascii, ANSI, ANSI256, or TrueColor.
func (o Output) Copy(str string)
Copy copies text to clipboard using OSC 52 escape sequence.
func (o Output) CopyPrimary(str string)
CopyPrimary copies text to primary clipboard (X11) using OSC 52 escape sequence.
func (o Output) CursorBack(n int)
CursorBack moves the cursor backwards a given number of cells.
func (o Output) CursorDown(n int)
CursorDown moves the cursor down a given number of lines.
func (o Output) CursorForward(n int)
CursorForward moves the cursor up a given number of lines.
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 (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 (o Output) CursorUp(n int)
CursorUp moves the cursor up a given number of lines.
func (o Output) DeleteLines(n int)
DeleteLines deletes the given number of lines, pulling any lines in the scrollable region below up.
func (o Output) DisableBracketedPaste()
DisableBracketedPaste disables bracketed paste.
func (o Output) DisableMouse()
DisableMouse disables Mouse Tracking mode.
func (o Output) DisableMouseAllMotion()
DisableMouseAllMotion disables All Motion Mouse mode.
func (o Output) DisableMouseCellMotion()
DisableMouseCellMotion disables Cell Motion Mouse Tracking mode.
func (o Output) DisableMouseExtendedMode()
DisableMouseExtendedMotion disables Extended Mouse mode (SGR).
func (o Output) DisableMouseHilite()
DisableMouseHilite disables Hilite Mouse Tracking mode.
func (o Output) DisableMousePixelsMode()
DisableMousePixelsMotion disables Pixel Motion Mouse mode (SGR-Pixels).
func (o Output) DisableMousePress()
DisableMousePress disables X10 mouse mode.
func (o Output) EnableBracketedPaste()
EnableBracketedPaste enables bracketed paste.
func (o Output) EnableMouse()
EnableMouse enables Mouse Tracking mode.
func (o Output) EnableMouseAllMotion()
EnableMouseAllMotion enables All Motion Mouse mode.
func (o Output) EnableMouseCellMotion()
EnableMouseCellMotion enables Cell Motion Mouse Tracking mode.
func (o Output) EnableMouseExtendedMode()
EnableMouseExtendedMotion enables Extended Mouse mode (SGR). This should be enabled in conjunction with EnableMouseCellMotion, and EnableMouseAllMotion.
func (o Output) EnableMouseHilite()
EnableMouseHilite enables Hilite Mouse Tracking mode.
func (o Output) EnableMousePixelsMode()
EnableMousePixelsMotion enables Pixel Motion Mouse mode (SGR-Pixels). This should be enabled in conjunction with EnableMouseCellMotion, and EnableMouseAllMotion.
func (o Output) EnableMousePress()
EnableMousePress enables X10 mouse mode. Button press events are sent only.
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 (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 (o Output) ExitAltScreen()
ExitAltScreen exits the alternate screen buffer and returns to the former terminal view.
func (o *Output) ForegroundColor() Color
ForegroundColor returns the terminal's default foreground color.
func (o *Output) HasDarkBackground() bool
HasDarkBackground returns whether terminal uses a dark-ish background.
func (o Output) HideCursor()
HideCursor hides the cursor.
func (o *Output) Hyperlink(link, name string) string
Hyperlink creates a hyperlink using OSC8.
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 (o Output) MoveCursor(row int, column int)
MoveCursor moves the cursor to a given position.
func (o *Output) Notify(title, body string)
Notify triggers a notification using OSC777.
func (o Output) Reset()
Reset the terminal to its default style, removing any active styles.
func (o Output) RestoreCursorPosition()
RestoreCursorPosition restores a saved cursor position.
func (o Output) RestoreScreen()
RestoreScreen restores a previously saved screen state.
func (o Output) SaveCursorPosition()
SaveCursorPosition saves the cursor position.
func (o Output) SaveScreen()
SaveScreen saves the screen state.
func (o Output) SetBackgroundColor(color Color)
SetBackgroundColor sets the default background color.
func (o Output) SetCursorColor(color Color)
SetCursorColor sets the cursor color.
func (o Output) SetForegroundColor(color Color)
SetForegroundColor sets the default foreground color.
func (o Output) SetWindowTitle(title string)
SetWindowTitle sets the terminal window title.
func (o Output) ShowCursor()
ShowCursor shows the cursor.
func (o Output) TTY() File
TTY returns the terminal's file descriptor. This may be nil if the output is not a terminal.
func (o Output) TemplateFuncs() template.FuncMap
TemplateFuncs returns template helpers for the given output.
func (o Output) Write(p []byte) (int, error)
func (o Output) WriteString(s string) (int, error)
WriteString writes the given string to the output.
OutputOption sets an option on Output.
type OutputOption = func(*Output)
func WithColorCache(v bool) OutputOption
WithColorCache returns a new OutputOption with fore- and background color values pre-fetched and cached.
func WithEnvironment(environ Environ) OutputOption
WithEnvironment returns a new OutputOption for the given environment.
func WithProfile(profile Profile) OutputOption
WithProfile returns a new OutputOption for the given profile.
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() 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.
Profile is a color profile: Ascii, ANSI, ANSI256, or TrueColor.
type Profile int
func ColorProfile() Profile
ColorProfile returns the supported color profile: Ascii, ANSI, ANSI256, or TrueColor.
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 (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 (p Profile) Convert(c Color) Color
Convert transforms a given Color to a Color supported within the Profile.
func (p Profile) FromColor(c color.Color) Color
FromColor creates a Color from a color.Color.
func (p Profile) String(s ...string) Style
String returns a new Style.
RGBColor is a hex-encoded color, e.g. "#abcdef".
type RGBColor string
func (c RGBColor) Sequence(bg bool) string
Sequence returns the ANSI Sequence for the color.
Style is a string that various rendering styles can be applied to.
type Style struct {
// contains filtered or unexported fields
}
func String(s ...string) Style
String returns a new Style.
func (t Style) Background(c Color) Style
Background sets a background color.
func (t Style) Blink() Style
Blink enables blink mode.
func (t Style) Bold() Style
Bold enables bold rendering.
func (t Style) CrossOut() Style
CrossOut enables crossed-out rendering.
func (t Style) Faint() Style
Faint enables faint rendering.
func (t Style) Foreground(c Color) Style
Foreground sets a foreground color.
func (t Style) Italic() Style
Italic enables italic rendering.
func (t Style) Overline() Style
Overline enables overline rendering.
func (t Style) Reverse() Style
Reverse enables reverse color mode.
func (t Style) String() string
func (t Style) Styled(s string) string
Styled renders s with all applied styles.
func (t Style) Underline() Style
Underline enables underline rendering.
func (t Style) Width() int
Width returns the width required to print all runes in Style.
| Name | Synopsis |
|---|---|
| .. | |
| examples | |
| color-chart | |
| hello-world | |