diff --git a/internal/ui/message.go b/internal/ui/message.go index 6ba60f3c0..612fd72a2 100644 --- a/internal/ui/message.go +++ b/internal/ui/message.go @@ -19,33 +19,35 @@ func NewMessage(term Terminal, verbosity uint) *Message { } } -// E reports an error +// E reports an error. This message is always printed to stderr. func (m *Message) E(msg string, args ...interface{}) { m.term.Error(fmt.Sprintf(msg, args...)) } // S prints a message, this is should only be used for very important messages -// that are not errors. +// that are not errors. The message is even printed if --quiet is specified. func (m *Message) S(msg string, args ...interface{}) { m.term.Print(fmt.Sprintf(msg, args...)) } -// P prints a message if verbosity >= 1, this is used for normal messages which -// are not errors. +// P prints a message if verbosity >= 1 (neither --quiet nor --verbose is specified), +// this is used for normal messages which are not errors. func (m *Message) P(msg string, args ...interface{}) { if m.v >= 1 { m.term.Print(fmt.Sprintf(msg, args...)) } } -// V prints a message if verbosity >= 2, this is used for verbose messages. +// V prints a message if verbosity >= 2 (equivalent to --verbose), this is used for +// verbose messages. func (m *Message) V(msg string, args ...interface{}) { if m.v >= 2 { m.term.Print(fmt.Sprintf(msg, args...)) } } -// VV prints a message if verbosity >= 3, this is used for debug messages. +// VV prints a message if verbosity >= 3 (equivalent to --verbose=2), this is used for +// debug messages. func (m *Message) VV(msg string, args ...interface{}) { if m.v >= 3 { m.term.Print(fmt.Sprintf(msg, args...)) diff --git a/internal/ui/progress/printer.go b/internal/ui/progress/printer.go index a1adc4af4..37d81f4d6 100644 --- a/internal/ui/progress/printer.go +++ b/internal/ui/progress/printer.go @@ -6,18 +6,27 @@ import "testing" // at different log levels. // It must be safe to call its methods from concurrent goroutines. type Printer interface { + // NewCounter returns a new progress counter. It is not shown if --quiet or --json is specified. NewCounter(description string) *Counter + // NewCounterTerminalOnly returns a new progress counter that is only shown if stdout points to a + // terminal. It is not shown if --quiet or --json is specified. NewCounterTerminalOnly(description string) *Counter - // E prints to stderr + // E reports an error. This message is always printed to stderr. + // Appends a newline if not present. E(msg string, args ...interface{}) - // S prints to stdout + // S prints a message, this is should only be used for very important messages + // that are not errors. The message is even printed if --quiet is specified. + // Appends a newline if not present. S(msg string, args ...interface{}) - // P prints to stdout unless quiet was passed + // P prints a message if verbosity >= 1 (neither --quiet nor --verbose is specified), + // this is used for normal messages which are not errors. Appends a newline if not present. P(msg string, args ...interface{}) - // V prints to stdout if verbose is set once + // V prints a message if verbosity >= 2 (equivalent to --verbose), this is used for + // verbose messages. Appends a newline if not present. V(msg string, args ...interface{}) - // VV prints to stdout if verbose is set twice + // VV prints a message if verbosity >= 3 (equivalent to --verbose=2), this is used for + // debug messages. Appends a newline if not present. VV(msg string, args ...interface{}) } diff --git a/internal/ui/terminal.go b/internal/ui/terminal.go index 949bc3465..262f1bcf7 100644 --- a/internal/ui/terminal.go +++ b/internal/ui/terminal.go @@ -5,9 +5,16 @@ import "io" // Terminal is used to write messages and display status lines which can be // updated. See termstatus.Terminal for a concrete implementation. type Terminal interface { + // Print writes a line to the terminal. Appends a newline if not present. Print(line string) + // Error writes an error to the terminal. Appends a newline if not present. Error(line string) + // SetStatus sets the status lines to the terminal. SetStatus(lines []string) + // CanUpdateStatus returns true if the terminal can update the status lines. CanUpdateStatus() bool + // OutputRaw returns the output writer. Should only be used if there is no + // other option. Must not be used in combination with Print, Error, SetStatus + // or any other method that writes to the terminal. OutputRaw() io.Writer }