Documentation
¶
Overview ¶
Package ui holds the terminal capability kernel that doctl's output components are built on. Env captures the current process's capabilities - terminals, color, animation, width - so components take them as an argument rather than a package global. Out carries data and Err carries chrome.
Index ¶
- Constants
- func IsCI() bool
- type Env
- func (e Env) DataProfile() termenv.Profile
- func (e Env) ErrRenderer() *lipgloss.Renderer
- func (e Env) ErrWriter() io.Writer
- func (e Env) Glyphs() Glyphs
- func (e Env) NewErrStyle() lipgloss.Style
- func (e Env) NewSpinner(message string, opts ...SpinnerOption) *Spinner
- func (e Env) NewStyle() lipgloss.Style
- func (e Env) Profile() termenv.Profile
- func (e Env) Renderer() *lipgloss.Renderer
- func (e Env) Sprint(style lipgloss.Style, s string) string
- func (e Env) SprintErr(style lipgloss.Style, s string) string
- func (e Env) SprintTone(tone Tone, s string) string
- func (e Env) Writer() io.Writer
- type Glyphs
- type Option
- type Spinner
- type SpinnerOption
- type Style
- type Tone
Constants ¶
const ( GlyphSuccess = "✓" GlyphFailure = "✗" GlyphWarning = "!" GlyphInfo = "i" GlyphCancelled = "·" GlyphPending = "⟳" GlyphBullet = "•" GlyphArrow = "❯" GlyphHint = "→" GlyphEllipsis = "…" GlyphSeparator = "·" GlyphNone = "—" // GlyphAsterisk marks a required field on a prompt. It is decoration rather // than state, which is why it is not part of Glyphs. GlyphAsterisk = "✱" )
Glyph characters are the one definition of doctl's symbol vocabulary, in the same way that style.go owns the palette.
const ( // ColorError is the red a failure is named in. ColorError lipgloss.Color = "#ff6188" // ColorSuccess is the green of a resource that reached its desired state. ColorSuccess lipgloss.Color = "#04b575" // ColorWarning is the yellow that reads as attention without alarm. ColorWarning lipgloss.Color = "#ffd866" // ColorInfo is the blue that names a resource. ColorInfo lipgloss.Color = "#2ea0f9" // ColorMuted is xterm 241, dim enough to recede behind a value. ColorMuted lipgloss.Color = "241" )
The semantic palette, and the one definition of doctl's colors. They are the colors doctl's interactive surfaces already use, so that a table, a prompt and an error all name the same state the same way. termenv downsamples them for terminals that cannot show truecolor.
const SpinnerInterval = 120 * time.Millisecond
SpinnerInterval is how often an animated spinner repaints.
const StageHeartbeat = time.Minute
StageHeartbeat is how often a plain stream repeats an unchanged stage.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Env ¶
type Env struct {
// Out is the destination for data: tables, JSON, anything pipeable.
Out io.Writer
// Err is the destination for chrome: spinners, prompts, and diagnostics.
Err io.Writer
// Style reports whether ANSI styling may be written to Out.
Style bool
// ErrStyle reports whether ANSI styling may be written to Err.
ErrStyle bool
// Anim reports whether animation may be written to Err. It is stricter than
// ErrStyle, additionally requiring an interactive, non-CI session.
Anim bool
// ASCII reports whether output must avoid non-ASCII glyphs.
ASCII bool
// Width is the session width, for chrome on Err, or 0 when undetermined.
Width int
// DataWidth is the width available to data on Out, or 0 when data must be
// left unconstrained. It is tracked separately from Width because a
// terminal on Err says nothing about Out: reflowing to a width Out does not
// have would corrupt a pipe.
DataWidth int
// DataTTY reports whether Out is an interactive terminal outside CI.
// Layout that is only meaningful on a screen someone is watching live -
// cards, boxed tables, the records fallback - is gated on it rather than
// on Style.
DataTTY bool
// ErrTTY reports whether Err is an interactive terminal outside CI, which
// gates glyphs and other screen-only chrome.
ErrTTY bool
// Machine reports whether machine-readable output was asked for. When true,
// Style, ErrStyle, and Anim are all false.
Machine bool
// Mask reports whether sensitive values (secrets, tokens, and similar)
// should be hidden rather than printed in full. It is independent of
// Machine: --output json still masks, since piping to a script is not
// consent to leak a secret into a log. It is true unless the invocation
// is running in CI or --show was passed.
Mask bool
// contains filtered or unexported fields
}
Env describes the capabilities available to a single command invocation.
func (Env) DataProfile ¶
DataProfile returns the color profile for Out, where a global must point.
func (Env) ErrRenderer ¶
ErrRenderer returns the lipgloss renderer bound to Err.
func (Env) NewErrStyle ¶
NewErrStyle returns an empty style bound to Err's renderer.
func (Env) NewSpinner ¶
func (e Env) NewSpinner(message string, opts ...SpinnerOption) *Spinner
NewSpinner returns a Spinner reporting message. The caller must Start it.
func (Env) Sprint ¶
Sprint renders s with style when styling is permitted on Out, rebinding the style to this Env's renderer.
func (Env) SprintTone ¶
SprintTone renders s in the color for tone when styling is permitted on Out, and returns s unchanged otherwise.
type Glyphs ¶
type Glyphs struct {
Success string
Failure string
Warning string
Info string
Cancelled string
Pending string
Bullet string
Arrow string
Ellipsis string
// Hint leads the suggestion that follows a diagnostic, pointing at what to
// do about it. It is a different arrow from Arrow, which prefixes prompts.
Hint string
// Separator and None carry no state, but both need an ASCII fallback.
Separator string
None string
// Spinner holds the animation frames, which must all be the same display
// width or the line jitters as it cycles.
Spinner []string
}
Glyphs is the symbol vocabulary used to convey state. It exists so that meaning survives when color does not, as when output is piped.
type Option ¶
type Option func(*config)
Option customises capability detection.
func WithAnimation ¶
WithAnimation forces animation on or off. Machine output still wins.
func WithInteractive ¶
WithInteractive records whether doctl's --interactive flag permitted it.
func WithMachineOutput ¶
WithMachineOutput suppresses all styling and animation, overriding options.
func WithProfile ¶
WithProfile forces the color profile of both streams; termenv.Ascii is off.
type Spinner ¶
type Spinner struct {
// contains filtered or unexported fields
}
Spinner reports the progress of a long-running operation. It renders to Err so that data on Out stays parseable: an animated frame on a terminal, one plain line per stage change elsewhere. Every method is a no-op after Stop.
func (*Spinner) Start ¶
func (s *Spinner) Start()
Start begins reporting progress. It animates on an interactive terminal, and otherwise prints the opening line and leaves later stages to Message.
type SpinnerOption ¶
type SpinnerOption func(*Spinner)
SpinnerOption configures a Spinner.
func WithHeading ¶
func WithHeading(format string, a ...any) SpinnerOption
WithHeading titles the wait, on its own line above the progress line.
type Style ¶
type Style struct {
// contains filtered or unexported fields
}
Style is a presentation helper bound to an Env, for chrome written to Err.
func (Style) ErrorLabel ¶
ErrorLabel returns the failure label, led by its glyph on a terminal.
func (Style) PaintCommand ¶
PaintCommand dims the lead-in of a suggestion and bolds the command path, so that the part worth copying stands out from the sentence around it.
func (Style) SuccessLine ¶
SuccessLine reports that a command finished, glyph and message painted together so that completion reads as one mark rather than a labelled diagnostic. The glyph leads only on a terminal, as ErrorLabel's does.
type Tone ¶
type Tone int
Tone is the meaning a value carries, separate from how it is painted.
const ( // ToneNone carries no meaning and is rendered unstyled. ToneNone Tone = iota // ToneSuccess is a resource that has reached its desired state. ToneSuccess // TonePending is a resource still moving towards it, or worth attention. TonePending // ToneError is a resource that failed or is unusable. ToneError // ToneMuted is a resource that is intentionally inert: off, deleted, unknown. ToneMuted // ToneIdentifier is the value that names the resource a row is about. // ToneFor never returns it: a name belongs to no vocabulary, so only a // caller that knows which column identifies the resource can ask for it. ToneIdentifier )
Source Files