terminal

README

terminal

Fortio's terminal is a readline style library. It handles prompts, edit (like Ctrl-A for beginning of line etc...), navigating through history using arrow keys, loading and saving history from file, etc... It works on everywhere go does (including macOS, Windows (using Terminal app), Linux).

See example/main.go for a rather complete example/demo.

See the godoc above for details.

The grol command line repl and others use this.

The implementations currently is a wrapper fully encapsulating (our fork of) x/term, i.e. fortio.org/term

Documentation

Overview

Library to interact with ansi/v100 style terminals.

Index

• Constants
• type AutoCompleteCallback
• type Terminal
  • func Open() (*Terminal, error)
  • func (t *Terminal) AddToHistory(commands ...string)
  • func (t *Terminal) AutoHistory() bool
  • func (t *Terminal) Close() error
  • func (t *Terminal) History() []string
  • func (t *Terminal) IsTerminal() bool
  • func (t *Terminal) NewHistory(capacity int)
  • func (t *Terminal) ReadLine() (string, error)
  • func (t *Terminal) ReplaceLatest(command string) string
  • func (t *Terminal) SetAutoCompleteCallback(f AutoCompleteCallback)
  • func (t *Terminal) SetAutoHistory(enabled bool)
  • func (t *Terminal) SetHistoryFile(f string) error
  • func (t *Terminal) SetPrompt(s string)

Constants

const DefaultHistoryCapacity = term.DefaultHistoryEntries

DefaultHistoryCapacity is the default number of entries in the history (99).

Types

type AutoCompleteCallback

type AutoCompleteCallback func(t *Terminal, line string, pos int, key rune) (newLine string, newPos int, ok bool)

AutoCompleteCallback is called with "this" terminal as first argument so AutoCompleteCallback can use t.Out etc. (compared to the original x/term callback).

type Terminal

type Terminal struct {
	// Use this for any output to the screen/console so the required \r are added in raw mode
	// the prompt and command edit is refresh as needed when input comes in.
	Out io.Writer
	// contains filtered or unexported fields
}

func Open

func Open() (*Terminal, error)

Open opens stdin as a terminal, do `defer terminal.Close()` to restore the terminal to its original state upon exit. fortio.org/log (and thus stdlib "log") will be redirected to the terminal in a manner that preserves the prompt.

func (*Terminal) AddToHistory

func (t *Terminal) AddToHistory(commands ...string)

AddToHistory add commands to the history.

func (*Terminal) AutoHistory

func (t *Terminal) AutoHistory() bool

AutoHistory returns the current auto history setting.

func (*Terminal) Close

func (t *Terminal) Close() error

Close restores the terminal to its original state. Must be called at exit to avoid leaving the terminal in raw mode. Safe to call multiple times. Will save the history to the history file if one was set using [SetHistoryFile] and the capacity is > 0.

func (*Terminal) History

func (t *Terminal) History() []string

History returns the current history state.

func (*Terminal) IsTerminal

func (t *Terminal) IsTerminal() bool

func (*Terminal) NewHistory

func (t *Terminal) NewHistory(capacity int)

NewHistory creates/resets the history to a new one with the given capacity. Using 0 as capacity will disable history reading and writing but not change the underlying history state from it's DefaultHistoryCapacity.

func (*Terminal) ReadLine

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

ReadLine reads a line from the terminal using the setup prompt and history and edit capabilities. Returns the line and an error if any. io.EOF is returned when the user presses ^D or ^C.

func (*Terminal) ReplaceLatest

func (t *Terminal) ReplaceLatest(command string) string

ReplaceLatest replaces the current history with the given commands, returns the previous value.

func (*Terminal) SetAutoCompleteCallback

func (t *Terminal) SetAutoCompleteCallback(f AutoCompleteCallback)

SetAutoCompleteCallback sets the callback called for each key press. Can be used to implement auto completion. See example/main.go for an example.

func (*Terminal) SetAutoHistory

func (t *Terminal) SetAutoHistory(enabled bool)

SetAutoHistory enables/disables auto history (default is enabled).

func (*Terminal) SetHistoryFile

func (t *Terminal) SetHistoryFile(f string) error

Sets up a file to load and save history from/to. File is being read when this is called. If no error is returned, the file will also be automatically updated on Close().

func (*Terminal) SetPrompt

func (t *Terminal) SetPrompt(s string)

Sets or change the prompt.