Documentation
¶
Overview ¶
Package render is the structured, non-interactive terminal display layer of the CLI kit.
It covers everything a command emits when it is reporting rather than prompting:
- OutputTable — aligned tables for row/column data, returned as a string.
- OutputKV — key-value blocks for headers and summaries, returned as a string.
- OutputFormat, the shared ExitCode convention, and an ErrorRenderer that turns an github.com/kbukum/gokit/errors.AppError into consistent text/JSON/YAML.
- StatusReporter — one-off feedback lines (success/warn/step/heading) for guided, multi-step flows, written to an injected io.Writer.
The pure builders (OutputTable, OutputKV, ErrorRenderer) return strings the caller writes; StatusReporter writes to an injected io.Writer. Theme use is per renderer: StatusReporter applies the palette and glyphs (github.com/kbukum/gokit/cli/theme.Palette, github.com/kbukum/gokit/cli/theme.Glyphs) so color and symbols honor NO_COLOR, TTY detection, and UTF-8 capability; OutputTable selects its border charset from glyph capability; OutputKV and ErrorRenderer emit plain text.
Index ¶
- type ErrorRenderer
- type ExitCode
- type OutputFormat
- type OutputKV
- type OutputTable
- type StatusReporter
- func (r *StatusReporter) Bullet(message string) error
- func (r *StatusReporter) Error(message string) error
- func (r *StatusReporter) Heading(title string) error
- func (r *StatusReporter) Info(message string) error
- func (r *StatusReporter) Step(current, total int, message string) error
- func (r *StatusReporter) Success(message string) error
- func (r *StatusReporter) Warn(message string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ErrorRenderer ¶
type ErrorRenderer struct {
// contains filtered or unexported fields
}
ErrorRenderer renders github.com/kbukum/gokit/errors.AppError values consistently for command-line applications.
func NewErrorRenderer ¶
func NewErrorRenderer(format OutputFormat) ErrorRenderer
NewErrorRenderer creates a renderer for the requested output format.
func (ErrorRenderer) Render ¶
func (r ErrorRenderer) Render(err error) (string, ExitCode)
Render renders an error and returns the matching CLI exit code.
The same exit code is returned regardless of format, so callers can render in any format and still exit consistently. A non-AppError is first wrapped as an internal AppError so every error renders through the same envelope.
type ExitCode ¶
type ExitCode int
ExitCode is the process exit-code convention shared by gokit CLIs.
const ( // ExitSuccess is a successful command. ExitSuccess ExitCode = 0 // ExitFailure is an unclassified failure. ExitFailure ExitCode = 1 // ExitUsage is invalid command input or configuration. ExitUsage ExitCode = 2 // ExitPermission is an authentication or authorization failure. ExitPermission ExitCode = 3 // ExitNotFound is a requested resource that was not found. ExitNotFound ExitCode = 4 // ExitConflict is a conflict with the current state. ExitConflict ExitCode = 5 ExitUnavailable ExitCode = 69 // ExitRateLimited is a rate-limited command. ExitRateLimited ExitCode = 75 // ExitTimeout is a command that timed out. ExitTimeout ExitCode = 124 // ExitCanceled is a command that was canceled. ExitCanceled ExitCode = 130 )
func ExitCodeForError ¶
ExitCodeForError maps an error's code onto the CLI exit-code convention.
It resolves the underlying github.com/kbukum/gokit/errors.AppError via errors.As; a nil error maps to ExitSuccess and any non-AppError to ExitFailure.
type OutputFormat ¶
type OutputFormat int
OutputFormat is a machine-readable output format for CLI renderers.
const ( // FormatText is human-readable terminal text (the zero value). FormatText OutputFormat = iota // FormatJSON is a JSON object or array. FormatJSON // FormatYAML is a YAML document. FormatYAML )
func ParseOutputFormat ¶
func ParseOutputFormat(name string) (OutputFormat, bool)
ParseOutputFormat parses a format from its lowercase name (text/json/yaml).
The second return value is false for any other value, so the caller can raise its own typed usage error naming the accepted values.
func (OutputFormat) String ¶
func (f OutputFormat) String() string
String returns the canonical lowercase name of the format.
type OutputKV ¶
type OutputKV struct {
// contains filtered or unexported fields
}
OutputKV is a key-value display block for headers and summaries.
Keys are right-aligned to the widest key so values line up in a column. Construct one with NewOutputKV; rendering is pure via OutputKV.String.
func NewOutputKV ¶
func NewOutputKV() *OutputKV
NewOutputKV creates an empty key-value output block.
type OutputTable ¶
type OutputTable struct {
// contains filtered or unexported fields
}
OutputTable is a formatted table for terminal output.
The zero value is not usable; construct one with NewOutputTable. Rendering is pure — OutputTable.String builds the whole table as a string — so callers choose where to write it. Borders default to Unicode box-drawing; pass an ASCII-only theme.Glyphs via OutputTable.WithGlyphs to stay byte-clean on non-UTF-8 terminals.
func NewOutputTable ¶
func NewOutputTable(columns ...string) *OutputTable
NewOutputTable creates a table with the given column headings.
func (*OutputTable) AddRow ¶
func (t *OutputTable) AddRow(cells ...string) *OutputTable
AddRow appends a row of cell values.
The row is normalized to the column count: extra cells are dropped and missing cells are padded with empty strings, so every rendered row lines up with the header and borders regardless of the caller's cell count.
func (*OutputTable) String ¶
func (t *OutputTable) String() string
String renders the table as a bordered, column-aligned block.
func (*OutputTable) WithGlyphs ¶
func (t *OutputTable) WithGlyphs(glyphs theme.Glyphs) *OutputTable
WithGlyphs selects the border charset from a glyph set's Unicode capability: box-drawing when Unicode is enabled, ASCII (+-|) otherwise.
func (*OutputTable) WithTitle ¶
func (t *OutputTable) WithTitle(title string) *OutputTable
WithTitle sets a human-readable table title and returns the receiver.
type StatusReporter ¶
type StatusReporter struct {
// contains filtered or unexported fields
}
StatusReporter emits one-off status feedback lines for guided, multi-step CLI flows over an injected writer and theme.Style.
Where progress animates ongoing work and prompt reads input, this renders the short, one-shot status lines a flow emits between steps: a green "✓ Detected Go", a "1/4" step counter, a section heading, or a warn/error notice. The theme.Style carries the color palette and glyph set, so every line honors NO_COLOR, TTY detection, and UTF-8 capability.
func NewStatusReporter ¶
func NewStatusReporter(w io.Writer, style theme.Style) *StatusReporter
NewStatusReporter builds a reporter from an explicit writer and style. Callers bind the writer to a real stream (typically stderr, the "diagnostics to stderr" convention) while tests pass an in-memory buffer.
func (*StatusReporter) Bullet ¶
func (r *StatusReporter) Bullet(message string) error
Bullet emits an indented bullet line: a dimmed bullet glyph followed by message.
func (*StatusReporter) Error ¶
func (r *StatusReporter) Error(message string) error
Error emits an error line: a red cross glyph followed by message.
func (*StatusReporter) Heading ¶
func (r *StatusReporter) Heading(title string) error
Heading emits a bold section heading preceded by a blank line.
func (*StatusReporter) Info ¶
func (r *StatusReporter) Info(message string) error
Info emits an informational line: a cyan info glyph followed by message.
func (*StatusReporter) Step ¶
func (r *StatusReporter) Step(current, total int, message string) error
Step emits a step line prefixed with a dimmed "current/total" counter.
func (*StatusReporter) Success ¶
func (r *StatusReporter) Success(message string) error
Success emits a success line: a green check glyph followed by message.
func (*StatusReporter) Warn ¶
func (r *StatusReporter) Warn(message string) error
Warn emits a warning line: a yellow warning glyph followed by message.
Source Files