terminal

Documentation

Overview

Package terminal is a modified version of https://github.com/hashicorp/waypoint-plugin-sdk/tree/74d9328929293551499078da388b8d057f3b2341/terminal.

This terminal package only contains the basic UI implementation and excludes the glint UI and noninteractive UI implementations as they do not yet have an Input implementation which we leverage in commands.

This terminal package does not contain the Status, Step, and StepGroup interface and implementation from the original terminal package since using the spinner package does not allow streaming outputs of a given Step or Status. Instead, we only use the UI interface to standardize Input and Output formatting.

Index

• Constants
• Variables
• func NewBasicUI(ctx context.Context) *basicUI
• func NewUI(ctx context.Context, bufOut io.Writer) *basicUI
• type Cell
• type Input
• type NamedValue
• type Option
  • func WithDiffAddedStyle() Option
  • func WithDiffRemovedStyle() Option
  • func WithDiffUnchangedStyle() Option
  • func WithErrorStyle() Option
  • func WithHeaderStyle() Option
  • func WithInfoStyle() Option
  • func WithLibraryStyle() Option
  • func WithStyle(style string) Option
  • func WithSuccessStyle() Option
  • func WithWarningStyle() Option
  • func WithWriter(w io.Writer) Option
• type Table
  • func NewTable(headers ...string) *Table
  • func (t *Table) AddRow(cols []string, colors []string)
  • func (t *Table) ToJson() []map[string]interface{}
• type UI

Constants

const (
	Yellow  = "yellow"
	Green   = "green"
	Red     = "red"
	Blue    = "blue"
	Magenta = "magenta"
	HiWhite = "hiwhite"
)

const (
	HeaderStyle        = "header"
	ErrorStyle         = "error"
	ErrorBoldStyle     = "error-bold"
	WarningStyle       = "warning"
	WarningBoldStyle   = "warning-bold"
	InfoStyle          = "info"
	LibraryStyle       = "library"
	SuccessStyle       = "success"
	SuccessBoldStyle   = "success-bold"
	DiffUnchangedStyle = "diff-unchanged"
	DiffAddedStyle     = "diff-added"
	DiffRemovedStyle   = "diff-removed"
)

Variables

var ErrNonInteractive = errors.New("noninteractive UI doesn't support this operation")

ErrNonInteractive is returned when Input is called on a non-Interactive UI.

Functions

func NewBasicUI

func NewBasicUI(ctx context.Context) *basicUI

NewBasicUI creates a new instance of the basicUI struct for the terminal with color output.

func NewUI

func NewUI(ctx context.Context, bufOut io.Writer) *basicUI

NewUI creates a new instance of the basicUI struct that outputs to the bufOut buffer.

Types

type Cell

type Cell struct {
	Value string
	Color string
}

Cell is a single entry for a table.

type Input

type Input struct {
	// Prompt is a single-line prompt to give the user such as "Continue?"
	// The user will input their answer after this prompt.
	Prompt string

	// Style is the style to apply to the input. If this is blank,
	// the output won't be colorized in any way.
	Style string

	// True if this input is a secret. The input will be masked.
	Secret bool
}

Input is the configuration for an input.

type NamedValue

type NamedValue struct {
	Name  string
	Value interface{}
}

Passed to UI.NamedValues to provide a nicely formatted key: value output.

type Option

type Option func(*config)

Option controls output styling.

func WithDiffAddedStyle

func WithDiffAddedStyle() Option

WithDiffAddedStyle colors the output in green.

func WithDiffRemovedStyle

func WithDiffRemovedStyle() Option

WithDiffRemovedStyle colors the output in red.

func WithDiffUnchangedStyle

func WithDiffUnchangedStyle() Option

WithDiffUnchangedStyle colors the diff style in white.

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 WithLibraryStyle

func WithLibraryStyle() Option

WithLibraryStyle styles the output with an arrow pointing to a section.

func WithStyle

func WithStyle(style string) Option

WithStyle allows for setting a style by passing a string.

func WithSuccessStyle

func WithSuccessStyle() Option

WithSuccessStyle styles the output as a success message.

func WithWarningStyle

func WithWarningStyle() Option

WithWarningStyle styles the output as an warning message.

func WithWriter

func WithWriter(w io.Writer) Option

WithWriter specifies the writer for the output.

type Table

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

Passed to UI.Table to provide a nicely formatted table.

func NewTable

func NewTable(headers ...string) *Table

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

func (*Table) AddRow

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

AddRow adds a row to the table.

func (*Table) ToJson

func (t *Table) ToJson() []map[string]interface{}

type UI

type UI interface {
	// Input asks the user for input. This will immediately return an error
	// if the UI doesn't support interaction. You can test for interaction
	// ahead of time with Interactive().
	Input(*Input) (string, error)

	// Interactive returns true if this prompt supports user interaction.
	// If this is false, Input will always error.
	Interactive() bool

	// 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.
	OutputWriters() (stdout, stderr io.Writer, err 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.