README
¶
Go terminal/console support
This repository provides Go terminal and console support packages. It's a fork of the golang.org/x/term pending approval of improvements upstream.
Download/Install
The easiest way to use is to run go get -u fortio.org/term.
Rather than use this lowlevel library, use fortio.org/terminal which wraps this one into a higher level and simpler more powerful API.
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
- Variables
- func GetSize(fd int) (width, height int, err error)
- func IsTerminal(fd int) bool
- func NewHistory(capacity int) *stRingBuffer
- func ReadPassword(fd int) ([]byte, error)
- func Restore(fd int, oldState *State) error
- type EscapeCodes
- type State
- type Terminal
- func (t *Terminal) AddToHistory(entry ...string)
- func (t *Terminal) AutoHistory(onOff bool)
- func (t *Terminal) History() []string
- func (t *Terminal) NewHistory(capacity int)
- func (t *Terminal) ReadLine() (line string, err error)
- func (t *Terminal) ReadPassword(prompt string) (line string, err error)
- func (t *Terminal) ReplaceLatest(entry string) string
- func (t *Terminal) SetBracketedPasteMode(on bool)
- func (t *Terminal) SetPrompt(prompt string)
- func (t *Terminal) SetSize(width, height int) error
- func (t *Terminal) Write(buf []byte) (n int, err error)
Constants ¶
const DefaultHistoryEntries = 100
DefaultHistoryEntries is the default number of entries in the history.
Variables ¶
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.
func NewHistory ¶
func NewHistory(capacity int) *stRingBuffer
Creates a new ring buffer of strings with the given capacity.
func ReadPassword ¶
ReadPassword reads a line of input from a terminal without local echo. This is commonly used for inputting passwords and other sensitive data. The slice returned does not include the \n.
Types ¶
type EscapeCodes ¶
type EscapeCodes struct {
// Foreground colors
Black, Red, Green, Yellow, Blue, Magenta, Cyan, White []byte
// Reset all attributes
Reset []byte
}
EscapeCodes contains escape sequences that can be written to the terminal in order to achieve different styles of text.
type State ¶
type State struct {
// contains filtered or unexported fields
}
State contains the state of a terminal.
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)
// Escape contains a pointer to the escape codes for this terminal.
// It's always a valid pointer, although the escape codes themselves
// may be empty if the terminal doesn't support them.
Escape *EscapeCodes
// 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) AddToHistory ¶
AddToHistory populates history.
func (*Terminal) AutoHistory ¶
AutoHistory sets whether lines are automatically added to the history before being returned by ReadLine() or not. Defaults to true.
func (*Terminal) History ¶
History returns a slice of strings containing the history of entered commands so far.
func (*Terminal) NewHistory ¶
NewHistory resets the history to one of a given capacity.
func (*Terminal) ReadPassword ¶
ReadPassword temporarily changes the prompt and reads a password, without echo, from the terminal.
func (*Terminal) ReplaceLatest ¶
ReplaceLatest replaces the most recent history entry with the given string. Enables to add invalid commands to the history for editing purpose and replace them with the corrected version. Returns the replaced entry.
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