Documentation
¶
Index ¶
- 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 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 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 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