colorz

Documentation

Overview

Package colorz provides supplemental color functionality.

Index

• func HasEffect(c *color.Color) bool
• func Strip(b []byte) []byte
• type ByteWriter
• type Printer
  • func NewPrinter(c *color.Color) Printer
• type Seqs
  • func ExtractSeqs(c *color.Color) Seqs
  • func (s Seqs) Append(dest, p []byte) []byte
  • func (s Seqs) Appendln(dest, p []byte) []byte
  • func (s Seqs) Write(w io.Writer, p []byte)
  • func (s Seqs) WriteByte(w ByteWriter, b byte)
  • func (s Seqs) Writeln(w io.Writer, p []byte)
  • func (s Seqs) WritelnByte(w ByteWriter, b byte)

Functions

func HasEffect

func HasEffect(c *color.Color) bool

HasEffect returns true if c has an effect, i.e. if c is non-nil and produces a non-empty color sequence. For example, if color.Color.DisableColor is invoked on c, HasEffect returns false.

func Strip

func Strip(b []byte) []byte

Strip returns a copy of b with all terminal color sequences removed.

Types

type ByteWriter

type ByteWriter interface {
	io.Writer
	WriteByte(byte) error
}

ByteWriter is implemented by bytes.Buffer. It's used by Seqs.WriteByte and Seqs.WritelnByte to avoid unnecessary allocations.

type Printer

type Printer interface {
	// Fragment prints colorized b to w. If b is empty, w is not written to.
	// Colorization breaks if b contains internal line breaks; instead use
	// [Printer.Block].
	Fragment(w io.Writer, b []byte) (n int, err error)

	// Line prints colorized b to w, always terminating with a newline. If b is
	// empty, a single newline is printed. Colorization breaks if b contains
	// internal line breaks; instead use [Printer.Block].
	Line(w io.Writer, b []byte) (n int, err error)

	// Block prints colorized b to w, preserving line breaks. If b terminates with
	// a newline, that newline is written to w; if not, a terminating newline is
	// not written. If b is empty, w is not written to.
	Block(w io.Writer, b []byte) (n int, err error)
}

Printer provides color-aware printing.

func NewPrinter

func NewPrinter(c *color.Color) Printer

NewPrinter returns a new Printer that uses c for colorization. If c is nil, or if c has no effect (see HasEffect), the returned Printer will not perform colorization.

type Seqs

type Seqs struct {
	Prefix []byte
	Suffix []byte
}

Seqs represents the prefix and suffix bytes for a terminal color sequence. Use ExtractSeqs to build a Seqs from a color.Color.

REVISIT: Life would be simpler if we just implemented our own Color type that embedded fatih/color.Color. There's a lot of messing around in this pkg.

func ExtractSeqs

func ExtractSeqs(c *color.Color) Seqs

ExtractSeqs extracts the prefix and suffix bytes for the terminal color sequence produced by c. The prefix and suffix are extracted even if c is disabled, e.g. via color.Color.DisableColor. If c is nil, or if there's no color sequence, the zero value is returned.

func (Seqs) Append

func (s Seqs) Append(dest, p []byte) []byte

Append appends colorized p to dest, returning the result. If p is empty, or if s.Prefix is empty, dest is returned unmodified.

func (Seqs) Appendln

func (s Seqs) Appendln(dest, p []byte) []byte

Appendln appends colorized p to dest and then a newline, returning the result.

func (Seqs) Write

func (s Seqs) Write(w io.Writer, p []byte)

Write writes p to w, prefixed and suffixed by c.Prefix and c.Suffix. If c is the zero value, or w is nil, or p is empty, Write is no-op. Write does not check for internal line breaks in p, which could break colorization. Note also that Write does not return the typical (n, err) for a Write method; it is intended for use with types such as bytes.Buffer where errors are not a significant concern.

func (Seqs) WriteByte

func (s Seqs) WriteByte(w ByteWriter, b byte)

WriteByte writes a colorized byte to w. This method is basically an optimization for when w is bytes.Buffer.

func (Seqs) Writeln

func (s Seqs) Writeln(w io.Writer, p []byte)

Writeln is like Write, but it always writes a terminating newline. If p is empty, only a newline is written. If p is already newline-terminated, an additional newline is NOT written.

func (Seqs) WritelnByte

func (s Seqs) WritelnByte(w ByteWriter, b byte)

WritelnByte writes a colorized byte and a newline to w. This method is basically an optimization for when w is bytes.Buffer.