iostream

package
v1.0.47876 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 11, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ColorEnabled 

func ColorEnabled(ctx context.Context) bool

func DebugContext 

func DebugContext(ctx context.Context, msg string, args ...any)

func Err 

func Err(ctx context.Context) io.Writer

func ErrIsTerminal added in v1.0.47519 

func ErrIsTerminal(ctx context.Context) bool

func ErrPrint 

func ErrPrint(ctx context.Context, s string)

func ErrPrintf 

func ErrPrintf(ctx context.Context, format string, a ...any)

func ErrPrintln 

func ErrPrintln(ctx context.Context, a ...any)

func FromCmd 

func FromCmd(ctx context.Context, cmd *cobra.Command, configTheme string) context.Context

FromCmd extracts Streams from a cobra.Command's Out/Err/In and reads the --quiet persistent flag if registered on the root command.

The color theme is resolved with the --theme flag taking precedence when it was explicitly set; otherwise configTheme (the stored CLI setting, "" if none) is used, falling back to the flag's "auto" default.

func In 

func In(ctx context.Context) io.Reader

func Indent 

func Indent(s, indent string) string

func InfoContext 

func InfoContext(ctx context.Context, msg string, args ...any)

func IsInteractive 

func IsInteractive(ctx context.Context) bool

func IsTerminal 

func IsTerminal(ctx context.Context) bool

func IsValidTheme 

func IsValidTheme(theme string) bool

IsValidTheme reports whether theme is one of the names returned by ValidThemes.

func Muted added in v1.0.47519 

func Muted(ctx context.Context, strs ...string) string

func Out 

func Out(ctx context.Context) io.Writer

func Print 

func Print(ctx context.Context, v string)

func PrintJSON 

func PrintJSON(ctx context.Context, v any) error

func PrintJSONFromReader 

func PrintJSONFromReader(ctx context.Context, r io.Reader) error

func PrintJSONStream 

func PrintJSONStream(ctx context.Context, produce func(emit func(any) error) error) error

func PrintMarkdown 

func PrintMarkdown(ctx context.Context, md string)

func Printf 

func Printf(ctx context.Context, format string, a ...any)

func Println 

func Println(ctx context.Context, a ...any)

func PromptSecret 

func PromptSecret(ctx context.Context, header string) (string, error)

PromptSecret presents a masked text input to collect a secret value. Returns ("", nil) if the user cancels.

func PromptSelect 

func PromptSelect(ctx context.Context, prompt string, options []string) (int, error)

PromptSelect presents an interactive single-choice list to the user and returns the index of the selected option. Returns (-1, nil) if the user cancels with esc or ctrl+c.

func PromptSelectDefault 

func PromptSelectDefault(ctx context.Context, prompt string, options []string, defaultIdx int) (int, error)

PromptSelectDefault is like PromptSelect but pre-highlights the option at defaultIdx. Returns the index of the selected option, or -1 if cancelled.

func PromptText 

func PromptText(ctx context.Context, header, placeholder string, defaultVal ...string) (string, error)

PromptText presents a plain (non-secret) single-line text input via bubbletea. header is the bold heading above the input; placeholder is shown inside the empty field; defaultVal (optional) is returned when the user presses Enter with an empty field. Returns ("", nil) if the user cancels with esc or ctrl+c.

func PromptThemePreview 

func PromptThemePreview(ctx context.Context, prompt string, labels, themes []string, defaultIdx int, sampleMarkdown string) (int, error)

PromptThemePreview presents a split-pane theme picker with a live markdown preview rendered in the highlighted theme. See Streams.PromptThemePreview.

func ReadSecret 

func ReadSecret(ctx context.Context, value string) (string, error)

ReadSecret reads a sensitive value from the streams in context. Returns value as-is unless value is "-", in which case reads one line from stdin.

func RenderMarkdownAt 

func RenderMarkdownAt(ctx context.Context, md string, width int) string

RenderMarkdownAt renders md as styled markdown wrapped to width columns when color is enabled, falling back to the raw markdown otherwise. Unlike PrintMarkdown it returns the string rather than writing it, for interactive full-screen views (e.g. the run-get help overlay) that re-wrap their content to the live terminal width.

func SpinnerEnabled 

func SpinnerEnabled(ctx context.Context) bool

func Success added in v1.0.47519 

func Success(ctx context.Context, strs ...string) string

func SymbolFail 

func SymbolFail(ctx context.Context) string

func SymbolOK 

func SymbolOK(ctx context.Context) string

func SymbolWarn 

func SymbolWarn(ctx context.Context) string

