diff options
Diffstat (limited to 'admin/notes/tree-sitter/html-manual/Pattern-Matching.html')
| -rw-r--r-- | admin/notes/tree-sitter/html-manual/Pattern-Matching.html | 450 |
1 files changed, 0 insertions, 450 deletions
diff --git a/admin/notes/tree-sitter/html-manual/Pattern-Matching.html b/admin/notes/tree-sitter/html-manual/Pattern-Matching.html deleted file mode 100644 index 9ef536b79dd..00000000000 --- a/admin/notes/tree-sitter/html-manual/Pattern-Matching.html +++ /dev/null @@ -1,450 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html> -<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> -<!-- This is the GNU Emacs Lisp Reference Manual -corresponding to Emacs version 29.0.50. - -Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "GNU General Public License," with the -Front-Cover Texts being "A GNU Manual," and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the -section entitled "GNU Free Documentation License." - -(a) The FSF's Back-Cover Text is: "You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom." --> -<title>Pattern Matching (GNU Emacs Lisp Reference Manual)</title> - -<meta name="description" content="Pattern Matching (GNU Emacs Lisp Reference Manual)"> -<meta name="keywords" content="Pattern Matching (GNU Emacs Lisp Reference Manual)"> -<meta name="resource-type" content="document"> -<meta name="distribution" content="global"> -<meta name="Generator" content="makeinfo"> -<meta name="viewport" content="width=device-width,initial-scale=1"> - -<link href="index.html" rel="start" title="Top"> -<link href="Index.html" rel="index" title="Index"> -<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> -<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source"> -<link href="Multiple-Languages.html" rel="next" title="Multiple Languages"> -<link href="Accessing-Node-Information.html" rel="prev" title="Accessing Node Information"> -<style type="text/css"> -<!-- -a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} -a.summary-letter {text-decoration: none} -blockquote.indentedblock {margin-right: 0em} -div.display {margin-left: 3.2em} -div.example {margin-left: 3.2em} -kbd {font-style: oblique} -pre.display {font-family: inherit} -pre.format {font-family: inherit} -pre.menu-comment {font-family: serif} -pre.menu-preformatted {font-family: serif} -span.nolinebreak {white-space: nowrap} -span.roman {font-family: initial; font-weight: normal} -span.sansserif {font-family: sans-serif; font-weight: normal} -span:hover a.copiable-anchor {visibility: visible} -ul.no-bullet {list-style: none} ---> -</style> -<link rel="stylesheet" type="text/css" href="./manual.css"> - - -</head> - -<body lang="en"> -<div class="section" id="Pattern-Matching"> -<div class="header"> -<p> -Next: <a href="Multiple-Languages.html" accesskey="n" rel="next">Parsing Text in Multiple Languages</a>, Previous: <a href="Accessing-Node-Information.html" accesskey="p" rel="prev">Accessing Node Information</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> -</div> -<hr> -<span id="Pattern-Matching-Tree_002dsitter-Nodes"></span><h3 class="section">37.5 Pattern Matching Tree-sitter Nodes</h3> -<span id="index-pattern-matching-with-tree_002dsitter-nodes"></span> - -<span id="index-capturing_002c-tree_002dsitter-node"></span> -<p>Tree-sitter lets Lisp programs match patterns using a small -declarative language. This pattern matching consists of two steps: -first tree-sitter matches a <em>pattern</em> against nodes in the syntax -tree, then it <em>captures</em> specific nodes that matched the pattern -and returns the captured nodes. -</p> -<p>We describe first how to write the most basic query pattern and how to -capture nodes in a pattern, then the pattern-matching function, and -finally the more advanced pattern syntax. -</p> -<span id="Basic-query-syntax"></span><h3 class="heading">Basic query syntax</h3> - -<span id="index-tree_002dsitter-query-pattern-syntax"></span> -<span id="index-pattern-syntax_002c-tree_002dsitter-query"></span> -<span id="index-query_002c-tree_002dsitter"></span> -<p>A <em>query</em> consists of multiple <em>patterns</em>. Each pattern is an -s-expression that matches a certain node in the syntax node. A -pattern has the form <code>(<var>type</var> (<var>child</var>…))</code><!-- /@w --> -</p> -<p>For example, a pattern that matches a <code>binary_expression</code> node that -contains <code>number_literal</code> child nodes would look like -</p> -<div class="example"> -<pre class="example">(binary_expression (number_literal)) -</pre></div> - -<p>To <em>capture</em> a node using the query pattern above, append -<code>@<var>capture-name</var></code> after the node pattern you want to -capture. For example, -</p> -<div class="example"> -<pre class="example">(binary_expression (number_literal) @number-in-exp) -</pre></div> - -<p>captures <code>number_literal</code> nodes that are inside a -<code>binary_expression</code> node with the capture name -<code>number-in-exp</code>. -</p> -<p>We can capture the <code>binary_expression</code> node as well, with, for -example, the capture name <code>biexp</code>: -</p> -<div class="example"> -<pre class="example">(binary_expression - (number_literal) @number-in-exp) @biexp -</pre></div> - -<span id="Query-function"></span><h3 class="heading">Query function</h3> - -<span id="index-query-functions_002c-tree_002dsitter"></span> -<p>Now we can introduce the <em>query functions</em>. -</p> -<dl class="def"> -<dt id="index-treesit_002dquery_002dcapture"><span class="category">Function: </span><span><strong>treesit-query-capture</strong> <em>node query &optional beg end node-only</em><a href='#index-treesit_002dquery_002dcapture' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function matches patterns in <var>query</var> within <var>node</var>. -The argument <var>query</var> can be either a string, a s-expression, or a -compiled query object. For now, we focus on the string syntax; -s-expression syntax and compiled query are described at the end of the -section. -</p> -<p>The argument <var>node</var> can also be a parser or a language symbol. A -parser means using its root node, a language symbol means find or -create a parser for that language in the current buffer, and use the -root node. -</p> -<p>The function returns all the captured nodes in a list of the form -<code>(<var><span class="nolinebreak">capture_name</span></var> . <var>node</var>)</code><!-- /@w -->. If <var>node-only</var> is -non-<code>nil</code>, it returns the list of nodes instead. By default the -entire text of <var>node</var> is searched, but if <var>beg</var> and <var>end</var> -are both non-<code>nil</code>, they specify the region of buffer text where -this function should match nodes. Any matching node whose span -overlaps with the region between <var>beg</var> and <var>end</var> are captured, -it doesn’t have to be completely in the region. -</p> -<span id="index-treesit_002dquery_002derror"></span> -<span id="index-treesit_002dquery_002dvalidate"></span> -<p>This function raises the <code>treesit-query-error</code> error if -<var>query</var> is malformed. The signal data contains a description of -the specific error. You can use <code>treesit-query-validate</code> to -validate and debug the query. -</p></dd></dl> - -<p>For example, suppose <var>node</var>’s text is <code>1 + 2</code>, and -<var>query</var> is -</p> -<div class="example"> -<pre class="example">(setq query - "(binary_expression - (number_literal) @number-in-exp) @biexp") -</pre></div> - -<p>Matching that query would return -</p> -<div class="example"> -<pre class="example">(treesit-query-capture node query) - ⇒ ((biexp . <var><node for "1 + 2"></var>) - (number-in-exp . <var><node for "1"></var>) - (number-in-exp . <var><node for "2"></var>)) -</pre></div> - -<p>As mentioned earlier, <var>query</var> could contain multiple patterns. -For example, it could have two top-level patterns: -</p> -<div class="example"> -<pre class="example">(setq query - "(binary_expression) @biexp - (number_literal) @number @biexp") -</pre></div> - -<dl class="def"> -<dt id="index-treesit_002dquery_002dstring"><span class="category">Function: </span><span><strong>treesit-query-string</strong> <em>string query language</em><a href='#index-treesit_002dquery_002dstring' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function parses <var>string</var> with <var>language</var>, matches its -root node with <var>query</var>, and returns the result. -</p></dd></dl> - -<span id="More-query-syntax"></span><h3 class="heading">More query syntax</h3> - -<p>Besides node type and capture, tree-sitter’s pattern syntax can -express anonymous node, field name, wildcard, quantification, -grouping, alternation, anchor, and predicate. -</p> -<span id="Anonymous-node"></span><h4 class="subheading">Anonymous node</h4> - -<p>An anonymous node is written verbatim, surrounded by quotes. A -pattern matching (and capturing) keyword <code>return</code> would be -</p> -<div class="example"> -<pre class="example">"return" @keyword -</pre></div> - -<span id="Wild-card"></span><h4 class="subheading">Wild card</h4> - -<p>In a pattern, ‘<samp>(_)</samp>’ matches any named node, and ‘<samp>_</samp>’ matches -any named and anonymous node. For example, to capture any named child -of a <code>binary_expression</code> node, the pattern would be -</p> -<div class="example"> -<pre class="example">(binary_expression (_) @in_biexp) -</pre></div> - -<span id="Field-name"></span><h4 class="subheading">Field name</h4> - -<p>It is possible to capture child nodes that have specific field names. -In the pattern below, <code>declarator</code> and <code>body</code> are field -names, indicated by the colon following them. -</p> -<div class="example"> -<pre class="example">(function_definition - declarator: (_) @func-declarator - body: (_) @func-body) -</pre></div> - -<p>It is also possible to capture a node that doesn’t have a certain -field, say, a <code>function_definition</code> without a <code>body</code> field. -</p> -<div class="example"> -<pre class="example">(function_definition !body) @func-no-body -</pre></div> - -<span id="Quantify-node"></span><h4 class="subheading">Quantify node</h4> - -<span id="index-quantify-node_002c-tree_002dsitter"></span> -<p>Tree-sitter recognizes quantification operators ‘<samp>*</samp>’, ‘<samp>+</samp>’ and -‘<samp>?</samp>’. Their meanings are the same as in regular expressions: -‘<samp>*</samp>’ matches the preceding pattern zero or more times, ‘<samp>+</samp>’ -matches one or more times, and ‘<samp>?</samp>’ matches zero or one time. -</p> -<p>For example, the following pattern matches <code>type_declaration</code> -nodes that has <em>zero or more</em> <code>long</code> keyword. -</p> -<div class="example"> -<pre class="example">(type_declaration "long"*) @long-type -</pre></div> - -<p>The following pattern matches a type declaration that has zero or one -<code>long</code> keyword: -</p> -<div class="example"> -<pre class="example">(type_declaration "long"?) @long-type -</pre></div> - -<span id="Grouping"></span><h4 class="subheading">Grouping</h4> - -<p>Similar to groups in regular expression, we can bundle patterns into -groups and apply quantification operators to them. For example, to -express a comma separated list of identifiers, one could write -</p> -<div class="example"> -<pre class="example">(identifier) ("," (identifier))* -</pre></div> - -<span id="Alternation"></span><h4 class="subheading">Alternation</h4> - -<p>Again, similar to regular expressions, we can express “match anyone -from this group of patterns” in a pattern. The syntax is a list of -patterns enclosed in square brackets. For example, to capture some -keywords in C, the pattern would be -</p> -<div class="example"> -<pre class="example">[ - "return" - "break" - "if" - "else" -] @keyword -</pre></div> - -<span id="Anchor"></span><h4 class="subheading">Anchor</h4> - -<p>The anchor operator ‘<samp>.</samp>’ can be used to enforce juxtaposition, -i.e., to enforce two things to be directly next to each other. The -two “things” can be two nodes, or a child and the end of its parent. -For example, to capture the first child, the last child, or two -adjacent children: -</p> -<div class="example"> -<pre class="example">;; Anchor the child with the end of its parent. -(compound_expression (_) @last-child .) -</pre><pre class="example"> - -</pre><pre class="example">;; Anchor the child with the beginning of its parent. -(compound_expression . (_) @first-child) -</pre><pre class="example"> - -</pre><pre class="example">;; Anchor two adjacent children. -(compound_expression - (_) @prev-child - . - (_) @next-child) -</pre></div> - -<p>Note that the enforcement of juxtaposition ignores any anonymous -nodes. -</p> -<span id="Predicate"></span><h4 class="subheading">Predicate</h4> - -<p>It is possible to add predicate constraints to a pattern. For -example, with the following pattern: -</p> -<div class="example"> -<pre class="example">( - (array . (_) @first (_) @last .) - (#equal @first @last) -) -</pre></div> - -<p>tree-sitter only matches arrays where the first element equals to -the last element. To attach a predicate to a pattern, we need to -group them together. A predicate always starts with a ‘<samp>#</samp>’. -Currently there are two predicates, <code>#equal</code> and <code>#match</code>. -</p> -<dl class="def"> -<dt id="index-equal-1"><span class="category">Predicate: </span><span><strong>equal</strong> <em>arg1 arg2</em><a href='#index-equal-1' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>Matches if <var>arg1</var> equals to <var>arg2</var>. Arguments can be either -strings or capture names. Capture names represent the text that the -captured node spans in the buffer. -</p></dd></dl> - -<dl class="def"> -<dt id="index-match-1"><span class="category">Predicate: </span><span><strong>match</strong> <em>regexp capture-name</em><a href='#index-match-1' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>Matches if the text that <var>capture-name</var>’s node spans in the buffer -matches regular expression <var>regexp</var>. Matching is case-sensitive. -</p></dd></dl> - -<p>Note that a predicate can only refer to capture names that appear in -the same pattern. Indeed, it makes little sense to refer to capture -names in other patterns. -</p> -<span id="S_002dexpression-patterns"></span><h3 class="heading">S-expression patterns</h3> - -<span id="index-tree_002dsitter-patterns-as-sexps"></span> -<span id="index-patterns_002c-tree_002dsitter_002c-in-sexp-form"></span> -<p>Besides strings, Emacs provides a s-expression based syntax for -tree-sitter patterns. It largely resembles the string-based syntax. -For example, the following query -</p> -<div class="example"> -<pre class="example">(treesit-query-capture - node "(addition_expression - left: (_) @left - \"+\" @plus-sign - right: (_) @right) @addition - - [\"return\" \"break\"] @keyword") -</pre></div> - -<p>is equivalent to -</p> -<div class="example"> -<pre class="example">(treesit-query-capture - node '((addition_expression - left: (_) @left - "+" @plus-sign - right: (_) @right) @addition - - ["return" "break"] @keyword)) -</pre></div> - -<p>Most patterns can be written directly as strange but nevertheless -valid s-expressions. Only a few of them needs modification: -</p> -<ul> -<li> Anchor ‘<samp>.</samp>’ is written as <code>:anchor</code>. -</li><li> ‘<samp>?</samp>’ is written as ‘<samp>:?</samp>’. -</li><li> ‘<samp>*</samp>’ is written as ‘<samp>:*</samp>’. -</li><li> ‘<samp>+</samp>’ is written as ‘<samp>:+</samp>’. -</li><li> <code>#equal</code> is written as <code>:equal</code>. In general, predicates -change their ‘<samp>#</samp>’ to ‘<samp>:</samp>’. -</li></ul> - -<p>For example, -</p> -<div class="example"> -<pre class="example">"( - (compound_expression . (_) @first (_)* @rest) - (#match \"love\" @first) - )" -</pre></div> - -<p>is written in s-expression as -</p> -<div class="example"> -<pre class="example">'(( - (compound_expression :anchor (_) @first (_) :* @rest) - (:match "love" @first) - )) -</pre></div> - -<span id="Compiling-queries"></span><h3 class="heading">Compiling queries</h3> - -<span id="index-compiling-tree_002dsitter-queries"></span> -<span id="index-queries_002c-compiling"></span> -<p>If a query is intended to be used repeatedly, especially in tight -loops, it is important to compile that query, because a compiled query -is much faster than an uncompiled one. A compiled query can be used -anywhere a query is accepted. -</p> -<dl class="def"> -<dt id="index-treesit_002dquery_002dcompile"><span class="category">Function: </span><span><strong>treesit-query-compile</strong> <em>language query</em><a href='#index-treesit_002dquery_002dcompile' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function compiles <var>query</var> for <var>language</var> into a compiled -query object and returns it. -</p> -<p>This function raises the <code>treesit-query-error</code> error if -<var>query</var> is malformed. The signal data contains a description of -the specific error. You can use <code>treesit-query-validate</code> to -validate and debug the query. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dquery_002dlanguage"><span class="category">Function: </span><span><strong>treesit-query-language</strong> <em>query</em><a href='#index-treesit_002dquery_002dlanguage' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function return the language of <var>query</var>. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dquery_002dexpand"><span class="category">Function: </span><span><strong>treesit-query-expand</strong> <em>query</em><a href='#index-treesit_002dquery_002dexpand' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function converts the s-expression <var>query</var> into the string -format. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dpattern_002dexpand"><span class="category">Function: </span><span><strong>treesit-pattern-expand</strong> <em>pattern</em><a href='#index-treesit_002dpattern_002dexpand' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function converts the s-expression <var>pattern</var> into the string -format. -</p></dd></dl> - -<p>For more details, read the tree-sitter project’s documentation about -pattern-matching, which can be found at -<a href="https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries">https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries</a>. -</p> -</div> -<hr> -<div class="header"> -<p> -Next: <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>, Previous: <a href="Accessing-Node-Information.html">Accessing Node Information</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> -</div> - - - -</body> -</html> |