term

package
v0.28.0 Latest Latest
Warning

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

 Go to latest Published: Jun 9, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CHAR_UNSPECIFIED    = 0
	CHAR_COLOR_SEQUENCE = 1
	CHAR_CONTROL        = 2
)

Variables

This section is empty.

Functions

func Fprintf 

func Fprintf(w io.Writer, format string, a ...any) (int, error)

Fprintf formats according to a format specifier and writes to w. It respects the global StderrLevel and StdoutLevel settings:

  • If w is os.Stdout and StdoutLevel is LevelNone, ANSI codes are stripped
  • If w is os.Stderr and StderrLevel is LevelNone, ANSI codes are stripped
  • Otherwise, output is passed through unchanged

This allows TUI applications to automatically disable colors when the output is redirected to a file or pipe.

func GetSize 

func GetSize(fd int) (width, height int, err error)

GetSize returns the dimensions of the terminal for the given file descriptor. Returns width, height in characters, and any error encountered.

func HasDarkBackground added in v0.28.0 

func HasDarkBackground() bool

HasDarkBackground reports whether the terminal has a dark background. Detection is lazy (executed at most once) and only queries the terminal if it is known to support OSC 11 reliably. Otherwise it defaults to true.

func IsCygwinTerminal 

func IsCygwinTerminal(fd uintptr) bool

func IsNativeTerminal 

func IsNativeTerminal(fd uintptr) bool

IsNativeTerminal returns true if the given file descriptor is a native terminal (not a Cygwin/MSYS2 pseudo-terminal).

func IsTerminal 

func IsTerminal(fd uintptr) bool

IsTerminal returns true if the given file descriptor is connected to a terminal. This works for both native terminals and Cygwin/MSYS2 pseudo-terminals.

func MakeRaw added in v0.28.0 

func MakeRaw(fd int) (*term.State, error)

MakeRaw puts the terminal connected to the given file descriptor into raw mode and returns the previous state of the terminal so that it can be restored.

func Restore added in v0.28.0 

func Restore(fd int, oldState *term.State) error

Restore restores the terminal connected to the given file descriptor to a previous state.

func SanitizeANSI 

func SanitizeANSI(content string, allowColor bool) string

SanitizeANSI sanitizes ANSI sequences in content for safe terminal output.

Behavior:

  • If allowColor is true: ANSI color sequences are preserved
  • If allowColor is false: All ANSI sequences are removed
  • Control characters (except tab and newline) are converted to caret notation (^G, etc.)

This is useful for displaying untrusted or external output safely in a TUI.

func SanitizedF 

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

SanitizedF formats according to a format specifier, sanitizes the result, and writes it to stderr. Color sequences are preserved based on StderrLevel.

This is a convenience function for safely printing formatted output to stderr in TUI applications, ensuring control characters are converted to caret notation.

Types

type AdaptiveColor added in v0.28.0 

type AdaptiveColor struct {
	Light color.Color
	Dark  color.Color
}

AdaptiveColor holds a pair of colors for light and dark backgrounds. It implements image/color.Color and selects the appropriate variant based on the terminal's background at runtime.

func (AdaptiveColor) RGBA added in v0.28.0 

func (c AdaptiveColor) RGBA() (uint32, uint32, uint32, uint32)

RGBA implements image/color.Color.

type ImageMode added in v0.25.0 

type ImageMode int

ImageMode represents a tri-state preference for inline image rendering, typically wired to a CLI flag like --image=auto|on|off. 

const (
	// ImageModeAuto honours the detected terminal capability: render images
	// only when DetectImageProtocol reports a supported protocol.
	ImageModeAuto ImageMode = iota
	// ImageModeOn forces image rendering even when detection returned
	// ImageNone (useful for terminals not on our whitelist, or for tmux
	// passthrough setups). When detection has no protocol, iTerm2 is used as
	// the most widely compatible default.
	ImageModeOn
	// ImageModeOff disables image rendering unconditionally.
	ImageModeOff
)

func ParseImageMode added in v0.25.0 

func ParseImageMode(s string) ImageMode

ParseImageMode parses a CLI/config string into an ImageMode. Recognised values are "auto", "on" (synonyms: "yes", "true", "1"), and "off" (synonyms: "no", "false", "0"). Unknown values fall back to ImageModeAuto so that misconfiguration never silently disables a feature the user wanted.

type ImageProtocol added in v0.25.0 

type ImageProtocol int

ImageProtocol represents an inline-image protocol supported by the hosting terminal. 