func Testing 

func Testing(ctx context.Context) context.Context

func Title 

func Title(ctx context.Context, strs ...string) string

func ValidThemes 

func ValidThemes() []string

ValidThemes returns the theme names accepted by the --theme flag and the "theme" CLI setting, sorted for stable display. This is the single source of truth for theme validation: "auto" detects the terminal background, "ansi" is our custom 16-color style, and the rest are glamour's built-in styles.

func Warning added in v1.0.47519 

func Warning(ctx context.Context, strs ...string) string

func WithJQFilter 

func WithJQFilter(ctx context.Context, jqFilter string) context.Context

func WithStreams 

func WithStreams(ctx context.Context, s Streams) context.Context

Types

type Spin 

type Spin struct {
	// contains filtered or unexported fields
}

Spin is a progress indicator. Call Stop when the operation completes. It is safe to call Stop on a nil or no-op Spin, and safe to call it more than once.

func Spinner 

func Spinner(ctx context.Context, active bool, msg string) *Spin

func (*Spin) Stop 

func (sp *Spin) Stop()

Stop halts the spinner and clears its line. It is safe to call on a nil or no-op Spin and safe to call more than once.

type Streams 

type Streams struct {
	Out   io.Writer // structured output (data results)
	Err   io.Writer // status messages, errors, progress
	In    io.Reader // user input for interactive prompts
	Quiet bool      // when true, ErrPrintf/ErrPrintln produce no output
	// contains filtered or unexported fields
}

Streams bundles the I/O channels passed through every command. All output must go through Streams — never write to os.Stdout directly.

func Get 

func Get(ctx context.Context) Streams

Get returns the Streams stored in ctx, or a discard-everything Streams if none was set. Use this when you need to pass a Streams value to a helper function (e.g. cmdutil.ConfirmOrForce) rather than calling the ctx-based package-level wrappers.

func (Streams) ColorEnabled 

func (s Streams) ColorEnabled() bool

ColorEnabled reports whether color and Unicode symbols should be used. False when: not a TTY, NO_COLOR set, CIRCLE_NO_COLOR set, or TERM=dumb. The --no-color flag is honored here too: root canonicalizes it into NO_COLOR before streams are built, so colorDisabled() already accounts for it.

func (Streams) Confirm 

func (s Streams) Confirm(ctx context.Context, prompt string) bool

Confirm presents a y/N confirmation prompt via bubbletea. Returns true only if the user presses y/Y. Returns false on n/N, esc, ctrl+c, enter, or any program error — the safe answer is always No.

func (Streams) DebugContext 

func (s Streams) DebugContext(ctx context.Context, msg string, args ...any)

func (Streams) ErrIsTerminal added in v1.0.47519 

func (s Streams) ErrIsTerminal() bool

ErrIsTerminal reports whether Err is a terminal. The update notifier requires both Out and Err to be TTYs before printing, so any pipe or redirect on either stream silences it — see internal/update.ShouldCheck.

func (Streams) ErrPrint 

func (s Streams) ErrPrint(str string)

ErrPrint writes a string to Err. No-op when Quiet is true.

func (Streams) ErrPrintf 

func (s Streams) ErrPrintf(format string, a ...any)

ErrPrintf writes a formatted string to Err. No-op when Quiet is true.

func (Streams) ErrPrintln 

func (s Streams) ErrPrintln(a ...any)

ErrPrintln writes a line to Err. No-op when Quiet is true.

func (Streams) InfoContext 

func (s Streams) InfoContext(ctx context.Context, msg string, args ...any)

func (Streams) IsInteractive 

func (s Streams) IsInteractive() bool

IsInteractive reports whether the session can support interactive prompts. False when: not a TTY, CI=true (running in a CI environment), or CIRCLE_NO_INTERACTIVE is set.

func (Streams) IsTerminal 

func (s Streams) IsTerminal() bool

IsTerminal reports whether Out is a terminal (i.e. a human is watching).

func (Streams) Muted added in v1.0.47519 

func (s Streams) Muted(strs ...string) string

Muted renders strs in the muted (gray) color, or plain when color is disabled.

func (Streams) Print 

func (s Streams) Print(v string)

Print writes a string to Out with no newline appended.

func (Streams) PrintJSON 

func (s Streams) PrintJSON(ctx context.Context, v any) error

func (Streams) PrintJSONFromReader 

func (s Streams) PrintJSONFromReader(ctx context.Context, r io.Reader) error

func (Streams) PrintJSONStream 

func (s Streams) PrintJSONStream(ctx context.Context, produce func(emit func(any) error) error) error

