smelt.keymap¶

Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.

Visibility: Public - Stable Lua API intended for user config and plugins.

Register chord→callback bindings and inspect the layered help index. Chords and modes are canonicalized at registration; unknown values raise immediately. UiHost-only.

smelt.keymap.help_sections¶

fun(): table

Return layered keybinding help as { title, entries = { { label, detail } } } rows. Filters vim-only chords when vim mode is disabled.

smelt.keymap.leader¶

fun(): string

Return the current <leader> expansion used when registering keymaps. Defaults to a single backslash (\).

smelt.keymap.list¶

fun(): table

Return the set of currently-bound { mode, chord, desc? } rows. mode is the canonical short form ("n"/"i"/"v"/""). chord is the display form after canonicalization and <leader> expansion.

smelt.keymap.prefixes¶

fun(pending: string, mode: string?): table

Return effective keymaps that extend pending in mode as { mode, chord, suffix, desc? } rows. pending may be empty to list top-level mappings, otherwise it is canonicalized with the current leader. mode accepts the same forms as set; when omitted, the focused Vim mode is used (or Normal outside an app). Mode-specific bindings shadow global bindings for the same chord.

smelt.keymap.set¶

fun(mode: string, chord: string, handler: fun(), opts: table?): smelt.Reg

Types: smelt.Reg

Bind chord in mode to a Lua callback. mode is "n"|"i"|"v"|"" (or the long form normal/insert/visual); the chord is canonicalized at registration and unknown values raise immediately. opts.desc is an optional one-line description used by keybinding help UIs. Re-binding the same (mode, chord) overwrites the prior handler. Returns a Reg whose :remove() drops the binding.

smelt.keymap.set_leader¶

fun(leader: string): nil

Set the <leader> expansion for subsequent keymap registrations. leader must be one canonicalizable key token, e.g. <space> or a single backslash (\). Existing keymaps keep the expansion they were registered with.

smelt.keymap.unset¶

fun(mode: string, chord: string): boolean

Drop the binding for chord in mode. mode accepts the same forms as set. Returns true if a binding was removed.