README
¶
Readline Bindings
This is a set of bindings to the GNU Readline Library.
The existing readline bindings for Go are more limited than this library, if you can believe it.
Note that the return type of String() has changed.
It was
func String(prompt string) string
and it's now
func String(prompt string) (string, error)
Installing the library
To install the library in order to use it, type:
go get github.com/bobappleyard/readline
You may need to be root.
For Mac OS X users, you may see errors like rl_catch_sigwinch undeclared. If so, you need to install GNU Readline via Homebrew:
brew install readline
On Mac OS X, if you encounter errors like these:
> go get github.com/bobappleyard/readline
# github.com/bobappleyard/readline
readline.go:38:19: error: stdio.h: No such file or directory
readline.go:39:20: error: stdlib.h: No such file or directory
In file included from /usr/local/opt/readline/include/readline/keymaps.h:35,
from /usr/local/opt/readline/include/readline/readline.h:37,
from readline.go:40:
/usr/local/opt/readline/include/readline/chardefs.h:25:19: error: ctype.h: No such file or directory
/usr/local/opt/readline/include/readline/chardefs.h:38:22: error: string.h: No such file or directory
In file included from readline.go:41:
/usr/local/opt/readline/include/readline/history.h:29:58: error: time.h: No such file or directory
You need to install "Command Line Tools" which can be done in XCode > Preferences > Downloads.
To install the library in order to hack on it, type
git clone git://github.com/bobappleyard/readline.git
Using the library
import "github.com/bobappleyard/readline"
These bindings provide access to three basic features of Readline:
- Getting text from a prompt (via the String() and Reader() functions).
- Managing the prompt's history (via the AddHistory(), GetHistory(), ClearHistory() and HistorySize() functions).
- Controlling tab completion (via the Completer variable).
An example of the library's use:
package main
import (
"io"
"fmt"
"github.com/bobappleyard/readline"
)
func main() {
for {
l, err := readline.String("> ")
if err == io.EOF {
break
}
if err != nil {
fmt.Println("error: ", err)
break
}
fmt.Println(l)
readline.AddHistory(l)
}
}
Documentation
¶
Overview ¶
This package provides access to basic GNU Readline functions. Currently supported are:
- getting text from a prompt (via the String() and NewReader() functions).
- managing the prompt's history (via the AddHistory(), GetHistory(), ClearHistory() and HistorySize() functions).
- controlling tab completion (via the Completer variable).
Here is a simple example:
package main
import (
"fmt"
"io"
"github.com/bobappleyard/readline"
)
func main() {
for {
l, err := readline.String("> ")
if err == io.EOF {
break
}
if err != nil {
fmt.Println("error: ", err)
break
}
fmt.Println(l)
readline.AddHistory(l)
}
}
Index ¶
- Variables
- func AddHistory(s string)
- func Cleanup()
- func ClearHistory()
- func ClearScreen()
- func FilenameCompleter(query, ctx string) []string
- func ForceUpdateDisplay()
- func GetHistory(i int) string
- func HistorySize() int
- func LoadHistory(path string) error
- func NewReader() io.Reader
- func RefreshLine()
- func ReplaceLine(text string, clearUndo int)
- func SaveHistory(path string) error
- func SetWordBreaks(cs string)
- func String(prompt string) (string, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var Completer = func(query, ctx string) []string { return nil }
This function provides entries for the tab completer.
var CompletionAppendChar = 0
If CompletionAppendChar is non-zero, readline will append the corresponding character to the prompt after each completion. A typical value would be a space.
var Continue = ".."
The continue prompt used by Reader(). The prompt can contain ANSI escape sequences, they will be escaped as necessary.
var Prompt = "> "
The prompt used by Reader(). The prompt can contain ANSI escape sequences, they will be escaped as necessary.
Functions ¶
func Cleanup ¶
func Cleanup()
Cleanup() frees internal memory and restores terminal attributes. This function should be called when program execution stops before the return of a String() call, so as not to leave the terminal in a corrupted state.
Example ¶
package main
import (
"fmt"
"github.com/bobappleyard/readline"
"os"
"os/signal"
"syscall"
)
func main() {
sigint := make(chan os.Signal, 1)
signal.Notify(sigint, syscall.SIGINT)
readline.CatchSigint = false
var line string
var err error
done := make(chan struct{})
go func() {
line, err = readline.String("> ")
close(done)
}()
select {
case <-sigint:
fmt.Println("\nInterrupted")
// Restore terminal attributes
readline.Cleanup()
// Note that we still have a goroutine reading from Stdin that
// will terminate when we exit.
os.Exit(1)
case <-done:
fmt.Printf("Read line %s, error %v\n", line, err)
}
}
Output:
func FilenameCompleter ¶
This function can be assigned to the Completer variable to use readline's default filename completion, or it can be called by a custom completer function to get a list of files and filter it.
func NewReader ¶
Begin reading lines. If more than one line is required, the continue prompt is used for subsequent lines.
func SetWordBreaks ¶
func SetWordBreaks(cs string)
Types ¶
This section is empty.
Source Files