term

README

Go terminal/console support

This repository provides Go terminal and console support packages.

Download/Install

The easiest way to install is to run go get -u golang.org/x/term. You can also manually git clone the repository to $GOPATH/src/golang.org/x/term.

Report Issues / Send Patches

This repository uses Gerrit for code changes. To learn how to submit changes to this repository, see https://golang.org/doc/contribute.html.

The main issue tracker for the term repository is located at https://github.com/golang/go/issues. Prefix your issue with "x/term:" in the subject line, so it is easy to find.

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

• Variables
• func GetSize(fd int) (width, height int, err error)
• func IsTerminal(fd int) bool
• func PeekKey(fd int, key rune) bool
• func Restore(fd int, oldState *State) error
• type State
  • func GetState(fd int) (*State, error)
  • func MakeRawInput(fd int) (*State, error)
  • func MakeRawOutput(fd int) (*State, error)
• type Terminal
  • func NewTerminal(c io.ReadWriter, prompt string) *Terminal
  • func (t *Terminal) ReadLine() (line string, err error)
  • func (t *Terminal) SetPrompt(prompt string)
  • func (t *Terminal) SetSize(width, height int) error
  • func (t *Terminal) Write(buf []byte) (n int, err error)

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

Functions

func GetSize

func GetSize(fd int) (width, height int, err error)

GetSize returns the visible dimensions of the given terminal.

These dimensions don't include any scrollback buffer height.

func IsTerminal

func IsTerminal(fd int) bool

IsTerminal returns whether the given file descriptor is a terminal.

func PeekKey

func PeekKey(fd int, key rune) bool

PeekKey scans the input buffer for the presence of a "key-down" event for the specified key character. Currently supported only on Windows.

func Restore

func Restore(fd int, oldState *State) error

Restore restores the terminal connected to the given file descriptor to a previous state.

Types

type State

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

State contains the state of a terminal.

func GetState

func GetState(fd int) (*State, error)

GetState returns the current state of a terminal which may be useful to restore the terminal after a signal.

func MakeRawInput

func MakeRawInput(fd int) (*State, error)

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

func MakeRawOutput(fd int) (*State, error)

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)
	// 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) ReadLine

func (t *Terminal) ReadLine() (line string, err error)

ReadLine returns a line of input from the terminal.

func (*Terminal) SetPrompt

func (t *Terminal) SetPrompt(prompt string)

SetPrompt sets the prompt to be used when reading subsequent lines.

func (*Terminal) SetSize

func (t *Terminal) SetSize(width, height int) error

func (*Terminal) Write

func (t *Terminal) Write(buf []byte) (n int, err error)