terminal

Documentation

Overview

Package terminal is used by plugins to read and write to a terminal UI. The abstractions presented in this package are meant to be portable across a variety of styles that may be presented to the user and enables plugins to focus on their core logic.

The primary interface to look at is UI.

Index

• Constants
• func Interpret(msg string, raw ...interface{}) (string, string)
• type NamedValue
• type Option
  • func WithErrorStyle() Option
  • func WithHeaderStyle() Option
  • func WithInfoStyle() Option
  • func WithStyle(style string) Option
  • func WithSuccessBoldStyle() Option
  • func WithSuccessStyle() Option
  • func WithWarningStyle() Option
• type Table
  • func NewTable(headers ...string) *Table
  • func (t *Table) Rich(cols []string, colors []string)
• type TableEntry
• type UI
  • func NonInteractiveUI(_ context.Context, w io.Writer) UI

Constants

const (
	Yellow = "yellow"
	Green  = "green"
	Red    = "red"
)

Color constants

const (
	HeaderStyle      = "header"
	ErrorStyle       = "error"
	WarningStyle     = "warning"
	InfoStyle        = "info"
	SuccessStyle     = "success"
	SuccessBoldStyle = "success-bold"
)

Style constants

Functions

func Interpret

func Interpret(msg string, raw ...interface{}) (string, string)

Interpret decomposes the msg and arguments into the message, style, and writer

Types

type NamedValue

type NamedValue struct {
	Value interface{}
	Name  string
}

NamedValue provides a nicely formatted key: value output

type Option

type Option func(*config)

Option controls output styling.

func WithErrorStyle

func WithErrorStyle() Option

WithErrorStyle styles the output as an error message.

func WithHeaderStyle

func WithHeaderStyle() Option

WithHeaderStyle styles the output like a header denoting a new section of execution. This should only be used with single-line output. Multi-line output will not look correct.

func WithInfoStyle

func WithInfoStyle() Option

WithInfoStyle styles the output like it's formatted information.

func WithStyle

func WithStyle(style string) Option

WithStyle adds a style option

func WithSuccessBoldStyle

func WithSuccessBoldStyle() Option

WithSuccessBoldStyle styles the output as a success message.

func WithSuccessStyle

func WithSuccessStyle() Option

WithSuccessStyle styles the output as a success message.

func WithWarningStyle

func WithWarningStyle() Option

WithWarningStyle styles the output as an error message.

type Table

type Table struct {
	Headers []string
	Rows    [][]TableEntry
}

Table provides a nicely formatted table.

func NewTable

func NewTable(headers ...string) *Table

NewTable creates a new Table structure that can be used with UI.Table.

func (*Table) Rich

func (t *Table) Rich(cols []string, colors []string)

Rich adds a row to the table.

type TableEntry

type TableEntry struct {
	Value string
	Color string
}

TableEntry is a single entry for a table.

type UI

type UI interface {
	// Output outputs a message directly to the terminal. The remaining
	// arguments should be interpolations for the format string. After the
	// interpolations you may add Options.
	Output(string, ...interface{})

	// Output data as a table of data. Each entry is a row which will be output
	// with the columns lined up nicely.
	NamedValues([]NamedValue, ...Option)

	// OutputWriters returns stdout and stderr writers. These are usually
	// but not always TTYs. This is useful for subprocesses, network requests,
	// etc. Note that writing to these is not thread-safe by default so
	// you must take care that there is only ever one writer.
	OutputWriter() (io.WriteCloser, error)

	// Table outputs the information formatted into a Table structure.
	Table(*Table, ...Option)
}

UI is the primary interface for interacting with a user via the CLI.

Some of the methods on this interface return values that have a lifetime such as Status and StepGroup. While these are still active (haven't called the close or equivalent method on these values), no other method on the UI should be called.

func NonInteractiveUI

func NonInteractiveUI(_ context.Context, w io.Writer) UI

NonInteractiveUI creates a new instance of a UI implementation that is non-interactive