Documentation
¶
Overview ¶
Package lineedit is wctr's interactive line editor, as a pure model: key events in, the line, the cursor, candidate listings and submitted lines out. It has no terminal, DOM or widget type in it, so every front end — the playground's xterm.js page, a go-widgets terminal widget — drives the same implementation.
It provides: editing (insert, Backspace, Delete, Left/Right, Home/End, Ctrl-A/E/B/F, Ctrl-U/K/W, Ctrl-L), history (Up/Down, Ctrl-P/N, bounded, exportable for persistence), reverse incremental search (Ctrl-R), and Tab completion through cobra's __complete (see Completer): a unique match is inserted with a trailing space (unless the directive says NoSpace), several are completed to their longest common prefix, a second Tab lists them in columns, or as "value -- description" lines when cobra gives descriptions, asking "Display all N possibilities? (y or n)" past a threshold. Completion understands the line's quoting.
ParseKeys turns terminal input (what xterm.js's onData delivers) into keys; Renderer turns successive States into ANSI output for a terminal. A widget can ignore both and use Key and State directly.
Index ¶
Constants ¶
const MaxLine = 4096
MaxLine bounds the line the splitter accepts.
Variables ¶
var ErrUnterminated = errors.New("unterminated quote or escape")
ErrUnterminated is returned for an open quote or a trailing backslash.
Functions ¶
func Format ¶
Format lays candidates out for a terminal cols wide: one aligned "value -- description" line each when any has a description (as zsh and fish show them), columns filled top to bottom otherwise (as bash).
Types ¶
type Completer ¶
type Completer func(ctx context.Context, words []string, current string) (cands []cli.Candidate, noSpace bool)
Completer lists the candidates for the word being typed: words are the complete words before it, current is its (unquoted) prefix. noSpace asks that a unique match get no trailing space.
type Editor ¶
type Editor struct {
// contains filtered or unexported fields
}
Editor is the line editor.
func (*Editor) SetHistory ¶
SetHistory replaces the history (a restored one), bounded. A restored history is untrusted (browser storage, a file): an entry that a user could not have typed — invalid UTF-8 or a non-printable rune, which the renderer would otherwise write to the terminal as is — is dropped.
type Event ¶
type Event struct {
// Submit is set when Enter ended a line; Line is that line.
Submit bool
Line string
// Print are lines to show above the prompt (a candidate listing, a
// question); the line is then shown again below them.
Print []string
// Interrupt is Ctrl-C on an empty or abandoned line ("^C").
Interrupt bool
// Clear is Ctrl-L: clear the screen, keep the line.
Clear bool
// EOF is Ctrl-D on an empty line.
EOF bool
// Bell is a key that did nothing (no completion, end of history).
Bell bool
}
Event is what a key did besides editing.
type Key ¶
Key is one key press.
type KeyCode ¶
type KeyCode int
KeyCode names a non-character key.
const ( KeyRune KeyCode = iota // a printable character, in Key.Rune KeyEnter KeyBackspace KeyDelete KeyLeft KeyRight KeyHome KeyEnd KeyUp KeyDown KeyTab KeyEscape KeyCtrlA KeyCtrlB KeyCtrlC KeyCtrlD KeyCtrlE KeyCtrlF KeyCtrlG KeyCtrlK KeyCtrlL KeyCtrlN KeyCtrlP KeyCtrlR KeyCtrlU KeyCtrlW KeyUnknown )
type Options ¶
type Options struct {
// Prompt is shown before the line (default "$ ").
Prompt string
// Complete answers Tab; nil disables completion.
Complete Completer
// HistorySize bounds the history (default 500).
HistorySize int
// Cols is the display width used for listings (default 80); SetCols
// changes it.
Cols int
}
Options configure an Editor.
type Partial ¶
type Partial struct {
// Words are the complete words before the one being typed.
Words []string
// Current is the word being typed, unquoted ("" for a new word).
Current string
// Start is the byte offset in the line where the current word begins.
Start int
// Quote is the quote the current word is still inside (' or "), or 0.
Quote byte
}
Partial is the line before the cursor, split for completion.
func SplitPartial ¶
SplitPartial splits a line prefix the way Split does, except that the last word may be unterminated (an open quote, a trailing backslash).
type Renderer ¶
type Renderer struct {
// Cols is the terminal width.
Cols int
// PromptStyle wraps the prompt (default bold cyan); "" for none.
PromptStyle string
// contains filtered or unexported fields
}
Renderer turns States into ANSI output for a terminal that does not wrap lines on its own behalf (xterm.js does: the renderer accounts for it). It assumes one column per rune.
func (*Renderer) Forget ¶
func (r *Renderer) Forget()
Forget drops what was rendered (the screen was cleared).
func (*Renderer) Leave ¶
Leave moves the cursor below the input (after Enter, Ctrl-C) and forgets it: the next Render starts a fresh prompt.
Source Files