PrintJSONStream renders a sequence of values that the caller supplies through the emit callback. Without a --jq filter each value is written immediately as its own JSONL record, so nothing is buffered. With a filter the whole sequence is collected and run through a single jq evaluation, letting the expression aggregate across records (e.g. `[.,inputs] | length`, `group_by(.result)`); jq's per-input semantics mean simple filters like `.name` still emit one result per record.

produce is invoked exactly once; it should call emit for each value and return any error encountered while producing them. emit errors surface to produce so it can decide whether to stop (callers streaming to a pipe that a downstream reader closed typically ignore them).

func (Streams) PrintMarkdown 

func (s Streams) PrintMarkdown(md string)

PrintMarkdown renders md and writes the result to Out. When Out is an interactive terminal and the rendered output is taller than the screen, it is shown in a scrollable full-screen viewport instead. Falls back to writing raw markdown on render error.

func (Streams) Printf 

func (s Streams) Printf(format string, a ...any)

Printf writes a formatted string to Out.

func (Streams) Println 

func (s Streams) Println(a ...any)

Println writes a line to Out.

func (Streams) PromptSecret 

func (s Streams) PromptSecret(ctx context.Context, header string) (string, error)

PromptSecret presents a masked text input via bubbletea to collect a secret value. header is displayed above the input field (e.g. "Enter value for MY_VAR"). Returns ("", nil) if the user cancels with esc or ctrl+c.

func (Streams) PromptSelect 

func (s Streams) PromptSelect(ctx context.Context, prompt string, options []string) (int, error)

PromptSelect presents a bubbletea single-choice list prompt. Returns the selected index, or -1 if the user cancels.

func (Streams) PromptSelectDefault 

func (s Streams) PromptSelectDefault(ctx context.Context, prompt string, options []string, defaultIdx int) (int, error)

PromptSelectDefault is like PromptSelect but starts the cursor on defaultIdx (clamped to the options) so a default choice is pre-highlighted.

func (Streams) PromptThemePreview 

func (s Streams) PromptThemePreview(ctx context.Context, prompt string, labels, themes []string, cursorIdx int, sampleMarkdown string) (int, error)

PromptThemePreview presents a split-pane theme picker: a select list of labels on the left and a live preview of sampleMarkdown rendered in the highlighted theme on the right. themes are the raw theme names parallel to labels; cursorIdx is the initially-highlighted option. Returns the selected index, or -1 if the user cancels.

func (Streams) ReadSecret 

func (s Streams) ReadSecret(value string) (string, error)

ReadSecret returns value as-is, unless value is "-", in which case it reads one line from In. Use this for flags or arguments that accept sensitive values (tokens, passwords, secrets) to allow callers to pipe the value in without exposing it in shell history or process listings: 

echo "mytoken" | circleci setting set token -

func (Streams) RenderMarkdown 

func (s Streams) RenderMarkdown(md string) (string, error)

RenderMarkdown renders md as styled markdown when color is enabled, falling back to the raw string when output is not a TTY or color is disabled. The rendered string is returned; use PrintMarkdown to write it to Out.

func (Streams) Spinner 

func (s Streams) Spinner(active bool, msg string) *Spin

Spinner creates and starts a progress indicator for msg.

Pass active=false (e.g. !jsonOut) to get a no-op Spin with no output. When quiet mode is on, the Spin is also a no-op. In a non-interactive session (no TTY, CI=true, spinner disabled) a plain "msg...\n" line is written to stderr instead of animating.

Always call Stop() when the operation completes.

func (Streams) SpinnerEnabled 

func (s Streams) SpinnerEnabled() bool

SpinnerEnabled reports whether an animated spinner should run: only in an interactive session with CIRCLE_SPINNER_DISABLED unset. Long-lived bubbletea programs that animate their own spinner (e.g. the run-get flow) should consult this and keep their loading placeholder static otherwise.

func (Streams) Success added in v1.0.47519 

func (s Streams) Success(strs ...string) string

Success renders strs in the success (green) color, or plain when color is disabled.

func (Streams) SymbolError 

func (s Streams) SymbolError(strs ...string) string

func (Streams) SymbolSuccess 

func (s Streams) SymbolSuccess(strs ...string) string

func (Streams) SymbolWarning 

func (s Streams) SymbolWarning(strs ...string) string

func (Streams) Title 

func (s Streams) Title(strs ...string) string

func (Streams) Warning added in v1.0.47519 

func (s Streams) Warning(strs ...string) string

Warning renders strs in the warning (yellow) color, or plain when color is disabled.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.