traxys/tree-sitter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #779 from tree-sitter/dot-doc-dash

Browse source 
Document query anchor operator (#771)
This commit is contained in:
Patrick Thomson 2020-10-23 18:22:38 -04:00 • committed by GitHub
commit 6fca3ebd9c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 32 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

32
docs/section-2-using-parsers.md
View file

@ -585,6 +585,38 @@ For example, this pattern would match any node inside a call:
(call (_) @call.inner)
```
#### Anchors
The anchor operator, `.`, is used to constrain the ways in which child patterns are matched. It has different behaviors depending on where it's placed inside a query.
When `.` is placed before the _first_ child within a parent pattern, the child will only match when it is the first named node in the parent. For example, the below pattern matches a given `array` node at most once, assigning the `@the-element` capture to the first `identifier` node in the parent `array`:
```
(array . (identifier) @the-element)
```
Without this anchor, the pattern would match once for every identifier in the array, with `@the-element` bound to each matched identifier.
Similarly, an anchor placed after a pattern's _last_ child will cause that child pattern to only match nodes that are the last named child of their parent. The below pattern matches only nodes that are the last named child within a `block`.
```
(block (_) @last-expression .)
```
Finally, an anchor _between_ two child patterns will cause the patterns to only match nodes that are immediate siblings. The pattern below, given a long dotted name like `a.b.c.d`, will only match pairs of consecutive identifiers: `a, b`, `b, c`, and `c, d`.
```
(dotted_name
(identifier) @prev-id
.
(identifier) @next-id)
```
Without the anchor, non-consecutive pairs like `a, c` and `b, d` would also be matched.
The restrictions placed on a pattern by an anchor operator ignore anonymous nodes.
#### Predicates
You can also specify arbitrary metadata and conditions associed with a pattern by adding _predicate_ S-expressions anywhere within your pattern. Predicate S-expressions start with a _predicate name_ beginning with a `#` character. After that, they can contain an arbitrary number of `@`-prefixed capture names or strings.