Documentation
¶
Overview ¶
Package iostreams provides an abstraction over standard I/O with TTY awareness, color control, and test substitution. Commands use IOStreams instead of os.Stdin, os.Stdout, and os.Stderr directly, enabling testable output and consistent terminal behavior across the application.
Index ¶
- type ColorScheme
- func (cs *ColorScheme) Blue(text string) string
- func (cs *ColorScheme) Bold(text string) string
- func (cs *ColorScheme) Color256(code int, text string) string
- func (cs *ColorScheme) Cyan(text string) string
- func (cs *ColorScheme) Dim(text string) string
- func (cs *ColorScheme) ErrorIcon() string
- func (cs *ColorScheme) Gray(text string) string
- func (cs *ColorScheme) Green(text string) string
- func (cs *ColorScheme) Magenta(text string) string
- func (cs *ColorScheme) Red(text string) string
- func (cs *ColorScheme) SuccessIcon() string
- func (cs *ColorScheme) WarningIcon() string
- func (cs *ColorScheme) Yellow(text string) string
- type IOStreams
- func (s *IOStreams) CanPrompt() bool
- func (s *IOStreams) ColorScheme() *ColorScheme
- func (s *IOStreams) IsColorEnabled() bool
- func (s *IOStreams) IsStdinTTY() bool
- func (s *IOStreams) IsStdoutTTY() bool
- func (s *IOStreams) SetColorEnabled(enabled bool)
- func (s *IOStreams) SetStdinTTY(isTTY bool)
- func (s *IOStreams) SetStdoutTTY(isTTY bool)
- func (s *IOStreams) SetTerminalWidth(width int)
- func (s *IOStreams) TerminalWidth() int
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ColorScheme ¶
type ColorScheme struct {
// contains filtered or unexported fields
}
ColorScheme provides ANSI color formatting that respects terminal capabilities. When color is disabled (non-TTY or user preference), all methods return the input string unmodified, ensuring clean output in piped and scripted contexts.
func NewColorScheme ¶
func NewColorScheme(enabled bool) *ColorScheme
NewColorScheme creates a ColorScheme. When enabled is false, all formatting methods become identity functions that return their input unmodified.
func (*ColorScheme) Blue ¶
func (cs *ColorScheme) Blue(text string) string
Blue applies blue foreground color — typically used for informational messages.
func (*ColorScheme) Bold ¶
func (cs *ColorScheme) Bold(text string) string
Bold applies bold formatting.
func (*ColorScheme) Color256 ¶
func (cs *ColorScheme) Color256(code int, text string) string
Color256 applies a 256-color foreground color using the given palette index (0–255). This enables fine-grained color choices beyond the basic 16 ANSI colors — e.g., muted theme-specific shades for state indicators.
func (*ColorScheme) Cyan ¶
func (cs *ColorScheme) Cyan(text string) string
Cyan applies cyan foreground color — typically used for highlights and links.
func (*ColorScheme) Dim ¶
func (cs *ColorScheme) Dim(text string) string
Dim applies the ANSI dim/faint attribute, which reduces the brightness of the text relative to the terminal's default foreground color. Unlike Gray, Dim is theme-adaptive: it produces muted dark text on light backgrounds and muted light text on dark backgrounds.
func (*ColorScheme) ErrorIcon ¶
func (cs *ColorScheme) ErrorIcon() string
ErrorIcon returns a colored cross mark when color is enabled, or a plain text indicator otherwise — suitable for indicating failures.
func (*ColorScheme) Gray ¶
func (cs *ColorScheme) Gray(text string) string
Gray applies a medium-gray foreground color — typically used for secondary information. It uses the 256-color code 244, which maps to rgb(128,128,128) (#808080) and is readable on both light and dark terminal backgrounds.
func (*ColorScheme) Green ¶
func (cs *ColorScheme) Green(text string) string
Green applies green foreground color — typically used for success states.
func (*ColorScheme) Magenta ¶
func (cs *ColorScheme) Magenta(text string) string
Magenta applies magenta foreground color.
func (*ColorScheme) Red ¶
func (cs *ColorScheme) Red(text string) string
Red applies red foreground color — typically used for errors and failures.
func (*ColorScheme) SuccessIcon ¶
func (cs *ColorScheme) SuccessIcon() string
SuccessIcon returns a colored check mark when color is enabled, or a plain text indicator otherwise — suitable for indicating successful operations.
func (*ColorScheme) WarningIcon ¶
func (cs *ColorScheme) WarningIcon() string
WarningIcon returns a colored warning symbol when color is enabled, or a plain text indicator otherwise.
func (*ColorScheme) Yellow ¶
func (cs *ColorScheme) Yellow(text string) string
Yellow applies yellow foreground color — typically used for warnings.
type IOStreams ¶
type IOStreams struct {
// In is the input reader, typically connected to os.Stdin.
In io.ReadCloser
// Out is the primary output writer, typically connected to os.Stdout.
Out io.Writer
// ErrOut is the error/diagnostic output writer, typically connected to os.Stderr.
ErrOut io.Writer
// contains filtered or unexported fields
}
IOStreams abstracts standard I/O with TTY awareness and color control. Commands read from In and write to Out (stdout) or ErrOut (stderr). In production, these are connected to real file descriptors; in tests, they are backed by in-memory buffers via Test().
func System ¶
func System() *IOStreams
System returns IOStreams connected to the real standard file descriptors with TTY detection and color support based on terminal capabilities. This is the production constructor — call it once at startup.
func Test ¶
Test returns IOStreams backed by in-memory buffers, suitable for tests. The returned buffers let tests inspect what a command wrote to stdout and stderr without touching the real terminal. TTY flags default to false; use SetStdoutTTY and SetStdinTTY to simulate terminal behavior.
func (*IOStreams) CanPrompt ¶
CanPrompt reports whether the application can prompt the user for input. This requires both stdin and stdout to be TTYs — if either is piped, interactive prompts would hang or produce garbled output.
func (*IOStreams) ColorScheme ¶
func (s *IOStreams) ColorScheme() *ColorScheme
ColorScheme returns a ColorScheme configured for this IOStreams instance. When color is disabled, the scheme returns strings unmodified.
func (*IOStreams) IsColorEnabled ¶
IsColorEnabled reports whether color output is enabled. Color is enabled by default when stdout is a TTY.
func (*IOStreams) IsStdinTTY ¶
IsStdinTTY reports whether stdin is connected to an interactive terminal.
func (*IOStreams) IsStdoutTTY ¶
IsStdoutTTY reports whether stdout is connected to an interactive terminal. Commands use this to decide between human-friendly output (colors, tables, relative timestamps) and machine-parseable output (plain text, absolute timestamps, tab-separated values).
func (*IOStreams) SetColorEnabled ¶
SetColorEnabled overrides the automatic color detection. Use this to force color on or off regardless of TTY status, for example when the user has set a NO_COLOR environment variable.
func (*IOStreams) SetStdinTTY ¶
SetStdinTTY overrides the stdin TTY flag. Used in tests to simulate terminal vs. piped input.
func (*IOStreams) SetStdoutTTY ¶
SetStdoutTTY overrides the stdout TTY flag and updates color enablement accordingly. Used in tests to simulate terminal vs. piped output.
func (*IOStreams) SetTerminalWidth ¶
SetTerminalWidth overrides the detected terminal width. Used in tests to simulate a terminal of a specific width without requiring a real TTY.
func (*IOStreams) TerminalWidth ¶
TerminalWidth returns the width of the terminal in columns. Returns 0 when stdout is not a TTY (piped output), signaling that callers should not apply width-dependent formatting (wrapping, truncation). If SetTerminalWidth has been called, the override value is returned instead of querying the terminal.
Source Files