diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/helix-keys.md | 36 | ||||
| -rw-r--r-- | docs/selections.md | 22 |
2 files changed, 38 insertions, 20 deletions
diff --git a/docs/helix-keys.md b/docs/helix-keys.md index 90efc463..35f62765 100644 --- a/docs/helix-keys.md +++ b/docs/helix-keys.md @@ -7,10 +7,17 @@ checkout (`~/05-genizah/helix`); that checkout now sits on the local `pardes-harness` branch, whose three commits add only the harness, so `book/src/keymap.md` is byte-identical at its tip (694e7dfd). As of phase 5 every helix-equivalent row in A and B is differentially verified against real -helix (see "Differential testing" at the bottom). Five of the six waivers are -named in the row they belong to; the sixth, `wiX-edit-drops-sel`, belongs to no -single key — it is the anchor-only divergence every insert-mode edit shares — -and is described in the Files list at the bottom instead. +helix (see "Differential testing" at the bottom). Every waiver is named in the +row it belongs to. + +**The reference helix is fixed at one commit:** the `hx-harness` built from +`694e7dfdd` on the genizah checkout's `pardes-harness` branch, which is upstream +`278b24389` (2026-06-29, `25.07-905`) plus the three harness commits. "helix" +in this document means that build, not the 25.07.1 release, which differs on +counted `Alt-(`/`Alt-)` and on `&`. Upstream master was 82 commits further on +2026-09-28 (`079a789e`); of those only `416a0e09` (continuing a comment in an +injected `comment` layer) touches the editing code, and it needs tree-sitter, +which the harness runs without. Code map, by SYMBOL — line numbers rot, names do not. Body-normal key RECOGNITION is `modal.Normal` in `src/modal.zig`: a state machine over `Role` (one @@ -227,7 +234,7 @@ grew `sels` + `primary`, emitted only when there is more than one range. | `y` with several ranges | one value per range, pasted back value i at range i by `p`/`P`/`R` and insert `Ctrl-r`; the acme cut/paste chords and a paste into a terminal take the values joined by newlines | `Registers.zig` | helix-verified | | `"<reg>` | the next command's register: any character names one of its own. Computed ones: `_` swallows writes and reads nothing (`"_d`), `#` is each range's number from 1, `.` each range's text, `%` the file's name, `/` the last `s`/`S` pattern; `+`/`*` the system clipboard. A count typed before `"` stays the command's | helix `select_register` | helix-verified | | insert `Ctrl-r <reg>` | type this range's value of the register (`Ctrl-r #` numbers the cursors). Esc after `Ctrl-r` only cancels it. `Ctrl-r +` reads what pardes last put on the clipboard, not the desktop's | helix `insert_register` | helix-verified | -| `a` … `Esc` with several ranges | the primary's appended-over span is restored; the others collapse to bare cursors | `Pane.append_at` is a single field. Waived (`msel-append`) | waived | +| insert mode with a selection | every range is carried through each edit as helix maps it (`Range::map`): typing at the head of an `i` range slides it, typing at the end of an `a` range stretches it, Enter slides or stretches it by what the cursor moved, and an arrow key collapses it. Esc after `a` pulls each range's end back one character (helix `restore_cursor`) | `edit.insertKey`, `Text.restore_cursor` | helix-verified | | `&` | align selections into columns: the k-th range of each line is column k, and spaces go in before each range until its head reaches the column's widest head, in display cells (`File.rawDisplayCol`) | helix `align_selections` as of the harness's helix (25.07.1 grouped columns differently). A range over several lines refuses. A TAB counts as `tab_width` cells, not up to the next stop | helix-verified | | `Alt-)` / `Alt-(` / `<n>Alt-)` | rotate the CONTENTS of the selections forward / back by one range (n ranges), in one edit; each range comes back over the text it now holds and the primary moves with its text | helix `rotate_selection_contents_*` as of the harness's helix: 25.07.1 read the count as a GROUP size instead (rotate by one within each run of n ranges) and left the primary where it was, which is what helix-golf's `invert_dictionary_2` relies on | helix-verified | @@ -389,11 +396,11 @@ Files (all in `test/hxcases/`): (runs the `hx-harness` binary from the helix checkout; override with `$HX_HARNESS`). Only needed when cases change — the diff itself runs offline. -- `waivers.jsonl` — named exemptions, each with a reason. Three live ones: - `wiX-edit-drops-sel` and `msel-append` (helix maps selections through - insert-mode edits, pardes does not) and `alt-c-window-op` (the pardes - window op deliberately shadows helix change-noyank). `msel-yank-paste` - went with registers of one value per range; `sel-regex-caret` and +- `waivers.jsonl` — named exemptions, each with a reason. One live one: + `alt-c-window-op` (the pardes window op deliberately shadows helix + change-noyank). `wiX-edit-drops-sel` and `msel-append` went when insert + mode began carrying every range through its edits, `msel-yank-paste` with + registers of one value per range, `sel-regex-caret` and `sel-regex-dot-newline` when `s`/`S` began searching line by line. - `parity.jsonl` — 80 further cases, used only by the parity gate below. - `parity-waivers.jsonl` — 14 named exemptions for the parity gate, in three @@ -412,10 +419,11 @@ Files (all in `test/hxcases/`): tested when an earlier one misses. The goldens are `hx-harness test/hxcases/golf.jsonl`; `zig build hxgolf` runs them. All ten examples reproduce their published result in hx 25.07.1 under the site's own conditions (a file of the example's language, auto-pairs - on). Under the harness pins two do not: `csv_to_sql` needs auto-pairs to - close its `VALUES (`, and `invert_dictionary_2` needs 25.07's - `<count>Alt-(` (rotate within groups of count) where the harness's newer - helix rotates by count. + on). Under the harness two do not, and their goldens are the harness's + anyway, which pardes follows: `csv_to_sql` needs auto-pairs (off in the + harness and absent in pardes) to close its `VALUES (`, and + `invert_dictionary_2` needs 25.07.1's `<count>Alt-(` (rotate within groups + of count) where the reference helix rotates by count. - `smoke.jsonl` — 20 cases referenced by nothing in the tree: no build step, no script. Either wire it up or delete it. diff --git a/docs/selections.md b/docs/selections.md index 0f000e2c..c08ccb14 100644 --- a/docs/selections.md +++ b/docs/selections.md @@ -3,6 +3,8 @@ How normal mode holds and changes its selections, and where that differs from helix's `Selection` (a list of ranges over gap offsets, with a primary index). Key-by-key behaviour is in docs/helix-keys.md; this is the model underneath. +"helix" here is the reference build docs/helix-keys.md names: `hx-harness` +at `694e7dfdd`, upstream `278b24389`. ## What a selection is @@ -25,8 +27,9 @@ plus up to 63 others. `s`, `n`/`N`, ...) rather than left behind by a motion. Only pardes reads it: the look (Enter) and execute (Tab) chords act on explicit selections and on the word under the cursor otherwise. -- `select` is `v` extend mode. `append_at` remembers where an `a` began, so - Esc can give back the range it appended over. +- `select` is `v` extend mode. `restore_cursor` says the insert session + began with `a`, so Esc gives each range back the character it was + stretched by. `Text.setRanges` is the one writer of a whole selection: it sorts by start, merges ranges that overlap or share a start (helix `normalize`), follows the @@ -67,6 +70,17 @@ A parsed action has a scope (`modal.Normal.Action.scope`). look) runs once from the primary and drops back to one cursor (`normal.multiOnce`). +## Insert mode + +Each range lives on through insert mode. Every insert-mode edit happens at +the cursor, so `edit.insertKey` runs it on the bare cursor and then carries +the range through what it did to the text, with helix's `Range::map` rules: +at an insertion, a backward range's head and an empty range move past it +and a forward range's head stays before it, so typing slides an `i` range +and stretches an `a` range. Enter slides or stretches the range by what the +cursor moved; an arrow key collapses it. The other ranges get the same by +the replay. + ## Undo, registers, repeat - One keystroke is one undo step however many ranges it edited: only the @@ -86,10 +100,6 @@ A parsed action has a scope (`modal.Normal.Action.scope`). ## Where it differs from helix -- Insert mode: helix maps every range through each keystroke's edit, so a - range an `i`/`a` started from stretches over what is typed and keeps its - anchor. Here only the cursor cells move, and after Esc only the primary's - `append_at` span comes back (waivers `wiX-edit-drops-sel`, `msel-append`). - Direction of a one-character range: both of its cells are the same cell, so it has none. helix can flip one (`Alt-;`) and the commands that read the head (`&`, the next extend) see the difference. |