README
¶
term
term is a modified version of the golang.org/x/term terminal/console
package.
Changes
- Split
MakeRawintoMakeRawInputandMakeRawOutput. - On Windows, support virtual key input processing.
- Added
PeekKeyfunction to peek at a single key press in the input buffer without consuming it. - Removed
ReadPasswordfunction. - Add additional ANSI color escape codes.
- Add a
HistoryTestCallbackfunction to support filtering lines out of input history. - Exposes VT100 escape codes directly as named variables (e.g.
term.Black,term.BrightBlue, etc.) - Improvements to handle break signals (ctrl-C).
Documentation
¶
Overview ¶
Package term provides support functions for dealing with terminals, as commonly found on UNIX systems.
Putting a terminal into raw mode is the most common requirement:
oldState, err := term.MakeRaw(int(os.Stdin.Fd()))
if err != nil {
panic(err)
}
defer term.Restore(int(os.Stdin.Fd()), oldState)
Note that on non-Unix systems os.Stdin.Fd() may not be 0.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( Black = string([]byte{keyEscape, '[', '3', '0', 'm'}) Red = string([]byte{keyEscape, '[', '3', '1', 'm'}) Green = string([]byte{keyEscape, '[', '3', '2', 'm'}) Yellow = string([]byte{keyEscape, '[', '3', '3', 'm'}) Blue = string([]byte{keyEscape, '[', '3', '4', 'm'}) Magenta = string([]byte{keyEscape, '[', '3', '5', 'm'}) Cyan = string([]byte{keyEscape, '[', '3', '6', 'm'}) White = string([]byte{keyEscape, '[', '3', '7', 'm'}) BrightBlack = string([]byte{keyEscape, '[', '9', '0', 'm'}) BrightRed = string([]byte{keyEscape, '[', '9', '1', 'm'}) BrightGreen = string([]byte{keyEscape, '[', '9', '2', 'm'}) BrightYellow = string([]byte{keyEscape, '[', '9', '3', 'm'}) BrightBlue = string([]byte{keyEscape, '[', '9', '4', 'm'}) BrightMagenta = string([]byte{keyEscape, '[', '9', '5', 'm'}) BrightCyan = string([]byte{keyEscape, '[', '9', '6', 'm'}) BrightWhite = string([]byte{keyEscape, '[', '9', '7', 'm'}) Reset = string([]byte{keyEscape, '[', '0', 'm'}) )
VT100 Escape codes
var ErrPasteIndicator = pasteIndicatorError{}
ErrPasteIndicator may be returned from ReadLine as the error, in addition to valid line data. It indicates that bracketed paste mode is enabled and that the returned line consists only of pasted data. Programs may wish to interpret pasted data more literally than typed data.
Functions ¶
func GetSize ¶
GetSize returns the visible dimensions of the given terminal.
These dimensions don't include any scrollback buffer height.
func IsTerminal ¶
IsTerminal returns whether the given file descriptor is a terminal.
Types ¶
type History ¶
type History interface {
// Add will be called by [Terminal.ReadLine] to add
// a new, most recent entry to the history.
// It is allowed to drop any entry, including
// the entry being added (e.g., if it's deemed an invalid entry),
// the least-recent entry (e.g., to keep the history bounded),
// or any other entry.
Add(entry string)
// Len returns the number of entries in the history.
Len() int
// At returns an entry from the history.
// Index 0 is the most-recently added entry and
// index Len()-1 is the least-recently added entry.
// If index is < 0 or >= Len(), it panics.
At(idx int) string
}
A History provides a (possibly bounded) queue of input lines read by Terminal.ReadLine.
type State ¶
type State struct {
// contains filtered or unexported fields
}
State contains the state of a terminal.
func GetState ¶
GetState returns the current state of a terminal which may be useful to restore the terminal after a signal.
func MakeRawInput ¶
MakeRawInput puts the terminal connected to the given file descriptor into raw input mode and returns the previous state of the terminal so that it can be restored.
func MakeRawOutput ¶
MakeRawOutput puts the terminal connected to the given file descriptor into raw output mode and returns the previous state of the terminal so that it can be restored.
type Terminal ¶
type Terminal struct {
// AutoCompleteCallback, if non-null, is called for each keypress with
// the full input line and the current position of the cursor (in
// bytes, as an index into |line|). If it returns ok=false, the key
// press is processed normally. Otherwise it returns a replacement line
// and the new cursor position.
AutoCompleteCallback func(line string, pos int, key rune) (newLine string, newPos int, ok bool)
// HistoryTestCallback, if non-null, is called before a line is added to
// the terminal's history buffer. If the line should be accepted into the
// history, the callback should return true.
HistoryTestCallback func(line string) (accept bool)
// History records and retrieves lines of input read by [ReadLine] which
// a user can retrieve and navigate using the up and down arrow keys.
//
// It is not safe to call ReadLine concurrently with any methods on
// History.
//
// [NewTerminal] sets this to a default implementation that records the
// last 100 lines of input.
History History
// contains filtered or unexported fields
}
Terminal contains the state for running a VT100 terminal that is capable of reading lines of input.
func NewTerminal ¶
func NewTerminal(c io.ReadWriter, prompt string) *Terminal
NewTerminal runs a VT100 terminal on the given ReadWriter. If the ReadWriter is a local terminal, that terminal must first have been put into raw mode. prompt is a string that is written at the start of each input line (i.e. "> ").
func (*Terminal) SetBracketedPasteMode ¶
SetBracketedPasteMode requests that the terminal bracket paste operations with markers. Not all terminals support this but, if it is supported, then enabling this mode will stop any autocomplete callback from running due to pastes. Additionally, any lines that are completely pasted will be returned from ReadLine with the error set to ErrPasteIndicator.
Source Files