README
¶
This is my customised fork of github.com/peterh/liner That package has to maintain a stable public API. Here, I make feature changes & additions as I please.
Documentation
¶
Overview ¶
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 ControlCodeHandler
- type ModeApplier
- type State
- func (s *State) AppendHistory(item string)
- func (s *State) Close() error
- func (s *State) Prompt(prompt string) (string, error)
- func (s *State) ReadHistory(r io.Reader) (num int, err error)
- func (s *State) SetCompleter(f Completer)
- func (s *State) SetMultiLineMode(mlmode bool)
- func (s *State) SetPunctuation(ps ...rune)
- func (s *State) SetTabCompletionStyle(tabStyle TabStyle)
- func (s *State) SetUnusedControlCodeHandler(f ControlCodeHandler)
- func (s *State) SetWordCompleter(f WordCompleter)
- func (s *State) WriteHistory(w io.Writer) (num int, err error)
- type TabStyle
- type WordCompleter
Examples ¶
Constants ¶
const HistoryLimit = 1000
HistoryLimit is the maximum number of entries saved in the scrollback history.
const KillRingMax = 60
Max elements to save on the killring
Variables ¶
var ErrNotTerminalOutput = errors.New("standard output is not a terminal")
ErrNotTerminalOutput is returned from Prompt if the platform is normally supported, but stdout has been redirected
Functions ¶
func TerminalSupported ¶
func TerminalSupported() bool
TerminalSupported returns true if the current terminal supports line editing features, and false if liner will use the 'dumb' fallback for input. Note that TerminalSupported does not check all factors that may cause liner to not fully support the terminal (such as stdin redirection)
Types ¶
type Completer ¶
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 ControlCodeHandler ¶
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 the current terminal input mode as an InputModeSetter.
This function is provided for convenience, and should not be necessary for most users of liner.
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, and sets the terminal into raw mode. To restore the terminal to its previous state, call State.Close().
Note if you are still using Go 1.0: NewLiner handles SIGWINCH, so it will leak a channel every time you call it. Therefore, it is recommened that you upgrade to a newer release of Go, or ensure that NewLiner is only called once.
func (*State) AppendHistory ¶
AppendHistory appends an entry to the scrollback history. AppendHistory should be called iff Prompt returns a valid command.
func (*State) Prompt ¶
Prompt displays p and returns a line of user input, not including a trailing newline character. An io.EOF error is returned if the user signals end-of-file by pressing Ctrl-D. Prompt allows line editing if the terminal supports it.
func (*State) ReadHistory ¶
ReadHistory reads scrollback history from r. Returns the number of lines read, and any read error (except io.EOF).
func (*State) SetCompleter ¶
SetCompleter sets the completion function that Liner will call to fetch completion candidates when the user presses tab.
func (*State) SetMultiLineMode ¶
SetMultiLineMode sets whether line is auto-wrapped. The default is false (single line).
func (*State) SetPunctuation ¶
SetPunctuation sets runes that will be considered stops for word-based cursor movement and deletion without requiring surrounding whitespace.
func (*State) SetTabCompletionStyle ¶
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) SetUnusedControlCodeHandler ¶
func (s *State) SetUnusedControlCodeHandler(f ControlCodeHandler)
SetUnusedControlCodeHandler sets a function that can choose to do something with ASCII control codes that Prompt reads but does not make use of for line editing purposes. When f returns true, the control code is considered to be handled and the normal beep is suppressed.
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 ¶
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)
Example ¶
This example demonstrates a way to retrieve the current history buffer without using a file.
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
type TabStyle ¶
type TabStyle int
TabStyle is used to select how tab completions are displayed.
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 ¶
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