Module keymap 

What a keypress means: one table, and the chain that reads it.

Deliberately close to pua’s

pua is a rollup tree over processes and this is a rollup tree over directories, so the two should feel like siblings: j/k, ←/→, *, z, g/G, s/S, /, ?, q and Esc all mean here exactly what they mean there, and this file is a rewrite of pua’s tui/keymap.rs rather than an independent invention.

It diverges exactly where the verbs do. pua kills one process and needs a key that asks before signalling; pristine marks a subtree and then commits a batch, which is two verbs rather than one. space marks (npkill’s key for the same idea), a marks or clears everything, and x — pua’s one key that writes — commits what is marked. The keys pua spends on sampling (space freezes, r re-samples) are free here, because a directory tree does not tick.

Why a table rather than a match

Three things have to agree about the keymap and drift apart the moment any of them is written by hand: the dispatcher, the help overlay and the footer. [KEYMAP] is the single statement of what is bound and all three read it, so a key that does something is a key the help page documents by construction.

Routing is a chain of surfaces

Overlay first, then the tree, then the globals. Spelled as a list of Surfaces rather than as branches in the dispatcher because of the guarantee attached to it: the tree can never shadow a global key, which is one assertion over the table rather than a property somebody has to keep noticing. An overlay is modal by omission — while one is up the chain simply does not contain the tree.

The pointer is a second table, for the same reason

[POINTER] is to a mouse event what [KEYMAP] is to a keystroke, and it is a table for the argument written above rather than by analogy: the dispatcher, the help overlay and the guarantee that no gesture acts undocumented all read it. What it does not need is the chain — a press has coordinates, so “which surface is this” is answered by super::render::hit geometrically, and restating the order here would be two rules that have to agree.

Structs

Binding

One row of the keymap: the keys that do a thing, and what the thing is.

Chord

One key, with the modifier that distinguishes it from the bare version.

Pointing

One row of the pointer map: a gesture, where it lands, and what it does there.

Enums

Action

What a keypress asked for.

Gesture

What the loop has judged one mouse event to be.

Motion

Where a motion key wants the cursor.

Overlay

Which overlay is up, if any.

Surface

Which layer of the screen a binding belongs to.

Target

What a gesture landed on, as the table names it — a Spot with the identity taken out.

Turn

Which way round a cycle goes.

Functions

action_for

What one terminal event means, here and now.

bindings

The whole keymap, for anything that renders or checks it.

chain

The surfaces a key is offered to, in order.

finish

Letting go of a press that never moved — the click.

help

The help page, as headed groups of (keys, sentence).

pointer

What one mouse gesture means, given what it landed on.

pointing

The whole pointer map, for anything that renders or checks it.