const (
	// ImageNone means the terminal is not known to support any inline image
	// protocol; callers should fall back to a textual representation
	// (e.g. a hex dump).
	ImageNone ImageProtocol = iota
	// ImageITerm2 is the iTerm2 / WezTerm OSC 1337 inline image protocol.
	ImageITerm2
	// ImageKitty is the Kitty graphics protocol, also implemented by WezTerm,
	// Ghostty and recent Konsole builds.
	ImageKitty
)

func DetectImageProtocol added in v0.25.0 

func DetectImageProtocol() ImageProtocol

DetectImageProtocol inspects environment variables to determine which inline-image protocol (if any) is supported by the current terminal.

This is intentionally an on-demand check rather than a package-init side effect: image rendering is the exception rather than the rule, so the environment probe should only run once the caller has decided it actually has an image to display.

Detection order:

  1. Kitty graphics: TERM=xterm-kitty, KITTY_WINDOW_ID set, KONSOLE_VERSION >= 22.04, or TERM_PROGRAM in {ghostty, WezTerm}.
  2. iTerm2 OSC 1337: TERM_PROGRAM=iTerm.app, or LC_TERMINAL=iTerm2.

WezTerm also speaks iTerm2's protocol and Sixel, but Kitty graphics is strictly richer (24-bit colour, no quantisation, chunked transfers), so it wins the tie.

Anything else returns ImageNone. Terminals with unreliable support (Warp, VSCode) are intentionally excluded from the auto whitelist; users can force rendering via --image=on.

func ResolveImage added in v0.25.0 

func ResolveImage(mode string) ImageProtocol

ResolveImage parses a user-supplied mode string and returns the inline image protocol the caller should use.

  • off: always returns ImageNone (environment probe is skipped).
  • on: returns the detected protocol, or ImageITerm2 when nothing was detected (most widely compatible default for tmux passthrough and terminals not on our whitelist).
  • auto (default): returns the detected protocol as-is.

func (ImageProtocol) String added in v0.25.0 

func (p ImageProtocol) String() string

String returns a short, lower-case name for the protocol, suitable for logging and configuration values.

func (ImageProtocol) Supported added in v0.25.0 

func (p ImageProtocol) Supported() bool

Supported reports whether the protocol is a real inline image protocol.

type Level 

type Level int

Level represents the color support level of a terminal.

The levels are:

  • LevelNone: No color support, ANSI codes are stripped
  • Level256: 256-color palette support (standard ANSI colors)
  • Level16M: 16 million colors (24-bit truecolor/RGB) support
const (
	LevelNone Level = iota
	Level256
	Level16M
)
var (
	// StderrLevel is the detected color support level for stderr.
	StderrLevel Level
	// StdoutLevel is the detected color support level for stdout.
	StdoutLevel Level
)

func (Level) Blue added in v0.19.1 

func (v Level) Blue(s string) string

Blue returns the string s wrapped in blue ANSI color codes. The color format depends on the Level:

  • Level16M: Uses RGB #00c8ff (truecolor)
  • Level256: Uses standard ANSI blue
  • LevelNone: Returns s unchanged

func (Level) Green added in v0.19.1 

func (v Level) Green(s string) string

Green returns the string s wrapped in green ANSI color codes. The color format depends on the Level:

  • Level16M: Uses RGB #43e97a (truecolor)
  • Level256: Uses standard ANSI green
  • LevelNone: Returns s unchanged

func (Level) Purple added in v0.19.1 

func (v Level) Purple(s string) string

Purple returns the string s wrapped in purple ANSI color codes. The color format depends on the Level:

  • Level16M: Uses RGB #7028e4 (truecolor)
  • Level256: Uses standard ANSI purple
  • LevelNone: Returns s unchanged

func (Level) Red added in v0.19.1 

func (v Level) Red(s string) string

Red returns the string s wrapped in red ANSI color codes. The color format depends on the Level:

  • Level16M: Uses RGB #f43b47 (truecolor)
  • Level256: Uses standard ANSI red
  • LevelNone: Returns s unchanged

func (Level) SupportColor 

func (level Level) SupportColor() bool

SupportColor returns true if the terminal supports any color output.

func (Level) Yellow added in v0.19.1 

func (v Level) Yellow(s string) string

Yellow returns the string s wrapped in yellow ANSI color codes. The color format depends on the Level:

  • Level16M: Uses RGB #fee240 (truecolor)
  • Level256: Uses standard ANSI yellow
  • LevelNone: Returns s unchanged

Source Files

View all Source files

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.