Documentation
¶
Index ¶
- func ClearLine() error
- func Error(text string) error
- func Errorf(format string, a ...interface{}) error
- func Info(text string) error
- func Infof(format string, a ...interface{}) error
- func InitFormatter(ioCtx io.Context)
- func Markdown(content string) error
- func MarkdownMessage(content string) error
- func MarkdownMessagef(format string, a ...interface{}) error
- func Markdownf(format string, a ...interface{}) error
- func SetColorProfile(profile termenv.Profile)
- func Success(text string) error
- func Successf(format string, a ...interface{}) error
- func Toast(icon, message string) error
- func Toastf(icon, format string, a ...interface{}) error
- func Warning(text string) error
- func Warningf(format string, a ...interface{}) error
- func Write(text string) error
- func Writef(format string, a ...interface{}) error
- func Writeln(text string) error
- type Formatter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClearLine ¶ added in v1.200.0
func ClearLine() error
ClearLine clears the current line in the terminal and returns cursor to the beginning. Respects NO_COLOR and terminal capabilities - uses ANSI escape sequences only when supported. When colors are disabled, only writes carriage return to move cursor to start of line. This is useful for replacing spinner messages or other dynamic output with final status messages. Flow: ui.ClearLine() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
Example usage:
// Clear spinner line and show success message
_ = ui.ClearLine()
_ = ui.Success("Operation completed successfully")
func Error ¶
Error writes an error message with red X to stderr (UI channel). This is a convenience wrapper with themed error icon and color. Flow: ui.Error() → ui.Format.Error() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
func Errorf ¶
Errorf writes a formatted error message with red X to stderr (UI channel). This is a convenience wrapper with themed error icon and color. Flow: ui.Errorf() → ui.Format.Errorf() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
func Info ¶
Info writes an info message with cyan info icon to stderr (UI channel). This is a convenience wrapper with themed info icon and color. Flow: ui.Info() → ui.Format.Info() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
func Infof ¶
Infof writes a formatted info message with cyan info icon to stderr (UI channel). This is a convenience wrapper with themed info icon and color. Flow: ui.Infof() → ui.Format.Infof() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
func InitFormatter ¶
InitFormatter initializes the global formatter with an I/O context. This should be called once at application startup (in root.go).
func Markdown ¶
Markdown writes rendered markdown to stdout (data channel). Use this for help text, documentation, and other pipeable formatted content. Note: Delegates to globalFormatter.Markdown() for rendering, then writes to data channel.
func MarkdownMessage ¶
MarkdownMessage writes rendered markdown to stderr (UI channel). Use this for formatted UI messages and errors.
func MarkdownMessagef ¶
MarkdownMessagef writes formatted markdown to stderr (UI channel).
func SetColorProfile ¶ added in v1.200.0
SetColorProfile sets the color profile for all UI systems (lipgloss, theme, logger). This is primarily intended for testing when environment variables are set after package initialization. For normal operation, color profiles are automatically configured during InitFormatter() based on terminal capabilities.
Example usage in tests:
t.Setenv("NO_COLOR", "1")
ui.SetColorProfile(termenv.Ascii)
func Success ¶
Success writes a success message with green checkmark to stderr (UI channel). This is a convenience wrapper with themed success icon and color. Flow: ui.Success() → ui.Format.Success() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
func Successf ¶
Successf writes a formatted success message with green checkmark to stderr (UI channel). This is a convenience wrapper with themed success icon and color. Flow: ui.Successf() → ui.Format.Successf() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
func Toast ¶ added in v1.199.0
Toast writes a toast notification with a custom icon and message to stderr (UI channel). This is the primary pattern for toast-style notifications with flexible icon support. Supports multiline messages - automatically splits on newlines and indents continuation lines. Flow: ui.Toast() → ui.Format.Toast() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
Parameters:
- icon: Custom icon/emoji (e.g., "📦", "🔧", "✓", or use theme.Styles.Checkmark.String())
- message: The message text (can contain newlines for multiline toasts)
Example usage:
ui.Toast("📦", "Using latest version: 1.2.3")
ui.Toast("🔧", "Tool not installed")
ui.Toast("✓", "Installation complete\nVersion: 1.2.3\nLocation: /usr/local/bin")
func Toastf ¶ added in v1.199.0
Toastf writes a formatted toast notification with a custom icon to stderr (UI channel). This is the primary pattern for formatted toast-style notifications with flexible icon support. Flow: ui.Toastf() → ui.Format.Toastf() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
Parameters:
- icon: Custom icon/emoji (e.g., "📦", "🔧", "✓", or use theme.Styles.Checkmark.String())
- format: Printf-style format string
- a: Format arguments
Example usage:
ui.Toastf("📦", "Using latest version: %s", version)
ui.Toastf("🔧", "Tool %s is not installed", toolName)
ui.Toastf(theme.Styles.Checkmark.String(), "Installed %s/%s@%s", owner, repo, version)
func Warning ¶
Warning writes a warning message with yellow warning sign to stderr (UI channel). This is a convenience wrapper with themed warning icon and color. Flow: ui.Warning() → ui.Format.Warning() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
func Warningf ¶
Warningf writes a formatted warning message with yellow warning sign to stderr (UI channel). This is a convenience wrapper with themed warning icon and color. Flow: ui.Warningf() → ui.Format.Warningf() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
func Write ¶
Write writes plain text to stderr (UI channel) without icons or automatic styling. Flow: ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr.
Types ¶
type Formatter ¶
type Formatter interface {
// Toast formatting - flexible toast notifications with custom icons and multiline support
// Automatically handles newlines with proper indentation
Toast(icon, message string) string // Returns "{icon} {message}" with multiline support
Toastf(icon, format string, a ...interface{}) string // Returns formatted toast
// Status message formatting - standardized output with icons
// This is the foundational method used by Success/Error/Warning/Info
StatusMessage(icon string, style *lipgloss.Style, text string) string
// Semantic formatting - returns styled strings with automatic icons (uses theme.StyleSet)
// These methods use Toast internally with predefined icons and colors
Success(text string) string // Returns "✓ {text}" in green
Successf(format string, a ...interface{}) string // Returns "✓ {formatted}" in green
Warning(text string) string // Returns "⚠ {text}" in yellow
Warningf(format string, a ...interface{}) string // Returns "⚠ {formatted}" in yellow
Error(text string) string // Returns "✗ {text}" in red
Errorf(format string, a ...interface{}) string // Returns "✗ {formatted}" in red
Info(text string) string // Returns "ℹ {text}" in cyan
Infof(format string, a ...interface{}) string // Returns "ℹ {formatted}" in cyan
Muted(text string) string // Returns muted text (gray, no icon)
// Text formatting - returns styled strings
Bold(text string) string // Returns bold text
Heading(text string) string // Returns heading-styled text
Label(text string) string // Returns label-styled text
// Theme access
Styles() *theme.StyleSet // Access to full theme-aware StyleSet
// Capability queries (delegates to terminal.Terminal)
ColorProfile() terminal.ColorProfile
SupportsColor() bool
// Markdown rendering - returns rendered markdown string (pure function, no I/O)
// For writing markdown to channels, use package-level ui.Markdown() or ui.MarkdownMessage()
Markdown(content string) (string, error)
}
Formatter provides text formatting with automatic degradation. Key Principle: Formatter RETURNS FORMATTED STRINGS - it never writes to streams.
Usage Pattern:
io := cmd.Context().Value(ioContextKey).(io.Context)
ui := cmd.Context().Value(uiFormatterKey).(ui.Formatter)
// Format text with automatic icons
msg := ui.Success("Deployment complete!") // Returns "✓ Deployment complete!" in green
// Developer chooses channel
fmt.Fprintf(io.UI(), "%s\n", msg) // UI message → stderr
Uses io.Terminal for capability detection and theme.StyleSet for styling.
var Format Formatter
Format exposes the global formatter for advanced use cases. Most code should use the package-level functions (ui.Success, ui.Error, etc.). Use this when you need the formatted string without writing it.
Source Files
Directories