@@ -1,22 +1,43 @@
1−# Usage
1+# Using Helix
22
3−(Currently not fully documented, see the [keymappings](./keymap.md) list for more.)
3+<!--toc:start-->
4+- [Registers](#registers)
5+ - [User-defined registers](#user-defined-registers)
6+ - [Special registers](#special-registers)
7+- [Surround](#surround)
8+- [Selecting and manipulating text with textobjects](#selecting-and-manipulating-text-with-textobjects)
9+- [Navigating using tree-sitter textobjects](#navigating-using-tree-sitter-textobjects)
10+- [Moving the selection with syntax-aware motions](#moving-the-selection-with-syntax-aware-motions)
11+<!--toc:end-->
412
5−See [tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) (accessible via `hx --tutor` or `:tutor`) for a vimtutor-like introduction.
13+For a full interactive introduction to Helix, refer to the
14+[tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) which
15+can be accessed via the command `hx --tutor` or `:tutor`.
16+
17+> 💡 Currently, not all functionality is fully documented, please refer to the
18+> [key mappings](./keymap.md) list.
619
720## Registers
821
9−Vim-like registers can be used to yank and store text to be pasted later. Usage is similar, with `"` being used to select a register:
22+In Helix, registers are storage locations for text and other data, such as the
23+result of a search. Registers can be used to cut, copy, and paste text, similar
24+to the clipboard in other text editors. Usage is similar to Vim, with `"` being
25+used to select a register.
26+
27+### User-defined registers
28+
29+Helix allows you to create your own named registers for storing text, for
30+example:
1031
1132- `"ay` - Yank the current selection to register `a`.
1233- `"op` - Paste the text in register `o` after the selection.
1334
14−If there is a selected register before invoking a change or delete command, the selection will be stored in the register and the action will be carried out:
35+If a register is selected before invoking a change or delete command, the selection will be stored in the register and the action will be carried out:
1536
1637- `"hc` - Store the selection in register `h` and then change it (delete and enter insert mode).
1738- `"md` - Store the selection in register `m` and delete it.
1839
19−### Special Registers
40+### Special registers
2041
2142| Register character | Contains |
2243| --- | --- |
@@ -25,41 +46,90 @@ If there is a selected register before invoking a change or delete command, the
2546| `"` | Last yanked text |
2647| `_` | Black hole |
2748
28−> There is no special register for copying to system clipboard, instead special commands and keybindings are provided. See the [keymap](keymap.md#space-mode) for the specifics.
29−> The black hole register works as a no-op register, meaning no data will be written to / read from it.
49+The system clipboard is not directly supported by a special register. Instead, special commands and keybindings are provided. Refer to the
50+[key map](keymap.md#space-mode) for more details.
51+
52+The black hole register is a no-op register, meaning that no data will be read or written to it.
3053
3154## Surround
3255
33−Functionality similar to [vim-surround](https://github.com/tpope/vim-surround) is built into
34−helix. The keymappings have been inspired from [vim-sandwich](https://github.com/machakann/vim-sandwich):
56+Helix includes built-in functionality similar to [vim-surround](https://github.com/tpope/vim-surround).
57+The keymappings have been inspired from [vim-sandwich](https://github.com/machakann/vim-sandwich):
3558
36−
59+
3760
38−- `ms` - Add surround characters
39−- `mr` - Replace surround characters
40−- `md` - Delete surround characters
61+| Key Sequence | Action |
62+| --------------------------------- | --------------------------------------- |
63+| `ms<char>` (after selecting text) | Add surround characters to selection |
64+| `mr<char_to_replace><new_char>` | Replace the closest surround characters |
65+| `md<char_to_delete>` | Delete the closest surround characters |
4166
42−`ms` acts on a selection, so select the text first and use `ms<char>`. `mr` and `md` work
43−on the closest pairs found and selections are not required; use counts to act in outer pairs.
67+You can use counts to act on outer pairs.
4468
45−It can also act on multiple selections (yay!). For example, to change every occurrence of `(use)` to `[use]`:
69+Surround can also act on multiple selections. For example, to change every occurrence of `(use)` to `[use]`:
4670
47−- `%` to select the whole file
48−- `s` to split the selections on a search term
49−- Input `use` and hit Enter
50−- `mr([` to replace the parens with square brackets
71+1. `%` to select the whole file
72+2. `s` to split the selections on a search term
73+3. Input `use` and hit Enter
74+4. `mr([` to replace the parentheses with square brackets
5175
52−Multiple characters are currently not supported, but planned.
76+Multiple characters are currently not supported, but planned for future release.
5377
54−## Syntax-tree Motions
78+## Selecting and manipulating text with textobjects
5579
56−`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) move the primary
57−selection according to the selection's place in the syntax tree. Let's walk
58−through an example to get familiar with them. Many languages have a syntax like
59−so for function calls:
80+In Helix, textobjects are a way to select, manipulate and operate on a piece of
81+text in a structured way. They allow you to refer to blocks of text based on
82+their structure or purpose, such as a word, sentence, paragraph, or even a
83+function or block of code.
6084
61−```
62−func(arg1, arg2, arg3)
85+
86+
87+
88+- `ma` - Select around the object (`va` in Vim, `<alt-a>` in Kakoune)
89+- `mi` - Select inside the object (`vi` in Vim, `<alt-i>` in Kakoune)
90+
91+| Key after `mi` or `ma` | Textobject selected |
92+| --- | --- |
93+| `w` | Word |
94+| `W` | WORD |
95+| `p` | Paragraph |
96+| `(`, `[`, `'`, etc. | Specified surround pairs |
97+| `m` | The closest surround pair |
98+| `f` | Function |
99+| `c` | Class |
100+| `a` | Argument/parameter |
101+| `o` | Comment |
102+| `t` | Test |
103+| `g` | Change |
104+
105+> 💡 `f`, `c`, etc. need a tree-sitter grammar active for the current
106+document and a special tree-sitter query file to work properly. [Only
107+some grammars][lang-support] currently have the query file implemented.
108+Contributions are welcome!
109+
110+## Navigating using tree-sitter textobjects
111+
112+Navigating between functions, classes, parameters, and other elements is
113+possible using tree-sitter and textobject queries. For
114+example to move to the next function use `]f`, to move to previous
115+class use `[c`, and so on.
116+
117+![Tree-sitter-nav-demo][tree-sitter-nav-demo]
118+
119+For the full reference see the [unimpaired][unimpaired-keybinds] section of the key bind
120+documentation.
121+
122+> 💡 This feature relies on tree-sitter textobjects
123+> and requires the corresponding query file to work properly.
124+
125+## Moving the selection with syntax-aware motions
126+
127+`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) allow you to move the
128+selection according to its location in the syntax tree. For example, many languages have the
129+following syntax for function calls:
130+
131+```js
132+func(arg1, arg2, arg3);
63133```
64134
65135A function call might be parsed by tree-sitter into a tree like the following.
@@ -93,77 +163,29 @@ a more intuitive tree format:
93163 └──────────┘ └──────────┘ └──────────┘
94164```
95165
96−Say we have a selection that wraps `arg1`. The selection is on the `arg1` leaf
97−in the tree above.
166+If you have a selection that wraps `arg1` (see the tree above), and you use
167+`Alt-n`, it will select the next sibling in the syntax tree: `arg2`.
98168
99−```
169+```js
170+// before
100171func([arg1], arg2, arg3)
172+// after
173+func(arg1, [arg2], arg3);
101174```
102175
103−Using `Alt-n` would select the next sibling in the syntax tree: `arg2`.
176+Similarly, `Alt-o` will expand the selection to the parent node, in this case, the
177+arguments node.
104178
105−```
106−func(arg1, [arg2], arg3)
107−```
108−
109−While `Alt-o` would expand the selection to the parent node. In the tree above we
110−can see that we would select the `arguments` node.
111−
112−```
113−func[(arg1, arg2, arg3)]
179+```js
180+func[(arg1, arg2, arg3)];
114181```
115182
116183There is also some nuanced behavior that prevents you from getting stuck on a
117−node with no sibling. If we have a selection on `arg1`, `Alt-p` would bring us
118−to the previous child node. Since `arg1` doesn't have a sibling to its left,
119−though, we climb the syntax tree and then take the previous selection. So
120−`Alt-p` will move the selection over to the "func" `identifier`.
121−
122−```
123−[func](arg1, arg2, arg3)
124−```
125−
126−## Textobjects
127−
128−
129−
130−
131−- `ma` - Select around the object (`va` in Vim, `<alt-a>` in Kakoune)
132−- `mi` - Select inside the object (`vi` in Vim, `<alt-i>` in Kakoune)
133−
134−| Key after `mi` or `ma` | Textobject selected |
135−| --- | --- |
136−| `w` | Word |
137−| `W` | WORD |
138−| `p` | Paragraph |
139−| `(`, `[`, `'`, etc | Specified surround pairs |
140−| `m` | Closest surround pair |
141−| `f` | Function |
142−| `c` | Class |
143−| `a` | Argument/parameter |
144−| `o` | Comment |
145−| `t` | Test |
146−| `g` | Change |
147−
148−> NOTE: `f`, `c`, etc need a tree-sitter grammar active for the current
149−document and a special tree-sitter query file to work properly. [Only
150−some grammars][lang-support] currently have the query file implemented.
151−Contributions are welcome!
152−
153−## Tree-sitter Textobject Based Navigation
154−
155−Navigating between functions, classes, parameters, etc is made
156−possible by leveraging tree-sitter and textobjects queries. For
157−example to move to the next function use `]f`, to move to previous
158−class use `[c`, and so on.
159−
160−![tree-sitter-nav-demo][tree-sitter-nav-demo]
161−
162−See the [unimpaired][unimpaired-keybinds] section of the keybind
163−documentation for the full reference.
164−
165−> NOTE: This feature is dependent on tree-sitter based textobjects
166−and therefore requires the corresponding query file to work properly.
184+node with no sibling. When using `Alt-p` with a selection on `arg1`, the previous
185+child node will be selected. In the event that `arg1` does not have a previous
186+sibling, the selection will move up the syntax tree and select the previous
187+element. As a result, using `Alt-p` with a selection on `arg1` will move the
188+selection to the "func" `identifier`.
167189
168190[lang-support]: ./lang-support.md
169191[unimpaired-keybinds]: ./keymap.md#unimpaired