Indentation

Indentation is a special form of horizontal spacing, where "blocks" are defined using start and end markers. Each block, which can be nested, sets an increasing indentation level which, when formatted in the output, will be prefixed with an appropriate number of indentation strings (defined in the language configuration).

@append_indent_start / @prepend_indent_start

The matched nodes will trigger indentation before (or, respectively, after) them. This will only apply to the lines following, until an indentation end is signalled. If indentation is started and ended on the same line, nothing will happen. This is useful, because we get the correct behaviour whether a node is formatted as single-line or multi-line. It is important that all indentation starts and ends are balanced.

Note
If indentation is not balanced, the formatting will (probably) not fail, but a warning will be logged.

Example

; Start an indented block after these
[
  "begin"
  "else"
  "then"
  "{"
] @append_indent_start

@append_indent_end / @prepend_indent_end

The matched nodes will trigger that indentation ends before (or, respectively, after) them.

Example

; End the indented block before these
[
  "end"
  "}"
] @prepend_indent_end

; End the indented block after these
[
  (else_clause)
  (then_clause)
] @append_indent_end

@multi_line_string

To be used on multi line strings in languages like Nix and Nickel that ignore indentation common to all lines of the multi line string. Consider the following Nickel example.

m%"a
b"%

@multi_line_string could format this as follows.

m%"
  a
  b
"%

Nickel considers these 2 strings above as equal because Nickel ignores indentation common to all lines of the multi line string. Otherwise, @multi_line_string would not be admissible in a Nickel formatter.

Here is an example query for Nickel.

(str_chunks_multi
  start: (multstr_start) @multi_line_string.start
  end: (multstr_end) @multi_line_string.end
  (#multi_line_string.last_insignificant!)
) @multi_line_string

As illustrated by this example, @multi_line_string requires both a @multi_line_string.start and a @multi_line_string.end directive in the same query matching the start and end delimiters of the string, for example m%" and "% in Nickel.

As furthermore illustrated by this example above, you can add an optional #multi_line_string.last_insignificant! predicate. It indicates that a line break can be introduced before the end delimiter if, in the input, the end delimiter is on the same line as the string's last non-whitespace line, as illustrated by b"% in the examples above. Nickel considers this not to change the string's value. Otherwise, #multi_line_string.last_insignificant! would not be admissible in a Nickel formatter. For example, Nix does consider this to change the string's value.

Here is an example query for Nix.

(indented_string_expression
  "''" @multi_line_string.start
  "''" @multi_line_string.end
  (#multi_line_string.carriage_return_significant!)
  (#multi_line_string.tab_significant!)
) @multi_line_string

As illustrated by this example, you can add an optional #multi_line_string.carriage_return_significant! predicate. It indicates that the formatted language made the questionable design decision that carriage returns always become part of the string's value. even if they occur at the very line end in a CRLF line ending.

As furthermore illustrated by this example above, you can add an optional #multi_line_string.tab_significant! predicate. It indicates that the formatted language made the questionable design decision that tabs always become part of the string's value. even if they occur in indentation common to all lines of the multi line string.

Example

(str_chunks_multi
  start: (multstr_start) @multi_line_string.start
  end: (multstr_end) @multi_line_string.end
  (#multi_line_string.last_insignificant!)
) @multi_line_string

@multi_line_indent_all

To be used on comments, or other leaf nodes, to indicate that we should indent all its lines, not just the first.

Example

(comment) @multi_line_indent_all

@single_line_no_indent

The matched node will be printed alone, on a single line, regardless of any indentation level. That is, this capture temporarily suspends normal indentation for the node that is matched.

Example

; line number directives must be alone on their line, and can't be indented
(line_number_directive) @single_line_no_indent