package liner

import "github.com/peterh/liner"

Package liner implements a simple command line editor, inspired by linenoise (https://github.com/antirez/linenoise/). This package supports WIN32 in addition to the xterm codes supported by everything else.

Index ¶

• Constants
• Variables
• func TerminalSupported() bool
• type Completer
• type ModeApplier
• func TerminalMode() (ModeApplier, error)
• type ShouldRestart
• type State
• func NewLiner() *State
• func (s *State) AppendHistory(item string)
• func (s *State) ClearHistory()
• func (s *State) Close() error
• func (s *State) PasswordPrompt(p string) (string, error)
• func (s *State) Prompt(p string) (string, error)
• func (s *State) ReadHistory(r io.Reader) (num int, err error)
• func (s *State) SetBeep(beep bool)
• func (s *State) SetCompleter(f Completer)
• func (s *State) SetCtrlCAborts(aborts bool)
• func (s *State) SetMultiLineMode(mlmode bool)
• func (s *State) SetShouldRestart(f ShouldRestart)
• func (s *State) SetTabCompletionStyle(tabStyle TabStyle)
• func (s *State) SetWordCompleter(f WordCompleter)
• func (s *State) WriteHistory(w io.Writer) (num int, err error)
• type TabStyle
• type WordCompleter

Examples ¶

• State.WriteHistory

Constants ¶

const HistoryLimit = 1000

HistoryLimit is the maximum number of entries saved in the scrollback history.

const KillRingMax = 60

KillRingMax is the max number of elements to save on the killring.

Variables ¶

var ErrInternal = errors.New("liner: internal error")

ErrInternal is returned when liner experiences an error that it cannot handle. For example, if the number of colums becomes zero during an active call to Prompt

var ErrInvalidPrompt = errors.New("invalid prompt")

ErrInvalidPrompt is returned from Prompt or PasswordPrompt if the prompt contains any unprintable runes (including substrings that could be colour codes on some platforms).

var ErrNotTerminalOutput = errors.New("standard output is not a terminal")

ErrNotTerminalOutput is returned from Prompt or PasswordPrompt if the platform is normally supported, but stdout has been redirected

var ErrPromptAborted = errors.New("prompt aborted")

ErrPromptAborted is returned from Prompt or PasswordPrompt when the user presses Ctrl-C if SetCtrlCAborts(true) has been called on the State

Functions ¶

func TerminalSupported ¶

func TerminalSupported() bool

TerminalSupported returns false because line editing is not supported on this platform.

Types ¶

type Completer ¶

type Completer func(line string) []string

Completer takes the currently edited line content at the left of the cursor and returns a list of completion candidates. If the line is "Hello, wo!!!" and the cursor is before the first '!', "Hello, wo" is passed to the completer which may return {"Hello, world", "Hello, Word"} to have "Hello, world!!!".

type ModeApplier ¶

type ModeApplier interface {
	ApplyMode() error
}

ModeApplier is the interface that wraps a representation of the terminal mode. ApplyMode sets the terminal to this mode.

func TerminalMode ¶

func TerminalMode() (ModeApplier, error)

TerminalMode returns a noop InputModeSetter on this platform.

type ShouldRestart ¶

type ShouldRestart func(err error) bool

ShouldRestart is passed the error generated by readNext and returns true if the the read should be restarted or false if the error should be returned.

type State ¶

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

State represents an open terminal

func NewLiner ¶

func NewLiner() *State

NewLiner initializes a new *State

Note that this operating system uses a fallback mode without line editing. Patches welcome.

func (*State) AppendHistory ¶

func (s *State) AppendHistory(item string)

AppendHistory appends an entry to the scrollback history. AppendHistory should be called iff Prompt returns a valid command.

func (*State) ClearHistory ¶

func (s *State) ClearHistory()

ClearHistory clears the scrollback history.

func (*State) Close ¶

func (s *State) Close() error

Close returns the terminal to its previous mode

func (*State) PasswordPrompt ¶

func (s *State) PasswordPrompt(p string) (string, error)

PasswordPrompt is not supported in this OS.

func (*State) Prompt ¶

func (s *State) Prompt(p string) (string, error)

Prompt displays p, and then waits for user input. Prompt does not support line editing on this operating system.

func (*State) ReadHistory ¶

func (s *State) ReadHistory(r io.Reader) (num int, err error)

ReadHistory reads scrollback history from r. Returns the number of lines read, and any read error (except io.EOF).

func (*State) SetBeep ¶

func (s *State) SetBeep(beep bool)

SetBeep sets whether liner should beep the terminal at various times (output ASCII BEL, 0x07). Default is true (will beep).

func (*State) SetCompleter ¶

func (s *State) SetCompleter(f Completer)

SetCompleter sets the completion function that Liner will call to fetch completion candidates when the user presses tab.

func (*State) SetCtrlCAborts ¶

func (s *State) SetCtrlCAborts(aborts bool)

SetCtrlCAborts sets whether Prompt on a supported terminal will return an ErrPromptAborted when Ctrl-C is pressed. The default is false (will not return when Ctrl-C is pressed). Unsupported terminals typically raise SIGINT (and Prompt does not return) regardless of the value passed to SetCtrlCAborts.

func (*State) SetMultiLineMode ¶

func (s *State) SetMultiLineMode(mlmode bool)

SetMultiLineMode sets whether line is auto-wrapped. The default is false (single line).

func (*State) SetShouldRestart ¶

func (s *State) SetShouldRestart(f ShouldRestart)

SetShouldRestart sets the restart function that Liner will call to determine whether to retry the call to, or return the error returned by, readNext.

func (*State) SetTabCompletionStyle ¶

func (s *State) SetTabCompletionStyle(tabStyle TabStyle)

SetTabCompletionStyle sets the behvavior when the Tab key is pressed for auto-completion. TabCircular is the default behavior and cycles through the list of candidates at the prompt. TabPrints will print the available completion candidates to the screen similar to BASH and GNU Readline

func (*State) SetWordCompleter ¶

func (s *State) SetWordCompleter(f WordCompleter)

SetWordCompleter sets the completion function that Liner will call to fetch completion candidates when the user presses tab.

func (*State) WriteHistory ¶

func (s *State) WriteHistory(w io.Writer) (num int, err error)

WriteHistory writes scrollback history to w. Returns the number of lines successfully written, and any write error.

Unlike the rest of liner's API, WriteHistory is safe to call from another goroutine while Prompt is in progress. This exception is to facilitate the saving of the history buffer during an unexpected exit (for example, due to Ctrl-C being invoked)

{
	var s State
	s.AppendHistory("foo")
	s.AppendHistory("bar")

	buf := new(bytes.Buffer)
	_, err := s.WriteHistory(buf)
	if err == nil {
		history := strings.Split(strings.TrimSpace(buf.String()), "\n")
		for i, line := range history {
			fmt.Println("History entry", i, ":", line)
		}
	}
	// Output:
	// History entry 0 : foo
	// History entry 1 : bar
}

History entry 0 : foo
History entry 1 : bar

type TabStyle ¶

type TabStyle int

TabStyle is used to select how tab completions are displayed.

const (
	TabCircular TabStyle = iota
	TabPrints
)

Two tab styles are currently available:

TabCircular cycles through each completion item and displays it directly on the prompt

TabPrints prints the list of completion items to the screen after a second tab key is pressed. This behaves similar to GNU readline and BASH (which uses readline)

type WordCompleter ¶

type WordCompleter func(line string, pos int) (head string, completions []string, tail string)

WordCompleter takes the currently edited line with the cursor position and returns the completion candidates for the partial word to be completed. If the line is "Hello, wo!!!" and the cursor is before the first '!', ("Hello, wo!!!", 9) is passed to the completer which may returns ("Hello, ", {"world", "Word"}, "!!!") to have "Hello, world!!!".

Source Files ¶

common.go fallbackinput.go width.go