pretty

Documentation

Overview

Package pretty contains utilities for formatting terminal help output, and a use of those to display marker help.

Terminal Output

The Span interface and Table struct allow you to construct tables with colored formatting, without causing ANSI formatting characters to mess up width calculations.

Marker Help

The MarkersSummary prints a summary table for marker help, while the MarkersDetails prints out more detailed information, with explainations of the individual marker fields.

Index

• type Decoration
  • func (d Decoration) Containing(contents Span) Span
• type Span
  • func FieldSyntaxHelp(arg help.FieldHelp) Span
  • func FromWriter(run func(io.Writer) error) Span
  • func Indented(amt int, content Span) Span
  • func Line(content Span) Span
  • func MarkerSyntaxHelp(def help.MarkerDoc) Span
  • func MarkersDetails(fullDetail bool, groupName string, markers []help.MarkerDoc) Span
  • func MarkersSummary(groupName string, markers []help.MarkerDoc) Span
  • func Newlines(amt int) Span
• type SpanWriter
  • func (m *SpanWriter) Print(s Span)
  • func (m *SpanWriter) VisualLength() int
  • func (m *SpanWriter) WriteTo(w io.Writer) error
• type Table
  • func (t *Table) Column(contents Span)
  • func (t *Table) EndRow()
  • func (t *Table) SkipRow(contents Span)
  • func (t *Table) StartRow()
  • func (t *Table) VisualLength() int
  • func (t *Table) WriteTo(out io.Writer) error
• type TableCalculator
  • func (c *TableCalculator) AddRowSizes(cellSizes ...int)
  • func (c *TableCalculator) ColumnWidths() []int
• type Text
  • func (t Text) VisualLength() int
  • func (t Text) WriteTo(w io.Writer) error

Types

type Decoration

type Decoration color.Color

Decoration represents a terminal decoration.

func (Decoration) Containing

func (d Decoration) Containing(contents Span) Span

Containing returns a Span that has the given decoration applied.

type Span

type Span interface {
	// VisualLength reports the "width" as perceived by the user on the terminal
	// (i.e. widest line, ignoring ANSI escape characters).
	VisualLength() int
	// WriteTo writes the full span contents to the given writer.
	WriteTo(io.Writer) error
}

Span is a chunk of content that is writable to an output, but knows how to calculate its apparent visual "width" on the terminal (not to be confused with the raw length, which may include zero-width coloring sequences).

func FieldSyntaxHelp

func FieldSyntaxHelp(arg help.FieldHelp) Span

func FromWriter

func FromWriter(run func(io.Writer) error) Span

FromWriter returns a span that takes content from a function expecting a Writer.

func Indented

func Indented(amt int, content Span) Span

Indented returns a span that indents all lines by the given number of tabs.

func Line

func Line(content Span) Span

Line returns a span that emits a newline, followed by the given content.

func MarkerSyntaxHelp

func MarkerSyntaxHelp(def help.MarkerDoc) Span

MarkerSyntaxHelp assembles syntax help for a given marker.

func MarkersDetails

func MarkersDetails(fullDetail bool, groupName string, markers []help.MarkerDoc) Span

MarkersDetails returns detailed help for the given markers, including detailed field help.

func MarkersSummary

func MarkersSummary(groupName string, markers []help.MarkerDoc) Span

MarkersSummary returns a condensed summary of help for the given markers.

func Newlines

func Newlines(amt int) Span

Newlines returns a span just containing some newlines.

type SpanWriter

type SpanWriter struct {
	// contains filtered or unexported fields
}

SpanWriter is a span that contains multiple sub-spans.

func (*SpanWriter) Print

func (m *SpanWriter) Print(s Span)

Print adds a new span to this SpanWriter.

func (*SpanWriter) VisualLength

func (m *SpanWriter) VisualLength() int

func (*SpanWriter) WriteTo

func (m *SpanWriter) WriteTo(w io.Writer) error

type Table

type Table struct {
	Sizing *TableCalculator
	// contains filtered or unexported fields
}

Table is a Span that writes its data in table form, with sizing controlled by the given table calculator. Rows are started with StartRow, followed by some calls to Column, followed by a call to EndRow. Once all rows are added, the table can be used as a Span.

func (*Table) Column

func (t *Table) Column(contents Span)

Column adds the given span as a new column to the current row.

func (*Table) EndRow

func (t *Table) EndRow()

EndRow ends the currently started row.

func (*Table) SkipRow

func (t *Table) SkipRow(contents Span)

SkipRow prints a span without having it contribute to the table calculation.

func (*Table) StartRow

func (t *Table) StartRow()

StartRow starts a new row. It must eventually be followed by EndRow.

func (*Table) VisualLength

func (t *Table) VisualLength() int

func (*Table) WriteTo

func (t *Table) WriteTo(out io.Writer) error

type TableCalculator

type TableCalculator struct {
	Padding  int
	MaxWidth int
	// contains filtered or unexported fields
}

TableCalculator calculates column widths (with optional padding) for a table based on the maximum required column width.

func (*TableCalculator) AddRowSizes

func (c *TableCalculator) AddRowSizes(cellSizes ...int)

AddRowSizes registers a new row with cells of the given sizes.

func (*TableCalculator) ColumnWidths

func (c *TableCalculator) ColumnWidths() []int

ColumnWidths calculates the appropriate column sizes given the previously registered rows.

type Text

type Text string

Text is a span that simply contains raw text. It's a good starting point.

func (Text) VisualLength

func (t Text) VisualLength() int

func (Text) WriteTo

func (t Text) WriteTo(w io.Writer) error