go-keybind

Key-binding config for Go TUI apps. Parse and normalize key strings, load/save JSON keybind files with merge-with-defaults semantics, validate for intra-area conflicts.

Go Version Go Reference GitHub release (latest by date) CI License: MIT

Install

go get github.com/floatpane/go-keybind

Usage

Parse and compare key strings

k, err := keybind.Parse("ctrl+shift+a")
// k.Ctrl = true, k.Shift = true, k.Base = "a"
// k.String() = "ctrl+shift+a"
// Aliases normalize to the same Key:
a, _ := keybind.Parse("escape")
b, _ := keybind.Parse("esc")
fmt.Println(a == b) // true
// Modifier order doesn't matter in input:
c, _ := keybind.Parse("shift+ctrl+a")
d, _ := keybind.Parse("ctrl+shift+a")
fmt.Println(c == d) // true

Load a keybind config from disk

type MyKeys struct {
 Quit string `json:"quit"`
 Reload string `json:"reload"`
 NavUp string `json:"nav_up"`
}
cfg, err := keybind.Load(cfgDir, "keybinds.json", MyKeys{
 Quit: "ctrl+c",
 Reload: "r",
 NavUp: "k",
})
// If keybinds.json didn't exist it was created with the defaults.
// Fields absent from an existing file keep their default values.

Validate for conflicts

conflicts := keybind.Validate(map[string]map[string]string{
 "global": {"quit": cfg.Quit, "reload": cfg.Reload},
 "nav": {"up": cfg.NavUp, "down": cfg.NavDown},
})
// Cross-area duplicates ("d" for delete in two different views) are fine.
// Only intra-area conflicts (two actions bound to the same key) are reported.

Use in a TUI event loop

quitKey := keybind.MustParse(cfg.Quit) // panics on bad config value
// In your event handler:
if event.String() == quitKey.String() {
 return tea.Quit
}

Supported keys

Documentation

Sister projects

Contributing

Security

License