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/cogentcore/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 )
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 is the input prompt (ANSI escape sequences are supported on all platforms)
Prompt string
// HistoryFile is the path to the file where persistent history will be stored
// (empty string disables).
HistoryFile string
// HistoryLimit is the maximum number of history entries to store. If it is 0
// or unset, the default value is 500; set to -1 to disable.
HistoryLimit int
DisableAutoSaveHistory bool
// HistorySearchFold enables case-insensitive history searching.
HistorySearchFold bool
// AutoComplete defines the tab-completion behavior. See the documentation for
// the AutoCompleter interface for details.
AutoComplete AutoCompleter
// Listener is an optional callback to intercept keypresses.
Listener Listener
// Painter is an optional callback to rewrite the buffer for display.
Painter Painter
// FuncFilterInputRune is an optional callback to translate keyboard inputs;
// it takes in the input rune and returns (translation, ok). If ok is false,
// the rune is skipped.
FuncFilterInputRune func(rune) (rune, bool)
// VimMode enables Vim-style insert mode by default.
VimMode bool
InterruptPrompt string
EOFPrompt string
EnableMask bool
MaskRune rune
// Undo controls whether to maintain an undo buffer (if enabled,
// Ctrl+_ will undo the previous action).
Undo bool
// These fields allow customizing terminal handling. Most clients should ignore them.
Stdin io.Reader
Stdout io.Writer
Stderr io.Writer
FuncIsTerminal func() bool
FuncMakeRaw func() error
FuncExitRaw func() error
FuncGetSize func() (width int, height int)
FuncOnWidthChanged func(func())
// 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) 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 ¶
func (i *Instance) DisableHistory()
DisableHistory disables the saving of input lines in history.
func (*Instance) EnableHistory ¶
func (i *Instance) EnableHistory()
EnableHistory enables the saving of input lines in history.
func (*Instance) GeneratePasswordConfig ¶
GeneratePasswordConfig generates a suitable Config for reading passwords; this config can be modified and then used with ReadLineWithConfig, or SetConfig.
func (*Instance) ReadLine ¶
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 ¶
func (*Instance) ReadLineWithDefault ¶
func (*Instance) ResetHistory ¶
func (i *Instance) ResetHistory()
func (*Instance) SaveToHistory ¶
SaveToHistory adds a string to the instance's stored history. This is particularly relevant when DisableAutoSaveHistory is configured.
func (*Instance) SetDefault ¶
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. |