# Operators

## Capturing Nodes

When matching patterns, you may want to process specific nodes within the pattern. Captures allow you to associate names
with specific nodes in a pattern, so that you can later refer to those nodes by those names. Capture names are written _after_
the nodes that they refer to, and start with an `@` character.

For example, this pattern would match any assignment of a `function` to an `identifier`, and it would associate the name
`the-function-name` with the identifier:

```query
(assignment_expression
  left: (identifier) @the-function-name
  right: (function))
```

And this pattern would match all method definitions, associating the name `the-method-name` with the method name, `the-class-name`
with the containing class name:

```query
(class_declaration
  name: (identifier) @the-class-name
  body: (class_body
    (method_definition
      name: (property_identifier) @the-method-name)))
```

## Quantification Operators

You can match a repeating sequence of sibling nodes using the postfix `+` and `*` _repetition_ operators, which work analogously
to the `+` and `*` operators [in regular expressions][regex]. The `+` operator matches _one or more_ repetitions of a pattern,
and the `*` operator matches _zero or more_.

For example, this pattern would match a sequence of one or more comments:

```query
(comment)+
```

This pattern would match a class declaration, capturing all of the decorators if any were present:

```query
(class_declaration
  (decorator)* @the-decorator
  name: (identifier) @the-name)
```

You can also mark a node as optional using the `?` operator. For example, this pattern would match all function calls, capturing
a string argument if one was present:

```query
(call_expression
  function: (identifier) @the-function
  arguments: (arguments (string)? @the-string-arg))
```

## Grouping Sibling Nodes

You can also use parentheses for grouping a sequence of _sibling_ nodes. For example, this pattern would match a comment
followed by a function declaration:

```query
(
  (comment)
  (function_declaration)
)
```

Any of the quantification operators mentioned above (`+`, `*`, and `?`) can also be applied to groups. For example, this
pattern would match a comma-separated series of numbers:

```query
(
  (number)
  ("," (number))*
)
```

## Alternations

An alternation is written as a pair of square brackets (`[]`) containing a list of alternative patterns.
This is similar to _character classes_ from regular expressions (`[abc]` matches either a, b, or c).

For example, this pattern would match a call to either a variable or an object property.
In the case of a variable, capture it as `@function`, and in the case of a property, capture it as `@method`:

```query
(call_expression
  function: [
    (identifier) @function
    (member_expression
      property: (property_identifier) @method)
  ])
```

This pattern would match a set of possible keyword tokens, capturing them as `@keyword`:

```query
[
  "break"
  "delete"
  "else"
  "for"
  "function"
  "if"
  "return"
  "try"
  "while"
] @keyword
```

Alternations can have quantified alternants, and then can have their own
quantifiers as well. See the following examples for an illustration of how these
cases work:

```query
;;; SOURCE CODE ;;;
; #include <foo>
; #include <bar>
; #include <baz>
; // comment
;;;;;;;;;;;;;;;;;;;

[
  (preproc_include)
  (comment)
]+ @capture
; ^ Produces one match with four captures:
; [
;   "#include <foo>\n",
;   "#include <bar>\n",
;   "#include <baz>\n",
;   "// comment",
; ]
;
; Regex equivalent: [ab]+

[
  (preproc_include)+
  (comment)
] @capture
; ^ Produces two matches; one with three captures, and one with one capture:
; [
;   "#include <foo>\n",
;   "#include <bar>\n",
;   "#include <baz>\n",
; ],
; [
;   "// comment",
; ]
;
; Regex equivalent: a+|b

[
  (preproc_include)
  (comment)
] @capture
; ^ Produces four matches, each with one capture:
; [
;   "#include <foo>\n",
; ],
; [
;   "#include <bar>\n",
; ],
; [
;   "#include <baz>\n",
; ],
; [
;   "// comment",
; ]
;
; Regex equivalent: [ab]
```

## 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 node in the parent `array`, only if it's an `identifier` node:

```query
(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`.

```query
(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`.

```query
(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.

### Anchors with Quantifiers and Groups

When an anchor is next to a quantified node (`*`, `+`, `?`), its meaning depends on whether the
anchor sits _between two patterns_ or _at the edge of a parent node_.

An anchor _between two child patterns_ constrains the two matched nodes to be immediate siblings.
If one of those patterns is a quantifier that matches zero nodes, there is no node on that side,
so the anchor imposes no constraint. For example, given

```query
(translation_unit (comment)* @doc . (function_definition) @function)
```

a `function_definition` with no preceding `comment` still matches, with `@doc` capturing nothing.
When comments are present, they must immediately precede the function.

An anchor at the _start or end of a node pattern_ (a leading or trailing `.`) constrains the
matched sequence to begin at the parent's first, or end at its last, named child. If the pattern
element next to that edge is a quantifier that matches zero nodes, the constraint applies to the
nearest node that the pattern _does_ match. For example, given

```query
(preproc_if (preproc_def)+ @def . (preproc_else)? @else .)
```

the trailing anchor requires the last matched node to be the parent's last named child: when a
`preproc_else` is present it must be last. When it is absent, the last `preproc_def` must be last.

Similarly, if an optionally quantified node is anchored between two siblings and matches zero nodes,
both sibling anchors collapse into one, constraining the outer nodes together. For example, given

```query
(translation_unit
  (declaration) @a
  .
  (comment)*
  .
  (function_definition) @b)
```

If there are no comments, `(declaration)` and `(function_definition)` must be immediate siblings
in order for the query to match.

An anchor may not appear at the first or last position inside a group `(...)` or an alternation
`[...]`. A group or alternation is not a node, so it has no first or last child to anchor against,
and there is no sibling on that side to anchor to. For example, write `(comment)* @doc . (function)`
rather than `((comment)+ @doc .)? (function)`.

[regex]: https://en.wikipedia.org/wiki/Regular_expression#Basic_concepts