Documentation
¶
Overview ¶
Package cout provides verbosity-levelled, coloured console output for command-line tools.
Tools separate what they *log* (clog, stderr, for diagnosing the tool) from what they *print* (this package, for the person running it). Every print call carries a minimum verbosity so a --quiet or --verbose flag is honoured in one place, and colour tags such as <red>...</> are rendered by gookit/color, which strips them when stdout is not a colour terminal.
Tags are rendered anywhere in the final string, arguments included, so helpers may build coloured fragments and pass them through %s.
Index ¶
- Variables
- func Errorf(format string, args ...any)
- func Printf(format string, args ...any)
- func Println(args ...any)
- func QuietOnlyf(format string, args ...any)
- func Quietf(format string, args ...any)
- func SetLevelFromFlags(silent, quiet, verbose bool)
- func Sprintf(format string, args ...any) string
- func Verbosef(format string, args ...any)
- func Writer() io.Writer
- type Flags
- type Verbosity
Constants ¶
This section is empty.
Variables ¶
var Err io.Writer = os.Stderr
Err is where Errorf writes. It defaults to stderr and is separate from Out so errors stay visible when Out is redirected or discarded.
var Level = VerbosityNormal
Level controls the output verbosity. Tools set it once from their flags before any output call; it is a plain variable rather than a setter so the cobra flag-handling block in every tool stays a one-line assignment.
var Out io.Writer = os.Stdout
Out is where normal output goes. It defaults to stdout; tools whose stdout is a data channel (a JSON emitter, an MCP server on stdio) point it at stderr so progress messages never corrupt the stream.
Functions ¶
func Errorf ¶
Errorf prints an error to Err in every mode except silent, so failures stay visible even when Out is machine-readable (quiet) or suppressed.
func Printf ¶
Printf prints normal output; suppressed in quiet and silent modes. Console write failures are not actionable, so they are dropped.
func Println ¶
func Println(args ...any)
Println prints normal output followed by a newline, rendering colour tags in its arguments; suppressed in quiet and silent modes.
func QuietOnlyf ¶
QuietOnlyf prints only in quiet mode. Use it when quiet mode has its own terse format for a line that normal mode prints differently via Printf, so the two never appear together.
func Quietf ¶
Quietf prints in quiet mode and above. Use it for the one line a script would parse, which should also appear in normal output alongside any decoration Printf adds around it.
func SetLevelFromFlags ¶ added in v0.2.0
func SetLevelFromFlags(silent, quiet, verbose bool)
SetLevelFromFlags sets the package Level from individual flag values; it is the one-liner that replaces the switch every tool used to carry.
func Sprintf ¶
Sprintf formats like fmt.Sprintf and renders colour tags in the result. Use it to build coloured fragments that are later passed to Printf and friends, or to colour text destined for somewhere other than Out.
Types ¶
type Flags ¶ added in v0.2.0
type Flags struct {
Silent bool `mapstructure:"silent"`
JSON bool `mapstructure:"json"`
Quiet bool `mapstructure:"quiet"`
Verbose bool `mapstructure:"verbose"`
}
Flags is the set of verbosity flags katbyte tools expose. Embed it in a tool's flag struct with `mapstructure:",squash"` and viper fills it from the "silent", "json", "quiet" and "verbose" keys; a tool registers only the flags it offers and keeps ownership of their names, shorthands and help text.
type Verbosity ¶
type Verbosity int
Verbosity is how much a tool prints. The levels are ordered, so "print at Normal and above" is a plain comparison.
const ( // VerbositySilent prints nothing at all, not even errors. For callers that // only want the exit code. VerbositySilent Verbosity = iota // VerbosityJSON is for tools that emit a JSON document on stdout at the // end of a run: nothing else is printed there, errors still go to Err. The // document itself is the tool's to write; this level only keeps the // channel clean. VerbosityJSON // VerbosityQuiet prints only the minimal machine-readable lines (Quietf, // QuietOnlyf) and errors. VerbosityQuiet // VerbosityNormal is the default: everything a person wants to see. VerbosityNormal // VerbosityVerbose adds the detail behind Verbosef, typically -v. VerbosityVerbose )
The verbosity levels, from least to most output.
func LevelFromFlags ¶ added in v0.2.0
LevelFromFlags is Flags.Level for tools that read their flags individually, for example straight from viper in a cobra pre-run hook. Tools with a JSON mode use Flags, which is the only place that level is selected.
Source Files