git.iko.soy/helix
on master help sign in
add section on syntax tree motions to the usage docs (#2568)
efae761Michael Davis
book/src/usage.md+72
compare with master
unifiedsplit
@@ -51,6 +51,78 @@ It can also act on multiple selections (yay!). For example, to change every occu
51
51
52Multiple characters are currently not supported, but planned.
52Multiple characters are currently not supported, but planned.
53
53
54+## Syntax-tree Motions
55+
56+`A-p`, `A-o`, `A-i`, and `A-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:
60+
61+```
62+func(arg1, arg2, arg3)
63+```
64+
65+A function call might be parsed by tree-sitter into a tree like the following.
66+
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+```
76+
77+Use `:tree-sitter-subtree` to view the syntax tree of the primary selection. In
78+a more intuitive tree format:
79+
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+```
95+
96+Say we have a selection that wraps `arg1`. The selection is on the `arg1` leaf
97+in the tree above.
98+
99+```
100+func([arg1], arg2, arg3)
101+```
102+
103+Using `A-n` would select the next sibling in the syntax tree: `arg2`.
104+
105+```
106+func(arg1, [arg2], arg3)
107+```
108+
109+While `A-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)]
114+```
115+
116+There 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`, `A-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 `A-p`
120+will move the selection over to the "func" `identifier`.
121+
122+```
123+[func](arg1, arg2, arg3)
124+```
125+
54## Textobjects
126## Textobjects
55
127
56Currently supported: `word`, `surround`, `function`, `class`, `parameter`.
128Currently supported: `word`, `surround`, `function`, `class`, `parameter`.