Documentation
¶
Overview ¶
Package status owns the side-channel for human-facing user-interface output.
This is the categorized narration stream that accompanies a tool's primary work.
The package's surface is the Narrator concrete type, which wraps a pkg/sink.Sink with the six categorized emission methods (Note, Warn, Error, Succeed, Fail, Print) and the program-name prefix. Color decoration is keyed off the sink's pkg/sink.Sink.IsTTY query — TTYs get ANSI color codes around the category symbol; non-TTYs get plain bytes.
Narrator emissions form a progress arc that conventionally concludes with Narrator.Succeed (positive resolution) or Narrator.Fail (negative resolution). The narration is event-stream in shape but story-shaped in semantic — successive Notes and Warns build context for the terminal Succeed/Fail.
Construction is immutable: callers pass program name + sink to NewNarrator once; no setters mutate the instance after construction. Silence is selected by passing pkg/sink.Discard as the sink, not by toggling a Narrator field.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Narrator ¶
type Narrator struct {
// contains filtered or unexported fields
}
Narrator is the categorized narration wrapper.
Methods emit "[<programName>] [<colored symbol>] <msg>\n" through the configured sink.Sink; Narrator.Print emits the raw message followed by a newline, with no decoration. All fields are unexported and set at construction by NewNarrator; the value is immutable from the caller's perspective. Mid-run reconfiguration (writer redirect, program rename) requires constructing a new Narrator and replacing the runtime environment's Status reference.
Color decoration is keyed off sink.Sink.IsTTY at construction — true → wrap symbols in ANSI codes, false → plain bytes. To suppress all output, construct with sink.Discard as the sink.
func NewNarrator ¶
NewNarrator constructs an immutable Narrator writing through the supplied sink.
Parameters:
- `programName`: name shown in the "[program]" prefix on categorized messages (e.g., "lore").
- `s`: the sink.Sink to write through. Must not be nil. Pass sink.Discard to suppress all narration; pass sink.Stderr for the standard cli case.
Returns:
- `*Narrator`: the constructed value, ready to install on a runtime environment spec.
func (*Narrator) Error ¶
Error emits a non-fatal error status message in red.
Parameters:
- `msg`: the error message to emit.
func (*Narrator) Fail ¶
Fail emits a fatal error status message in red and returns a Go error wrapping the message.
Parameters:
- `msg`: the fatal-error message to emit.
Returns:
- `error`: a non-nil error wrapping msg. Callers typically return this to abort the operation.
func (*Narrator) Note ¶
Note emits an informational status message in gray.
Parameters:
- `msg`: the informational message to emit.
func (*Narrator) Print ¶
Print emits raw text followed by a newline.
No decoration; intended for starlark `print()` output where the script's exact bytes are what the user expects.
Parameters:
- `msg`: the raw text to emit.
Source Files