prompt

Documentation

Overview

Package prompt implements CLI prompts to the user.

Index

• Variables
• func Confirmation(ctx context.Context, out io.Writer, in Reader, question string) (bool, error)
• func Input(ctx context.Context, out io.Writer, in Reader, question string) (string, error)
• func NotifyExit()
• func Password(ctx context.Context, out io.Writer, in SecureReader, question string) (string, error)
• func PickOne(ctx context.Context, out io.Writer, in Reader, question string, ...) (string, error)
• func SetStdin(rd StdinReader)
• type ContextReader
  • func NewContextReader(rd io.Reader) *ContextReader
  • func (cr *ContextReader) Close() error
  • func (cr *ContextReader) IsTerminal() bool
  • func (cr *ContextReader) Password() *PasswordReader
  • func (cr *ContextReader) ReadContext(ctx context.Context) ([]byte, error)
  • func (cr *ContextReader) ReadPassword(ctx context.Context) ([]byte, error)
• type FakeReader
  • func NewFakeReader() *FakeReader
  • func (r *FakeReader) AddError(err error) *FakeReader
  • func (r *FakeReader) AddReply(fn FakeReplyFunc) *FakeReader
  • func (r *FakeReader) AddString(s string) *FakeReader
  • func (r *FakeReader) IsTerminal() bool
  • func (r *FakeReader) ReadContext(ctx context.Context) ([]byte, error)
  • func (r *FakeReader) ReadPassword(ctx context.Context) ([]byte, error)
• type FakeReplyFunc
• type PasswordReader
  • func (pr *PasswordReader) ReadContext(ctx context.Context) ([]byte, error)
• type Reader
• type SecureReader
• type StdinReader
  • func Stdin() StdinReader

Variables

var ErrNotTerminal = errors.New("underlying reader is not a terminal")

ErrNotTerminal is returned by password reads attempted in non-terminal readers.

var ErrReaderClosed = errors.New("ContextReader has been closed")

ErrReaderClosed is returned from ContextReader.ReadContext after it is closed.

Functions

func Confirmation

func Confirmation(ctx context.Context, out io.Writer, in Reader, question string) (bool, error)

Confirmation prompts the user for a yes/no confirmation for question. The prompt is written to out and the answer is read from in.

question should be a plain sentence without "yes/no"-type hints at the end.

ctx can be canceled to abort the prompt.

func Input

func Input(ctx context.Context, out io.Writer, in Reader, question string) (string, error)

Input prompts the user for freeform text input. The prompt is written to out and the answer is read from in.

ctx can be canceled to abort the prompt.

func NotifyExit

func NotifyExit()

NotifyExit notifies prompt singletons, such as Stdin, that the program is about to exit. This allows singletons to perform actions such as restoring terminal state. Once NotifyExit is called the singletons will be closed.

func Password

func Password(ctx context.Context, out io.Writer, in SecureReader, question string) (string, error)

Password prompts the user for a password. The prompt is written to out and the answer is read from in. The in reader has to be a terminal.

func PickOne

func PickOne(ctx context.Context, out io.Writer, in Reader, question string, options []string) (string, error)

PickOne prompts the user to pick one of the provided string options. The prompt is written to out and the answer is read from in.

question should be a plain sentence without the list of provided options.

ctx can be canceled to abort the prompt.

func SetStdin

func SetStdin(rd StdinReader)

SetStdin allows callers to change the Stdin reader. Useful to replace Stdin for tests, but should be avoided in production code.

Types

type ContextReader

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

ContextReader is a wrapper around an underlying io.Reader or terminal that allows reads to be abandoned. An abandoned read may be reclaimed by future callers. ContextReader instances are not safe for concurrent use, callers may block indefinitely and reads may be lost.

func NewContextReader

func NewContextReader(rd io.Reader) *ContextReader

NewContextReader creates a new ContextReader wrapping rd. Callers should avoid reading from rd after the ContextReader is used, as abandoned calls may be in progress. It is safe to read from rd if one can guarantee that no calls where abandoned. Calling ContextReader.Close attempts to release resources, but note that ongoing reads cannot be interrupted.

func (*ContextReader) Close

func (cr *ContextReader) Close() error

Close closes the context reader, attempting to release resources and aborting ongoing and future ReadContext calls. Background reads that are already blocked cannot be interrupted, thus Close doesn't guarantee a release of all resources.

func (*ContextReader) IsTerminal

func (cr *ContextReader) IsTerminal() bool

IsTerminal returns whether the given reader is a terminal.

func (*ContextReader) Password

func (cr *ContextReader) Password() *PasswordReader

Password returns a PasswordReader from a ContextReader. The returned PasswordReader is only functional if the underlying reader is a terminal.

func (*ContextReader) ReadContext

func (cr *ContextReader) ReadContext(ctx context.Context) ([]byte, error)

ReadContext returns the next chunk of output from the reader. If ctx is canceled before the read completes, the current read is abandoned and may be reclaimed by future callers. It is not safe to read from the underlying reader after a read is abandoned, nor is it safe to concurrently call ReadContext.

func (*ContextReader) ReadPassword

func (cr *ContextReader) ReadPassword(ctx context.Context) ([]byte, error)

ReadPassword reads a password from the underlying reader, provided that the reader is a terminal. It follows the semantics of ReadContext.

type FakeReader

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

func NewFakeReader

func NewFakeReader() *FakeReader

NewFakeReader returns a fake that can be used in place of a ContextReader. Call Add functions in the desired order to configure responses. Each call represents a read reply, in order.

func (*FakeReader) AddError

func (r *FakeReader) AddError(err error) *FakeReader

func (*FakeReader) AddReply

func (r *FakeReader) AddReply(fn FakeReplyFunc) *FakeReader

func (*FakeReader) AddString

func (r *FakeReader) AddString(s string) *FakeReader

func (*FakeReader) IsTerminal

func (r *FakeReader) IsTerminal() bool

func (*FakeReader) ReadContext

func (r *FakeReader) ReadContext(ctx context.Context) ([]byte, error)

func (*FakeReader) ReadPassword

func (r *FakeReader) ReadPassword(ctx context.Context) ([]byte, error)

type FakeReplyFunc

type FakeReplyFunc func(context.Context) (string, error)

type PasswordReader

type PasswordReader ContextReader

PasswordReader is a ContextReader that reads passwords from the underlying terminal.

func (*PasswordReader) ReadContext

func (pr *PasswordReader) ReadContext(ctx context.Context) ([]byte, error)

ReadContext reads a password from the underlying reader, provided that the reader is a terminal. It is equivalent to ContextReader.ReadPassword. It follows the semantics of ReadContext.

type Reader

type Reader interface {
	// ReadContext reads from the underlying buffer, respecting context
	// cancellation.
	ReadContext(ctx context.Context) ([]byte, error)
}

Reader is the interface for prompt readers.

type SecureReader

type SecureReader interface {
	// ReadPassword reads from the underlying buffer, respecting context
	// cancellation.
	ReadPassword(ctx context.Context) ([]byte, error)
}

SecureReader is the interface for password readers.

type StdinReader

type StdinReader interface {
	IsTerminal() bool
	Reader
	SecureReader
}

StdinReader contains ContextReader methods applicable to stdin.

func Stdin

func Stdin() StdinReader

Stdin returns a singleton ContextReader wrapped around os.Stdin.

os.Stdin should not be used directly after the first call to this function to avoid losing data.