Documentation
¶
Overview ¶
Package components is the set of shapes a command prints in.
There is no template engine between a command and its terminal: the markup each component prints is written directly into the component itself.
Index ¶
- func EnsureDynamicContentIsHighlighted(s string) string
- func EnsureNoPunctuation(s string) string
- func EnsurePunctuation(s string) string
- type Alert
- type Ask
- type AskWithCompletion
- type BulletList
- type Choice
- type Component
- type Confirm
- type Error
- type Factory
- func (f *Factory) Alert(message string, verbosity ...Verbosity)
- func (f *Factory) Ask(question, def string) (string, error)
- func (f *Factory) AskWithCompletion(question string, choices []string, def string) (string, error)
- func (f *Factory) BulletList(elements []string, verbosity ...Verbosity)
- func (f *Factory) Choice(question string, choices []string, def string) (string, error)
- func (f *Factory) Confirm(question string, def bool) (bool, error)
- func (f *Factory) Error(message string, verbosity ...Verbosity)
- func (f *Factory) Info(message string, verbosity ...Verbosity)
- func (f *Factory) Line(style, message string, verbosity ...Verbosity)
- func (f *Factory) Output() Output
- func (f *Factory) Secret(question string) (string, error)
- func (f *Factory) Success(message string, verbosity ...Verbosity)
- func (f *Factory) Task(description string, task TaskFunc, verbosity ...Verbosity) error
- func (f *Factory) TwoColumnDetail(first, second string, verbosity ...Verbosity)
- func (f *Factory) Warn(message string, verbosity ...Verbosity)
- type Info
- type Line
- type Mutator
- type Output
- type Secret
- type Success
- type Task
- type TaskFunc
- type TwoColumnDetail
- type Verbosity
- type Warn
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureDynamicContentIsHighlighted ¶
EnsureDynamicContentIsHighlighted emboldens every [bracketed] run.
The escape sequence is written here rather than a markup tag, because there is no formatter between this and the terminal.
func EnsureNoPunctuation ¶
EnsureNoPunctuation drops a trailing . ? ! or : .
It is what keeps a task description from reading "migrating the database. ....... DONE".
func EnsurePunctuation ¶
EnsurePunctuation adds a full stop when there is none.
A line component is a sentence, and a sentence ends. The empty string is the exception: it returns empty rather than a bare full stop.
Types ¶
type Alert ¶
type Alert struct{ Component }
Alert renders a message in a box, in capitals.
func (Alert) Render ¶
Render writes the alert.
The band is as wide as the terminal and three lines tall: a blank padding line, the message centered and inverted, and another blank padding line. The message is uppercased through [upperVisible] rather than strings.ToUpper, because the message has already been through EnsureDynamicContentIsHighlighted and a naive uppercase would mangle the escape sequences that mutator adds.
There is a blank line above the band and none below: whatever renders next supplies its own leading margin, the way Line.Render does with its own trailing NewLine.
type AskWithCompletion ¶
type AskWithCompletion struct{ Component }
AskWithCompletion is Ask with a list the terminal completes from.
func NewAskWithCompletion ¶
func NewAskWithCompletion(output Output, base string) AskWithCompletion
NewAskWithCompletion returns the component.
type BulletList ¶
type BulletList struct{ Component }
BulletList renders one line per element, each with a leading mark.
func NewBulletList ¶
func NewBulletList(output Output, base string) BulletList
NewBulletList returns the component.
func (BulletList) Render ¶
func (b BulletList) Render(elements []string, verbosity ...Verbosity)
Render writes the list.
The dim colour covers the whole line, mark and element together, not just the mark.
type Choice ¶
type Choice struct{ Component }
Choice offers a numbered list and returns the option that was picked.
The prompt keeps asking until it gets an answer it understands.
type Component ¶
type Component struct {
// contains filtered or unexported fields
}
Component is what every console component holds: the output it renders into and the root it shortens paths against.
The markup is written straight to the stream, with no template or output buffer in between.
func NewComponent ¶
NewComponent returns a component over an output.
base is the application root, and it is what EnsureRelativePaths strips. Passing it in is what keeps a component testable.
type Confirm ¶
type Confirm struct{ Component }
Confirm asks a yes or no question.
func NewConfirm ¶
NewConfirm returns the component.
type Factory ¶
type Factory struct {
// contains filtered or unexported fields
}
Factory is where a command reaches for a component.
Each method is declared rather than resolved from a name at run time, which is what makes a typo a compile error rather than a failure once the command runs.
func NewFactory ¶
NewFactory returns the factory for one output.
base is the application root that EnsureRelativePaths strips from a path, and empty means paths are printed as they came.
func (*Factory) AskWithCompletion ¶
AskWithCompletion is Ask with a list the terminal completes from.
func (*Factory) BulletList ¶
BulletList renders one line per element.
func (*Factory) Line ¶
Line renders a labelled sentence in one of the four styles: info, success, warn, error.
func (*Factory) TwoColumnDetail ¶
TwoColumnDetail renders a label and its value, joined by dots.
type Line ¶
type Line struct{ Component }
Line renders a labelled sentence: the chip, then the message.
It is what Info, Success, Warn and Error are each one call to.
func NewLineComponent ¶
NewLineComponent returns the component.
The constructor is not called NewLine because the package already has that name on Output, and a package with two NewLine of different shapes is a package where the completion list picks the wrong one.
func (Line) Render ¶
Render writes the labelled line.
The top margin is 2 minus the line endings already written, floored at zero: two labelled lines in a row get one blank line between them and never two.
An unknown style panics. The four names are a closed set the caller writes as a literal, so an unknown one is a mistake in the command rather than anything a person typed, and a panic is what Go spends on that.
type Mutator ¶
Mutator rewrites the text of a component before it is rendered.
func EnsureRelativePaths ¶
EnsureRelativePaths strips the application root from every path in the text, curried over the root.
The root is given here rather than read from a global, because a component that reaches for a global to shorten a path is a component no test can pin. Base is set by the Factory.
type Output ¶
type Output interface {
// Write puts text out without a line ending.
Write(message string, verbosity ...Verbosity)
// Writeln puts one line out.
Writeln(message string, verbosity ...Verbosity)
// NewLine writes count blank lines, one when count is omitted.
NewLine(count ...int)
// NewLinesWritten is how many line endings the last write left behind. The
// Line component reads it to decide its top margin.
NewLinesWritten() int
// GetTerminalWidth is how many columns there are to fill.
GetTerminalWidth() int
// Ask puts a question and returns the answer, or def when it is empty.
Ask(question, def string) (string, error)
// AskWithCompletion is Ask with a list the terminal completes from.
AskWithCompletion(question string, choices []string, def string) (string, error)
// Secret asks for a value the terminal must not show.
Secret(question string) (string, error)
// Confirm asks a yes or no question.
Confirm(question string, def bool) (bool, error)
// Choice offers a numbered list and returns the option that was picked.
Choice(question string, choices []string, def string) (string, error)
}
Output is the terminal a component renders into.
It is the minimal set of methods a component actually calls, kept as an interface so this package does not import console, which imports this one: a component is the leaf, and the IO is what satisfies it.
type Secret ¶
type Secret struct{ Component }
Secret asks for a value the terminal must not show.
A terminal that will not stop echoing is an error here rather than a choice between showing the value or not.
type Success ¶
type Success struct{ Component }
Success renders a line that reports something worked.
func NewSuccess ¶
NewSuccess returns the component.
type Task ¶
type Task struct{ Component }
Task renders a description, runs the work and reports how it went, on one line.
type TaskFunc ¶
type TaskFunc func() (view.TaskResult, error)
TaskFunc is the work a Task component runs.
A non-nil error makes the line read FAIL whatever the result says.
type TwoColumnDetail ¶
type TwoColumnDetail struct{ Component }
TwoColumnDetail renders a label on the left and its value on the right, joined by dots.
func NewTwoColumnDetail ¶
func NewTwoColumnDetail(output Output, base string) TwoColumnDetail
NewTwoColumnDetail returns the component.
func (TwoColumnDetail) Render ¶
func (t TwoColumnDetail) Render(first, second string, verbosity ...Verbosity)
Render writes the line.
type Verbosity ¶
type Verbosity int
Verbosity is how much a command is allowed to say.
It is declared here, in the leaf, rather than in console: a component may not import the package that builds it, and one set of constants in the package that cannot import is better than two sets that agree by hand. console aliases this type, so console.Verbosity and components.Verbosity are one type and not two.
const ( // VerbosityQuiet writes nothing at all: -q. VerbosityQuiet Verbosity = 16 // VerbosityNormal is the default. VerbosityNormal Verbosity = 32 // VerbosityVerbose is -v. VerbosityVerbose Verbosity = 64 // VerbosityVeryVerbose is -vv. VerbosityVeryVerbose Verbosity = 128 // VerbosityDebug is -vvv. VerbosityDebug Verbosity = 256 )
Source Files