[feature] Public API for registering/removing key event callbacks

[kzhrv]

Hi, I’m integrating reeflective/readline into a shell that exposes programmable keypress events to users.

At the moment I can approximate this by rebinding key sequences through inputrc/keymaps and replaying the original bind, but that is adapter-heavy and not as trustworthy as a native hook.

Current issue

What I need is a frontend-level way to:

• observe a specific key sequence
• inspect a small editor state snapshot
• optionally modify the line/cursor/hint state
• optionally continue with the original key binding

Requested API

Something like:

type KeyEventState struct {
    Line        string
    CursorPos   int
    KeyPress    string
    InputMode   string
    PreviewMode string
}

type KeyEventResult struct {
    SetLine   []rune
    SetPos    int
    HintText  []rune
    Continue  bool
}

func (rl *Shell) AddKeyEvent(seq string, cb func(int, *KeyEventState) *KeyEventResult) error
func (rl *Shell) RemoveKeyEvent(seq string) error

Again, this is just an example shape.

Why this matters

This would allow integrations to support:

• programmable key bindings
• shell-defined key events
• editor-state-aware scripting/hooks

without having to patch keymaps indirectly.

Important point

I am not asking for your internals to mirror another library’s exact event model.
A small, stable, public key event hook would already remove a lot of adapter complexity.

[maxlandon]

Solved — without expanding the library's API, because the capability is already fully expressible in user code through the existing command + keymap primitives.

A "key event" is just a command of your own, bound to the sequence you care about. Inside it you:

• inspect a snapshot of editor state via the public accessors (rl.Line(), rl.Cursor(), rl.Keys.Caller(), rl.Keymap.Main()),
• modify the line/cursor/hint through the same setters,
• and "continue with the original binding" by looking up the command previously bound on that sequence and calling it (rl.Keymap.Commands()[name]).

We've documented exactly this in the Programmable Commands wiki page, under a new "Key-event callbacks" section. It includes a complete, drop-in helper that packages the pattern into precisely the shape you sketched:

func (k *KeyEvents) AddKeyEvent(seq string, cb func(arg int, state *KeyEventState) *KeyEventResult) error
func (k *KeyEvents) RemoveKeyEvent(seq string) error

with KeyEventState{Line, CursorPos, KeyPress, InputMode} and KeyEventResult{SetLine, SetPos, HintText, Continue} — observe a sequence, inspect state, optionally mutate line/cursor/hint, and optionally fall through to the original bind. RemoveKeyEvent restores the prior bind. The page also covers the practical details: inputrc.Unescape for sequences, registering into each keymap (emacs/vi-insert/vi-command) if users switch modes, re-injecting keys with rl.Keys.Feed(...) when the original bind was a macro, and reading further keys for multi-key gestures via rl.Keymap.PendingCursor().

Since this is pure user code, no library addition is warranted — a native hook wouldn't be more capable than the bound-command approach, and it would add surface we'd have to keep stable. Closing as resolved-by-documentation; the section ships with the v1.2.0 docs. Happy to refine the example if you hit a gap.

[kzhrv]

Cheers. Thank you for the understanding.