aboutsummaryrefslogtreecommitdiff
path: root/book/src
diff options
context:
space:
mode:
authorMichael Davis2022-05-26 01:39:58 +0000
committerGitHub2022-05-26 01:39:58 +0000
commitefae76160d19ebba2bba31ecd5c104374c7b4483 (patch)
tree2ba1a96bc3f61c823a89042d03be4f22c68b825b /book/src
parent7160e745f72e5d742e19fecf9a7e78f32e5b34da (diff)
add section on syntax tree motions to the usage docs (#2568)
Diffstat (limited to 'book/src')
-rw-r--r--book/src/usage.md72
1 files changed, 72 insertions, 0 deletions
diff --git a/book/src/usage.md b/book/src/usage.md
index 7871e2b9..ad21a94c 100644
--- a/book/src/usage.md
+++ b/book/src/usage.md
@@ -51,6 +51,78 @@ It can also act on multiple selections (yay!). For example, to change every occu
Multiple characters are currently not supported, but planned.
+## Syntax-tree Motions
+
+`A-p`, `A-o`, `A-i`, and `A-n` (or `Alt` and arrow keys) move the primary
+selection according to the selection's place in the syntax tree. Let's walk
+through an example to get familiar with them. Many languages have a syntax like
+so for function calls:
+
+```
+func(arg1, arg2, arg3)
+```
+
+A function call might be parsed by tree-sitter into a tree like the following.
+
+```tsq
+(call
+ function: (identifier) ; func
+ arguments:
+ (arguments ; (arg1, arg2, arg3)
+ (identifier) ; arg1
+ (identifier) ; arg2
+ (identifier))) ; arg3
+```
+
+Use `:tree-sitter-subtree` to view the syntax tree of the primary selection. In
+a more intuitive tree format:
+
+```
+ ┌────┐
+ │call│
+ ┌─────┴────┴─────┐
+ │ │
+┌─────▼────┐ ┌────▼────┐
+│identifier│ │arguments│
+│ "func" │ ┌────┴───┬─────┴───┐
+└──────────┘ │ │ │
+ │ │ │
+ ┌─────────▼┐ ┌────▼─────┐ ┌▼─────────┐
+ │identifier│ │identifier│ │identifier│
+ │ "arg1" │ │ "arg2" │ │ "arg3" │
+ └──────────┘ └──────────┘ └──────────┘
+```
+
+Say we have a selection that wraps `arg1`. The selection is on the `arg1` leaf
+in the tree above.
+
+```
+func([arg1], arg2, arg3)
+```
+
+Using `A-n` would select the next sibling in the syntax tree: `arg2`.
+
+```
+func(arg1, [arg2], arg3)
+```
+
+While `A-o` would expand the selection to the parent node. In the tree above we
+can see that we would select the `arguments` node.
+
+```
+func[(arg1, arg2, arg3)]
+```
+
+There is also some nuanced behavior that prevents you from getting stuck on a
+node with no sibling. If we have a selection on `arg1`, `A-p` would bring us
+to the previous child node. Since `arg1` doesn't have a sibling to its left,
+though, we climb the syntax tree and then take the previous selection. So `A-p`
+will move the selection over to the "func" `identifier`.
+
+```
+[func](arg1, arg2, arg3)
+```
+
## Textobjects
Currently supported: `word`, `surround`, `function`, `class`, `parameter`.