From b5d20f07b653449bf467ce2699abf67e28214108 Mon Sep 17 00:00:00 2001 From: Patrick Thomson Date: Fri, 23 Oct 2020 14:34:56 -0400 Subject: [PATCH 1/4] Document query anchor operator (#771) This was taken more or less directly from @maxbrunsfeld's PR comments in https://github.com/tree-sitter/tree-sitter/pull/549. :tophat: --- docs/section-2-using-parsers.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/section-2-using-parsers.md b/docs/section-2-using-parsers.md index a9f5de02..e73dee55 100644 --- a/docs/section-2-using-parsers.md +++ b/docs/section-2-using-parsers.md @@ -585,6 +585,38 @@ For example, this pattern would match any node inside a call: (call (_) @call.inner) ``` + +#### Anchor Nodes + +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) +``` + +Were this anchor operator elided, 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) +``` + +Were the anchor elided, non-consecutive pairs like `a, c` and `b, d` would 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. From b42b873564546c5838f7acba0afa2722b0f033b4 Mon Sep 17 00:00:00 2001 From: Patrick Thomson Date: Fri, 23 Oct 2020 15:11:17 -0400 Subject: [PATCH 2/4] Update docs/section-2-using-parsers.md Co-authored-by: Max Brunsfeld --- docs/section-2-using-parsers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/section-2-using-parsers.md b/docs/section-2-using-parsers.md index e73dee55..3b2f282a 100644 --- a/docs/section-2-using-parsers.md +++ b/docs/section-2-using-parsers.md @@ -613,7 +613,7 @@ Finally, an anchor _between_ two child patterns will cause the patterns to only (identifier) @next-id) ``` -Were the anchor elided, non-consecutive pairs like `a, c` and `b, d` would be matched. +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. From 4d8cdc2f368c127fcb439309a9b78d9a889fdf6e Mon Sep 17 00:00:00 2001 From: Patrick Thomson Date: Fri, 23 Oct 2020 15:11:23 -0400 Subject: [PATCH 3/4] Update docs/section-2-using-parsers.md Co-authored-by: Max Brunsfeld --- docs/section-2-using-parsers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/section-2-using-parsers.md b/docs/section-2-using-parsers.md index 3b2f282a..7166c776 100644 --- a/docs/section-2-using-parsers.md +++ b/docs/section-2-using-parsers.md @@ -596,7 +596,7 @@ When `.` is placed before the _first_ child within a parent pattern, the child w (array . (identifier) @the-element) ``` -Were this anchor operator elided, the pattern would match once for every identifier in the array, with `@the-element` bound to each matched identifier. +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`. From 1749a5d672673cda78e6dd02baac7bec76eee335 Mon Sep 17 00:00:00 2001 From: Patrick Thomson Date: Fri, 23 Oct 2020 15:11:53 -0400 Subject: [PATCH 4/4] Shorter wording. --- docs/section-2-using-parsers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/section-2-using-parsers.md b/docs/section-2-using-parsers.md index 7166c776..75c508f5 100644 --- a/docs/section-2-using-parsers.md +++ b/docs/section-2-using-parsers.md @@ -586,7 +586,7 @@ For example, this pattern would match any node inside a call: ``` -#### Anchor Nodes +#### 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.