Documentation
¶
Index ¶
- Constants
- func AppendRich(dst []byte, text string, colorCode int, options ...RichOption) []byte
- func IsNop(w io.Writer) bool
- func NopOutput() io.Writer
- func Rich(text string, colorCode int, options ...RichOption) string
- func RichText(text string, colorCode int, options ...RichOption) string
- func ScanLines(r io.Reader, stop <-chan struct{}, emit func(line []byte), onError func(error))
- func SupportsColor(w io.Writer) bool
- func WriteRich(w io.Writer, text string, colorCode int, options ...RichOption) (int, error)
- type Printer
- func (p *Printer) AddOutput(writers ...io.Writer)
- func (p *Printer) Clone() *Printer
- func (p *Printer) Print(v any) (int, error)
- func (p *Printer) Printf(format string, a ...any) (int, error)
- func (p *Printer) Println(v any) (int, error)
- func (p *Printer) Scan(r io.Reader) (cancel func())
- func (p *Printer) SetOutput(w io.Writer)
- func (p *Printer) Terminal() (*Printer, bool)
- func (p *Printer) TerminalOrStderr() io.Writer
- func (p *Printer) TerminalOrStdout() io.Writer
- func (p *Printer) Write(data []byte) (int, error)
- func (p *Printer) WriteRich(text string, colorCode int, options ...RichOption) (int, error)
- func (p *Printer) WriteRichLine(title string, colorCode int, style []RichOption, body []byte) (int, error)
- func (p *Printer) WriteString(s string) (int, error)
- type RichOption
Constants ¶
const ( Black = 30 + iota Red Green Yellow Blue Magenta Cyan White Gray = White ColorReset = 0 )
Standard color codes, any color code can be passed to `Rich` package-level function, when the destination terminal supports.
const MaxScanLine = 1 << 20
MaxScanLine caps one logical line read by ScanLines. Past it the rest of the line is dropped and ScanTruncated is appended to what was kept, so a child process that writes megabytes without a newline cannot grow memory without bound, and a reader can tell a clipped record from a complete one.
const ScanTruncated = " [truncated]"
ScanTruncated marks a line that hit MaxScanLine.
Variables ¶
This section is empty.
Functions ¶
func AppendRich ¶ added in v0.2.0
func AppendRich(dst []byte, text string, colorCode int, options ...RichOption) []byte
AppendRich appends "text" wrapped in the ANSI color and style codes to "dst" and returns the extended slice. It is RichText for callers building a line in a buffer, which is what keeps a colored title from costing an allocation per log line.
When terminal.SupportColors is off the plain text is appended instead.
func Rich ¶
func Rich(text string, colorCode int, options ...RichOption) string
Rich returns a formatted string with color and style codes when this process's os.Stdout is a terminal, and the plain text otherwise.
It asks about os.Stdout on every call, because os.Stdout is an assignable variable that test helpers routinely swap. Nothing on golog's own write path calls Rich; the Printer decides per writer once, through SupportsColor.
func RichText ¶ added in v0.2.0
func RichText(text string, colorCode int, options ...RichOption) string
RichText returns "text" wrapped in the ANSI color and style codes, without consulting os.Stdout the way Rich does.
It is for callers that already know whether their destination can render colors -- because they were told (LevelMetadata.Text's enableColor) or because they asked about the writer itself (SupportsColor). Rich has to guess for them, and guesses about a different file descriptor.
The process-wide terminal.SupportColors switch still applies.
func ScanLines ¶ added in v0.2.0
ScanLines reads "r" line by line and calls "emit" for every complete, non-empty line, without its trailing newline (and without a carriage return before it, for CRLF input). It returns when "r" is exhausted, when "stop" is closed, or on a read error; an error other than io.EOF is passed to "onError" unless "stop" has been closed, in which case it is the expected consequence of the caller shutting the reader down.
Lines longer than MaxScanLine are truncated as described there. The slice passed to "emit" is reused for the next line, so it must not be retained.
Logger.Scan and Printer.Scan are both built on it.
func SupportsColor ¶
SupportsColor determines if the output supports ANSI color codes.
For an *os.File the answer is a syscall, so callers on a hot path should ask once and remember, as the Printer and Logger.SetLevelOutput do.
Types ¶
type Printer ¶
type Printer struct {
// contains filtered or unexported fields
}
Printer is a simple printer that manages multiple output writers and provides thread-safe atomic writes.
func NewPrinter ¶
NewPrinter creates a new Printer with the given initial writer.
func (*Printer) Clone ¶
Clone creates a deep copy of the Printer, including its writers and rich map.
func (*Printer) Println ¶
Println writes the string representation of v followed by a newline to all writers.
func (*Printer) Scan ¶
Scan scans from the provided reader and writes lines to the printer. It returns a cancel function to stop the scanning operation, which is safe to call more than once. A read error other than the end of the input is written to the printer as "scan: <error>".
func (*Printer) Terminal ¶
Terminal returns a new Printer that includes the writers that output destination is a terminal kind. If no terminal writers exist, it returns nil and false.
func (*Printer) TerminalOrStderr ¶
TerminalOrStderr returns an io.Writer that includes the writers that output destination is a terminal kind. If no terminal writers exist, it returns os.Stderr.
func (*Printer) TerminalOrStdout ¶
TerminalOrStdout returns an io.Writer that includes the writers that output destination is a terminal kind. If no terminal writers exist, it returns os.Stdout.
func (*Printer) WriteRich ¶
WriteRich writes a formatted string with color and style to all registered writers. It checks each writer's support for rich text and writes accordingly.
func (*Printer) WriteRichLine ¶ added in v0.2.0
func (p *Printer) WriteRichLine(title string, colorCode int, style []RichOption, body []byte) (int, error)
WriteRichLine writes "title", colored for the writers that render color and plain for the ones that do not, immediately followed by "body", as exactly one Write per writer.
This is how a log line reaches the writers whole: the title is the only part that differs per writer, so the two renderings are built once each and each writer receives its line in a single call. Anything less lets another goroutine writing to the same file slip in between the pieces.
type RichOption ¶
type RichOption int
Style options for rich text formatting
const ( Background RichOption = iota Underline Bold )