terminal

package
v0.0.0-...-7ae29b8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 18, 2023 License: MPL-2.0 Imports: 30 Imported by: 6

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

View Source 
const (
	StatusOK      = "ok"
	StatusError   = "error"
	StatusWarn    = "warn"
	StatusTimeout = "timeout"
	StatusAbort   = "abort"
)
View Source 
const (
	TermRows    = 10
	TermColumns = 100
)
View Source 
const (
	Yellow = "yellow"
	Green  = "green"
	Red    = "red"
)
View Source 
const (
	HeaderStyle      = "header"
	ErrorStyle       = "error"
	ErrorBoldStyle   = "error-bold"
	WarningStyle     = "warning"
	WarningBoldStyle = "warning-bold"
	InfoStyle        = "info"
	InfoBoldStyle    = "info-bold"
	SuccessStyle     = "success"
	SuccessBoldStyle = "success-bold"
)

Variables

View Source 
var ErrNonInteractive = nonInteractiveError()

Functions

func Interpret 

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

Interpret decomposes the msg and arguments into the message, style, disabled new line, writer, and color

Types

type Display 

type Display struct {
	Entries []*DisplayEntry
	// contains filtered or unexported fields
}

func NewDisplay 

func NewDisplay(ctx context.Context, w io.Writer) *Display

func (*Display) Close 

func (d *Display) Close() error

func (*Display) Display 

func (d *Display) Display(ctx context.Context)

func (*Display) NewStatus 

func (d *Display) NewStatus(indent int) *DisplayEntry

func (*Display) NewStatusWithBody 

func (d *Display) NewStatusWithBody(indent, lines int) *DisplayEntry

type DisplayEntry 

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

func (*DisplayEntry) SetBody 

func (e *DisplayEntry) SetBody(line int, data string)

func (*DisplayEntry) SetStatus 

func (e *DisplayEntry) SetStatus(status string)

func (*DisplayEntry) StartSpinner 

func (e *DisplayEntry) StartSpinner()

func (*DisplayEntry) StopSpinner 

func (e *DisplayEntry) StopSpinner()

func (*DisplayEntry) Update 

func (e *DisplayEntry) Update(str string, args ...interface{})

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 styled in any way.
	Style string

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

	// Color is the color to apply to the input. If this is blank,
	// the output will be the default color for the terminal.
	Color string
}

Input is the configuration for an input.

type MachineReadableFormat 

type MachineReadableFormat int64

Type is an enum of all the available machine readable formats 

const (
	TableFormat MachineReadableFormat = iota
)

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 WithColor 

func WithColor(color string) Option

WithColor specifies the color of the output.

func WithErrorBoldStyle 

func WithErrorBoldStyle() Option

WithErrorBoldStyle styles the output as a bold error message.

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 WithInfoBoldStyle 

func WithInfoBoldStyle() Option

WithInfoStyle styles the output like it's formatted information.

func WithInfoStyle 

func WithInfoStyle() Option

WithInfoStyle styles the output like it's formatted information.

func WithNewLine 

func WithNewLine() Option

WithNewLine ensures a new line character from being suffixed at the end of the message

func WithStyle 

func WithStyle(style string) Option

func WithSuccessBoldStyle 

func WithSuccessBoldStyle() Option

WithSuccessBoldStyle styles the output as a bold success message

func WithSuccessStyle 

func WithSuccessStyle() Option

WithSuccessStyle styles the output as a success message.

func WithWarningBoldStyle 

func WithWarningBoldStyle() Option

WithWarningBoldStyle styles the output as a bold warning message.

func WithWarningStyle 

func WithWarningStyle() Option

WithWarningStyle styles the output as a warning message.

func WithWriter 

func WithWriter(w io.Writer) Option

WithWriter specifies the writer for the output.

func WithoutNewLine 

func WithoutNewLine() Option

WithoutNewLine prevents a new line character from being suffixed at the end of the message

type Status 

