ui

Documentation

Overview

Package ui provides a simple way to interact with the user through the terminal, i.e. the interface of a CLI.

Index

• Variables
• func Ask(io IO, question string) (string, error)
• func AskAndValidate(io IO, question string, n int, validationFunc func(string) error) (string, error)
• func AskMultiline(IO IO, question string) ([]byte, error)
• func AskPassphrase(io IO, question string, repeatPhrase string, n int) (string, error)
• func AskSecret(io IO, question string) (string, error)
• func AskWithDefault(io IO, question, defaultValue string) (string, error)
• func AskYesNo(io IO, question string, t ConfirmationType) (bool, error)
• func Choose(io IO, question string, options []string, n int) (int, error)
• func ChooseDynamicOptions(io IO, question string, getOptions func() ([]Option, bool, error), addOwn bool, ...) (string, error)
• func ChooseDynamicOptionsValidate(io IO, question string, getOptions func() ([]Option, bool, error), ...) (string, error)
• func ConfirmCaseInsensitive(io IO, question string, expected ...string) (bool, error)
• func EOFKey() string
• func Readln(r io.Reader) (string, error)
• type ConfirmationType
• type IO
  • func NewUserIO() IO
• type Option
  • func (o Option) String() string

Variables

var (

	// ErrCannotAsk occurs when prompting for input is impossible.
	ErrCannotAsk = askErr.Code("cannot_ask_for_input").Error("Cannot ask for interactive input.\n\n" +
		"This usually happens when you run something non-interactively that needs to ask interactive questions.")
	ErrPassphrasesDoNotMatch = askErr.Code("passphrase_does_not_match").Error("passphrases do not match")
)

Errors

var (
	ErrReadInput = errRead.Code("read_input").ErrorPref("could not read input: %s")
)

Errors

Functions

func Ask

func Ask(io IO, question string) (string, error)

Ask prints out the question and reads the first line of input.

func AskAndValidate

func AskAndValidate(io IO, question string, n int, validationFunc func(string) error) (string, error)

AskAndValidate asks the user a question and re-prompts the configured amount of times when the users answer does not validate.

func AskMultiline

func AskMultiline(IO IO, question string) ([]byte, error)

AskMultiline prints out the question and reads back the input until an EOF is reached. The input is displayed to the user.

func AskPassphrase

func AskPassphrase(io IO, question string, repeatPhrase string, n int) (string, error)

AskPassphrase asks for a password and then asks to type it again for confirmation. When the user types two different passphrases, he is asked again. When the answers still haven't matched after trying n times, the error ErrPassphrasesDoNotMatch is returned. For the empty answer ("") no confirmation is asked.

func AskSecret

func AskSecret(io IO, question string) (string, error)

AskSecret prints out the question and reads back the input, without echoing it back. Useful for passwords and other sensitive inputs.

func AskWithDefault

func AskWithDefault(io IO, question, defaultValue string) (string, error)

AskWithDefault prints out the question and reads the first line of input. If no input is given, the default value is returned.

func AskYesNo

func AskYesNo(io IO, question string, t ConfirmationType) (bool, error)

AskYesNo asks the user for confirmation. A user must type in "yes" or "no" and then press enter. It has fuzzy matching, so "y", "Y", "yes", "YES", and "Yes" all count as confirmations. If no input is given, it will return true with DefaultYes and false with DefaultNo. If the input is not recognized, it will ask again. The function retries 3 times. If it still has no valid response after that, it returns false.

func Choose

func Choose(io IO, question string, options []string, n int) (int, error)

Choose gives the user the provided options asks them to choose one. It returns the index of the option chosen, starting with 0.

func ChooseDynamicOptions

func ChooseDynamicOptions(io IO, question string, getOptions func() ([]Option, bool, error), addOwn bool, optionName string) (string, error)

func ChooseDynamicOptionsValidate

func ChooseDynamicOptionsValidate(io IO, question string, getOptions func() ([]Option, bool, error), optionName string, validateFunc func(string) error) (string, error)

func ConfirmCaseInsensitive

func ConfirmCaseInsensitive(io IO, question string, expected ...string) (bool, error)

ConfirmCaseInsensitive asks the user to confirm by typing one of the expected strings. The comparison is not case-sensitive. If multiple values for expected are given, true is returned if the input equals any of the the expected values.

func EOFKey

func EOFKey() string

EOFKey returns the key that should be pressed to enter an EOF. This can be used to end multiline input.

func Readln

func Readln(r io.Reader) (string, error)

Readln reads 1 line of input from a io.Reader. The newline character is not included in the response.

Types

type ConfirmationType

type ConfirmationType int

ConfirmationType defines what AskYesNo uses as the default answer.

const (
	// DefaultNone assumes no default [y/n]
	DefaultNone ConfirmationType = iota
	// DefaultNo assumes no as the default answer [y/N]
	DefaultNo
	// DefaultYes assumes yes as the default answer [Y/n]
	DefaultYes
)

type IO

type IO interface {
	// Input returns an io,Reader that reads input for the current process.
	// If the process's input is piped, this reads from the pipe otherwise it asks input from the user.
	Input() io.Reader
	// Output returns an io.Writer that writes output for the current process.
	// If the process's output is piped, this writes to the pipe otherwise it prints to the terminal.
	Output() io.Writer
	// Stdin returns the *os.File of the current process's stdin stream.
	Stdin() *os.File
	// Stdin returns the *os.File of the current process's stdout stream.
	Stdout() *os.File
	// Prompts returns an io.Reader and io.Writer that read and write directly to/from the terminal, even if the
	// input or output of the current process is piped.
	// If this is not supported, an error is returned.
	Prompts() (io.Reader, io.Writer, error)
	// ReadSecret reads a line of input from the terminal while hiding the entered characters.
	// Returns an error if secret input is not supported.
	ReadSecret() ([]byte, error)
	// IsInputPiped returns whether the current process's input is piped from another process.
	IsInputPiped() bool
	// IsOutputPiped returns whether the current process's output is piped to another process.
	IsOutputPiped() bool
}

IO is an interface to work with input/output.

func NewUserIO

func NewUserIO() IO

NewUserIO creates a new ttyIO if a TTY is available, otherwise it returns a standardIO.

type Option

type Option struct {
	Value   string
	Display string
}

func (Option) String

func (o Option) String() string