Documentation
¶
Overview ¶
Package term is a small, dependency-free terminal-capability helper for the Chatwright CLI. It answers exactly three questions a runtime-output renderer needs — is this a real terminal (so a line can be redrawn in place), may ANSI colour be used, and is a UTF-8 symbol (✓/✗/⚠) safe to print or must an ASCII fallback be used — and packages the answers as a Profile, computed once per output stream.
This package deliberately adds no third-party dependency (no golang.org/x/term, no colour library): the CLI ships as a single static binary, and TTY/colour detection is a handful of lines once NO_COLOR, CLICOLOR and CLICOLOR_FORCE are accounted for. See Profile and NewProfile.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ASCIIOnly ¶
ASCIIOnly reports whether output should stick to ASCII rather than UTF-8 symbols (✓/✗/⚠), read from the same POSIX locale variables a shell itself consults (see utf8LocaleEnvVars). No locale variable set at all — the common case on a freshly-provisioned CI runner, and always the case on Windows, which has no LANG/LC_* convention — is treated as "cannot confirm UTF-8" and so, conservatively, ASCII: a missing checkmark is a cosmetic downgrade, a mis-rendered one (a UTF-8 sequence a terminal can't decode showing as replacement-character boxes) is a worse first impression than plain ASCII would have been.
func ColorEnabled ¶
ColorEnabled decides whether ANSI colour escapes may be written, given whether the stream is interactive and the process environment, in this precedence (highest first):
- NO_COLOR set to any non-empty value (https://no-color.org) — colour is always off. This is checked first and unconditionally, including ahead of CLICOLOR_FORCE: an explicit opt-out (commonly set org-wide, e.g. by a CI image) must never be silently overridden by a force flag a different tool or shell profile happens to also export.
- CLICOLOR_FORCE set to a non-empty value other than "0" — colour is always on, even when the stream is not a terminal (the convention's own "no matter what").
- CLICOLOR set to exactly "0" — colour is off.
- Otherwise — colour is on exactly when interactive is true (the BSD/CLICOLOR default: colour when attached to a terminal, plain text into a pipe).
func FormatDuration ¶
FormatDuration renders d for a human reader, the way `chatwright run`'s summary and progress lines both need (never a bare nanosecond count, and never time.Duration's own String, whose "1h2m3.456789s" full-precision tail is noise for a CLI's own progress/summary output):
- under one second: whole milliseconds, e.g. "850ms";
- under one minute: one decimal place of seconds, e.g. "1.2s";
- one minute or more: minutes and whole seconds, e.g. "2m03s".
A negative d is treated as zero (clock skew between two injected times should never render as a negative duration a user has to puzzle over).
func IsTerminal ¶
IsTerminal reports whether f is connected to a real terminal rather than a pipe, a redirected file, or /dev/null — the same "is this a character device" heuristic most dependency-free Go CLIs use in place of a platform-specific ioctl (golang.org/x/term's TIOCGETA/GetConsoleMode underneath is more precise about *which* fd is a console on Windows, but this package's brief is "dependency-light," and a wrong answer here only ever costs cosmetic degradation — plain text instead of colour/redraw — never a functional one).
Types ¶
type Profile ¶
type Profile struct {
// Interactive is true when the underlying stream is a real terminal
// (see IsTerminal) — never influenced by NO_COLOR/CLICOLOR/
// CLICOLOR_FORCE, which only ever narrow or force *colour*, not
// interactivity. A renderer uses Interactive (not Color) to decide
// whether it may redraw a line in place with a bare carriage return: an
// in-place redraw sent to a pipe or a log file corrupts it regardless
// of colour, so CLICOLOR_FORCE must never turn that on, and NO_COLOR
// must never turn it off.
Interactive bool
// Color is true when ANSI SGR colour escapes may be written — see
// ColorEnabled for the precedence NO_COLOR/CLICOLOR/CLICOLOR_FORCE are
// resolved in.
Color bool
// ASCII is true when the stream cannot be trusted to render UTF-8 (see
// ASCIIOnly) — a renderer must use an ASCII fallback for any symbol it
// would otherwise print as ✓/✗/⚠.
ASCII bool
}
Profile is everything a renderer needs to decide how much terminal capability it may use for one output stream — computed once (via NewProfile) and threaded through rather than re-detected per line.
func NewProfile ¶
NewProfile computes a Profile for out from whether out is a real terminal (IsTerminal) and the process environment (via getenv — pass os.Getenv; a function, not the map, so tests can supply a fake one without mutating real process environment variables).
func (Profile) Bold ¶
Bold, Dim, Red, Green, Yellow and Cyan each wrap s in the named SGR colour/style when p.Color, or return s unchanged otherwise — see colorize.
Source Files