git.iko.soy/helix
on 0b8a00a help sign in
helix/book/src/usage.md
169 lines 6.7 kB history raw
1# Usage
3(Currently not fully documented, see the [keymappings](./keymap.md) list for more.)
5See [tutor.txt](https://github.com/helix-editor/helix/blob/master/runtime/tutor.txt) (accessible via `hx --tutor` or `:tutor`) for a vimtutor-like introduction.
7## Registers
9Vim-like registers can be used to yank and store text to be pasted later. Usage is similar, with `"` being used to select a register:
11- `"ay` - Yank the current selection to register `a`.
12- `"op` - Paste the text in register `o` after the selection.
14If 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:
16- `"hc` - Store the selection in register `h` and then change it (delete and enter insert mode).
17- `"md` - Store the selection in register `m` and delete it.
19### Special Registers
21| Register character | Contains |
22| --- | --- |
23| `/` | Last search |
24| `:` | Last executed command |
25| `"` | Last yanked text |
26| `_` | Black hole |
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.
31## Surround
33Functionality similar to [vim-surround](https://github.com/tpope/vim-surround) is built into
34helix. The keymappings have been inspired from [vim-sandwich](https://github.com/machakann/vim-sandwich):
36![surround demo](https://user-images.githubusercontent.com/23398472/122865801-97073180-d344-11eb-8142-8f43809982c6.gif)
38- `ms` - Add surround characters
39- `mr` - Replace surround characters
40- `md` - Delete surround characters
42`ms` acts on a selection, so select the text first and use `ms<char>`. `mr` and `md` work
43on the closest pairs found and selections are not required; use counts to act in outer pairs.
45It can also act on multiple selections (yay!). For example, to change every occurrence of `(use)` to `[use]`:
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
52Multiple characters are currently not supported, but planned.
54## Syntax-tree Motions
56`A-p`, `A-o`, `A-i`, and `A-n` (or `Alt` and arrow keys) move the primary
57selection according to the selection's place in the syntax tree. Let's walk
58through an example to get familiar with them. Many languages have a syntax like
59so for function calls:
61```
62func(arg1, arg2, arg3)
63```
65A function call might be parsed by tree-sitter into a tree like the following.
67```tsq
68(call
69 function: (identifier) ; func
70 arguments:
71 (arguments ; (arg1, arg2, arg3)
72 (identifier) ; arg1
73 (identifier) ; arg2
74 (identifier))) ; arg3
75```
77Use `:tree-sitter-subtree` to view the syntax tree of the primary selection. In
78a more intuitive tree format:
80```
81 ┌────┐
82 │call│
83 ┌─────┴────┴─────┐
84 │ │
85┌─────▼────┐ ┌────▼────┐
86│identifier│ │arguments│
87│ "func" │ ┌────┴───┬─────┴───┐
88└──────────┘ │ │ │
89 │ │ │
90 ┌─────────▼┐ ┌────▼─────┐ ┌▼─────────┐
91 │identifier│ │identifier│ │identifier│
92 │ "arg1" │ │ "arg2" │ │ "arg3" │
93 └──────────┘ └──────────┘ └──────────┘
94```
96Say we have a selection that wraps `arg1`. The selection is on the `arg1` leaf
97in the tree above.
99```
100func([arg1], arg2, arg3)
101```
103Using `A-n` would select the next sibling in the syntax tree: `arg2`.
105```
106func(arg1, [arg2], arg3)
107```
109While `A-o` would expand the selection to the parent node. In the tree above we
110can see that we would select the `arguments` node.
112```
113func[(arg1, arg2, arg3)]
114```
116There is also some nuanced behavior that prevents you from getting stuck on a
117node with no sibling. If we have a selection on `arg1`, `A-p` would bring us
118to the previous child node. Since `arg1` doesn't have a sibling to its left,
119though, we climb the syntax tree and then take the previous selection. So `A-p`
120will move the selection over to the "func" `identifier`.
122```
123[func](arg1, arg2, arg3)
124```
126## Textobjects
128Currently supported: `word`, `surround`, `function`, `class`, `parameter`.
130![textobject-demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif)
131![textobject-treesitter-demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif)
133- `ma` - Select around the object (`va` in vim, `<alt-a>` in kakoune)
134- `mi` - Select inside the object (`vi` in vim, `<alt-i>` in kakoune)
136| Key after `mi` or `ma` | Textobject selected |
137| --- | --- |
138| `w` | Word |
139| `W` | WORD |
140| `(`, `[`, `'`, etc | Specified surround pairs |
141| `m` | Closest surround pair |
142| `f` | Function |
143| `c` | Class |
144| `a` | Argument/parameter |
145| `o` | Comment |
147> NOTE: `f`, `c`, etc need a tree-sitter grammar active for the current
148document and a special tree-sitter query file to work properly. [Only
149some grammars][lang-support] currently have the query file implemented.
150Contributions are welcome!
152## Tree-sitter Textobject Based Navigation
154Navigating between functions, classes, parameters, etc is made
155possible by leveraging tree-sitter and textobjects queries. For
156example to move to the next function use `]f`, to move to previous
157class use `[c`, and so on.
159![tree-sitter-nav-demo][tree-sitter-nav-demo]
161See the [unimpaired][unimpaired-keybinds] section of the keybind
162documentation for the full reference.
164> NOTE: This feature is dependent on tree-sitter based textobjects
165and therefore requires the corresponding query file to work properly.
167[lang-support]: ./lang-support.md
168[unimpaired-keybinds]: ./keymap.md#unimpaired
169[tree-sitter-nav-demo]: https://user-images.githubusercontent.com/23398472/152332550-7dfff043-36a2-4aec-b8f2-77c13eb56d6f.gif