prompt

README

Prompt

Prompt is a command line prompt editor with history, kill-ring, and tab completion. It was inspired by linenoise and derivatives which eschew usage of terminfo/termcap in favor of treating everything like a VT100 terminal. This is taken a bit further with support for additional input escape sequences that cover ~75% of the terminals in the terminfo database. A minimal set of output escape sequences is used for rendering the prompt.

Documentation

Index

• type CompletionFunc
• type Option
  • func WithCompleter(fn CompletionFunc) Option
  • func WithHistory(path string, maxSize int) Option
  • func WithInput(r io.Reader) Option
  • func WithInputFinished(fn func(text string) bool) Option
  • func WithOutput(w io.Writer) Option
  • func WithSize(width, height int) Option
  • func WithTTY(tty *os.File) Option
• type Prompt
  • func New(options ...Option) (*Prompt, error)
  • func (p *Prompt) Close() error
  • func (p *Prompt) ReadLine(prompt string) (string, error)

Types

type CompletionFunc

type CompletionFunc func(text []rune, wordStart, wordEnd int) []string

CompletionFunc is used to find the completions of the word delineated by [wordStart,wordEnd) within text. The full text is provided so that context-sensitive completion can be performed (e.g. a keyword might only be valid in certain contexts). The list of completions should be returned in priority order.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option defines the interface for Prompt options.

func WithCompleter

func WithCompleter(fn CompletionFunc) Option

WithCompleter allows configuring a callback that will be invoked when text is entered or deleted in order to determine completions of the word at the current position.

func WithHistory

func WithHistory(path string, maxSize int) Option

func WithInput

func WithInput(r io.Reader) Option

WithInput allows configuring the input reader for a Prompt. This option is primarily useful for tests.

func WithInputFinished

func WithInputFinished(fn func(text string) bool) Option

WithInputFinished allows configuring a callback that will be invoked when enter is pressed to determine if the input is considered complete or not. If the input is not complete, a newline is instead inserted into the input.

func WithOutput

func WithOutput(w io.Writer) Option

WithOutput allows configuring the output writer for a Prompt. This option is primarily useful for tests.

func WithSize

func WithSize(width, height int) Option

WithSize allows configuring the initial width and height of a Prompt. Typically, the width and height of the terminal are automatically determined. This option is primarily useful for tests in conjunction with the WithInput and WithOutput options.

func WithTTY

func WithTTY(tty *os.File) Option

WithTTY allows configuring a prompt with a different TTY than stdin/stdout.

type Prompt

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

Prompt contains the state for reading single or multi-line input from a terminal. Similar to readline, libedit, and other CLI line reading libraries, Prompt provides support for basic editing functionality such as cursor movement, deletion, a kill ring, and history.

Prompt supports a common subset of the universe of key input sequences which are used by ~75% of the terminals in the terminfo database, including most modern terminals. Prompt itself does not use terminfo. Additionally, Prompt requires that the terminal handle a minimal set of ANSI escape sequences for rendering text:

• cursor-up: ESC[A
• cursor-down: ESC[B
• cursor-right: ESC[C
• cursor-left: ESC[D
• cursor-home: ESC[H
• erase-line-to-right: ESC[K
• erase-screen: ESC[2J

Prompt eschews using more advanced terminal operations such as insert/delete character and insert mode. This decision results in Prompt having to re-render more lines of text on editing operations, yet for line editing the difference usually amounts to sending a few hundred bytes to the terminal (for a long line). On modern hardware and networks, this amount of data is trivial. The benefit of eschewing more advanced terminal operations is that the same rendering output is used for all terminals as opposed to the libedit/readline approach which requires intimate knowledge of the terminal capabilities (via terminfo) and which can sometimes go horribly wrong resulting in corruption of the rendered text.

func New

func New(options ...Option) (*Prompt, error)

New creates a new Prompt using the supplied options. If no options are specified, the Prompt uses os.Stdin and os.Stdout for input and output.

func (*Prompt) Close

func (p *Prompt) Close() error

Close closes the Prompt, releasing any open resources.

func (*Prompt) ReadLine

func (p *Prompt) ReadLine(prompt string) (string, error)

ReadLine reads a line of input. If the input is canceled, io.EOF is returned as the error.