type Status interface {
	// Update writes a new status. This should be a single line.
	Update(msg string)

	// Indicate that a step has finished, confering an ok, error, or warn upon
	// it's finishing state. If the status is not StatusOK, StatusError, or StatusWarn
	// then the status text is written directly to the output, allowing for custom
	// statuses.
	Step(status, msg string)

	// Close should be called when the live updating is complete. The
	// status will be cleared from the line.
	Close() error
}

Status is used to provide an updating status to the user. The status usually has some animated element along with it such as a spinner.

type Step 

type Step interface {
	// The Writer has data written to it as though it was a terminal. This will appear
	// as body text under the Step's message and status.
	TermOutput() io.Writer

	// Change the Steps displayed message
	Update(string, ...interface{})

	// Update the status of the message. Supported values are in status.go.
	Status(status string)

	// Called when the step has finished. This must be done otherwise the StepGroup
	// will wait forever for it's Steps to finish.
	Done()

	// Sets the status to Error and finishes the Step if it's not already done.
	// This is usually done in a defer so that any return before the Done() shows
	// the Step didn't completely properly.
	Abort()
}

A Step is the unit of work within a StepGroup. This can be driven by concurrent goroutines safely.

type StepGroup 

type StepGroup interface {
	// Start a step in the output with the arguments making up the initial message
	Add(string, ...interface{}) Step

	// Wait for all steps to finish. This allows a StepGroup to be used like
	// a sync.WaitGroup with each step being run in a separate goroutine.
	// This must be called to properly clean up the step group.
	Wait()
}

StepGroup is a group of steps (that may be concurrent).

type Table 

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

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) 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 Term 

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

func NewTerm 

func NewTerm(ctx context.Context, d *DisplayEntry, height, width int) (*Term, error)

func (*Term) Close 

func (t *Term) Close() error

func (*Term) DamageDone 

func (t *Term) DamageDone(r state.Rect, cr screen.CellReader) error

func (*Term) MoveCursor 

func (t *Term) MoveCursor(p state.Pos) error

func (*Term) Output 

func (t *Term) Output(data []byte) error

func (*Term) SetTermProp 

func (t *Term) SetTermProp(attr state.TermAttr, val interface{}) error

func (*Term) StringEvent 

func (t *Term) StringEvent(kind string, data []byte) error

func (*Term) Write 

func (t *Term) Write(b []byte) (int, error)

type TextComponent 

type TextComponent struct {
	*glint.TextComponent
	// contains filtered or unexported fields
}

func Text 

func Text(v string, styles ...glint.StyleOption) *TextComponent

func (*TextComponent) Append 

func (t *TextComponent) Append(v string)

func (*TextComponent) Body 

func (t *TextComponent) Body(ctx context.Context) glint.Component

func (*TextComponent) Clear 

func (t *TextComponent) Clear()

func (*TextComponent) StyleMatch 

func (t *TextComponent) StyleMatch(styles ...glint.StyleOption) bool

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{})

	// ClearLine clears the content from the current line
	ClearLine()

	// MachineReadable returns true if this UI is for machine readable
	// output.
	MachineReadable() bool

	// 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)

	// Status returns a live-updating status that can be used for single-line
	// status updates that typically have a spinner or some similar style.
	// While a Status is live (Close isn't called), other methods on UI should
	// NOT be called.
	Status() Status

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

	// StepGroup returns a value that can be used to output individual (possibly
	// parallel) steps that have their own message, status indicator, spinner, and
	// body. No other output mechanism (Output, Input, Status, etc.) may be
	// called until the StepGroup is complete.
	StepGroup() StepGroup
}

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 BasicUI 

func BasicUI(ctx context.Context) UI

func ConsoleUI 

func ConsoleUI(ctx context.Context) UI

Returns a UI which will write to the current processes stdout/stderr.

func GlintUI 

func GlintUI(ctx context.Context) UI

func MachineReadableUI 

func MachineReadableUI(ctx context.Context, format MachineReadableFormat) UI

func NonInteractiveUI 

func NonInteractiveUI(ctx context.Context) UI

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.