Documentation
¶
Overview ¶
Package output centralizes everything the CLI writes to a terminal and the process exit codes it uses. It is the only package (besides cmd/) allowed to call fmt.Print* — the `forbidigo` linter enforces that, so output formatting and exit codes stay in one place.
Exit codes (PLAN.md "Output and UX conventions"):
0 ok · 1 error · 2 usage · 3 auth required · 4 not found · 5 throttled
Index ¶
- Constants
- func ApplyJQ(w io.Writer, expr string, data []byte) error
- func Authf(format string, args ...any) error
- func CodeOf(err error) int
- func DetectInteractive(stdin io.Reader, stdout io.Writer, noInput bool) bool
- func Errorf(format string, args ...any) error
- func HintOf(err error) string
- func HumanAge(now, t time.Time) string
- func HumanDuration(d time.Duration) string
- func HumanDurationSeconds(d time.Duration) string
- func IsTerminal(w io.Writer) bool
- func JoinNonEmpty(sep string, parts ...string) string
- func NotFoundf(format string, args ...any) error
- func Throttledf(format string, args ...any) error
- func Usagef(format string, args ...any) error
- func WithCode(err error, code int) error
- func WithHint(err error, hint string) error
- type Error
- type ExitCoder
- type Hinter
- type Options
- type Printer
- func (p *Printer) Bold(s string) string
- func (p *Printer) Color() bool
- func (p *Printer) Debugf(format string, args ...any)
- func (p *Printer) Definitions(pairs [][2]string)
- func (p *Printer) Dim(s string) string
- func (p *Printer) Err() io.Writer
- func (p *Printer) Errorf(format string, args ...any)
- func (p *Printer) Interactive() bool
- func (p *Printer) JQ() string
- func (p *Printer) JSON(v any) error
- func (p *Printer) JSONBytes(raw []byte) error
- func (p *Printer) JSONMode() bool
- func (p *Printer) Markdown(s, indent string)
- func (p *Printer) Out() io.Writer
- func (p *Printer) Print(args ...any)
- func (p *Printer) Printf(format string, args ...any)
- func (p *Printer) Println(args ...any)
- func (p *Printer) Quiet() bool
- func (p *Printer) ReportError(err error)
- func (p *Printer) Statusf(format string, args ...any)
- func (p *Printer) Successf(format string, args ...any)
- func (p *Printer) Table(headers []string, rows [][]string)
- func (p *Printer) Warnf(format string, args ...any)
Constants ¶
const ( CodeOK = 0 CodeError = 1 CodeUsage = 2 CodeAuth = 3 CodeNotFound = 4 CodeThrottled = 5 )
Exit codes. They are part of the CLI contract and are documented in docs/commands and the README.
Variables ¶
This section is empty.
Functions ¶
func ApplyJQ ¶
ApplyJQ runs a jq expression over JSON-encoded data and writes the results to out, one per line: a string result prints unquoted (which is what a script wants) and anything else prints as compact JSON. It implements the --jq flag, which is documented in PLAN.md's output conventions next to --json.
func CodeOf ¶
CodeOf returns the exit code for err: 0 for nil, the code carried by an *Error, the value from ExitCode for anything implementing ExitCoder, and 1 for anything else.
func DetectInteractive ¶
DetectInteractive decides whether prompts are allowed: both stdin and stdout must be terminals, --no-input must be off and CI must not be set. PLAN.md requires the automatic detection; it is our logic, not cobra's or MSAL's, so it is tested on its own.
func HintOf ¶
HintOf returns the hint attached to err, if any: our own Error first, then any error implementing Hinter.
func HumanAge ¶
HumanAge renders how long ago t was, at a granularity that is useful at a glance. Future timestamps read as "in …", which matters for token expiry.
func HumanDuration ¶
HumanDuration renders a duration as the largest one or two units.
func HumanDurationSeconds ¶
HumanDurationSeconds renders a duration with a unit, for documented windows such as the 15-minute device-code sign-in window.
func IsTerminal ¶
IsTerminal reports whether w is an interactive terminal.
func JoinNonEmpty ¶
JoinNonEmpty joins the non-empty strings with sep; a small helper that keeps renderers from emitting stray separators for missing values.
func Throttledf ¶
Throttledf builds a throttled error (exit 5).
Types ¶
type Error ¶
Error is an error that carries the process exit code and, optionally, the one-line fix we want to show the user.
type ExitCoder ¶
type ExitCoder interface {
ExitCode() int
}
ExitCoder is implemented by errors that know their own exit code, such as the Graph APIError (a 404 is exit 4, a 429 is exit 5, and so on).
type Hinter ¶
type Hinter interface {
Hint() string
}
Hinter is implemented by errors that carry a suggested fix.
type Options ¶
type Options struct {
Out io.Writer
Err io.Writer
JSON bool
// JQ is a jq expression applied to the JSON output. Setting it implies
// JSON mode, so --jq alone is enough.
JQ string
NoColor bool
Quiet bool
Verbose int
Interactive bool
}
Options configures a Printer. The CLI fills it from global flags plus TTY detection; tests construct it directly.
type Printer ¶
type Printer struct {
// contains filtered or unexported fields
}
Printer writes everything the CLI shows a human, in the one place the linters allow formatted output. It never writes to os.Stdout or os.Stderr directly.
func New ¶
New builds a Printer. Colour is on only for a terminal that did not ask for plain text: NO_COLOR, TERM=dumb, --no-color, --json and a pipe all disable it. CLICOLOR_FORCE=1 keeps colour even when the output is not a terminal, which is what the pty-based tests and colour-sensitive scripts use.
func (*Printer) Bold ¶
Bold renders s bold on a terminal and unchanged otherwise, so a caller does not have to know whether styling is on.
func (*Printer) Definitions ¶
Definitions prints aligned label/value pairs, the shape used by `teams auth status`, `teams doctor` and `teams cache info`.
func (*Printer) Errorf ¶
Errorf writes an error to stderr without exiting; use the returned error to carry the exit code.
func (*Printer) Interactive ¶
Interactive reports whether the CLI may prompt: a TTY on both ends and no --no-input or CI environment. PLAN.md: non-interactive mode never prompts, it fails fast with an exit code.
func (*Printer) JSON ¶
JSON encodes v to stdout with a stable two-space indent. It is the only output path that is a documented schema, so it never contains styling.
func (*Printer) JSONBytes ¶
JSONBytes writes an already-encoded JSON document, re-indented, through the same --jq path JSON uses.
It is the printer for `teams api`, where the response is a document the CLI did not build and does not model: printing it as a Go value would mean decoding and re-encoding something whose schema is whatever Graph returned. A body that is not JSON at all is not accepted here (the caller writes it verbatim instead).
func (*Printer) Markdown ¶
Markdown renders a message body or a description for a human. On a terminal the markdown is styled through glamour; when the output is piped it is printed verbatim, because markdown is already plain text and a script wants the source, not a styled version of it (PLAN.md "Output and UX conventions").
indent is prefixed to every rendered line, which is how a body reads as part of the header line above it.
func (*Printer) ReportError ¶
ReportError prints an error and its hint exactly once, in the shape users and scripts expect: `error: …` on stderr, then an indented `hint: …`.
func (*Printer) Statusf ¶
Statusf writes progress to stderr, so stdout stays parseable. It is suppressed by --quiet.