<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>book/src/guides/indent.md - fork/helix @ 23.05</title>
<meta name="description" content="book/src/guides/indent.md in fork/helix at 23.05.">
<meta property="og:title" content="book/src/guides/indent.md - fork/helix @ 23.05">
<meta property="og:description" content="book/src/guides/indent.md in fork/helix at 23.05.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="23.05" data-tip="7f5940be80eaa3aec7903903072b7108f41dd97b">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/helix</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/helix</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">David Else</span><span class="commit-message" data-commit="707457c632e3b79f71d6b7ad2f62716e98080af2">Rewrite and refactor all documentation (#5534)</span><span class="snapshot-sha sha" data-commit="707457c632e3b79f71d6b7ad2f62716e98080af2">707457c6</span><time datetime="2023-03-06T09:27:17+00:00" title="2023-03-06 09:27:17 +0000">2023-03-06</time></p>
<header class="topbar"><details class="switcher"><summary>23.05</summary><div class="menu"><strong>branches</strong><a href="/fork/helix/ref/master/">master</a><strong>tags</strong><a class="current" href="/fork/helix/ref/23.05/">23.05</a><a href="/fork/helix/ref/23.10/">23.10</a><a href="/fork/helix/ref/24.03/">24.03</a><a href="/fork/helix/ref/24.07/">24.07</a><a href="/fork/helix/ref/25.01/">25.01</a><a href="/fork/helix/ref/25.01.1/">25.01.1</a><a href="/fork/helix/ref/25.07/">25.07</a><a href="/fork/helix/ref/25.07.1/">25.07.1</a><a class="all" href="/fork/helix/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/helix/">helix</a> / <a href="/fork/helix/ref/23.05/tree/book/">book</a> / <a href="/fork/helix/ref/23.05/tree/book/src/">src</a> / <a href="/fork/helix/ref/23.05/tree/book/src/guides/">guides</a> / <span class="cur">indent.md</span></nav>
<span class="view-stats"><span>3.5 KiB</span><span>93 lines</span></span><span class="actions"><a class="raw" href="/fork/helix/raw/b660d785734ea8551fd441af0057c646c14a8670/book/src/guides/indent.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Adding indent queries</h1>
<p>Helix uses tree-sitter to correctly indent new lines. This requires
a tree-sitter grammar and an <code>indent.scm</code> query file placed in
<code>runtime/queries/{language}/indents.scm</code>. The indentation for a line
is calculated by traversing the syntax tree from the lowest node at the
beginning of the new line. Each of these nodes contributes to the total
indent when it is captured by the query (in what way depends on the name
of the capture).</p>
<p>Note that it matters where these added indents begin. For example,
multiple indent level increases that start on the same line only increase
the total indent level by 1.</p>
<h2>Scopes</h2>
<p>Added indents don't always apply to the whole node. For example, in most
cases when a node should be indented, we actually only want everything
except for its first line to be indented. For this, there are several
scopes (more scopes may be added in the future if required):</p>
<ul>
<li>
<p><code>all</code>:
This scope applies to the whole captured node. This is only different from
<code>tail</code> when the captured node is the first node on its line.</p>
</li>
<li>
<p><code>tail</code>:
This scope applies to everything except for the first line of the
captured node.</p>
</li>
</ul>
<p>Every capture type has a default scope which should do the right thing
in most situations. When a different scope is required, this can be
changed by using a <code>#set!</code> declaration anywhere in the pattern:</p>
<pre class="language-query"><a-p>(</a-p><a-v>assignment_expression</a-v>
  <a-v>right</a-v><a-p>:</a-p> <a-p>(</a-p><a-s>_</a-s><a-p>)</a-p> <a-p>@</a-p><a-t>indent</a-t>
  <a-p>(#</a-p><a-f>set</a-f><a-p>!</a-p> <a-s>&quot;scope&quot;</a-s> <a-s>&quot;all&quot;</a-s><a-p>))</a-p></pre>
<h2>Capture types</h2>
<ul>
<li>
<p><code>@indent</code> (default scope <code>tail</code>):
Increase the indent level by 1. Multiple occurrences in the same line
don't stack. If there is at least one <code>@indent</code> and one <code>@outdent</code>
capture on the same line, the indent level isn't changed at all.</p>
</li>
<li>
<p><code>@outdent</code> (default scope <code>all</code>):
Decrease the indent level by 1. The same rules as for <code>@indent</code> apply.</p>
</li>
<li>
<p><code>@extend</code>:
Extend the range of this node to the end of the line and to lines that
are indented more than the line that this node starts on. This is useful
for languages like Python, where for the purpose of indentation some nodes
(like functions or classes) should also contain indented lines that follow them.</p>
</li>
<li>
<p><code>@extend.prevent-once</code>:
Prevents the first extension of an ancestor of this node. For example, in Python
a return expression always ends the block that it is in. Note that this only stops the
extension of the next <code>@extend</code> capture. If multiple ancestors are captured,
only the extension of the innermost one is prevented. All other ancestors are unaffected
(regardless of whether the innermost ancestor would actually have been extended).</p>
</li>
</ul>
<h2>Predicates</h2>
<p>In some cases, an S-expression cannot express exactly what pattern should be matched.
For that, tree-sitter allows for predicates to appear anywhere within a pattern,
similar to how <code>#set!</code> declarations work:</p>
<pre class="language-query"><a-p>(</a-p><a-v>some_kind</a-v>
  <a-p>(</a-p><a-v>child_kind</a-v><a-p>)</a-p> <a-p>@</a-p><a-t>indent</a-t>
  <a-p>(#</a-p><a-f>predicate</a-f><a-p>?</a-p> arg1 arg2 <a-o>...</a-o><a-p>)</a-p>
<a-p>)</a-p></pre>
<p>The number of arguments depends on the predicate that's used.
Each argument is either a capture (<code>@name</code>) or a string (<code>"some string"</code>).
The following predicates are supported by tree-sitter:</p>
<ul>
<li>
<p><code>#eq?</code>/<code>#not-eq?</code>:
The first argument (a capture) must/must not be equal to the second argument
(a capture or a string).</p>
</li>
<li>
<p><code>#match?</code>/<code>#not-match?</code>:
The first argument (a capture) must/must not match the regex given in the
second argument (a string).</p>
</li>
</ul>
<p>Additionally, we support some custom predicates for indent queries:</p>
<ul>
<li>
<p><code>#not-kind-eq?</code>:
The kind of the first argument (a capture) must not be equal to the second
argument (a string).</p>
</li>
<li>
<p><code>#same-line?</code>/<code>#not-same-line?</code>:
The captures given by the 2 arguments must/must not start on the same line.</p>
</li>
</ul>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>Adding indent queries</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">Helix uses tree-sitter to correctly indent new lines. This requires</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">a tree-sitter grammar and an `indent.scm` query file placed in</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">`runtime/queries/{language}/indents.scm`. The indentation for a line</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">is calculated by traversing the syntax tree from the lowest node at the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">beginning of the new line. Each of these nodes contributes to the total</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text">indent when it is captured by the query (in what way depends on the name</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">of the capture).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">Note that it matters where these added indents begin. For example,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">multiple indent level increases that start on the same line only increase</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">the total indent level by 1.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"><a-p>##</a-p> <a-tt>Scopes</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">Added indents don&#39;t always apply to the whole node. For example, in most</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text">cases when a node should be indented, we actually only want everything</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">except for its first line to be indented. For this, there are several</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">scopes (more scopes may be added in the future if required):</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>- </a-p>`all`:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">This scope applies to the whole captured node. This is only different from</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text">`tail` when the captured node is the first node on its line.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p>- `tail`:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"><a-p>This scope applies to everything except for the first line of the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>captured node.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>Every capture type has a default scope which should do the right thing</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>in most situations. When a different scope is required, this can be</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"><a-p>changed by using a `#set!` declaration anywhere in the pattern:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"><a-p>```</a-p><a-tl>scm</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-p>(assignment_expression</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"><a-p>  right: (_) @indent</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>  (#set! &quot;scope&quot; &quot;all&quot;))</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"><a-p>## </a-p><a-tt>Capture types</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"><a-p>- `@indent` (default scope `tail`):</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p>Increase the indent level by 1. Multiple occurrences in the same line</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>don&#39;t stack. If there is at least one `@indent` and one `@outdent`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>capture on the same line, the indent level isn&#39;t changed at all.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"><a-p>- `@outdent` (default scope `all`):</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>Decrease the indent level by 1. The same rules as for `@indent` apply.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"><a-p>- `@extend`:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"><a-p>Extend the range of this node to the end of the line and to lines that</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>are indented more than the line that this node starts on. This is useful</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"><a-p>for languages like Python, where for the purpose of indentation some nodes</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"><a-p>(like functions or classes) should also contain indented lines that follow them.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"><a-p>- `@extend.prevent-once`:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"><a-p>Prevents the first extension of an ancestor of this node. For example, in Python</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>a return expression always ends the block that it is in. Note that this only stops the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"><a-p>extension of the next `@extend` capture. If multiple ancestors are captured,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"><a-p>only the extension of the innermost one is prevented. All other ancestors are unaffected</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"><a-p>(regardless of whether the innermost ancestor would actually have been extended).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"><a-p>## </a-p><a-tt>Predicates</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>In some cases, an S-expression cannot express exactly what pattern should be matched.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"><a-p>For that, tree-sitter allows for predicates to appear anywhere within a pattern,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"><a-p>similar to how `#set!` declarations work:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"><a-p>```</a-p><a-tl>scm</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"><a-p>(some_kind</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"><a-p>  (child_kind) @indent</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"><a-p>  (#predicate? arg1 arg2 ...)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"><a-p>The number of arguments depends on the predicate that&#39;s used.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"><a-p>Each argument is either a capture (`@name`) or a string (`&quot;some string&quot;`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"><a-p>The following predicates are supported by tree-sitter:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"><a-p>- `#eq?`/`#not-eq?`:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"><a-p>The first argument (a capture) must/must not be equal to the second argument</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"><a-p>(a capture or a string).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"><a-p>- `#match?`/`#not-match?`:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"><a-p>The first argument (a capture) must/must not match the regex given in the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"><a-p>second argument (a string).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"><a-p>Additionally, we support some custom predicates for indent queries:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"><a-p>- `#not-kind-eq?`:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"><a-p>The kind of the first argument (a capture) must not be equal to the second</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"><a-p>argument (a string).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"><a-p>- </a-p>`#same-line?`/`#not-same-line?`:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text">The captures given by the 2 arguments must/must not start on the same line.</span></span></pre></div></div>
</main>
</body>
</html>
