README
¶
readline
This is a pure Go implementation of functionality comparable to GNU Readline, i.e. line editing and command history for simple TUI programs.
It is a fork of chzyer/readline.
- Relative to the upstream repository, it is actively maintained and has numerous bug fixes
- See our changelog for details on fixes and improvements
- See our migration guide for advice on how to migrate from upstream
- Relative to x/term, it has more features (e.g. tab-completion)
- In use by multiple projects: gopass, fq, and ircdog
package main
import (
"fmt"
"log"
"github.com/ergochat/readline"
)
func main() {
// see readline.NewFromConfig for advanced options:
rl, err := readline.New("> ")
if err != nil {
log.Fatal(err)
}
defer rl.Close()
log.SetOutput(rl.Stderr()) // redraw the prompt correctly after log output
for {
line, err := rl.ReadLine()
// `err` is either nil, io.EOF, readline.ErrInterrupt, or an unexpected
// condition in stdin:
if err != nil {
return
}
// `line` is returned without the terminating \n or CRLF:
fmt.Fprintf(rl, "you wrote: %s\n", line)
}
}
Documentation
¶
Index ¶
- Constants
- Variables
- type AutoCompleter
- type Config
- type Instance
- func (i *Instance) CaptureExitSignal()
- func (i *Instance) ClearScreen()
- func (i *Instance) Close() error
- func (i *Instance) DisableHistory()
- func (i *Instance) EnableHistory()
- func (i *Instance) GeneratePasswordConfig() *Config
- func (i *Instance) GetConfig() *Config
- func (i *Instance) IsVimMode() bool
- func (i *Instance) ReadLine() (string, error)
- func (i *Instance) ReadLineWithConfig(cfg *Config) (string, error)
- func (i *Instance) ReadLineWithDefault(defaultValue string) (string, error)
- func (i *Instance) ReadPassword(prompt string) ([]byte, error)
- func (i *Instance) ReadSlice() ([]byte, error)
- func (i *Instance) Readline() (string, error)
- func (i *Instance) Refresh()
- func (i *Instance) ResetHistory()
- func (i *Instance) SaveToHistory(content string) error
- func (i *Instance) SetConfig(cfg *Config) error
- func (i *Instance) SetDefault(defaultValue string)
- func (i *Instance) SetPrompt(s string)
- func (i *Instance) SetVimMode(on bool)
- func (i *Instance) Stderr() io.Writer
- func (i *Instance) Stdout() io.Writer
- func (i *Instance) Write(b []byte) (int, error)
- type Listener
- type Painter
- type PrefixCompleter
Constants ¶
const ( CharLineStart = 1 CharBackward = 2 CharInterrupt = 3 CharEOT = 4 CharLineEnd = 5 CharForward = 6 CharBell = 7 CharCtrlH = 8 CharTab = 9 CharCtrlJ = 10 CharKill = 11 CharCtrlL = 12 CharEnter = 13 CharNext = 14 CharPrev = 16 CharBckSearch = 18 CharFwdSearch = 19 CharTranspose = 20 CharCtrlU = 21 CharCtrlW = 23 CharCtrlY = 25 CharCtrlZ = 26 CharEsc = 27 CharCtrl_ = 31 CharO = 79 CharEscapeEx = 91 CharBackspace = 127 )
const ( MetaBackward rune = -iota - 1 MetaForward MetaDelete MetaBackspace MetaTranspose MetaShiftTab MetaDeleteKey )
const ( VIM_NORMAL = iota VIM_INSERT VIM_VISUAL )
Variables ¶
var (
ErrInterrupt = errors.New("Interrupt")
)
var NewEx = NewFromConfig
NewEx is an alias for NewFromConfig, for compatibility.
Functions ¶
This section is empty.
Types ¶
type AutoCompleter ¶
type AutoCompleter interface {
// Readline will pass the whole line and current offset to it
// Completer need to pass all the candidates, and how long they shared the same characters in line
// Example:
// [go, git, git-shell, grep]
// Do("g", 1) => ["o", "it", "it-shell", "rep"], 1
// Do("gi", 2) => ["t", "t-shell"], 2
// Do("git", 3) => ["", "-shell"], 3
Do(line []rune, pos int) (newLine [][]rune, length int)
}
type Config ¶
type Config struct {
// prompt supports ANSI escape sequence, so we can color some characters even in windows
Prompt string
// readline will persist historys to file where HistoryFile specified
HistoryFile string
// specify the max length of historys, it's 500 by default, set it to -1 to disable history
HistoryLimit int
DisableAutoSaveHistory bool
// enable case-insensitive history searching
HistorySearchFold bool
// AutoCompleter will called once user press TAB
AutoComplete AutoCompleter
// Listener is an optional callback to intercept keypresses.
Listener Listener
Painter Painter
// If VimMode is true, readline will in vim.insert mode by default
VimMode bool
InterruptPrompt string
EOFPrompt string
// Function that returns width, height of the terminal or -1,-1 if unknown
FuncGetSize func() (width int, height int)
Stdin io.Reader
Stdout io.Writer
Stderr io.Writer
EnableMask bool
MaskRune rune
// Whether to maintain an undo buffer (Ctrl+_ to undo if enabled)
Undo bool
// filter input runes (may be used to disable CtrlZ or for translating some keys to different actions)
// -> output = new (translated) rune and true/false if continue with processing this one
FuncFilterInputRune func(rune) (rune, bool)
// force use interactive even stdout is not a tty
FuncIsTerminal func() bool
FuncMakeRaw func() error
FuncExitRaw func() error
FuncOnWidthChanged func(func())
ForceUseInteractive bool
// contains filtered or unexported fields
}
type Instance ¶
type Instance struct {
// contains filtered or unexported fields
}
func NewFromConfig ¶
NewFromConfig creates a readline instance from the specified configuration.
func (*Instance) CaptureExitSignal ¶
func (i *Instance) CaptureExitSignal()
CaptureExitSignal registers handlers for common exit signals that will close the readline instance.
func (*Instance) ClearScreen ¶ added in v0.0.6
func (i *Instance) ClearScreen()
ClearScreen clears the screen.
func (*Instance) Close ¶
Close() closes the readline instance, cleaning up state changes to the terminal. It interrupts any concurrent Readline() operation, so it can be asynchronously or from a signal handler. It is concurrency-safe and idempotent, so it can be called multiple times.
func (*Instance) DisableHistory ¶ added in v0.0.4
func (i *Instance) DisableHistory()
DisableHistory disables the saving of input lines in history.
func (*Instance) EnableHistory ¶ added in v0.0.4
func (i *Instance) EnableHistory()
EnableHistory enables the saving of input lines in history.
func (*Instance) GeneratePasswordConfig ¶ added in v0.0.4
GeneratePasswordConfig generates a suitable Config for reading passwords; this config can be modified and then used with ReadLineWithConfig, or SetConfig.
func (*Instance) ReadLine ¶ added in v0.0.4
ReadLine reads a line from the configured input source, allowing inline editing. The returned error is either nil, io.EOF, or readline.ErrInterrupt.
func (*Instance) ReadLineWithConfig ¶ added in v0.0.4
func (*Instance) ReadLineWithDefault ¶ added in v0.0.4
func (*Instance) ResetHistory ¶
func (i *Instance) ResetHistory()
func (*Instance) SaveToHistory ¶ added in v0.0.4
SaveToHistory adds a string to the instance's stored history. This is particularly relevant when DisableAutoSaveHistory is configured.
func (*Instance) SetDefault ¶ added in v0.0.3
SetDefault prefills a default value for the next call to Readline() or related methods. The value will appear after the prompt for the user to edit, with the cursor at the end of the line.
type Listener ¶
Listener is a callback type to listen for keypresses while the line is being edited. It is invoked initially with (nil, 0, 0), and then subsequently for any keypress until (but not including) the newline/enter keypress that completes the input.
type Painter ¶
Painter is a callback type to allow modifying the buffer before it is rendered on screen, for example, to implement real-time syntax highlighting.
type PrefixCompleter ¶
type PrefixCompleter struct {
// Name is the name of a command, subcommand, or argument eligible for completion.
Name string
// Callback is optional; if defined, it takes the current line and returns
// a list of possible completions associated with the current node (i.e.
// in place of Name).
Callback func(string) []string
// Children is a list of possible completions that can follow the current node.
Children []*PrefixCompleter
// contains filtered or unexported fields
}
PrefixCompleter implements AutoCompleter via a recursive tree.
func NewPrefixCompleter ¶
func NewPrefixCompleter(pc ...*PrefixCompleter) *PrefixCompleter
func PcItem ¶
func PcItem(name string, pc ...*PrefixCompleter) *PrefixCompleter
func PcItemDynamic ¶
func PcItemDynamic(callback func(string) []string, pc ...*PrefixCompleter) *PrefixCompleter
func (*PrefixCompleter) Do ¶
func (p *PrefixCompleter) Do(line []rune, pos int) (newLine [][]rune, offset int)
func (*PrefixCompleter) SetChildren ¶
func (p *PrefixCompleter) SetChildren(children []*PrefixCompleter)
func (*PrefixCompleter) Tree ¶
func (p *PrefixCompleter) Tree(prefix string) string
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
example
|
|
|
readline-pass-strength
This is a small example using readline to read a password and check it's strength while typing using the zxcvbn library.
|
This is a small example using readline to read a password and check it's strength while typing using the zxcvbn library. |
|
internal
|
|
|
term
Package term provides support functions for dealing with terminals, as commonly found on UNIX systems.
|
Package term provides support functions for dealing with terminals, as commonly found on UNIX systems. |