aboutsummaryrefslogtreecommitdiffstats
path: root/admin
diff options
context:
space:
mode:
authorEli Zaretskii2023-03-19 08:09:33 +0200
committerEli Zaretskii2023-03-19 08:09:33 +0200
commit0bebd0e5f09b6fbed2e54f9b8464e93bdd6ad11e (patch)
tree41d19f431cd3e1e293d9f9a8f829e84ad100fa63 /admin
parent6674c362ad94373dacd22b7fd426406539e8d957 (diff)
downloademacs-0bebd0e5f09b6fbed2e54f9b8464e93bdd6ad11e.tar.gz
emacs-0bebd0e5f09b6fbed2e54f9b8464e93bdd6ad11e.zip
; Remove 'build-module' and 'html-manual' directories from 'admin'
These files were temporarily in the repository and are no longer needed, once they fulfilled their job.
Diffstat (limited to 'admin')
-rw-r--r--admin/notes/tree-sitter/build-module/README17
-rwxr-xr-xadmin/notes/tree-sitter/build-module/batch.sh27
-rwxr-xr-xadmin/notes/tree-sitter/build-module/build.sh86
-rw-r--r--admin/notes/tree-sitter/html-manual/Accessing-Node.html205
-rw-r--r--admin/notes/tree-sitter/html-manual/Language-Definitions.html401
-rw-r--r--admin/notes/tree-sitter/html-manual/Multiple-Languages.html327
-rw-r--r--admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html247
-rw-r--r--admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html280
-rw-r--r--admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html125
-rw-r--r--admin/notes/tree-sitter/html-manual/Pattern-Matching.html450
-rw-r--r--admin/notes/tree-sitter/html-manual/Retrieving-Node.html420
-rw-r--r--admin/notes/tree-sitter/html-manual/Tree_002dsitter-C-API.html211
-rw-r--r--admin/notes/tree-sitter/html-manual/Using-Parser.html230
-rwxr-xr-xadmin/notes/tree-sitter/html-manual/build-manual.sh23
-rw-r--r--admin/notes/tree-sitter/html-manual/manual.css374
15 files changed, 0 insertions, 3423 deletions
diff --git a/admin/notes/tree-sitter/build-module/README b/admin/notes/tree-sitter/build-module/README
deleted file mode 100644
index 2fcb9778dae..00000000000
--- a/admin/notes/tree-sitter/build-module/README
+++ /dev/null
@@ -1,17 +0,0 @@
1To build the language definition for a particular language, run
2
3 ./build.sh <language>
4
5eg,
6
7 ./build.sh html
8
9The dynamic module will be in /dist directory
10
11To build all modules at once, run
12
13 ./batch.sh
14
15This gives you C, JSON, Go, HTML, Javascript, CSS, Python, Typescript
16(tsx), C# (csharp), C++ (cpp), Rust. More can be added to batch.sh
17unless it's directory structure is not standard. \ No newline at end of file
diff --git a/admin/notes/tree-sitter/build-module/batch.sh b/admin/notes/tree-sitter/build-module/batch.sh
deleted file mode 100755
index 58272c74549..00000000000
--- a/admin/notes/tree-sitter/build-module/batch.sh
+++ /dev/null
@@ -1,27 +0,0 @@
1#!/bin/bash
2
3languages=(
4 'bash'
5 'c'
6 'cmake'
7 'cpp'
8 'css'
9 'c-sharp'
10 'dockerfile'
11 'go'
12 'go-mod'
13 'html'
14 'javascript'
15 'json'
16 'python'
17 'rust'
18 'toml'
19 'tsx'
20 'typescript'
21 'yaml'
22)
23
24for language in "${languages[@]}"
25do
26 ./build.sh $language
27done
diff --git a/admin/notes/tree-sitter/build-module/build.sh b/admin/notes/tree-sitter/build-module/build.sh
deleted file mode 100755
index 9dc674237ca..00000000000
--- a/admin/notes/tree-sitter/build-module/build.sh
+++ /dev/null
@@ -1,86 +0,0 @@
1#!/bin/bash
2
3lang=$1
4topdir="$PWD"
5
6case $(uname) in
7 "Darwin")
8 soext="dylib"
9 ;;
10 *"MINGW"*)
11 soext="dll"
12 ;;
13 *)
14 soext="so"
15 ;;
16esac
17
18echo "Building ${lang}"
19
20### Retrieve sources
21
22org="tree-sitter"
23repo="tree-sitter-${lang}"
24sourcedir="tree-sitter-${lang}/src"
25grammardir="tree-sitter-${lang}"
26
27case "${lang}" in
28 "dockerfile")
29 org="camdencheek"
30 ;;
31 "cmake")
32 org="uyha"
33 ;;
34 "go-mod")
35 # The parser is called "gomod".
36 lang="gomod"
37 org="camdencheek"
38 ;;
39 "typescript")
40 sourcedir="tree-sitter-typescript/typescript/src"
41 grammardir="tree-sitter-typescript/typescript"
42 ;;
43 "tsx")
44 repo="tree-sitter-typescript"
45 sourcedir="tree-sitter-typescript/tsx/src"
46 grammardir="tree-sitter-typescript/tsx"
47 ;;
48 "yaml")
49 org="ikatyang"
50 ;;
51esac
52
53git clone "https://github.com/${org}/${repo}.git" \
54 --depth 1 --quiet
55cp "${grammardir}"/grammar.js "${sourcedir}"
56# We have to go into the source directory to compile, because some
57# C files refer to files like "../../common/scanner.h".
58cd "${sourcedir}"
59
60### Build
61
62cc -fPIC -c -I. parser.c
63# Compile scanner.c.
64if test -f scanner.c
65then
66 cc -fPIC -c -I. scanner.c
67fi
68# Compile scanner.cc.
69if test -f scanner.cc
70then
71 c++ -fPIC -I. -c scanner.cc
72fi
73# Link.
74if test -f scanner.cc
75then
76 c++ -fPIC -shared *.o -o "libtree-sitter-${lang}.${soext}"
77else
78 cc -fPIC -shared *.o -o "libtree-sitter-${lang}.${soext}"
79fi
80
81### Copy out
82
83mkdir -p "${topdir}/dist"
84cp "libtree-sitter-${lang}.${soext}" "${topdir}/dist"
85cd "${topdir}"
86rm -rf "${repo}"
diff --git a/admin/notes/tree-sitter/html-manual/Accessing-Node.html b/admin/notes/tree-sitter/html-manual/Accessing-Node.html
deleted file mode 100644
index afbbdaa11b5..00000000000
--- a/admin/notes/tree-sitter/html-manual/Accessing-Node.html
+++ /dev/null
@@ -1,205 +0,0 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6<!-- This is the GNU Emacs Lisp Reference Manual
7corresponding to Emacs version 29.0.50.
8
9Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
10
11Permission is granted to copy, distribute and/or modify this document
12under the terms of the GNU Free Documentation License, Version 1.3 or
13any later version published by the Free Software Foundation; with the
14Invariant Sections being "GNU General Public License," with the
15Front-Cover Texts being "A GNU Manual," and with the Back-Cover
16Texts as in (a) below. A copy of the license is included in the
17section entitled "GNU Free Documentation License."
18
19(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
20modify this GNU manual. Buying copies from the FSF supports it in
21developing GNU and promoting software freedom." -->
22<title>Accessing Node (GNU Emacs Lisp Reference Manual)</title>
23
24<meta name="description" content="Accessing Node (GNU Emacs Lisp Reference Manual)">
25<meta name="keywords" content="Accessing Node (GNU Emacs Lisp Reference Manual)">
26<meta name="resource-type" content="document">
27<meta name="distribution" content="global">
28<meta name="Generator" content="makeinfo">
29<meta name="viewport" content="width=device-width,initial-scale=1">
30
31<link href="index.html" rel="start" title="Top">
32<link href="Index.html" rel="index" title="Index">
33<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
34<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
35<link href="Pattern-Matching.html" rel="next" title="Pattern Matching">
36<link href="Retrieving-Node.html" rel="prev" title="Retrieving Node">
37<style type="text/css">
38<!--
39a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
40a.summary-letter {text-decoration: none}
41blockquote.indentedblock {margin-right: 0em}
42div.display {margin-left: 3.2em}
43div.example {margin-left: 3.2em}
44kbd {font-style: oblique}
45pre.display {font-family: inherit}
46pre.format {font-family: inherit}
47pre.menu-comment {font-family: serif}
48pre.menu-preformatted {font-family: serif}
49span.nolinebreak {white-space: nowrap}
50span.roman {font-family: initial; font-weight: normal}
51span.sansserif {font-family: sans-serif; font-weight: normal}
52span:hover a.copiable-anchor {visibility: visible}
53ul.no-bullet {list-style: none}
54-->
55</style>
56<link rel="stylesheet" type="text/css" href="./manual.css">
57
58
59</head>
60
61<body lang="en">
62<div class="section" id="Accessing-Node">
63<div class="header">
64<p>
65Next: <a href="Pattern-Matching.html" accesskey="n" rel="next">Pattern Matching Tree-sitter Nodes</a>, Previous: <a href="Retrieving-Node.html" accesskey="p" rel="prev">Retrieving Node</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<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>
66</div>
67<hr>
68<span id="Accessing-Node-Information"></span><h3 class="section">37.4 Accessing Node Information</h3>
69
70<p>Before going further, make sure you have read the basic conventions
71about tree-sitter nodes in the previous node.
72</p>
73<span id="Basic-information"></span><h3 class="heading">Basic information</h3>
74
75<p>Every node is associated with a parser, and that parser is associated
76with a buffer. The following functions let you retrieve them.
77</p>
78<dl class="def">
79<dt id="index-treesit_002dnode_002dparser"><span class="category">Function: </span><span><strong>treesit-node-parser</strong> <em>node</em><a href='#index-treesit_002dnode_002dparser' class='copiable-anchor'> &para;</a></span></dt>
80<dd><p>This function returns <var>node</var>&rsquo;s associated parser.
81</p></dd></dl>
82
83<dl class="def">
84<dt id="index-treesit_002dnode_002dbuffer"><span class="category">Function: </span><span><strong>treesit-node-buffer</strong> <em>node</em><a href='#index-treesit_002dnode_002dbuffer' class='copiable-anchor'> &para;</a></span></dt>
85<dd><p>This function returns <var>node</var>&rsquo;s parser&rsquo;s associated buffer.
86</p></dd></dl>
87
88<dl class="def">
89<dt id="index-treesit_002dnode_002dlanguage"><span class="category">Function: </span><span><strong>treesit-node-language</strong> <em>node</em><a href='#index-treesit_002dnode_002dlanguage' class='copiable-anchor'> &para;</a></span></dt>
90<dd><p>This function returns <var>node</var>&rsquo;s parser&rsquo;s associated language.
91</p></dd></dl>
92
93<p>Each node represents a piece of text in the buffer. Functions below
94finds relevant information about that text.
95</p>
96<dl class="def">
97<dt id="index-treesit_002dnode_002dstart"><span class="category">Function: </span><span><strong>treesit-node-start</strong> <em>node</em><a href='#index-treesit_002dnode_002dstart' class='copiable-anchor'> &para;</a></span></dt>
98<dd><p>Return the start position of <var>node</var>.
99</p></dd></dl>
100
101<dl class="def">
102<dt id="index-treesit_002dnode_002dend"><span class="category">Function: </span><span><strong>treesit-node-end</strong> <em>node</em><a href='#index-treesit_002dnode_002dend' class='copiable-anchor'> &para;</a></span></dt>
103<dd><p>Return the end position of <var>node</var>.
104</p></dd></dl>
105
106<dl class="def">
107<dt id="index-treesit_002dnode_002dtext"><span class="category">Function: </span><span><strong>treesit-node-text</strong> <em>node &amp;optional object</em><a href='#index-treesit_002dnode_002dtext' class='copiable-anchor'> &para;</a></span></dt>
108<dd><p>Returns the buffer text that <var>node</var> represents. (If <var>node</var> is
109retrieved from parsing a string, it will be text from that string.)
110</p></dd></dl>
111
112<p>Here are some basic checks on tree-sitter nodes.
113</p>
114<dl class="def">
115<dt id="index-treesit_002dnode_002dp"><span class="category">Function: </span><span><strong>treesit-node-p</strong> <em>object</em><a href='#index-treesit_002dnode_002dp' class='copiable-anchor'> &para;</a></span></dt>
116<dd><p>Checks if <var>object</var> is a tree-sitter syntax node.
117</p></dd></dl>
118
119<dl class="def">
120<dt id="index-treesit_002dnode_002deq"><span class="category">Function: </span><span><strong>treesit-node-eq</strong> <em>node1 node2</em><a href='#index-treesit_002dnode_002deq' class='copiable-anchor'> &para;</a></span></dt>
121<dd><p>Checks if <var>node1</var> and <var>node2</var> are the same node in a syntax
122tree.
123</p></dd></dl>
124
125<span id="Property-information"></span><h3 class="heading">Property information</h3>
126
127<p>In general, nodes in a concrete syntax tree fall into two categories:
128<em>named nodes</em> and <em>anonymous nodes</em>. Whether a node is named
129or anonymous is determined by the language definition
130(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
131</p>
132<span id="index-tree_002dsitter-missing-node"></span>
133<p>Apart from being named/anonymous, a node can have other properties. A
134node can be &ldquo;missing&rdquo;: missing nodes are inserted by the parser in
135order to recover from certain kinds of syntax errors, i.e., something
136should probably be there according to the grammar, but not there.
137</p>
138<span id="index-tree_002dsitter-extra-node"></span>
139<p>A node can be &ldquo;extra&rdquo;: extra nodes represent things like comments,
140which can appear anywhere in the text.
141</p>
142<span id="index-tree_002dsitter-node-that-has-changes"></span>
143<p>A node &ldquo;has changes&rdquo; if the buffer changed since when the node is
144retrieved, i.e., outdated.
145</p>
146<span id="index-tree_002dsitter-node-that-has-error"></span>
147<p>A node &ldquo;has error&rdquo; if the text it spans contains a syntax error. It
148can be the node itself has an error, or one of its
149children/grandchildren... has an error.
150</p>
151<dl class="def">
152<dt id="index-treesit_002dnode_002dcheck"><span class="category">Function: </span><span><strong>treesit-node-check</strong> <em>node property</em><a href='#index-treesit_002dnode_002dcheck' class='copiable-anchor'> &para;</a></span></dt>
153<dd><p>This function checks if <var>node</var> has <var>property</var>. <var>property</var>
154can be <code>'named</code>, <code>'missing</code>, <code>'extra</code>,
155<code>'has-changes</code>, or <code>'has-error</code>.
156</p></dd></dl>
157
158
159<dl class="def">
160<dt id="index-treesit_002dnode_002dtype"><span class="category">Function: </span><span><strong>treesit-node-type</strong> <em>node</em><a href='#index-treesit_002dnode_002dtype' class='copiable-anchor'> &para;</a></span></dt>
161<dd><p>Named nodes have &ldquo;types&rdquo; (see <a href="Language-Definitions.html#tree_002dsitter-node-type">node type</a>).
162For example, a named node can be a <code>string_literal</code> node, where
163<code>string_literal</code> is its type.
164</p>
165<p>This function returns <var>node</var>&rsquo;s type as a string.
166</p></dd></dl>
167
168<span id="Information-as-a-child-or-parent"></span><h3 class="heading">Information as a child or parent</h3>
169
170<dl class="def">
171<dt id="index-treesit_002dnode_002dindex"><span class="category">Function: </span><span><strong>treesit-node-index</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dnode_002dindex' class='copiable-anchor'> &para;</a></span></dt>
172<dd><p>This function returns the index of <var>node</var> as a child node of its
173parent. If <var>named</var> is non-nil, it only count named nodes
174(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
175</p></dd></dl>
176
177<dl class="def">
178<dt id="index-treesit_002dnode_002dfield_002dname"><span class="category">Function: </span><span><strong>treesit-node-field-name</strong> <em>node</em><a href='#index-treesit_002dnode_002dfield_002dname' class='copiable-anchor'> &para;</a></span></dt>
179<dd><p>A child of a parent node could have a field name (see <a href="Language-Definitions.html#tree_002dsitter-node-field-name">field name</a>). This function returns the field name
180of <var>node</var> as a child of its parent.
181</p></dd></dl>
182
183<dl class="def">
184<dt id="index-treesit_002dnode_002dfield_002dname_002dfor_002dchild"><span class="category">Function: </span><span><strong>treesit-node-field-name-for-child</strong> <em>node n</em><a href='#index-treesit_002dnode_002dfield_002dname_002dfor_002dchild' class='copiable-anchor'> &para;</a></span></dt>
185<dd><p>This function returns the field name of the <var>n</var>&rsquo;th child of
186<var>node</var>.
187</p></dd></dl>
188
189<dl class="def">
190<dt id="index-treesit_002dchild_002dcount"><span class="category">Function: </span><span><strong>treesit-node-child-count</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dchild_002dcount' class='copiable-anchor'> &para;</a></span></dt>
191<dd><p>This function finds the number of children of <var>node</var>. If
192<var>named</var> is non-nil, it only counts named child (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
193</p></dd></dl>
194
195</div>
196<hr>
197<div class="header">
198<p>
199Next: <a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>, Previous: <a href="Retrieving-Node.html">Retrieving Node</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<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>
200</div>
201
202
203
204</body>
205</html>
diff --git a/admin/notes/tree-sitter/html-manual/Language-Definitions.html b/admin/notes/tree-sitter/html-manual/Language-Definitions.html
deleted file mode 100644
index 9b1e0021272..00000000000
--- a/admin/notes/tree-sitter/html-manual/Language-Definitions.html
+++ /dev/null
@@ -1,401 +0,0 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6<!-- This is the GNU Emacs Lisp Reference Manual
7corresponding to Emacs version 29.0.50.
8
9Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
10
11Permission is granted to copy, distribute and/or modify this document
12under the terms of the GNU Free Documentation License, Version 1.3 or
13any later version published by the Free Software Foundation; with the
14Invariant Sections being "GNU General Public License," with the
15Front-Cover Texts being "A GNU Manual," and with the Back-Cover
16Texts as in (a) below. A copy of the license is included in the
17section entitled "GNU Free Documentation License."
18
19(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
20modify this GNU manual. Buying copies from the FSF supports it in
21developing GNU and promoting software freedom." -->
22<title>Language Definitions (GNU Emacs Lisp Reference Manual)</title>
23
24<meta name="description" content="Language Definitions (GNU Emacs Lisp Reference Manual)">
25<meta name="keywords" content="Language Definitions (GNU Emacs Lisp Reference Manual)">
26<meta name="resource-type" content="document">
27<meta name="distribution" content="global">
28<meta name="Generator" content="makeinfo">
29<meta name="viewport" content="width=device-width,initial-scale=1">
30
31<link href="index.html" rel="start" title="Top">
32<link href="Index.html" rel="index" title="Index">
33<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
34<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
35<link href="Using-Parser.html" rel="next" title="Using Parser">
36<style type="text/css">
37<!--
38a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
39a.summary-letter {text-decoration: none}
40blockquote.indentedblock {margin-right: 0em}
41div.display {margin-left: 3.2em}
42div.example {margin-left: 3.2em}
43kbd {font-style: oblique}
44pre.display {font-family: inherit}
45pre.format {font-family: inherit}
46pre.menu-comment {font-family: serif}
47pre.menu-preformatted {font-family: serif}
48span.nolinebreak {white-space: nowrap}
49span.roman {font-family: initial; font-weight: normal}
50span.sansserif {font-family: sans-serif; font-weight: normal}
51span:hover a.copiable-anchor {visibility: visible}
52ul.no-bullet {list-style: none}
53-->
54</style>
55<link rel="stylesheet" type="text/css" href="./manual.css">
56
57
58</head>
59
60<body lang="en">
61<div class="section" id="Language-Definitions">
62<div class="header">
63<p>
64Next: <a href="Using-Parser.html" accesskey="n" rel="next">Using Tree-sitter Parser</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<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>
65</div>
66<hr>
67<span id="Tree_002dsitter-Language-Definitions"></span><h3 class="section">37.1 Tree-sitter Language Definitions</h3>
68<span id="index-language-definitions_002c-for-tree_002dsitter"></span>
69
70<span id="Loading-a-language-definition"></span><h3 class="heading">Loading a language definition</h3>
71<span id="index-loading-language-definition-for-tree_002dsitter"></span>
72
73<span id="index-language-argument_002c-for-tree_002dsitter"></span>
74<p>Tree-sitter relies on language definitions to parse text in that
75language. In Emacs, a language definition is represented by a symbol.
76For example, the C language definition is represented as the symbol
77<code>c</code>, and <code>c</code> can be passed to tree-sitter functions as the
78<var>language</var> argument.
79</p>
80<span id="index-treesit_002dextra_002dload_002dpath"></span>
81<span id="index-treesit_002dload_002dlanguage_002derror"></span>
82<span id="index-treesit_002dload_002dsuffixes"></span>
83<p>Tree-sitter language definitions are distributed as dynamic libraries.
84In order to use a language definition in Emacs, you need to make sure
85that the dynamic library is installed on the system. Emacs looks for
86language definitions in several places, in the following order:
87</p>
88<ul>
89<li> first, in the list of directories specified by the variable
90<code>treesit-extra-load-path</code>;
91</li><li> then, in the <samp>tree-sitter</samp> subdirectory of the directory
92specified by <code>user-emacs-directory</code> (see <a href="Init-File.html">The Init File</a>);
93</li><li> and finally, in the system&rsquo;s default locations for dynamic libraries.
94</li></ul>
95
96<p>In each of these directories, Emacs looks for a file with file-name
97extensions specified by the variable <code>dynamic-library-suffixes</code>.
98</p>
99<p>If Emacs cannot find the library or has problems loading it, Emacs
100signals the <code>treesit-load-language-error</code> error. The data of
101that signal could be one of the following:
102</p>
103<dl compact="compact">
104<dt><span><code>(not-found <var>error-msg</var> &hellip;)</code></span></dt>
105<dd><p>This means that Emacs could not find the language definition library.
106</p></dd>
107<dt><span><code>(symbol-error <var>error-msg</var>)</code></span></dt>
108<dd><p>This means that Emacs could not find in the library the expected function
109that every language definition library should export.
110</p></dd>
111<dt><span><code>(version-mismatch <var>error-msg</var>)</code></span></dt>
112<dd><p>This means that the version of language definition library is incompatible
113with that of the tree-sitter library.
114</p></dd>
115</dl>
116
117<p>In all of these cases, <var>error-msg</var> might provide additional
118details about the failure.
119</p>
120<dl class="def">
121<dt id="index-treesit_002dlanguage_002davailable_002dp"><span class="category">Function: </span><span><strong>treesit-language-available-p</strong> <em>language &amp;optional detail</em><a href='#index-treesit_002dlanguage_002davailable_002dp' class='copiable-anchor'> &para;</a></span></dt>
122<dd><p>This function returns non-<code>nil</code> if the language definitions for
123<var>language</var> exist and can be loaded.
124</p>
125<p>If <var>detail</var> is non-<code>nil</code>, return <code>(t . nil)</code> when
126<var>language</var> is available, and <code>(nil . <var>data</var>)</code> when it&rsquo;s
127unavailable. <var>data</var> is the signal data of
128<code>treesit-load-language-error</code>.
129</p></dd></dl>
130
131<span id="index-treesit_002dload_002dname_002doverride_002dlist"></span>
132<p>By convention, the file name of the dynamic library for <var>language</var> is
133<samp>libtree-sitter-<var>language</var>.<var>ext</var></samp>, where <var>ext</var> is the
134system-specific extension for dynamic libraries. Also by convention,
135the function provided by that library is named
136<code>tree_sitter_<var>language</var></code>. If a language definition library
137doesn&rsquo;t follow this convention, you should add an entry
138</p>
139<div class="example">
140<pre class="example">(<var>language</var> <var>library-base-name</var> <var>function-name</var>)
141</pre></div>
142
143<p>to the list in the variable <code>treesit-load-name-override-list</code>, where
144<var>library-base-name</var> is the basename of the dynamic library&rsquo;s file name,
145(usually, <samp>libtree-sitter-<var>language</var></samp>), and
146<var>function-name</var> is the function provided by the library
147(usually, <code>tree_sitter_<var>language</var></code>). For example,
148</p>
149<div class="example">
150<pre class="example">(cool-lang &quot;libtree-sitter-coool&quot; &quot;tree_sitter_cooool&quot;)
151</pre></div>
152
153<p>for a language that considers itself too &ldquo;cool&rdquo; to abide by
154conventions.
155</p>
156<span id="index-language_002ddefinition-version_002c-compatibility"></span>
157<dl class="def">
158<dt id="index-treesit_002dlanguage_002dversion"><span class="category">Function: </span><span><strong>treesit-language-version</strong> <em>&amp;optional min-compatible</em><a href='#index-treesit_002dlanguage_002dversion' class='copiable-anchor'> &para;</a></span></dt>
159<dd><p>This function returns the version of the language-definition
160Application Binary Interface (<acronym>ABI</acronym>) supported by the
161tree-sitter library. By default, it returns the latest ABI version
162supported by the library, but if <var>min-compatible</var> is
163non-<code>nil</code>, it returns the oldest ABI version which the library
164still can support. Language definition libraries must be built for
165ABI versions between the oldest and the latest versions supported by
166the tree-sitter library, otherwise the library will be unable to load
167them.
168</p></dd></dl>
169
170<span id="Concrete-syntax-tree"></span><h3 class="heading">Concrete syntax tree</h3>
171<span id="index-syntax-tree_002c-concrete"></span>
172
173<p>A syntax tree is what a parser generates. In a syntax tree, each node
174represents a piece of text, and is connected to each other by a
175parent-child relationship. For example, if the source text is
176</p>
177<div class="example">
178<pre class="example">1 + 2
179</pre></div>
180
181<p>its syntax tree could be
182</p>
183<div class="example">
184<pre class="example"> +--------------+
185 | root &quot;1 + 2&quot; |
186 +--------------+
187 |
188 +--------------------------------+
189 | expression &quot;1 + 2&quot; |
190 +--------------------------------+
191 | | |
192+------------+ +--------------+ +------------+
193| number &quot;1&quot; | | operator &quot;+&quot; | | number &quot;2&quot; |
194+------------+ +--------------+ +------------+
195</pre></div>
196
197<p>We can also represent it as an s-expression:
198</p>
199<div class="example">
200<pre class="example">(root (expression (number) (operator) (number)))
201</pre></div>
202
203<span id="Node-types"></span><h4 class="subheading">Node types</h4>
204<span id="index-node-types_002c-in-a-syntax-tree"></span>
205
206<span id="index-type-of-node_002c-tree_002dsitter"></span>
207<span id="tree_002dsitter-node-type"></span><span id="index-named-node_002c-tree_002dsitter"></span>
208<span id="tree_002dsitter-named-node"></span><span id="index-anonymous-node_002c-tree_002dsitter"></span>
209<p>Names like <code>root</code>, <code>expression</code>, <code>number</code>, and
210<code>operator</code> specify the <em>type</em> of the nodes. However, not all
211nodes in a syntax tree have a type. Nodes that don&rsquo;t have a type are
212known as <em>anonymous nodes</em>, and nodes with a type are <em>named
213nodes</em>. Anonymous nodes are tokens with fixed spellings, including
214punctuation characters like bracket &lsquo;<samp>]</samp>&rsquo;, and keywords like
215<code>return</code>.
216</p>
217<span id="Field-names"></span><h4 class="subheading">Field names</h4>
218
219<span id="index-field-name_002c-tree_002dsitter"></span>
220<span id="index-tree_002dsitter-node-field-name"></span>
221<span id="tree_002dsitter-node-field-name"></span><p>To make the syntax tree easier to analyze, many language definitions
222assign <em>field names</em> to child nodes. For example, a
223<code>function_definition</code> node could have a <code>declarator</code> and a
224<code>body</code>:
225</p>
226<div class="example">
227<pre class="example">(function_definition
228 declarator: (declaration)
229 body: (compound_statement))
230</pre></div>
231
232<span id="Exploring-the-syntax-tree"></span><h3 class="heading">Exploring the syntax tree</h3>
233<span id="index-explore-tree_002dsitter-syntax-tree"></span>
234<span id="index-inspection-of-tree_002dsitter-parse-tree-nodes"></span>
235
236<p>To aid in understanding the syntax of a language and in debugging of
237Lisp program that use the syntax tree, Emacs provides an &ldquo;explore&rdquo;
238mode, which displays the syntax tree of the source in the current
239buffer in real time. Emacs also comes with an &ldquo;inspect mode&rdquo;, which
240displays information of the nodes at point in the mode-line.
241</p>
242<dl class="def">
243<dt id="index-treesit_002dexplore_002dmode"><span class="category">Command: </span><span><strong>treesit-explore-mode</strong><a href='#index-treesit_002dexplore_002dmode' class='copiable-anchor'> &para;</a></span></dt>
244<dd><p>This mode pops up a window displaying the syntax tree of the source in
245the current buffer. Selecting text in the source buffer highlights
246the corresponding nodes in the syntax tree display. Clicking
247on nodes in the syntax tree highlights the corresponding text in the
248source buffer.
249</p></dd></dl>
250
251<dl class="def">
252<dt id="index-treesit_002dinspect_002dmode"><span class="category">Command: </span><span><strong>treesit-inspect-mode</strong><a href='#index-treesit_002dinspect_002dmode' class='copiable-anchor'> &para;</a></span></dt>
253<dd><p>This minor mode displays on the mode-line the node that <em>starts</em>
254at point. For example, the mode-line can display
255</p>
256<div class="example">
257<pre class="example"><var>parent</var> <var>field</var>: (<var>node</var> (<var>child</var> (&hellip;)))
258</pre></div>
259
260<p>where <var>node</var>, <var>child</var>, etc., are nodes which begin at point.
261<var>parent</var> is the parent of <var>node</var>. <var>node</var> is displayed in
262a bold typeface. <var>field-name</var>s are field names of <var>node</var> and
263of <var>child</var>, etc.
264</p>
265<p>If no node starts at point, i.e., point is in the middle of a node,
266then the mode line displays the earliest node that spans point, and
267its immediate parent.
268</p>
269<p>This minor mode doesn&rsquo;t create parsers on its own. It uses the first
270parser in <code>(treesit-parser-list)</code> (see <a href="Using-Parser.html">Using Tree-sitter Parser</a>).
271</p></dd></dl>
272
273<span id="Reading-the-grammar-definition"></span><h3 class="heading">Reading the grammar definition</h3>
274<span id="index-reading-grammar-definition_002c-tree_002dsitter"></span>
275
276<p>Authors of language definitions define the <em>grammar</em> of a
277programming language, which determines how a parser constructs a
278concrete syntax tree out of the program text. In order to use the
279syntax tree effectively, you need to consult the <em>grammar file</em>.
280</p>
281<p>The grammar file is usually <samp>grammar.js</samp> in a language
282definition&rsquo;s project repository. The link to a language definition&rsquo;s
283home page can be found on
284<a href="https://tree-sitter.github.io/tree-sitter">tree-sitter&rsquo;s
285homepage</a>.
286</p>
287<p>The grammar definition is written in JavaScript. For example, the
288rule matching a <code>function_definition</code> node looks like
289</p>
290<div class="example">
291<pre class="example">function_definition: $ =&gt; seq(
292 $.declaration_specifiers,
293 field('declarator', $.declaration),
294 field('body', $.compound_statement)
295)
296</pre></div>
297
298<p>The rules are represented by functions that take a single argument
299<var>$</var>, representing the whole grammar. The function itself is
300constructed by other functions: the <code>seq</code> function puts together
301a sequence of children; the <code>field</code> function annotates a child
302with a field name. If we write the above definition in the so-called
303<em>Backus-Naur Form</em> (<acronym>BNF</acronym>) syntax, it would look like
304</p>
305<div class="example">
306<pre class="example">function_definition :=
307 &lt;declaration_specifiers&gt; &lt;declaration&gt; &lt;compound_statement&gt;
308</pre></div>
309
310<p>and the node returned by the parser would look like
311</p>
312<div class="example">
313<pre class="example">(function_definition
314 (declaration_specifier)
315 declarator: (declaration)
316 body: (compound_statement))
317</pre></div>
318
319<p>Below is a list of functions that one can see in a grammar definition.
320Each function takes other rules as arguments and returns a new rule.
321</p>
322<dl compact="compact">
323<dt><span><code>seq(<var>rule1</var>, <var>rule2</var>, &hellip;)</code></span></dt>
324<dd><p>matches each rule one after another.
325</p></dd>
326<dt><span><code>choice(<var>rule1</var>, <var>rule2</var>, &hellip;)</code></span></dt>
327<dd><p>matches one of the rules in its arguments.
328</p></dd>
329<dt><span><code>repeat(<var>rule</var>)</code></span></dt>
330<dd><p>matches <var>rule</var> for <em>zero or more</em> times.
331This is like the &lsquo;<samp>*</samp>&rsquo; operator in regular expressions.
332</p></dd>
333<dt><span><code>repeat1(<var>rule</var>)</code></span></dt>
334<dd><p>matches <var>rule</var> for <em>one or more</em> times.
335This is like the &lsquo;<samp>+</samp>&rsquo; operator in regular expressions.
336</p></dd>
337<dt><span><code>optional(<var>rule</var>)</code></span></dt>
338<dd><p>matches <var>rule</var> for <em>zero or one</em> time.
339This is like the &lsquo;<samp>?</samp>&rsquo; operator in regular expressions.
340</p></dd>
341<dt><span><code>field(<var>name</var>, <var>rule</var>)</code></span></dt>
342<dd><p>assigns field name <var>name</var> to the child node matched by <var>rule</var>.
343</p></dd>
344<dt><span><code>alias(<var>rule</var>, <var>alias</var>)</code></span></dt>
345<dd><p>makes nodes matched by <var>rule</var> appear as <var>alias</var> in the syntax
346tree generated by the parser. For example,
347</p>
348<div class="example">
349<pre class="example">alias(preprocessor_call_exp, call_expression)
350</pre></div>
351
352<p>makes any node matched by <code>preprocessor_call_exp</code> appear as
353<code>call_expression</code>.
354</p></dd>
355</dl>
356
357<p>Below are grammar functions of lesser importance for reading a
358language definition.
359</p>
360<dl compact="compact">
361<dt><span><code>token(<var>rule</var>)</code></span></dt>
362<dd><p>marks <var>rule</var> to produce a single leaf node. That is, instead of
363generating a parent node with individual child nodes under it,
364everything is combined into a single leaf node. See <a href="Retrieving-Nodes.html">Retrieving Nodes</a>.
365</p></dd>
366<dt><span><code>token.immediate(<var>rule</var>)</code></span></dt>
367<dd><p>Normally, grammar rules ignore preceding whitespace; this
368changes <var>rule</var> to match only when there is no preceding
369whitespaces.
370</p></dd>
371<dt><span><code>prec(<var>n</var>, <var>rule</var>)</code></span></dt>
372<dd><p>gives <var>rule</var> the level-<var>n</var> precedence.
373</p></dd>
374<dt><span><code>prec.left([<var>n</var>,] <var>rule</var>)</code></span></dt>
375<dd><p>marks <var>rule</var> as left-associative, optionally with level <var>n</var>.
376</p></dd>
377<dt><span><code>prec.right([<var>n</var>,] <var>rule</var>)</code></span></dt>
378<dd><p>marks <var>rule</var> as right-associative, optionally with level <var>n</var>.
379</p></dd>
380<dt><span><code>prec.dynamic(<var>n</var>, <var>rule</var>)</code></span></dt>
381<dd><p>this is like <code>prec</code>, but the precedence is applied at runtime
382instead.
383</p></dd>
384</dl>
385
386<p>The documentation of the tree-sitter project has
387<a href="https://tree-sitter.github.io/tree-sitter/creating-parsers">more
388about writing a grammar</a>. Read especially &ldquo;The Grammar DSL&rdquo;
389section.
390</p>
391</div>
392<hr>
393<div class="header">
394<p>
395Next: <a href="Using-Parser.html">Using Tree-sitter Parser</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<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>
396</div>
397
398
399
400</body>
401</html>
diff --git a/admin/notes/tree-sitter/html-manual/Multiple-Languages.html b/admin/notes/tree-sitter/html-manual/Multiple-Languages.html
deleted file mode 100644
index 390d9082590..00000000000
--- a/admin/notes/tree-sitter/html-manual/Multiple-Languages.html
+++ /dev/null
@@ -1,327 +0,0 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6<!-- This is the GNU Emacs Lisp Reference Manual
7corresponding to Emacs version 29.0.50.
8
9Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
10
11Permission is granted to copy, distribute and/or modify this document
12under the terms of the GNU Free Documentation License, Version 1.3 or
13any later version published by the Free Software Foundation; with the
14Invariant Sections being "GNU General Public License," with the
15Front-Cover Texts being "A GNU Manual," and with the Back-Cover
16Texts as in (a) below. A copy of the license is included in the
17section entitled "GNU Free Documentation License."
18
19(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
20modify this GNU manual. Buying copies from the FSF supports it in
21developing GNU and promoting software freedom." -->
22<title>Multiple Languages (GNU Emacs Lisp Reference Manual)</title>
23
24<meta name="description" content="Multiple Languages (GNU Emacs Lisp Reference Manual)">
25<meta name="keywords" content="Multiple Languages (GNU Emacs Lisp Reference Manual)">
26<meta name="resource-type" content="document">
27<meta name="distribution" content="global">
28<meta name="Generator" content="makeinfo">
29<meta name="viewport" content="width=device-width,initial-scale=1">
30
31<link href="index.html" rel="start" title="Top">
32<link href="Index.html" rel="index" title="Index">
33<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
34<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
35<link href="Tree_002dsitter-major-modes.html" rel="next" title="Tree-sitter major modes">
36<link href="Pattern-Matching.html" rel="prev" title="Pattern Matching">
37<style type="text/css">
38<!--
39a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
40a.summary-letter {text-decoration: none}
41blockquote.indentedblock {margin-right: 0em}
42div.display {margin-left: 3.2em}
43div.example {margin-left: 3.2em}
44kbd {font-style: oblique}
45pre.display {font-family: inherit}
46pre.format {font-family: inherit}
47pre.menu-comment {font-family: serif}
48pre.menu-preformatted {font-family: serif}
49span.nolinebreak {white-space: nowrap}
50span.roman {font-family: initial; font-weight: normal}
51span.sansserif {font-family: sans-serif; font-weight: normal}
52span:hover a.copiable-anchor {visibility: visible}
53ul.no-bullet {list-style: none}
54-->
55</style>
56<link rel="stylesheet" type="text/css" href="./manual.css">
57
58
59</head>
60
61<body lang="en">
62<div class="section" id="Multiple-Languages">
63<div class="header">
64<p>
65Next: <a href="Tree_002dsitter-major-modes.html" accesskey="n" rel="next">Developing major modes with tree-sitter</a>, Previous: <a href="Pattern-Matching.html" accesskey="p" rel="prev">Pattern Matching Tree-sitter Nodes</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<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>
66</div>
67<hr>
68<span id="Parsing-Text-in-Multiple-Languages"></span><h3 class="section">37.6 Parsing Text in Multiple Languages</h3>
69<span id="index-multiple-languages_002c-parsing-with-tree_002dsitter"></span>
70<span id="index-parsing-multiple-languages-with-tree_002dsitter"></span>
71<p>Sometimes, the source of a programming language could contain snippets
72of other languages; <acronym>HTML</acronym> + <acronym>CSS</acronym> + JavaScript is one
73example. In that case, text segments written in different languages
74need to be assigned different parsers. Traditionally, this is
75achieved by using narrowing. While tree-sitter works with narrowing
76(see <a href="Using-Parser.html#tree_002dsitter-narrowing">narrowing</a>), the recommended way is
77instead to set regions of buffer text (i.e., ranges) in which a parser
78will operate. This section describes functions for setting and
79getting ranges for a parser.
80</p>
81<p>Lisp programs should call <code>treesit-update-ranges</code> to make sure
82the ranges for each parser are correct before using parsers in a
83buffer, and call <code>treesit-language-at</code> to figure out the language
84responsible for the text at some position. These two functions don&rsquo;t
85work by themselves, they need major modes to set
86<code>treesit-range-settings</code> and
87<code>treesit-language-at-point-function</code>, which do the actual work.
88These functions and variables are explained in more detail towards the
89end of the section.
90</p>
91<span id="Getting-and-setting-ranges"></span><h3 class="heading">Getting and setting ranges</h3>
92
93<dl class="def">
94<dt id="index-treesit_002dparser_002dset_002dincluded_002dranges"><span class="category">Function: </span><span><strong>treesit-parser-set-included-ranges</strong> <em>parser ranges</em><a href='#index-treesit_002dparser_002dset_002dincluded_002dranges' class='copiable-anchor'> &para;</a></span></dt>
95<dd><p>This function sets up <var>parser</var> to operate on <var>ranges</var>. The
96<var>parser</var> will only read the text of the specified ranges. Each
97range in <var>ranges</var> is a list of the form <code>(<var>beg</var>&nbsp;.&nbsp;<var>end</var>)</code><!-- /@w -->.
98</p>
99<p>The ranges in <var>ranges</var> must come in order and must not overlap.
100That is, in pseudo code:
101</p>
102<div class="example">
103<pre class="example">(cl-loop for idx from 1 to (1- (length ranges))
104 for prev = (nth (1- idx) ranges)
105 for next = (nth idx ranges)
106 should (&lt;= (car prev) (cdr prev)
107 (car next) (cdr next)))
108</pre></div>
109
110<span id="index-treesit_002drange_002dinvalid"></span>
111<p>If <var>ranges</var> violates this constraint, or something else went
112wrong, this function signals the <code>treesit-range-invalid</code> error.
113The signal data contains a specific error message and the ranges we
114are trying to set.
115</p>
116<p>This function can also be used for disabling ranges. If <var>ranges</var>
117is <code>nil</code>, the parser is set to parse the whole buffer.
118</p>
119<p>Example:
120</p>
121<div class="example">
122<pre class="example">(treesit-parser-set-included-ranges
123 parser '((1 . 9) (16 . 24) (24 . 25)))
124</pre></div>
125</dd></dl>
126
127<dl class="def">
128<dt id="index-treesit_002dparser_002dincluded_002dranges"><span class="category">Function: </span><span><strong>treesit-parser-included-ranges</strong> <em>parser</em><a href='#index-treesit_002dparser_002dincluded_002dranges' class='copiable-anchor'> &para;</a></span></dt>
129<dd><p>This function returns the ranges set for <var>parser</var>. The return
130value is the same as the <var>ranges</var> argument of
131<code>treesit-parser-included-ranges</code>: a list of cons cells of the form
132<code>(<var>beg</var>&nbsp;.&nbsp;<var>end</var>)</code><!-- /@w -->. If <var>parser</var> doesn&rsquo;t have any
133ranges, the return value is <code>nil</code>.
134</p>
135<div class="example">
136<pre class="example">(treesit-parser-included-ranges parser)
137 &rArr; ((1 . 9) (16 . 24) (24 . 25))
138</pre></div>
139</dd></dl>
140
141<dl class="def">
142<dt id="index-treesit_002dquery_002drange"><span class="category">Function: </span><span><strong>treesit-query-range</strong> <em>source query &amp;optional beg end</em><a href='#index-treesit_002dquery_002drange' class='copiable-anchor'> &para;</a></span></dt>
143<dd><p>This function matches <var>source</var> with <var>query</var> and returns the
144ranges of captured nodes. The return value is a list of cons cells of
145the form <code>(<var>beg</var>&nbsp;.&nbsp;<var>end</var>)</code><!-- /@w -->, where <var>beg</var> and
146<var>end</var> specify the beginning and the end of a region of text.
147</p>
148<p>For convenience, <var>source</var> can be a language symbol, a parser, or a
149node. If it&rsquo;s a language symbol, this function matches in the root
150node of the first parser using that language; if a parser, this
151function matches in the root node of that parser; if a node, this
152function matches in that node.
153</p>
154<p>The argument <var>query</var> is the query used to capture nodes
155(see <a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>). The capture names don&rsquo;t matter. The
156arguments <var>beg</var> and <var>end</var>, if both non-<code>nil</code>, limit the
157range in which this function queries.
158</p>
159<p>Like other query functions, this function raises the
160<code>treesit-query-error</code> error if <var>query</var> is malformed.
161</p></dd></dl>
162
163<span id="Supporting-multiple-languages-in-Lisp-programs"></span><h3 class="heading">Supporting multiple languages in Lisp programs</h3>
164
165<p>It should suffice for general Lisp programs to call the following two
166functions in order to support program sources that mixes multiple
167languages.
168</p>
169<dl class="def">
170<dt id="index-treesit_002dupdate_002dranges"><span class="category">Function: </span><span><strong>treesit-update-ranges</strong> <em>&amp;optional beg end</em><a href='#index-treesit_002dupdate_002dranges' class='copiable-anchor'> &para;</a></span></dt>
171<dd><p>This function updates ranges for parsers in the buffer. It makes sure
172the parsers&rsquo; ranges are set correctly between <var>beg</var> and <var>end</var>,
173according to <code>treesit-range-settings</code>. If omitted, <var>beg</var>
174defaults to the beginning of the buffer, and <var>end</var> defaults to the
175end of the buffer.
176</p>
177<p>For example, fontification functions use this function before querying
178for nodes in a region.
179</p></dd></dl>
180
181<dl class="def">
182<dt id="index-treesit_002dlanguage_002dat"><span class="category">Function: </span><span><strong>treesit-language-at</strong> <em>pos</em><a href='#index-treesit_002dlanguage_002dat' class='copiable-anchor'> &para;</a></span></dt>
183<dd><p>This function returns the language of the text at buffer position
184<var>pos</var>. Under the hood it calls
185<code>treesit-language-at-point-function</code> and returns its return
186value. If <code>treesit-language-at-point-function</code> is <code>nil</code>,
187this function returns the language of the first parser in the returned
188value of <code>treesit-parser-list</code>. If there is no parser in the
189buffer, it returns <code>nil</code>.
190</p></dd></dl>
191
192<span id="Supporting-multiple-languages-in-major-modes"></span><h3 class="heading">Supporting multiple languages in major modes</h3>
193
194<span id="index-host-language_002c-tree_002dsitter"></span>
195<span id="index-tree_002dsitter-host-and-embedded-languages"></span>
196<span id="index-embedded-language_002c-tree_002dsitter"></span>
197<p>Normally, in a set of languages that can be mixed together, there is a
198<em>host language</em> and one or more <em>embedded languages</em>. A Lisp
199program usually first parses the whole document with the host
200language&rsquo;s parser, retrieves some information, sets ranges for the
201embedded languages with that information, and then parses the embedded
202languages.
203</p>
204<p>Take a buffer containing <acronym>HTML</acronym>, <acronym>CSS</acronym> and JavaScript
205as an example. A Lisp program will first parse the whole buffer with
206an <acronym>HTML</acronym> parser, then query the parser for
207<code>style_element</code> and <code>script_element</code> nodes, which
208correspond to <acronym>CSS</acronym> and JavaScript text, respectively. Then
209it sets the range of the <acronym>CSS</acronym> and JavaScript parser to the
210ranges in which their corresponding nodes span.
211</p>
212<p>Given a simple <acronym>HTML</acronym> document:
213</p>
214<div class="example">
215<pre class="example">&lt;html&gt;
216 &lt;script&gt;1 + 2&lt;/script&gt;
217 &lt;style&gt;body { color: &quot;blue&quot;; }&lt;/style&gt;
218&lt;/html&gt;
219</pre></div>
220
221<p>a Lisp program will first parse with a <acronym>HTML</acronym> parser, then set
222ranges for <acronym>CSS</acronym> and JavaScript parsers:
223</p>
224<div class="example">
225<pre class="example">;; Create parsers.
226(setq html (treesit-parser-create 'html))
227(setq css (treesit-parser-create 'css))
228(setq js (treesit-parser-create 'javascript))
229</pre><pre class="example">
230
231</pre><pre class="example">;; Set CSS ranges.
232(setq css-range
233 (treesit-query-range
234 'html
235 &quot;(style_element (raw_text) @capture)&quot;))
236(treesit-parser-set-included-ranges css css-range)
237</pre><pre class="example">
238
239</pre><pre class="example">;; Set JavaScript ranges.
240(setq js-range
241 (treesit-query-range
242 'html
243 &quot;(script_element (raw_text) @capture)&quot;))
244(treesit-parser-set-included-ranges js js-range)
245</pre></div>
246
247<p>Emacs automates this process in <code>treesit-update-ranges</code>. A
248multi-language major mode should set <code>treesit-range-settings</code> so
249that <code>treesit-update-ranges</code> knows how to perform this process
250automatically. Major modes should use the helper function
251<code>treesit-range-rules</code> to generate a value that can be assigned to
252<code>treesit-range-settings</code>. The settings in the following example
253directly translate into operations shown above.
254</p>
255<div class="example">
256<pre class="example">(setq-local treesit-range-settings
257 (treesit-range-rules
258 :embed 'javascript
259 :host 'html
260 '((script_element (raw_text) @capture))
261</pre><pre class="example">
262
263</pre><pre class="example"> :embed 'css
264 :host 'html
265 '((style_element (raw_text) @capture))))
266</pre></div>
267
268<dl class="def">
269<dt id="index-treesit_002drange_002drules"><span class="category">Function: </span><span><strong>treesit-range-rules</strong> <em>&amp;rest query-specs</em><a href='#index-treesit_002drange_002drules' class='copiable-anchor'> &para;</a></span></dt>
270<dd><p>This function is used to set <var>treesit-range-settings</var>. It
271takes care of compiling queries and other post-processing, and outputs
272a value that <var>treesit-range-settings</var> can have.
273</p>
274<p>It takes a series of <var>query-spec</var>s, where each <var>query-spec</var> is
275a <var>query</var> preceded by zero or more <var>keyword</var>/<var>value</var>
276pairs. Each <var>query</var> is a tree-sitter query in either the
277string, s-expression or compiled form, or a function.
278</p>
279<p>If <var>query</var> is a tree-sitter query, it should be preceded by two
280<var>:keyword</var>/<var>value</var> pairs, where the <code>:embed</code> keyword
281specifies the embedded language, and the <code>:host</code> keyword
282specified the host language.
283</p>
284<p><code>treesit-update-ranges</code> uses <var>query</var> to figure out how to set
285the ranges for parsers for the embedded language. It queries
286<var>query</var> in a host language parser, computes the ranges in which
287the captured nodes span, and applies these ranges to embedded
288language parsers.
289</p>
290<p>If <var>query</var> is a function, it doesn&rsquo;t need any <var>:keyword</var> and
291<var>value</var> pair. It should be a function that takes 2 arguments,
292<var>start</var> and <var>end</var>, and sets the ranges for parsers in the
293current buffer in the region between <var>start</var> and <var>end</var>. It is
294fine for this function to set ranges in a larger region that
295encompasses the region between <var>start</var> and <var>end</var>.
296</p></dd></dl>
297
298<dl class="def">
299<dt id="index-treesit_002drange_002dsettings"><span class="category">Variable: </span><span><strong>treesit-range-settings</strong><a href='#index-treesit_002drange_002dsettings' class='copiable-anchor'> &para;</a></span></dt>
300<dd><p>This variable helps <code>treesit-update-ranges</code> in updating the
301ranges for parsers in the buffer. It is a list of <var>setting</var>s
302where the exact format of a <var>setting</var> is considered internal. You
303should use <code>treesit-range-rules</code> to generate a value that this
304variable can have.
305</p>
306</dd></dl>
307
308
309<dl class="def">
310<dt id="index-treesit_002dlanguage_002dat_002dpoint_002dfunction"><span class="category">Variable: </span><span><strong>treesit-language-at-point-function</strong><a href='#index-treesit_002dlanguage_002dat_002dpoint_002dfunction' class='copiable-anchor'> &para;</a></span></dt>
311<dd><p>This variable&rsquo;s value should be a function that takes a single
312argument, <var>pos</var>, which is a buffer position, and returns the
313language of the buffer text at <var>pos</var>. This variable is used by
314<code>treesit-language-at</code>.
315</p></dd></dl>
316
317</div>
318<hr>
319<div class="header">
320<p>
321Next: <a href="Tree_002dsitter-major-modes.html">Developing major modes with tree-sitter</a>, Previous: <a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<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>
322</div>
323
324
325
326</body>
327</html>
diff --git a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html b/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html
deleted file mode 100644
index a3fe6622162..00000000000
--- a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html
+++ /dev/null
@@ -1,247 +0,0 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6<!-- This is the GNU Emacs Lisp Reference Manual
7corresponding to Emacs version 29.0.50.
8
9Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
10
11Permission is granted to copy, distribute and/or modify this document
12under the terms of the GNU Free Documentation License, Version 1.3 or
13any later version published by the Free Software Foundation; with the
14Invariant Sections being "GNU General Public License," with the
15Front-Cover Texts being "A GNU Manual," and with the Back-Cover
16Texts as in (a) below. A copy of the license is included in the
17section entitled "GNU Free Documentation License."
18
19(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
20modify this GNU manual. Buying copies from the FSF supports it in
21developing GNU and promoting software freedom." -->
22<title>Parser-based Font Lock (GNU Emacs Lisp Reference Manual)</title>
23
24<meta name="description" content="Parser-based Font Lock (GNU Emacs Lisp Reference Manual)">
25<meta name="keywords" content="Parser-based Font Lock (GNU Emacs Lisp Reference Manual)">
26<meta name="resource-type" content="document">
27<meta name="distribution" content="global">
28<meta name="Generator" content="makeinfo">
29<meta name="viewport" content="width=device-width,initial-scale=1">
30
31<link href="index.html" rel="start" title="Top">
32<link href="Index.html" rel="index" title="Index">
33<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
34<link href="Font-Lock-Mode.html" rel="up" title="Font Lock Mode">
35<link href="Multiline-Font-Lock.html" rel="prev" title="Multiline Font Lock">
36<style type="text/css">
37<!--
38a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
39a.summary-letter {text-decoration: none}
40blockquote.indentedblock {margin-right: 0em}
41div.display {margin-left: 3.2em}
42div.example {margin-left: 3.2em}
43kbd {font-style: oblique}
44pre.display {font-family: inherit}
45pre.format {font-family: inherit}
46pre.menu-comment {font-family: serif}
47pre.menu-preformatted {font-family: serif}
48span.nolinebreak {white-space: nowrap}
49span.roman {font-family: initial; font-weight: normal}
50span.sansserif {font-family: sans-serif; font-weight: normal}
51span:hover a.copiable-anchor {visibility: visible}
52ul.no-bullet {list-style: none}
53-->
54</style>
55<link rel="stylesheet" type="text/css" href="./manual.css">
56
57
58</head>
59
60<body lang="en">
61<div class="subsection" id="Parser_002dbased-Font-Lock">
62<div class="header">
63<p>
64Previous: <a href="Multiline-Font-Lock.html" accesskey="p" rel="prev">Multiline Font Lock Constructs</a>, Up: <a href="Font-Lock-Mode.html" accesskey="u" rel="up">Font Lock Mode</a> &nbsp; [<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>
65</div>
66<hr>
67<span id="Parser_002dbased-Font-Lock-1"></span><h4 class="subsection">24.6.10 Parser-based Font Lock</h4>
68<span id="index-parser_002dbased-font_002dlock"></span>
69
70
71<p>Besides simple syntactic font lock and regexp-based font lock, Emacs
72also provides complete syntactic font lock with the help of a parser.
73Currently, Emacs uses the tree-sitter library (see <a href="Parsing-Program-Source.html">Parsing Program Source</a>) for this purpose.
74</p>
75<p>Parser-based font lock and other font lock mechanisms are not mutually
76exclusive. By default, if enabled, parser-based font lock runs first,
77replacing syntactic font lock, then the regexp-based font lock.
78</p>
79<p>Although parser-based font lock doesn&rsquo;t share the same customization
80variables with regexp-based font lock, it uses similar customization
81schemes. The tree-sitter counterpart of <var>font-lock-keywords</var> is
82<var>treesit-font-lock-settings</var>.
83</p>
84<span id="index-tree_002dsitter-fontifications_002c-overview"></span>
85<span id="index-fontifications-with-tree_002dsitter_002c-overview"></span>
86<p>In general, tree-sitter fontification works as follows:
87</p>
88<ul>
89<li> A Lisp program (usually, part of a major mode) provides a <em>query</em>
90consisting of <em>patterns</em>, each pattern associated with a
91<em>capture name</em>.
92
93</li><li> The tree-sitter library finds the nodes in the parse tree
94that match these patterns, tags the nodes with the corresponding
95capture names, and returns them to the Lisp program.
96
97</li><li> The Lisp program uses the returned nodes to highlight the portions of
98buffer text corresponding to each node as appropriate, using the
99tagged capture names of the nodes to determine the correct
100fontification. For example, a node tagged <code>font-lock-keyword</code>
101would be highlighted in <code>font-lock-keyword</code> face.
102</li></ul>
103
104<p>For more information about queries, patterns, and capture names, see
105<a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>.
106</p>
107<p>To setup tree-sitter fontification, a major mode should first set
108<code>treesit-font-lock-settings</code> with the output of
109<code>treesit-font-lock-rules</code>, then call
110<code>treesit-major-mode-setup</code>.
111</p>
112<dl class="def">
113<dt id="index-treesit_002dfont_002dlock_002drules"><span class="category">Function: </span><span><strong>treesit-font-lock-rules</strong> <em>&amp;rest query-specs</em><a href='#index-treesit_002dfont_002dlock_002drules' class='copiable-anchor'> &para;</a></span></dt>
114<dd><p>This function is used to set <var>treesit-font-lock-settings</var>. It
115takes care of compiling queries and other post-processing, and outputs
116a value that <var>treesit-font-lock-settings</var> accepts. Here&rsquo;s an
117example:
118</p>
119<div class="example">
120<pre class="example">(treesit-font-lock-rules
121 :language 'javascript
122 :feature 'constant
123 :override t
124 '((true) @font-lock-constant-face
125 (false) @font-lock-constant-face)
126 :language 'html
127 :feature 'script
128 &quot;(script_element) @font-lock-builtin-face&quot;)
129</pre></div>
130
131<p>This function takes a series of <var>query-spec</var>s, where each
132<var>query-spec</var> is a <var>query</var> preceded by one or more
133<var>:keyword</var>/<var>value</var> pairs. Each <var>query</var> is a
134tree-sitter query in either the string, s-expression or compiled form.
135</p>
136<p>For each <var>query</var>, the <var>:keyword</var>/<var>value</var> pairs that
137precede it add meta information to it. The <code>:language</code> keyword
138declares <var>query</var>&rsquo;s language. The <code>:feature</code> keyword sets the
139feature name of <var>query</var>. Users can control which features are
140enabled with <code>font-lock-maximum-decoration</code> and
141<code>treesit-font-lock-feature-list</code> (described below). These two
142keywords are mandatory.
143</p>
144<p>Other keywords are optional:
145</p>
146<table>
147<thead><tr><th width="15%">Keyword</th><th width="15%">Value</th><th width="60%">Description</th></tr></thead>
148<tr><td width="15%"><code>:override</code></td><td width="15%">nil</td><td width="60%">If the region already has a face, discard the new face</td></tr>
149<tr><td width="15%"></td><td width="15%">t</td><td width="60%">Always apply the new face</td></tr>
150<tr><td width="15%"></td><td width="15%"><code>append</code></td><td width="60%">Append the new face to existing ones</td></tr>
151<tr><td width="15%"></td><td width="15%"><code>prepend</code></td><td width="60%">Prepend the new face to existing ones</td></tr>
152<tr><td width="15%"></td><td width="15%"><code>keep</code></td><td width="60%">Fill-in regions without an existing face</td></tr>
153</table>
154
155<p>Lisp programs mark patterns in <var>query</var> with capture names (names
156that starts with <code>@</code>), and tree-sitter will return matched nodes
157tagged with those same capture names. For the purpose of
158fontification, capture names in <var>query</var> should be face names like
159<code>font-lock-keyword-face</code>. The captured node will be fontified
160with that face.
161</p>
162<span id="index-treesit_002dfontify_002dwith_002doverride"></span>
163<p>Capture names can also be function names, in which case the function
164is called with 4 arguments: <var>node</var> and <var>override</var>, <var>start</var>
165and <var>end</var>, where <var>node</var> is the node itself, <var>override</var> is
166the override property of the rule which captured this node, and
167<var>start</var> and <var>end</var> limits the region in which this function
168should fontify. (If this function wants to respect the <var>override</var>
169argument, it can use <code>treesit-fontify-with-override</code>.)
170</p>
171<p>Beyond the 4 arguments presented, this function should accept more
172arguments as optional arguments for future extensibility.
173</p>
174<p>If a capture name is both a face and a function, the face takes
175priority. If a capture name is neither a face nor a function, it is
176ignored.
177</p></dd></dl>
178
179<dl class="def">
180<dt id="index-treesit_002dfont_002dlock_002dfeature_002dlist"><span class="category">Variable: </span><span><strong>treesit-font-lock-feature-list</strong><a href='#index-treesit_002dfont_002dlock_002dfeature_002dlist' class='copiable-anchor'> &para;</a></span></dt>
181<dd><p>This is a list of lists of feature symbols. Each element of the list
182is a list that represents a decoration level.
183<code>font-lock-maximum-decoration</code> controls which levels are
184activated.
185</p>
186<p>Each element of the list is a list of the form <code>(<var>feature</var>&nbsp;&hellip;)</code><!-- /@w -->, where each <var>feature</var> corresponds to the
187<code>:feature</code> value of a query defined in
188<code>treesit-font-lock-rules</code>. Removing a feature symbol from this
189list disables the corresponding query during font-lock.
190</p>
191<p>Common feature names, for many programming languages, include
192<code>definition</code>, <code>type</code>, <code>assignment</code>, <code>builtin</code>,
193<code>constant</code>, <code>keyword</code>, <code>string-interpolation</code>,
194<code>comment</code>, <code>doc</code>, <code>string</code>, <code>operator</code>,
195<code>preprocessor</code>, <code>escape-sequence</code>, and <code>key</code>. Major
196modes are free to subdivide or extend these common features.
197</p>
198<p>Some of these features warrant some explanation: <code>definition</code>
199highlights whatever is being defined, e.g., the function name in a
200function definition, the struct name in a struct definition, the
201variable name in a variable definition; <code>assignment</code> highlights
202the whatever is being assigned to, e.g., the variable or field in an
203assignment statement; <code>key</code> highlights keys in key-value pairs,
204e.g., keys in a JSON object, or a Python dictionary; <code>doc</code>
205highlights docstrings or doc-comments.
206</p>
207<p>For example, the value of this variable could be:
208</p><div class="example">
209<pre class="example">((comment string doc) ; level 1
210 (function-name keyword type builtin constant) ; level 2
211 (variable-name string-interpolation key)) ; level 3
212</pre></div>
213
214<p>Major modes should set this variable before calling
215<code>treesit-major-mode-setup</code>.
216</p>
217<span id="index-treesit_002dfont_002dlock_002drecompute_002dfeatures"></span>
218<p>For this variable to take effect, a Lisp program should call
219<code>treesit-font-lock-recompute-features</code> (which resets
220<code>treesit-font-lock-settings</code> accordingly), or
221<code>treesit-major-mode-setup</code> (which calls
222<code>treesit-font-lock-recompute-features</code>).
223</p></dd></dl>
224
225<dl class="def">
226<dt id="index-treesit_002dfont_002dlock_002dsettings"><span class="category">Variable: </span><span><strong>treesit-font-lock-settings</strong><a href='#index-treesit_002dfont_002dlock_002dsettings' class='copiable-anchor'> &para;</a></span></dt>
227<dd><p>A list of settings for tree-sitter based font lock. The exact format
228of each setting is considered internal. One should always use
229<code>treesit-font-lock-rules</code> to set this variable.
230</p>
231</dd></dl>
232
233<p>Multi-language major modes should provide range functions in
234<code>treesit-range-functions</code>, and Emacs will set the ranges
235accordingly before fontifing a region (see <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>).
236</p>
237</div>
238<hr>
239<div class="header">
240<p>
241Previous: <a href="Multiline-Font-Lock.html">Multiline Font Lock Constructs</a>, Up: <a href="Font-Lock-Mode.html">Font Lock Mode</a> &nbsp; [<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>
242</div>
243
244
245
246</body>
247</html>
diff --git a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html b/admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html
deleted file mode 100644
index cf1257f3102..00000000000
--- a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html
+++ /dev/null
@@ -1,280 +0,0 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6<!-- This is the GNU Emacs Lisp Reference Manual
7corresponding to Emacs version 29.0.50.
8
9Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
10
11Permission is granted to copy, distribute and/or modify this document
12under the terms of the GNU Free Documentation License, Version 1.3 or
13any later version published by the Free Software Foundation; with the
14Invariant Sections being "GNU General Public License," with the
15Front-Cover Texts being "A GNU Manual," and with the Back-Cover
16Texts as in (a) below. A copy of the license is included in the
17section entitled "GNU Free Documentation License."
18
19(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
20modify this GNU manual. Buying copies from the FSF supports it in
21developing GNU and promoting software freedom." -->
22<title>Parser-based Indentation (GNU Emacs Lisp Reference Manual)</title>
23
24<meta name="description" content="Parser-based Indentation (GNU Emacs Lisp Reference Manual)">
25<meta name="keywords" content="Parser-based Indentation (GNU Emacs Lisp Reference Manual)">
26<meta name="resource-type" content="document">
27<meta name="distribution" content="global">
28<meta name="Generator" content="makeinfo">
29<meta name="viewport" content="width=device-width,initial-scale=1">
30
31<link href="index.html" rel="start" title="Top">
32<link href="Index.html" rel="index" title="Index">
33<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
34<link href="Auto_002dIndentation.html" rel="up" title="Auto-Indentation">
35<link href="SMIE.html" rel="prev" title="SMIE">
36<style type="text/css">
37<!--
38a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
39a.summary-letter {text-decoration: none}
40blockquote.indentedblock {margin-right: 0em}
41div.display {margin-left: 3.2em}
42div.example {margin-left: 3.2em}
43kbd {font-style: oblique}
44pre.display {font-family: inherit}
45pre.format {font-family: inherit}
46pre.menu-comment {font-family: serif}
47pre.menu-preformatted {font-family: serif}
48span.nolinebreak {white-space: nowrap}
49span.roman {font-family: initial; font-weight: normal}
50span.sansserif {font-family: sans-serif; font-weight: normal}
51span:hover a.copiable-anchor {visibility: visible}
52ul.no-bullet {list-style: none}
53-->
54</style>
55<link rel="stylesheet" type="text/css" href="./manual.css">
56
57
58</head>
59
60<body lang="en">
61<div class="subsection" id="Parser_002dbased-Indentation">
62<div class="header">
63<p>
64Previous: <a href="SMIE.html" accesskey="p" rel="prev">Simple Minded Indentation Engine</a>, Up: <a href="Auto_002dIndentation.html" accesskey="u" rel="up">Automatic Indentation of code</a> &nbsp; [<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>
65</div>
66<hr>
67<span id="Parser_002dbased-Indentation-1"></span><h4 class="subsection">24.7.2 Parser-based Indentation</h4>
68<span id="index-parser_002dbased-indentation"></span>
69
70
71<p>When built with the tree-sitter library (see <a href="Parsing-Program-Source.html">Parsing Program Source</a>), Emacs is capable of parsing the program source and producing
72a syntax tree. This syntax tree can be used for guiding the program
73source indentation commands. For maximum flexibility, it is possible
74to write a custom indentation function that queries the syntax tree
75and indents accordingly for each language, but that is a lot of work.
76It is more convenient to use the simple indentation engine described
77below: then the major mode needs only to write some indentation rules
78and the engine takes care of the rest.
79</p>
80<p>To enable the parser-based indentation engine, either set
81<var>treesit-simple-indent-rules</var> and call
82<code>treesit-major-mode-setup</code>, or equivalently, set the value of
83<code>indent-line-function</code> to <code>treesit-indent</code>.
84</p>
85<dl class="def">
86<dt id="index-treesit_002dindent_002dfunction"><span class="category">Variable: </span><span><strong>treesit-indent-function</strong><a href='#index-treesit_002dindent_002dfunction' class='copiable-anchor'> &para;</a></span></dt>
87<dd><p>This variable stores the actual function called by
88<code>treesit-indent</code>. By default, its value is
89<code>treesit-simple-indent</code>. In the future we might add other,
90more complex indentation engines.
91</p></dd></dl>
92
93<span id="Writing-indentation-rules"></span><h3 class="heading">Writing indentation rules</h3>
94<span id="index-indentation-rules_002c-for-parser_002dbased-indentation"></span>
95
96<dl class="def">
97<dt id="index-treesit_002dsimple_002dindent_002drules"><span class="category">Variable: </span><span><strong>treesit-simple-indent-rules</strong><a href='#index-treesit_002dsimple_002dindent_002drules' class='copiable-anchor'> &para;</a></span></dt>
98<dd><p>This local variable stores indentation rules for every language. It is
99a list of the form: <code>(<var>language</var>&nbsp;.&nbsp;<var>rules</var>)</code><!-- /@w -->, where
100<var>language</var> is a language symbol, and <var>rules</var> is a list of the
101form <code>(<var>matcher</var>&nbsp;<var>anchor</var>&nbsp;<var>offset</var>)</code><!-- /@w -->.
102</p>
103<p>First, Emacs passes the smallest tree-sitter node at the beginning of
104the current line to <var>matcher</var>; if it returns non-<code>nil</code>, this
105rule is applicable. Then Emacs passes the node to <var>anchor</var>, which
106returns a buffer position. Emacs takes the column number of that
107position, adds <var>offset</var> to it, and the result is the indentation
108column for the current line. <var>offset</var> can be an integer or a
109variable whose value is an integer.
110</p>
111<p>The <var>matcher</var> and <var>anchor</var> are functions, and Emacs provides
112convenient defaults for them.
113</p>
114<p>Each <var>matcher</var> or <var>anchor</var> is a function that takes three
115arguments: <var>node</var>, <var>parent</var>, and <var>bol</var>. The argument
116<var>bol</var> is the buffer position whose indentation is required: the
117position of the first non-whitespace character after the beginning of
118the line. The argument <var>node</var> is the largest (highest-in-tree)
119node that starts at that position; and <var>parent</var> is the parent of
120<var>node</var>. However, when that position is in a whitespace or inside
121a multi-line string, no node can start at that position, so
122<var>node</var> is <code>nil</code>. In that case, <var>parent</var> would be the
123smallest node that spans that position.
124</p>
125<p>Emacs finds <var>bol</var>, <var>node</var> and <var>parent</var> and
126passes them to each <var>matcher</var> and <var>anchor</var>. <var>matcher</var>
127should return non-<code>nil</code> if the rule is applicable, and
128<var>anchor</var> should return a buffer position.
129</p></dd></dl>
130
131<dl class="def">
132<dt id="index-treesit_002dsimple_002dindent_002dpresets"><span class="category">Variable: </span><span><strong>treesit-simple-indent-presets</strong><a href='#index-treesit_002dsimple_002dindent_002dpresets' class='copiable-anchor'> &para;</a></span></dt>
133<dd><p>This is a list of defaults for <var>matcher</var>s and <var>anchor</var>s in
134<code>treesit-simple-indent-rules</code>. Each of them represents a function
135that takes 3 arguments: <var>node</var>, <var>parent</var> and <var>bol</var>. The
136available default functions are:
137</p>
138<dl compact="compact">
139<dt id='index-no_002dnode'><span><code>no-node</code><a href='#index-no_002dnode' class='copiable-anchor'> &para;</a></span></dt>
140<dd><p>This matcher is a function that is called with 3 arguments:
141<var>node</var>, <var>parent</var>, and <var>bol</var>, and returns non-<code>nil</code>,
142indicating a match, if <var>node</var> is <code>nil</code>, i.e., there is no
143node that starts at <var>bol</var>. This is the case when <var>bol</var> is on
144an empty line or inside a multi-line string, etc.
145</p>
146</dd>
147<dt id='index-parent_002dis'><span><code>parent-is</code><a href='#index-parent_002dis' class='copiable-anchor'> &para;</a></span></dt>
148<dd><p>This matcher is a function of one argument, <var>type</var>; it returns a
149function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
150and <var>bol</var>, and returns non-<code>nil</code> (i.e., a match) if
151<var>parent</var>&rsquo;s type matches regexp <var>type</var>.
152</p>
153</dd>
154<dt id='index-node_002dis'><span><code>node-is</code><a href='#index-node_002dis' class='copiable-anchor'> &para;</a></span></dt>
155<dd><p>This matcher is a function of one argument, <var>type</var>; it returns a
156function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
157and <var>bol</var>, and returns non-<code>nil</code> if <var>node</var>&rsquo;s type matches
158regexp <var>type</var>.
159</p>
160</dd>
161<dt id='index-query'><span><code>query</code><a href='#index-query' class='copiable-anchor'> &para;</a></span></dt>
162<dd><p>This matcher is a function of one argument, <var>query</var>; it returns a
163function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
164and <var>bol</var>, and returns non-<code>nil</code> if querying <var>parent</var>
165with <var>query</var> captures <var>node</var> (see <a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>).
166</p>
167</dd>
168<dt id='index-match'><span><code>match</code><a href='#index-match' class='copiable-anchor'> &para;</a></span></dt>
169<dd><p>This matcher is a function of 5 arguments: <var>node-type</var>,
170<var>parent-type</var>, <var>node-field</var>, <var>node-index-min</var>, and
171<var>node-index-max</var>). It returns a function that is called with 3
172arguments: <var>node</var>, <var>parent</var>, and <var>bol</var>, and returns
173non-<code>nil</code> if <var>node</var>&rsquo;s type matches regexp <var>node-type</var>,
174<var>parent</var>&rsquo;s type matches regexp <var>parent-type</var>, <var>node</var>&rsquo;s
175field name in <var>parent</var> matches regexp <var>node-field</var>, and
176<var>node</var>&rsquo;s index among its siblings is between <var>node-index-min</var>
177and <var>node-index-max</var>. If the value of an argument is <code>nil</code>,
178this matcher doesn&rsquo;t check that argument. For example, to match the
179first child where parent is <code>argument_list</code>, use
180</p>
181<div class="example">
182<pre class="example">(match nil &quot;argument_list&quot; nil nil 0 0)
183</pre></div>
184
185</dd>
186<dt id='index-comment_002dend'><span><code>comment-end</code><a href='#index-comment_002dend' class='copiable-anchor'> &para;</a></span></dt>
187<dd><p>This matcher is a function that is called with 3 arguments:
188<var>node</var>, <var>parent</var>, and <var>bol</var>, and returns non-<code>nil</code> if
189point is before a comment ending token. Comment ending tokens are
190defined by regular expression <code>treesit-comment-end</code>
191(see <a href="Tree_002dsitter-major-modes.html">treesit-comment-end</a>).
192</p>
193</dd>
194<dt id='index-first_002dsibling'><span><code>first-sibling</code><a href='#index-first_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
195<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
196<var>parent</var>, and <var>bol</var>, and returns the start of the first child
197of <var>parent</var>.
198</p>
199</dd>
200<dt id='index-parent'><span><code>parent</code><a href='#index-parent' class='copiable-anchor'> &para;</a></span></dt>
201<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
202<var>parent</var>, and <var>bol</var>, and returns the start of <var>parent</var>.
203</p>
204</dd>
205<dt id='index-parent_002dbol'><span><code>parent-bol</code><a href='#index-parent_002dbol' class='copiable-anchor'> &para;</a></span></dt>
206<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
207<var>parent</var>, and <var>bol</var>, and returns the first non-space character
208on the line of <var>parent</var>.
209</p>
210</dd>
211<dt id='index-prev_002dsibling'><span><code>prev-sibling</code><a href='#index-prev_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
212<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
213<var>parent</var>, and <var>bol</var>, and returns the start of the previous
214sibling of <var>node</var>.
215</p>
216</dd>
217<dt id='index-no_002dindent'><span><code>no-indent</code><a href='#index-no_002dindent' class='copiable-anchor'> &para;</a></span></dt>
218<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
219<var>parent</var>, and <var>bol</var>, and returns the start of <var>node</var>.
220</p>
221</dd>
222<dt id='index-prev_002dline'><span><code>prev-line</code><a href='#index-prev_002dline' class='copiable-anchor'> &para;</a></span></dt>
223<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
224<var>parent</var>, and <var>bol</var>, and returns the first non-whitespace
225character on the previous line.
226</p>
227</dd>
228<dt id='index-point_002dmin'><span><code>point-min</code><a href='#index-point_002dmin' class='copiable-anchor'> &para;</a></span></dt>
229<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
230<var>parent</var>, and <var>bol</var>, and returns the beginning of the buffer.
231This is useful as the beginning of the buffer is always at column 0.
232</p>
233</dd>
234<dt id='index-comment_002dstart'><span><code>comment-start</code><a href='#index-comment_002dstart' class='copiable-anchor'> &para;</a></span></dt>
235<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
236<var>parent</var>, and <var>bol</var>, and returns the position right after the
237comment-start token. Comment-start tokens are defined by regular
238expression <code>treesit-comment-start</code> (see <a href="Tree_002dsitter-major-modes.html">treesit-comment-start</a>). This function assumes <var>parent</var> is
239the comment node.
240</p>
241</dd>
242<dt id='index-coment_002dstart_002dskip'><span><code>comment-start-skip</code><a href='#index-coment_002dstart_002dskip' class='copiable-anchor'> &para;</a></span></dt>
243<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
244<var>parent</var>, and <var>bol</var>, and returns the position after the
245comment-start token and any whitespace characters following that
246token. Comment-start tokens are defined by regular expression
247<code>treesit-comment-start</code>. This function assumes <var>parent</var> is
248the comment node.
249</p></dd>
250</dl>
251</dd></dl>
252
253<span id="Indentation-utilities"></span><h3 class="heading">Indentation utilities</h3>
254<span id="index-utility-functions-for-parser_002dbased-indentation"></span>
255
256<p>Here are some utility functions that can help writing parser-based
257indentation rules.
258</p>
259<dl class="def">
260<dt id="index-treesit_002dcheck_002dindent"><span class="category">Function: </span><span><strong>treesit-check-indent</strong> <em>mode</em><a href='#index-treesit_002dcheck_002dindent' class='copiable-anchor'> &para;</a></span></dt>
261<dd><p>This function checks the current buffer&rsquo;s indentation against major
262mode <var>mode</var>. It indents the current buffer according to
263<var>mode</var> and compares the results with the current indentation.
264Then it pops up a buffer showing the differences. Correct
265indentation (target) is shown in green color, current indentation is
266shown in red color. </p></dd></dl>
267
268<p>It is also helpful to use <code>treesit-inspect-mode</code> (see <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>) when writing indentation rules.
269</p>
270</div>
271<hr>
272<div class="header">
273<p>
274Previous: <a href="SMIE.html">Simple Minded Indentation Engine</a>, Up: <a href="Auto_002dIndentation.html">Automatic Indentation of code</a> &nbsp; [<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>
275</div>
276
277
278
279</body>
280</html>
diff --git a/admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html b/admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html
deleted file mode 100644
index 58f6b4e9d5a..00000000000
--- a/admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html
+++ /dev/null
@@ -1,125 +0,0 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6<!-- This is the GNU Emacs Lisp Reference Manual
7corresponding to Emacs version 29.0.50.
8
9Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
10
11Permission is granted to copy, distribute and/or modify this document
12under the terms of the GNU Free Documentation License, Version 1.3 or
13any later version published by the Free Software Foundation; with the
14Invariant Sections being "GNU General Public License," with the
15Front-Cover Texts being "A GNU Manual," and with the Back-Cover
16Texts as in (a) below. A copy of the license is included in the
17section entitled "GNU Free Documentation License."
18
19(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
20modify this GNU manual. Buying copies from the FSF supports it in
21developing GNU and promoting software freedom." -->
22<title>Parsing Program Source (GNU Emacs Lisp Reference Manual)</title>
23
24<meta name="description" content="Parsing Program Source (GNU Emacs Lisp Reference Manual)">
25<meta name="keywords" content="Parsing Program Source (GNU Emacs Lisp Reference Manual)">
26<meta name="resource-type" content="document">
27<meta name="distribution" content="global">
28<meta name="Generator" content="makeinfo">
29<meta name="viewport" content="width=device-width,initial-scale=1">
30
31<link href="index.html" rel="start" title="Top">
32<link href="Index.html" rel="index" title="Index">
33<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
34<link href="index.html" rel="up" title="Top">
35<link href="Abbrevs.html" rel="next" title="Abbrevs">
36<link href="Syntax-Tables.html" rel="prev" title="Syntax Tables">
37<style type="text/css">
38<!--
39a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
40a.summary-letter {text-decoration: none}
41blockquote.indentedblock {margin-right: 0em}
42div.display {margin-left: 3.2em}
43div.example {margin-left: 3.2em}
44kbd {font-style: oblique}
45pre.display {font-family: inherit}
46pre.format {font-family: inherit}
47pre.menu-comment {font-family: serif}
48pre.menu-preformatted {font-family: serif}
49span.nolinebreak {white-space: nowrap}
50span.roman {font-family: initial; font-weight: normal}
51span.sansserif {font-family: sans-serif; font-weight: normal}
52span:hover a.copiable-anchor {visibility: visible}
53ul.no-bullet {list-style: none}
54-->
55</style>
56<link rel="stylesheet" type="text/css" href="./manual.css">
57
58
59</head>
60
61<body lang="en">
62<div class="chapter" id="Parsing-Program-Source">
63<div class="header">
64<p>
65Next: <a href="Abbrevs.html" accesskey="n" rel="next">Abbrevs and Abbrev Expansion</a>, Previous: <a href="Syntax-Tables.html" accesskey="p" rel="prev">Syntax Tables</a>, Up: <a href="index.html" accesskey="u" rel="up">Emacs Lisp</a> &nbsp; [<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>
66</div>
67<hr>
68<span id="Parsing-Program-Source-1"></span><h2 class="chapter">37 Parsing Program Source</h2>
69
70<span id="index-syntax-tree_002c-from-parsing-program-source"></span>
71<p>Emacs provides various ways to parse program source text and produce a
72<em>syntax tree</em>. In a syntax tree, text is no longer considered a
73one-dimensional stream of characters, but a structured tree of nodes,
74where each node representing a piece of text. Thus, a syntax tree can
75enable interesting features like precise fontification, indentation,
76navigation, structured editing, etc.
77</p>
78<p>Emacs has a simple facility for parsing balanced expressions
79(see <a href="Parsing-Expressions.html">Parsing Expressions</a>). There is also the SMIE library for
80generic navigation and indentation (see <a href="SMIE.html">Simple Minded Indentation Engine</a>).
81</p>
82<p>In addition to those, Emacs also provides integration with
83<a href="https://tree-sitter.github.io/tree-sitter">the tree-sitter
84library</a>) if support for it was compiled in. The tree-sitter library
85implements an incremental parser and has support from a wide range of
86programming languages.
87</p>
88<dl class="def">
89<dt id="index-treesit_002davailable_002dp"><span class="category">Function: </span><span><strong>treesit-available-p</strong><a href='#index-treesit_002davailable_002dp' class='copiable-anchor'> &para;</a></span></dt>
90<dd><p>This function returns non-<code>nil</code> if tree-sitter features are
91available for the current Emacs session.
92</p></dd></dl>
93
94<p>To be able to parse the program source using the tree-sitter library
95and access the syntax tree of the program, a Lisp program needs to
96load a language definition library, and create a parser for that
97language and the current buffer. After that, the Lisp program can
98query the parser about specific nodes of the syntax tree. Then, it
99can access various kinds of information about each node, and search
100for nodes using a powerful pattern-matching syntax. This chapter
101explains how to do all this, and also how a Lisp program can work with
102source files that mix multiple programming languages.
103</p>
104
105<ul class="section-toc">
106<li><a href="Language-Definitions.html" accesskey="1">Tree-sitter Language Definitions</a></li>
107<li><a href="Using-Parser.html" accesskey="2">Using Tree-sitter Parser</a></li>
108<li><a href="Retrieving-Nodes.html" accesskey="3">Retrieving Nodes</a></li>
109<li><a href="Accessing-Node-Information.html" accesskey="4">Accessing Node Information</a></li>
110<li><a href="Pattern-Matching.html" accesskey="5">Pattern Matching Tree-sitter Nodes</a></li>
111<li><a href="Multiple-Languages.html" accesskey="6">Parsing Text in Multiple Languages</a></li>
112<li><a href="Tree_002dsitter-major-modes.html" accesskey="7">Developing major modes with tree-sitter</a></li>
113<li><a href="Tree_002dsitter-C-API.html" accesskey="8">Tree-sitter C API Correspondence</a></li>
114</ul>
115</div>
116<hr>
117<div class="header">
118<p>
119Next: <a href="Abbrevs.html">Abbrevs and Abbrev Expansion</a>, Previous: <a href="Syntax-Tables.html">Syntax Tables</a>, Up: <a href="index.html">Emacs Lisp</a> &nbsp; [<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>
120</div>
121
122
123
124</body>
125</html>
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 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6<!-- This is the GNU Emacs Lisp Reference Manual
7corresponding to Emacs version 29.0.50.
8
9Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
10
11Permission is granted to copy, distribute and/or modify this document
12under the terms of the GNU Free Documentation License, Version 1.3 or
13any later version published by the Free Software Foundation; with the
14Invariant Sections being "GNU General Public License," with the
15Front-Cover Texts being "A GNU Manual," and with the Back-Cover
16Texts as in (a) below. A copy of the license is included in the
17section entitled "GNU Free Documentation License."
18
19(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
20modify this GNU manual. Buying copies from the FSF supports it in
21developing GNU and promoting software freedom." -->
22<title>Pattern Matching (GNU Emacs Lisp Reference Manual)</title>
23
24<meta name="description" content="Pattern Matching (GNU Emacs Lisp Reference Manual)">
25<meta name="keywords" content="Pattern Matching (GNU Emacs Lisp Reference Manual)">
26<meta name="resource-type" content="document">
27<meta name="distribution" content="global">
28<meta name="Generator" content="makeinfo">
29<meta name="viewport" content="width=device-width,initial-scale=1">
30
31<link href="index.html" rel="start" title="Top">
32<link href="Index.html" rel="index" title="Index">
33<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
34<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
35<link href="Multiple-Languages.html" rel="next" title="Multiple Languages">
36<link href="Accessing-Node-Information.html" rel="prev" title="Accessing Node Information">
37<style type="text/css">
38<!--
39a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
40a.summary-letter {text-decoration: none}
41blockquote.indentedblock {margin-right: 0em}
42div.display {margin-left: 3.2em}
43div.example {margin-left: 3.2em}
44kbd {font-style: oblique}
45pre.display {font-family: inherit}
46pre.format {font-family: inherit}
47pre.menu-comment {font-family: serif}
48pre.menu-preformatted {font-family: serif}
49span.nolinebreak {white-space: nowrap}
50span.roman {font-family: initial; font-weight: normal}
51span.sansserif {font-family: sans-serif; font-weight: normal}
52span:hover a.copiable-anchor {visibility: visible}
53ul.no-bullet {list-style: none}
54-->
55</style>
56<link rel="stylesheet" type="text/css" href="./manual.css">
57
58
59</head>
60
61<body lang="en">
62<div class="section" id="Pattern-Matching">
63<div class="header">
64<p>
65Next: <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> &nbsp; [<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>
66</div>
67<hr>
68<span id="Pattern-Matching-Tree_002dsitter-Nodes"></span><h3 class="section">37.5 Pattern Matching Tree-sitter Nodes</h3>
69<span id="index-pattern-matching-with-tree_002dsitter-nodes"></span>
70
71<span id="index-capturing_002c-tree_002dsitter-node"></span>
72<p>Tree-sitter lets Lisp programs match patterns using a small
73declarative language. This pattern matching consists of two steps:
74first tree-sitter matches a <em>pattern</em> against nodes in the syntax
75tree, then it <em>captures</em> specific nodes that matched the pattern
76and returns the captured nodes.
77</p>
78<p>We describe first how to write the most basic query pattern and how to
79capture nodes in a pattern, then the pattern-matching function, and
80finally the more advanced pattern syntax.
81</p>
82<span id="Basic-query-syntax"></span><h3 class="heading">Basic query syntax</h3>
83
84<span id="index-tree_002dsitter-query-pattern-syntax"></span>
85<span id="index-pattern-syntax_002c-tree_002dsitter-query"></span>
86<span id="index-query_002c-tree_002dsitter"></span>
87<p>A <em>query</em> consists of multiple <em>patterns</em>. Each pattern is an
88s-expression that matches a certain node in the syntax node. A
89pattern has the form <code>(<var>type</var>&nbsp;(<var>child</var>&hellip;))</code><!-- /@w -->
90</p>
91<p>For example, a pattern that matches a <code>binary_expression</code> node that
92contains <code>number_literal</code> child nodes would look like
93</p>
94<div class="example">
95<pre class="example">(binary_expression (number_literal))
96</pre></div>
97
98<p>To <em>capture</em> a node using the query pattern above, append
99<code>@<var>capture-name</var></code> after the node pattern you want to
100capture. For example,
101</p>
102<div class="example">
103<pre class="example">(binary_expression (number_literal) @number-in-exp)
104</pre></div>
105
106<p>captures <code>number_literal</code> nodes that are inside a
107<code>binary_expression</code> node with the capture name
108<code>number-in-exp</code>.
109</p>
110<p>We can capture the <code>binary_expression</code> node as well, with, for
111example, the capture name <code>biexp</code>:
112</p>
113<div class="example">
114<pre class="example">(binary_expression
115 (number_literal) @number-in-exp) @biexp
116</pre></div>
117
118<span id="Query-function"></span><h3 class="heading">Query function</h3>
119
120<span id="index-query-functions_002c-tree_002dsitter"></span>
121<p>Now we can introduce the <em>query functions</em>.
122</p>
123<dl class="def">
124<dt id="index-treesit_002dquery_002dcapture"><span class="category">Function: </span><span><strong>treesit-query-capture</strong> <em>node query &amp;optional beg end node-only</em><a href='#index-treesit_002dquery_002dcapture' class='copiable-anchor'> &para;</a></span></dt>
125<dd><p>This function matches patterns in <var>query</var> within <var>node</var>.
126The argument <var>query</var> can be either a string, a s-expression, or a
127compiled query object. For now, we focus on the string syntax;
128s-expression syntax and compiled query are described at the end of the
129section.
130</p>
131<p>The argument <var>node</var> can also be a parser or a language symbol. A
132parser means using its root node, a language symbol means find or
133create a parser for that language in the current buffer, and use the
134root node.
135</p>
136<p>The function returns all the captured nodes in a list of the form
137<code>(<var><span class="nolinebreak">capture_name</span></var>&nbsp;.&nbsp;<var>node</var>)</code><!-- /@w -->. If <var>node-only</var> is
138non-<code>nil</code>, it returns the list of nodes instead. By default the
139entire text of <var>node</var> is searched, but if <var>beg</var> and <var>end</var>
140are both non-<code>nil</code>, they specify the region of buffer text where
141this function should match nodes. Any matching node whose span
142overlaps with the region between <var>beg</var> and <var>end</var> are captured,
143it doesn&rsquo;t have to be completely in the region.
144</p>
145<span id="index-treesit_002dquery_002derror"></span>
146<span id="index-treesit_002dquery_002dvalidate"></span>
147<p>This function raises the <code>treesit-query-error</code> error if
148<var>query</var> is malformed. The signal data contains a description of
149the specific error. You can use <code>treesit-query-validate</code> to
150validate and debug the query.
151</p></dd></dl>
152
153<p>For example, suppose <var>node</var>&rsquo;s text is <code>1 + 2</code>, and
154<var>query</var> is
155</p>
156<div class="example">
157<pre class="example">(setq query
158 &quot;(binary_expression
159 (number_literal) @number-in-exp) @biexp&quot;)
160</pre></div>
161
162<p>Matching that query would return
163</p>
164<div class="example">
165<pre class="example">(treesit-query-capture node query)
166 &rArr; ((biexp . <var>&lt;node for &quot;1 + 2&quot;&gt;</var>)
167 (number-in-exp . <var>&lt;node for &quot;1&quot;&gt;</var>)
168 (number-in-exp . <var>&lt;node for &quot;2&quot;&gt;</var>))
169</pre></div>
170
171<p>As mentioned earlier, <var>query</var> could contain multiple patterns.
172For example, it could have two top-level patterns:
173</p>
174<div class="example">
175<pre class="example">(setq query
176 &quot;(binary_expression) @biexp
177 (number_literal) @number @biexp&quot;)
178</pre></div>
179
180<dl class="def">
181<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'> &para;</a></span></dt>
182<dd><p>This function parses <var>string</var> with <var>language</var>, matches its
183root node with <var>query</var>, and returns the result.
184</p></dd></dl>
185
186<span id="More-query-syntax"></span><h3 class="heading">More query syntax</h3>
187
188<p>Besides node type and capture, tree-sitter&rsquo;s pattern syntax can
189express anonymous node, field name, wildcard, quantification,
190grouping, alternation, anchor, and predicate.
191</p>
192<span id="Anonymous-node"></span><h4 class="subheading">Anonymous node</h4>
193
194<p>An anonymous node is written verbatim, surrounded by quotes. A
195pattern matching (and capturing) keyword <code>return</code> would be
196</p>
197<div class="example">
198<pre class="example">&quot;return&quot; @keyword
199</pre></div>
200
201<span id="Wild-card"></span><h4 class="subheading">Wild card</h4>
202
203<p>In a pattern, &lsquo;<samp>(_)</samp>&rsquo; matches any named node, and &lsquo;<samp>_</samp>&rsquo; matches
204any named and anonymous node. For example, to capture any named child
205of a <code>binary_expression</code> node, the pattern would be
206</p>
207<div class="example">
208<pre class="example">(binary_expression (_) @in_biexp)
209</pre></div>
210
211<span id="Field-name"></span><h4 class="subheading">Field name</h4>
212
213<p>It is possible to capture child nodes that have specific field names.
214In the pattern below, <code>declarator</code> and <code>body</code> are field
215names, indicated by the colon following them.
216</p>
217<div class="example">
218<pre class="example">(function_definition
219 declarator: (_) @func-declarator
220 body: (_) @func-body)
221</pre></div>
222
223<p>It is also possible to capture a node that doesn&rsquo;t have a certain
224field, say, a <code>function_definition</code> without a <code>body</code> field.
225</p>
226<div class="example">
227<pre class="example">(function_definition !body) @func-no-body
228</pre></div>
229
230<span id="Quantify-node"></span><h4 class="subheading">Quantify node</h4>
231
232<span id="index-quantify-node_002c-tree_002dsitter"></span>
233<p>Tree-sitter recognizes quantification operators &lsquo;<samp>*</samp>&rsquo;, &lsquo;<samp>+</samp>&rsquo; and
234&lsquo;<samp>?</samp>&rsquo;. Their meanings are the same as in regular expressions:
235&lsquo;<samp>*</samp>&rsquo; matches the preceding pattern zero or more times, &lsquo;<samp>+</samp>&rsquo;
236matches one or more times, and &lsquo;<samp>?</samp>&rsquo; matches zero or one time.
237</p>
238<p>For example, the following pattern matches <code>type_declaration</code>
239nodes that has <em>zero or more</em> <code>long</code> keyword.
240</p>
241<div class="example">
242<pre class="example">(type_declaration &quot;long&quot;*) @long-type
243</pre></div>
244
245<p>The following pattern matches a type declaration that has zero or one
246<code>long</code> keyword:
247</p>
248<div class="example">
249<pre class="example">(type_declaration &quot;long&quot;?) @long-type
250</pre></div>
251
252<span id="Grouping"></span><h4 class="subheading">Grouping</h4>
253
254<p>Similar to groups in regular expression, we can bundle patterns into
255groups and apply quantification operators to them. For example, to
256express a comma separated list of identifiers, one could write
257</p>
258<div class="example">
259<pre class="example">(identifier) (&quot;,&quot; (identifier))*
260</pre></div>
261
262<span id="Alternation"></span><h4 class="subheading">Alternation</h4>
263
264<p>Again, similar to regular expressions, we can express &ldquo;match anyone
265from this group of patterns&rdquo; in a pattern. The syntax is a list of
266patterns enclosed in square brackets. For example, to capture some
267keywords in C, the pattern would be
268</p>
269<div class="example">
270<pre class="example">[
271 &quot;return&quot;
272 &quot;break&quot;
273 &quot;if&quot;
274 &quot;else&quot;
275] @keyword
276</pre></div>
277
278<span id="Anchor"></span><h4 class="subheading">Anchor</h4>
279
280<p>The anchor operator &lsquo;<samp>.</samp>&rsquo; can be used to enforce juxtaposition,
281i.e., to enforce two things to be directly next to each other. The
282two &ldquo;things&rdquo; can be two nodes, or a child and the end of its parent.
283For example, to capture the first child, the last child, or two
284adjacent children:
285</p>
286<div class="example">
287<pre class="example">;; Anchor the child with the end of its parent.
288(compound_expression (_) @last-child .)
289</pre><pre class="example">
290
291</pre><pre class="example">;; Anchor the child with the beginning of its parent.
292(compound_expression . (_) @first-child)
293</pre><pre class="example">
294
295</pre><pre class="example">;; Anchor two adjacent children.
296(compound_expression
297 (_) @prev-child
298 .
299 (_) @next-child)
300</pre></div>
301
302<p>Note that the enforcement of juxtaposition ignores any anonymous
303nodes.
304</p>
305<span id="Predicate"></span><h4 class="subheading">Predicate</h4>
306
307<p>It is possible to add predicate constraints to a pattern. For
308example, with the following pattern:
309</p>
310<div class="example">
311<pre class="example">(
312 (array . (_) @first (_) @last .)
313 (#equal @first @last)
314)
315</pre></div>
316
317<p>tree-sitter only matches arrays where the first element equals to
318the last element. To attach a predicate to a pattern, we need to
319group them together. A predicate always starts with a &lsquo;<samp>#</samp>&rsquo;.
320Currently there are two predicates, <code>#equal</code> and <code>#match</code>.
321</p>
322<dl class="def">
323<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'> &para;</a></span></dt>
324<dd><p>Matches if <var>arg1</var> equals to <var>arg2</var>. Arguments can be either
325strings or capture names. Capture names represent the text that the
326captured node spans in the buffer.
327</p></dd></dl>
328
329<dl class="def">
330<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'> &para;</a></span></dt>
331<dd><p>Matches if the text that <var>capture-name</var>&rsquo;s node spans in the buffer
332matches regular expression <var>regexp</var>. Matching is case-sensitive.
333</p></dd></dl>
334
335<p>Note that a predicate can only refer to capture names that appear in
336the same pattern. Indeed, it makes little sense to refer to capture
337names in other patterns.
338</p>
339<span id="S_002dexpression-patterns"></span><h3 class="heading">S-expression patterns</h3>
340
341<span id="index-tree_002dsitter-patterns-as-sexps"></span>
342<span id="index-patterns_002c-tree_002dsitter_002c-in-sexp-form"></span>
343<p>Besides strings, Emacs provides a s-expression based syntax for
344tree-sitter patterns. It largely resembles the string-based syntax.
345For example, the following query
346</p>
347<div class="example">
348<pre class="example">(treesit-query-capture
349 node &quot;(addition_expression
350 left: (_) @left
351 \&quot;+\&quot; @plus-sign
352 right: (_) @right) @addition
353
354 [\&quot;return\&quot; \&quot;break\&quot;] @keyword&quot;)
355</pre></div>
356
357<p>is equivalent to
358</p>
359<div class="example">
360<pre class="example">(treesit-query-capture
361 node '((addition_expression
362 left: (_) @left
363 &quot;+&quot; @plus-sign
364 right: (_) @right) @addition
365
366 [&quot;return&quot; &quot;break&quot;] @keyword))
367</pre></div>
368
369<p>Most patterns can be written directly as strange but nevertheless
370valid s-expressions. Only a few of them needs modification:
371</p>
372<ul>
373<li> Anchor &lsquo;<samp>.</samp>&rsquo; is written as <code>:anchor</code>.
374</li><li> &lsquo;<samp>?</samp>&rsquo; is written as &lsquo;<samp>:?</samp>&rsquo;.
375</li><li> &lsquo;<samp>*</samp>&rsquo; is written as &lsquo;<samp>:*</samp>&rsquo;.
376</li><li> &lsquo;<samp>+</samp>&rsquo; is written as &lsquo;<samp>:+</samp>&rsquo;.
377</li><li> <code>#equal</code> is written as <code>:equal</code>. In general, predicates
378change their &lsquo;<samp>#</samp>&rsquo; to &lsquo;<samp>:</samp>&rsquo;.
379</li></ul>
380
381<p>For example,
382</p>
383<div class="example">
384<pre class="example">&quot;(
385 (compound_expression . (_) @first (_)* @rest)
386 (#match \&quot;love\&quot; @first)
387 )&quot;
388</pre></div>
389
390<p>is written in s-expression as
391</p>
392<div class="example">
393<pre class="example">'((
394 (compound_expression :anchor (_) @first (_) :* @rest)
395 (:match &quot;love&quot; @first)
396 ))
397</pre></div>
398
399<span id="Compiling-queries"></span><h3 class="heading">Compiling queries</h3>
400
401<span id="index-compiling-tree_002dsitter-queries"></span>
402<span id="index-queries_002c-compiling"></span>
403<p>If a query is intended to be used repeatedly, especially in tight
404loops, it is important to compile that query, because a compiled query
405is much faster than an uncompiled one. A compiled query can be used
406anywhere a query is accepted.
407</p>
408<dl class="def">
409<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'> &para;</a></span></dt>
410<dd><p>This function compiles <var>query</var> for <var>language</var> into a compiled
411query object and returns it.
412</p>
413<p>This function raises the <code>treesit-query-error</code> error if
414<var>query</var> is malformed. The signal data contains a description of
415the specific error. You can use <code>treesit-query-validate</code> to
416validate and debug the query.
417</p></dd></dl>
418
419<dl class="def">
420<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'> &para;</a></span></dt>
421<dd><p>This function return the language of <var>query</var>.
422</p></dd></dl>
423
424<dl class="def">
425<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'> &para;</a></span></dt>
426<dd><p>This function converts the s-expression <var>query</var> into the string
427format.
428</p></dd></dl>
429
430<dl class="def">
431<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'> &para;</a></span></dt>
432<dd><p>This function converts the s-expression <var>pattern</var> into the string
433format.
434</p></dd></dl>
435
436<p>For more details, read the tree-sitter project&rsquo;s documentation about
437pattern-matching, which can be found at
438<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>.
439</p>
440</div>
441<hr>
442<div class="header">
443<p>
444Next: <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> &nbsp; [<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>
445</div>
446
447
448
449</body>
450</html>
diff --git a/admin/notes/tree-sitter/html-manual/Retrieving-Node.html b/admin/notes/tree-sitter/html-manual/Retrieving-Node.html
deleted file mode 100644
index 16eeb0b1091..00000000000
--- a/admin/notes/tree-sitter/html-manual/Retrieving-Node.html
+++ /dev/null
@@ -1,420 +0,0 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6<!-- This is the GNU Emacs Lisp Reference Manual
7corresponding to Emacs version 29.0.50.
8
9Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
10
11Permission is granted to copy, distribute and/or modify this document
12under the terms of the GNU Free Documentation License, Version 1.3 or
13any later version published by the Free Software Foundation; with the
14Invariant Sections being "GNU General Public License," with the
15Front-Cover Texts being "A GNU Manual," and with the Back-Cover
16Texts as in (a) below. A copy of the license is included in the
17section entitled "GNU Free Documentation License."
18
19(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
20modify this GNU manual. Buying copies from the FSF supports it in
21developing GNU and promoting software freedom." -->
22<title>Retrieving Node (GNU Emacs Lisp Reference Manual)</title>
23
24<meta name="description" content="Retrieving Node (GNU Emacs Lisp Reference Manual)">
25<meta name="keywords" content="Retrieving Node (GNU Emacs Lisp Reference Manual)">
26<meta name="resource-type" content="document">
27<meta name="distribution" content="global">
28<meta name="Generator" content="makeinfo">
29<meta name="viewport" content="width=device-width,initial-scale=1">
30
31<link href="index.html" rel="start" title="Top">
32<link href="Index.html" rel="index" title="Index">
33<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
34<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
35<link href="Accessing-Node-Information.html" rel="next" title="Accessing Node Information">
36<link href="Using-Parser.html" rel="prev" title="Using Parser">
37<style type="text/css">
38<!--
39a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
40a.summary-letter {text-decoration: none}
41blockquote.indentedblock {margin-right: 0em}
42div.display {margin-left: 3.2em}
43div.example {margin-left: 3.2em}
44kbd {font-style: oblique}
45pre.display {font-family: inherit}
46pre.format {font-family: inherit}
47pre.menu-comment {font-family: serif}
48pre.menu-preformatted {font-family: serif}
49span.nolinebreak {white-space: nowrap}
50span.roman {font-family: initial; font-weight: normal}
51span.sansserif {font-family: sans-serif; font-weight: normal}
52span:hover a.copiable-anchor {visibility: visible}
53ul.no-bullet {list-style: none}
54-->
55</style>
56<link rel="stylesheet" type="text/css" href="./manual.css">
57
58
59</head>
60
61<body lang="en">
62<div class="section" id="Retrieving-Node">
63<div class="header">
64<p>
65Next: <a href="Accessing-Node-Information.html" accesskey="n" rel="next">Accessing Node Information</a>, Previous: <a href="Using-Parser.html" accesskey="p" rel="prev">Using Tree-sitter Parser</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<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>
66</div>
67<hr>
68<span id="Retrieving-Node-1"></span><h3 class="section">37.3 Retrieving Node</h3>
69<span id="index-retrieve-node_002c-tree_002dsitter"></span>
70<span id="index-tree_002dsitter_002c-find-node"></span>
71<span id="index-get-node_002c-tree_002dsitter"></span>
72
73<span id="index-terminology_002c-for-tree_002dsitter-functions"></span>
74<p>Here&rsquo;s some terminology and conventions we use when documenting
75tree-sitter functions.
76</p>
77<p>We talk about a node being &ldquo;smaller&rdquo; or &ldquo;larger&rdquo;, and &ldquo;lower&rdquo; or
78&ldquo;higher&rdquo;. A smaller and lower node is lower in the syntax tree and
79therefore spans a smaller portion of buffer text; a larger and higher
80node is higher up in the syntax tree, it contains many smaller nodes
81as its children, and therefore spans a larger portion of text.
82</p>
83<p>When a function cannot find a node, it returns <code>nil</code>. For
84convenience, all functions that take a node as argument and return
85a node, also accept the node argument of <code>nil</code> and in that case
86just return <code>nil</code>.
87</p>
88<span id="index-treesit_002dnode_002doutdated"></span>
89<p>Nodes are not automatically updated when the associated buffer is
90modified, and there is no way to update a node once it is retrieved.
91Using an outdated node signals the <code>treesit-node-outdated</code> error.
92</p>
93<span id="Retrieving-node-from-syntax-tree"></span><h3 class="heading">Retrieving node from syntax tree</h3>
94<span id="index-retrieving-tree_002dsitter-nodes"></span>
95<span id="index-syntax-tree_002c-retrieving-nodes"></span>
96
97<dl class="def">
98<dt id="index-treesit_002dnode_002dat"><span class="category">Function: </span><span><strong>treesit-node-at</strong> <em>pos &amp;optional parser-or-lang named</em><a href='#index-treesit_002dnode_002dat' class='copiable-anchor'> &para;</a></span></dt>
99<dd><p>This function returns the <em>smallest</em> node that starts at or after
100the buffer position <var>pos</var>. In other words, the start of the node
101is greater or equal to <var>pos</var>.
102</p>
103<p>When <var>parser-or-lang</var> is <code>nil</code> or omitted, this function uses
104the first parser in <code>(treesit-parser-list)</code> of the current
105buffer. If <var>parser-or-lang</var> is a parser object, it uses that
106parser; if <var>parser-or-lang</var> is a language, it finds the first
107parser using that language in <code>(treesit-parser-list)</code>, and uses
108that.
109</p>
110<p>If <var>named</var> is non-<code>nil</code>, this function looks for a named node
111only (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
112</p>
113<p>When <var>pos</var> is after all the text in the buffer, technically there
114is no node after <var>pos</var>. But for convenience, this function will
115return the last leaf node in the parse tree. If <var>strict</var> is
116non-<code>nil</code>, this function will strictly comply to the semantics and
117return <var>nil</var>.
118</p>
119<p>Example:
120</p>
121<div class="example">
122<pre class="example">;; Find the node at point in a C parser's syntax tree.
123(treesit-node-at (point) 'c)
124 &rArr; #&lt;treesit-node (primitive_type) in 23-27&gt;
125</pre></div>
126</dd></dl>
127
128<dl class="def">
129<dt id="index-treesit_002dnode_002don"><span class="category">Function: </span><span><strong>treesit-node-on</strong> <em>beg end &amp;optional parser-or-lang named</em><a href='#index-treesit_002dnode_002don' class='copiable-anchor'> &para;</a></span></dt>
130<dd><p>This function returns the <em>smallest</em> node that covers the region
131of buffer text between <var>beg</var> and <var>end</var>. In other words, the
132start of the node is before or at <var>beg</var>, and the end of the node
133is at or after <var>end</var>.
134</p>
135<p><em>Beware:</em> calling this function on an empty line that is not
136inside any top-level construct (function definition, etc.) most
137probably will give you the root node, because the root node is the
138smallest node that covers that empty line. Most of the time, you want
139to use <code>treesit-node-at</code>, described above, instead.
140</p>
141<p>When <var>parser-or-lang</var> is <code>nil</code>, this function uses the first
142parser in <code>(treesit-parser-list)</code> of the current buffer. If
143<var>parser-or-lang</var> is a parser object, it uses that parser; if
144<var>parser-or-lang</var> is a language, it finds the first parser using
145that language in <code>(treesit-parser-list)</code>, and uses that.
146</p>
147<p>If <var>named</var> is non-<code>nil</code>, this function looks for a named node
148only (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
149</p></dd></dl>
150
151<dl class="def">
152<dt id="index-treesit_002dparser_002droot_002dnode"><span class="category">Function: </span><span><strong>treesit-parser-root-node</strong> <em>parser</em><a href='#index-treesit_002dparser_002droot_002dnode' class='copiable-anchor'> &para;</a></span></dt>
153<dd><p>This function returns the root node of the syntax tree generated by
154<var>parser</var>.
155</p></dd></dl>
156
157<dl class="def">
158<dt id="index-treesit_002dbuffer_002droot_002dnode"><span class="category">Function: </span><span><strong>treesit-buffer-root-node</strong> <em>&amp;optional language</em><a href='#index-treesit_002dbuffer_002droot_002dnode' class='copiable-anchor'> &para;</a></span></dt>
159<dd><p>This function finds the first parser that uses <var>language</var> in
160<code>(treesit-parser-list)</code> of the current buffer, and returns the
161root node generated by that parser. If it cannot find an appropriate
162parser, it returns <code>nil</code>.
163</p></dd></dl>
164
165<p>Given a node, a Lisp program can retrieve other nodes starting from
166it, or query for information about this node.
167</p>
168<span id="Retrieving-node-from-other-nodes"></span><h3 class="heading">Retrieving node from other nodes</h3>
169<span id="index-syntax-tree-nodes_002c-retrieving-from-other-nodes"></span>
170
171<span id="By-kinship"></span><h4 class="subheading">By kinship</h4>
172<span id="index-kinship_002c-syntax-tree-nodes"></span>
173<span id="index-nodes_002c-by-kinship"></span>
174<span id="index-syntax-tree-nodes_002c-by-kinship"></span>
175
176<dl class="def">
177<dt id="index-treesit_002dnode_002dparent"><span class="category">Function: </span><span><strong>treesit-node-parent</strong> <em>node</em><a href='#index-treesit_002dnode_002dparent' class='copiable-anchor'> &para;</a></span></dt>
178<dd><p>This function returns the immediate parent of <var>node</var>.
179</p></dd></dl>
180
181<dl class="def">
182<dt id="index-treesit_002dnode_002dchild"><span class="category">Function: </span><span><strong>treesit-node-child</strong> <em>node n &amp;optional named</em><a href='#index-treesit_002dnode_002dchild' class='copiable-anchor'> &para;</a></span></dt>
183<dd><p>This function returns the <var>n</var>&rsquo;th child of <var>node</var>. If
184<var>named</var> is non-<code>nil</code>, it counts only named nodes
185(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
186</p>
187<p>For example, in a node that represents a string <code>&quot;text&quot;</code>, there
188are three children nodes: the opening quote <code>&quot;</code>, the string text
189<code>text</code>, and the closing quote <code>&quot;</code>. Among these nodes, the
190first child is the opening quote <code>&quot;</code>, and the first named child
191is the string text.
192</p>
193<p>This function returns <code>nil</code> if there is no <var>n</var>&rsquo;th child.
194<var>n</var> could be negative, e.g., <code>-1</code> represents the last child.
195</p></dd></dl>
196
197<dl class="def">
198<dt id="index-treesit_002dnode_002dchildren"><span class="category">Function: </span><span><strong>treesit-node-children</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dnode_002dchildren' class='copiable-anchor'> &para;</a></span></dt>
199<dd><p>This function returns all of <var>node</var>&rsquo;s children as a list. If
200<var>named</var> is non-<code>nil</code>, it retrieves only named nodes.
201</p></dd></dl>
202
203<dl class="def">
204<dt id="index-treesit_002dnext_002dsibling"><span class="category">Function: </span><span><strong>treesit-node-next-sibling</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dnext_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
205<dd><p>This function finds the next sibling of <var>node</var>. If <var>named</var> is
206non-<code>nil</code>, it finds the next named sibling.
207</p></dd></dl>
208
209<dl class="def">
210<dt id="index-treesit_002dprev_002dsibling"><span class="category">Function: </span><span><strong>treesit-node-prev-sibling</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dprev_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
211<dd><p>This function finds the previous sibling of <var>node</var>. If
212<var>named</var> is non-<code>nil</code>, it finds the previous named sibling.
213</p></dd></dl>
214
215<span id="By-field-name"></span><h4 class="subheading">By field name</h4>
216<span id="index-nodes_002c-by-field-name"></span>
217<span id="index-syntax-tree-nodes_002c-by-field-name"></span>
218
219<p>To make the syntax tree easier to analyze, many language definitions
220assign <em>field names</em> to child nodes (see <a href="Language-Definitions.html#tree_002dsitter-node-field-name">field name</a>). For example, a <code>function_definition</code> node
221could have a <code>declarator</code> node and a <code>body</code> node.
222</p>
223<dl class="def">
224<dt id="index-treesit_002dchild_002dby_002dfield_002dname"><span class="category">Function: </span><span><strong>treesit-node-child-by-field-name</strong> <em>node field-name</em><a href='#index-treesit_002dchild_002dby_002dfield_002dname' class='copiable-anchor'> &para;</a></span></dt>
225<dd><p>This function finds the child of <var>node</var> whose field name is
226<var>field-name</var>, a string.
227</p>
228<div class="example">
229<pre class="example">;; Get the child that has &quot;body&quot; as its field name.
230(treesit-node-child-by-field-name node &quot;body&quot;)
231 &rArr; #&lt;treesit-node (compound_statement) in 45-89&gt;
232</pre></div>
233</dd></dl>
234
235<span id="By-position"></span><h4 class="subheading">By position</h4>
236<span id="index-nodes_002c-by-position"></span>
237<span id="index-syntax-tree-nodes_002c-by-position"></span>
238
239<dl class="def">
240<dt id="index-treesit_002dfirst_002dchild_002dfor_002dpos"><span class="category">Function: </span><span><strong>treesit-node-first-child-for-pos</strong> <em>node pos &amp;optional named</em><a href='#index-treesit_002dfirst_002dchild_002dfor_002dpos' class='copiable-anchor'> &para;</a></span></dt>
241<dd><p>This function finds the first child of <var>node</var> that extends beyond
242buffer position <var>pos</var>. &ldquo;Extends beyond&rdquo; means the end of the
243child node is greater or equal to <var>pos</var>. This function only looks
244for immediate children of <var>node</var>, and doesn&rsquo;t look in its
245grandchildren. If <var>named</var> is non-<code>nil</code>, it looks for the
246first named child (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
247</p></dd></dl>
248
249<dl class="def">
250<dt id="index-treesit_002dnode_002ddescendant_002dfor_002drange"><span class="category">Function: </span><span><strong>treesit-node-descendant-for-range</strong> <em>node beg end &amp;optional named</em><a href='#index-treesit_002dnode_002ddescendant_002dfor_002drange' class='copiable-anchor'> &para;</a></span></dt>
251<dd><p>This function finds the <em>smallest</em> descendant node of <var>node</var>
252that spans the region of text between positions <var>beg</var> and
253<var>end</var>. It is similar to <code>treesit-node-at</code>. If <var>named</var>
254is non-<code>nil</code>, it looks for smallest named child.
255</p></dd></dl>
256
257<span id="Searching-for-node"></span><h3 class="heading">Searching for node</h3>
258
259<dl class="def">
260<dt id="index-treesit_002dsearch_002dsubtree"><span class="category">Function: </span><span><strong>treesit-search-subtree</strong> <em>node predicate &amp;optional backward all limit</em><a href='#index-treesit_002dsearch_002dsubtree' class='copiable-anchor'> &para;</a></span></dt>
261<dd><p>This function traverses the subtree of <var>node</var> (including
262<var>node</var> itself), looking for a node for which <var>predicate</var>
263returns non-<code>nil</code>. <var>predicate</var> is a regexp that is matched
264against each node&rsquo;s type, or a predicate function that takes a node
265and returns non-<code>nil</code> if the node matches. The function returns
266the first node that matches, or <code>nil</code> if none does.
267</p>
268<p>By default, this function only traverses named nodes, but if <var>all</var>
269is non-<code>nil</code>, it traverses all the nodes. If <var>backward</var> is
270non-<code>nil</code>, it traverses backwards (i.e., it visits the last child first
271when traversing down the tree). If <var>limit</var> is non-<code>nil</code>, it
272must be a number that limits the tree traversal to that many levels
273down the tree.
274</p></dd></dl>
275
276<dl class="def">
277<dt id="index-treesit_002dsearch_002dforward"><span class="category">Function: </span><span><strong>treesit-search-forward</strong> <em>start predicate &amp;optional backward all</em><a href='#index-treesit_002dsearch_002dforward' class='copiable-anchor'> &para;</a></span></dt>
278<dd><p>Like <code>treesit-search-subtree</code>, this function also traverses the
279parse tree and matches each node with <var>predicate</var> (except for
280<var>start</var>), where <var>predicate</var> can be a regexp or a function.
281For a tree like the below where <var>start</var> is marked S, this function
282traverses as numbered from 1 to 12:
283</p>
284<div class="example">
285<pre class="example"> 12
286 |
287 S--------3----------11
288 | | |
289o--o-+--o 1--+--2 6--+-----10
290| | | |
291o o +-+-+ +--+--+
292 | | | | |
293 4 5 7 8 9
294</pre></div>
295
296<p>Note that this function doesn&rsquo;t traverse the subtree of <var>start</var>,
297and it always traverse leaf nodes first, then upwards.
298</p>
299<p>Like <code>treesit-search-subtree</code>, this function only searches for
300named nodes by default, but if <var>all</var> is non-<code>nil</code>, it
301searches for all nodes. If <var>backward</var> is non-<code>nil</code>, it
302searches backwards.
303</p>
304<p>While <code>treesit-search-subtree</code> traverses the subtree of a node,
305this function starts with node <var>start</var> and traverses every node
306that comes after it in the buffer position order, i.e., nodes with
307start positions greater than the end position of <var>start</var>.
308</p>
309<p>In the tree shown above, <code>treesit-search-subtree</code> traverses node
310S (<var>start</var>) and nodes marked with <code>o</code>, where this function
311traverses the nodes marked with numbers. This function is useful for
312answering questions like &ldquo;what is the first node after <var>start</var> in
313the buffer that satisfies some condition?&rdquo;
314</p></dd></dl>
315
316<dl class="def">
317<dt id="index-treesit_002dsearch_002dforward_002dgoto"><span class="category">Function: </span><span><strong>treesit-search-forward-goto</strong> <em>node predicate &amp;optional start backward all</em><a href='#index-treesit_002dsearch_002dforward_002dgoto' class='copiable-anchor'> &para;</a></span></dt>
318<dd><p>This function moves point to the start or end of the next node after
319<var>node</var> in the buffer that matches <var>predicate</var>. If <var>start</var>
320is non-<code>nil</code>, stop at the beginning rather than the end of a node.
321</p>
322<p>This function guarantees that the matched node it returns makes
323progress in terms of buffer position: the start/end position of the
324returned node is always greater than that of <var>node</var>.
325</p>
326<p>Arguments <var>predicate</var>, <var>backward</var> and <var>all</var> are the same
327as in <code>treesit-search-forward</code>.
328</p></dd></dl>
329
330<dl class="def">
331<dt id="index-treesit_002dinduce_002dsparse_002dtree"><span class="category">Function: </span><span><strong>treesit-induce-sparse-tree</strong> <em>root predicate &amp;optional process-fn limit</em><a href='#index-treesit_002dinduce_002dsparse_002dtree' class='copiable-anchor'> &para;</a></span></dt>
332<dd><p>This function creates a sparse tree from <var>root</var>&rsquo;s subtree.
333</p>
334<p>It takes the subtree under <var>root</var>, and combs it so only the nodes
335that match <var>predicate</var> are left. Like previous functions, the
336<var>predicate</var> can be a regexp string that matches against each
337node&rsquo;s type, or a function that takes a node and return non-<code>nil</code>
338if it matches.
339</p>
340<p>For example, for a subtree on the left that consist of both numbers
341and letters, if <var>predicate</var> is &ldquo;letter only&rdquo;, the returned tree
342is the one on the right.
343</p>
344<div class="example">
345<pre class="example"> a a a
346 | | |
347+---+---+ +---+---+ +---+---+
348| | | | | | | | |
349b 1 2 b | | b c d
350 | | =&gt; | | =&gt; |
351 c +--+ c + e
352 | | | | |
353 +--+ d 4 +--+ d
354 | | |
355 e 5 e
356</pre></div>
357
358<p>If <var>process-fn</var> is non-<code>nil</code>, instead of returning the matched
359nodes, this function passes each node to <var>process-fn</var> and uses the
360returned value instead. If non-<code>nil</code>, <var>limit</var> is the number of
361levels to go down from <var>root</var>.
362</p>
363<p>Each node in the returned tree looks like
364<code>(<var><span class="nolinebreak">tree-sitter-node</span></var>&nbsp;.&nbsp;(<var>child</var>&nbsp;&hellip;))</code><!-- /@w -->. The
365<var>tree-sitter-node</var> of the root of this tree will be nil if
366<var>root</var> doesn&rsquo;t match <var>predicate</var>. If no node matches
367<var>predicate</var>, the function returns <code>nil</code>.
368</p></dd></dl>
369
370<span id="More-convenience-functions"></span><h3 class="heading">More convenience functions</h3>
371
372<dl class="def">
373<dt id="index-treesit_002dfilter_002dchild"><span class="category">Function: </span><span><strong>treesit-filter-child</strong> <em>node predicate &amp;optional named</em><a href='#index-treesit_002dfilter_002dchild' class='copiable-anchor'> &para;</a></span></dt>
374<dd><p>This function finds immediate children of <var>node</var> that satisfy
375<var>predicate</var>.
376</p>
377<p>The <var>predicate</var> function takes a node as the argument and should
378return non-<code>nil</code> to indicate that the node should be kept. If
379<var>named</var> is non-<code>nil</code>, this function only examines the named
380nodes.
381</p></dd></dl>
382
383<dl class="def">
384<dt id="index-treesit_002dparent_002duntil"><span class="category">Function: </span><span><strong>treesit-parent-until</strong> <em>node predicate</em><a href='#index-treesit_002dparent_002duntil' class='copiable-anchor'> &para;</a></span></dt>
385<dd><p>This function repeatedly finds the parents of <var>node</var>, and returns
386the parent that satisfies <var>predicate</var>, a function that takes a
387node as the argument. If no parent satisfies <var>predicate</var>, this
388function returns <code>nil</code>.
389</p></dd></dl>
390
391<dl class="def">
392<dt id="index-treesit_002dparent_002dwhile"><span class="category">Function: </span><span><strong>treesit-parent-while</strong> <em>node predicate</em><a href='#index-treesit_002dparent_002dwhile' class='copiable-anchor'> &para;</a></span></dt>
393<dd><p>This function repeatedly finds the parent of <var>node</var>, and keeps
394doing so as long as the nodes satisfy <var>predicate</var>, a function that
395takes a node as the argument. That is, this function returns the
396farthest parent that still satisfies <var>predicate</var>.
397</p></dd></dl>
398
399<dl class="def">
400<dt id="index-treesit_002dnode_002dtop_002dlevel"><span class="category">Function: </span><span><strong>treesit-node-top-level</strong> <em>node &amp;optional type</em><a href='#index-treesit_002dnode_002dtop_002dlevel' class='copiable-anchor'> &para;</a></span></dt>
401<dd><p>This function returns the highest parent of <var>node</var> that has the
402same type as <var>node</var>. If no such parent exists, it returns
403<code>nil</code>. Therefore this function is also useful for testing
404whether <var>node</var> is top-level.
405</p>
406<p>If <var>type</var> is non-<code>nil</code>, this function matches each parent&rsquo;s
407type with <var>type</var> as a regexp, rather than using <var>node</var>&rsquo;s type.
408</p></dd></dl>
409
410</div>
411<hr>
412<div class="header">
413<p>
414Next: <a href="Accessing-Node-Information.html">Accessing Node Information</a>, Previous: <a href="Using-Parser.html">Using Tree-sitter Parser</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<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>
415</div>
416
417
418
419</body>
420</html>
diff --git a/admin/notes/tree-sitter/html-manual/Tree_002dsitter-C-API.html b/admin/notes/tree-sitter/html-manual/Tree_002dsitter-C-API.html
deleted file mode 100644
index 1d992b828ea..00000000000
--- a/admin/notes/tree-sitter/html-manual/Tree_002dsitter-C-API.html
+++ /dev/null
@@ -1,211 +0,0 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6<!-- This is the GNU Emacs Lisp Reference Manual
7corresponding to Emacs version 29.0.50.
8
9Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
10
11Permission is granted to copy, distribute and/or modify this document
12under the terms of the GNU Free Documentation License, Version 1.3 or
13any later version published by the Free Software Foundation; with the
14Invariant Sections being "GNU General Public License," with the
15Front-Cover Texts being "A GNU Manual," and with the Back-Cover
16Texts as in (a) below. A copy of the license is included in the
17section entitled "GNU Free Documentation License."
18
19(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
20modify this GNU manual. Buying copies from the FSF supports it in
21developing GNU and promoting software freedom." -->
22<title>Tree-sitter C API (GNU Emacs Lisp Reference Manual)</title>
23
24<meta name="description" content="Tree-sitter C API (GNU Emacs Lisp Reference Manual)">
25<meta name="keywords" content="Tree-sitter C API (GNU Emacs Lisp Reference Manual)">
26<meta name="resource-type" content="document">
27<meta name="distribution" content="global">
28<meta name="Generator" content="makeinfo">
29<meta name="viewport" content="width=device-width,initial-scale=1">
30
31<link href="index.html" rel="start" title="Top">
32<link href="Index.html" rel="index" title="Index">
33<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
34<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
35<link href="Tree_002dsitter-major-modes.html" rel="prev" title="Tree-sitter major modes">
36<style type="text/css">
37<!--
38a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
39a.summary-letter {text-decoration: none}
40blockquote.indentedblock {margin-right: 0em}
41div.display {margin-left: 3.2em}
42div.example {margin-left: 3.2em}
43kbd {font-style: oblique}
44pre.display {font-family: inherit}
45pre.format {font-family: inherit}
46pre.menu-comment {font-family: serif}
47pre.menu-preformatted {font-family: serif}
48span.nolinebreak {white-space: nowrap}
49span.roman {font-family: initial; font-weight: normal}
50span.sansserif {font-family: sans-serif; font-weight: normal}
51span:hover a.copiable-anchor {visibility: visible}
52ul.no-bullet {list-style: none}
53-->
54</style>
55<link rel="stylesheet" type="text/css" href="./manual.css">
56
57
58</head>
59
60<body lang="en">
61<div class="section" id="Tree_002dsitter-C-API">
62<div class="header">
63<p>
64Previous: <a href="Tree_002dsitter-major-modes.html" accesskey="p" rel="prev">Developing major modes with tree-sitter</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<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>
65</div>
66<hr>
67<span id="Tree_002dsitter-C-API-Correspondence"></span><h3 class="section">37.8 Tree-sitter C API Correspondence</h3>
68
69<p>Emacs&rsquo; tree-sitter integration doesn&rsquo;t expose every feature
70provided by tree-sitter&rsquo;s C API. Missing features include:
71</p>
72<ul>
73<li> Creating a tree cursor and navigating the syntax tree with it.
74</li><li> Setting timeout and cancellation flag for a parser.
75</li><li> Setting the logger for a parser.
76</li><li> Printing a <acronym>DOT</acronym> graph of the syntax tree to a file.
77</li><li> Copying and modifying a syntax tree. (Emacs doesn&rsquo;t expose a tree
78object.)
79</li><li> Using (row, column) coordinates as position.
80</li><li> Updating a node with changes. (In Emacs, retrieve a new node instead
81of updating the existing one.)
82</li><li> Querying statics of a language definition.
83</li></ul>
84
85<p>In addition, Emacs makes some changes to the C API to make the API more
86convenient and idiomatic:
87</p>
88<ul>
89<li> Instead of using byte positions, the Emacs Lisp API uses character
90positions.
91</li><li> Null nodes are converted to nil.
92</li></ul>
93
94<p>Below is the correspondence between all C API functions and their
95ELisp counterparts. Sometimes one ELisp function corresponds to
96multiple C functions, and many C functions don&rsquo;t have an ELisp
97counterpart.
98</p>
99<div class="example">
100<pre class="example">ts_parser_new treesit-parser-create
101ts_parser_delete
102ts_parser_set_language
103ts_parser_language treesit-parser-language
104ts_parser_set_included_ranges treesit-parser-set-included-ranges
105ts_parser_included_ranges treesit-parser-included-ranges
106ts_parser_parse
107ts_parser_parse_string treesit-parse-string
108ts_parser_parse_string_encoding
109ts_parser_reset
110ts_parser_set_timeout_micros
111ts_parser_timeout_micros
112ts_parser_set_cancellation_flag
113ts_parser_cancellation_flag
114ts_parser_set_logger
115ts_parser_logger
116ts_parser_print_dot_graphs
117ts_tree_copy
118ts_tree_delete
119ts_tree_root_node
120ts_tree_language
121ts_tree_edit
122ts_tree_get_changed_ranges
123ts_tree_print_dot_graph
124ts_node_type treesit-node-type
125ts_node_symbol
126ts_node_start_byte treesit-node-start
127ts_node_start_point
128ts_node_end_byte treesit-node-end
129ts_node_end_point
130ts_node_string treesit-node-string
131ts_node_is_null
132ts_node_is_named treesit-node-check
133ts_node_is_missing treesit-node-check
134ts_node_is_extra treesit-node-check
135ts_node_has_changes
136ts_node_has_error treesit-node-check
137ts_node_parent treesit-node-parent
138ts_node_child treesit-node-child
139ts_node_field_name_for_child treesit-node-field-name-for-child
140ts_node_child_count treesit-node-child-count
141ts_node_named_child treesit-node-child
142ts_node_named_child_count treesit-node-child-count
143ts_node_child_by_field_name treesit-node-by-field-name
144ts_node_child_by_field_id
145ts_node_next_sibling treesit-node-next-sibling
146ts_node_prev_sibling treesit-node-prev-sibling
147ts_node_next_named_sibling treesit-node-next-sibling
148ts_node_prev_named_sibling treesit-node-prev-sibling
149ts_node_first_child_for_byte treesit-node-first-child-for-pos
150ts_node_first_named_child_for_byte treesit-node-first-child-for-pos
151ts_node_descendant_for_byte_range treesit-descendant-for-range
152ts_node_descendant_for_point_range
153ts_node_named_descendant_for_byte_range treesit-descendant-for-range
154ts_node_named_descendant_for_point_range
155ts_node_edit
156ts_node_eq treesit-node-eq
157ts_tree_cursor_new
158ts_tree_cursor_delete
159ts_tree_cursor_reset
160ts_tree_cursor_current_node
161ts_tree_cursor_current_field_name
162ts_tree_cursor_current_field_id
163ts_tree_cursor_goto_parent
164ts_tree_cursor_goto_next_sibling
165ts_tree_cursor_goto_first_child
166ts_tree_cursor_goto_first_child_for_byte
167ts_tree_cursor_goto_first_child_for_point
168ts_tree_cursor_copy
169ts_query_new
170ts_query_delete
171ts_query_pattern_count
172ts_query_capture_count
173ts_query_string_count
174ts_query_start_byte_for_pattern
175ts_query_predicates_for_pattern
176ts_query_step_is_definite
177ts_query_capture_name_for_id
178ts_query_string_value_for_id
179ts_query_disable_capture
180ts_query_disable_pattern
181ts_query_cursor_new
182ts_query_cursor_delete
183ts_query_cursor_exec treesit-query-capture
184ts_query_cursor_did_exceed_match_limit
185ts_query_cursor_match_limit
186ts_query_cursor_set_match_limit
187ts_query_cursor_set_byte_range
188ts_query_cursor_set_point_range
189ts_query_cursor_next_match
190ts_query_cursor_remove_match
191ts_query_cursor_next_capture
192ts_language_symbol_count
193ts_language_symbol_name
194ts_language_symbol_for_name
195ts_language_field_count
196ts_language_field_name_for_id
197ts_language_field_id_for_name
198ts_language_symbol_type
199ts_language_version
200</pre></div>
201</div>
202<hr>
203<div class="header">
204<p>
205Previous: <a href="Tree_002dsitter-major-modes.html">Developing major modes with tree-sitter</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<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>
206</div>
207
208
209
210</body>
211</html>
diff --git a/admin/notes/tree-sitter/html-manual/Using-Parser.html b/admin/notes/tree-sitter/html-manual/Using-Parser.html
deleted file mode 100644
index fd8fc482f46..00000000000
--- a/admin/notes/tree-sitter/html-manual/Using-Parser.html
+++ /dev/null
@@ -1,230 +0,0 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6<!-- This is the GNU Emacs Lisp Reference Manual
7corresponding to Emacs version 29.0.50.
8
9Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
10
11Permission is granted to copy, distribute and/or modify this document
12under the terms of the GNU Free Documentation License, Version 1.3 or
13any later version published by the Free Software Foundation; with the
14Invariant Sections being "GNU General Public License," with the
15Front-Cover Texts being "A GNU Manual," and with the Back-Cover
16Texts as in (a) below. A copy of the license is included in the
17section entitled "GNU Free Documentation License."
18
19(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
20modify this GNU manual. Buying copies from the FSF supports it in
21developing GNU and promoting software freedom." -->
22<title>Using Parser (GNU Emacs Lisp Reference Manual)</title>
23
24<meta name="description" content="Using Parser (GNU Emacs Lisp Reference Manual)">
25<meta name="keywords" content="Using Parser (GNU Emacs Lisp Reference Manual)">
26<meta name="resource-type" content="document">
27<meta name="distribution" content="global">
28<meta name="Generator" content="makeinfo">
29<meta name="viewport" content="width=device-width,initial-scale=1">
30
31<link href="index.html" rel="start" title="Top">
32<link href="Index.html" rel="index" title="Index">
33<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
34<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
35<link href="Retrieving-Nodes.html" rel="next" title="Retrieving Nodes">
36<link href="Language-Definitions.html" rel="prev" title="Language Definitions">
37<style type="text/css">
38<!--
39a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
40a.summary-letter {text-decoration: none}
41blockquote.indentedblock {margin-right: 0em}
42div.display {margin-left: 3.2em}
43div.example {margin-left: 3.2em}
44kbd {font-style: oblique}
45pre.display {font-family: inherit}
46pre.format {font-family: inherit}
47pre.menu-comment {font-family: serif}
48pre.menu-preformatted {font-family: serif}
49span.nolinebreak {white-space: nowrap}
50span.roman {font-family: initial; font-weight: normal}
51span.sansserif {font-family: sans-serif; font-weight: normal}
52span:hover a.copiable-anchor {visibility: visible}
53ul.no-bullet {list-style: none}
54-->
55</style>
56<link rel="stylesheet" type="text/css" href="./manual.css">
57
58
59</head>
60
61<body lang="en">
62<div class="section" id="Using-Parser">
63<div class="header">
64<p>
65Next: <a href="Retrieving-Nodes.html" accesskey="n" rel="next">Retrieving Nodes</a>, Previous: <a href="Language-Definitions.html" accesskey="p" rel="prev">Tree-sitter Language Definitions</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<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>
66</div>
67<hr>
68<span id="Using-Tree_002dsitter-Parser"></span><h3 class="section">37.2 Using Tree-sitter Parser</h3>
69<span id="index-tree_002dsitter-parser_002c-using"></span>
70
71<p>This section describes how to create and configure a tree-sitter
72parser. In Emacs, each tree-sitter parser is associated with a
73buffer. As the user edits the buffer, the associated parser and
74syntax tree are automatically kept up-to-date.
75</p>
76<dl class="def">
77<dt id="index-treesit_002dmax_002dbuffer_002dsize"><span class="category">Variable: </span><span><strong>treesit-max-buffer-size</strong><a href='#index-treesit_002dmax_002dbuffer_002dsize' class='copiable-anchor'> &para;</a></span></dt>
78<dd><p>This variable contains the maximum size of buffers in which
79tree-sitter can be activated. Major modes should check this value
80when deciding whether to enable tree-sitter features.
81</p></dd></dl>
82
83<dl class="def">
84<dt id="index-treesit_002dcan_002denable_002dp"><span class="category">Function: </span><span><strong>treesit-can-enable-p</strong><a href='#index-treesit_002dcan_002denable_002dp' class='copiable-anchor'> &para;</a></span></dt>
85<dd><p>This function checks whether the current buffer is suitable for
86activating tree-sitter features. It basically checks
87<code>treesit-available-p</code> and <code>treesit-max-buffer-size</code>.
88</p></dd></dl>
89
90<span id="index-creating-tree_002dsitter-parsers"></span>
91<span id="index-tree_002dsitter-parser_002c-creating"></span>
92<dl class="def">
93<dt id="index-treesit_002dparser_002dcreate"><span class="category">Function: </span><span><strong>treesit-parser-create</strong> <em>language &amp;optional buffer no-reuse</em><a href='#index-treesit_002dparser_002dcreate' class='copiable-anchor'> &para;</a></span></dt>
94<dd><p>Create a parser for the specified <var>buffer</var> and <var>language</var>
95(see <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>). If <var>buffer</var> is omitted or
96<code>nil</code>, it stands for the current buffer.
97</p>
98<p>By default, this function reuses a parser if one already exists for
99<var>language</var> in <var>buffer</var>, but if <var>no-reuse</var> is
100non-<code>nil</code>, this function always creates a new parser.
101</p></dd></dl>
102
103<p>Given a parser, we can query information about it.
104</p>
105<dl class="def">
106<dt id="index-treesit_002dparser_002dbuffer"><span class="category">Function: </span><span><strong>treesit-parser-buffer</strong> <em>parser</em><a href='#index-treesit_002dparser_002dbuffer' class='copiable-anchor'> &para;</a></span></dt>
107<dd><p>This function returns the buffer associated with <var>parser</var>.
108</p></dd></dl>
109
110<dl class="def">
111<dt id="index-treesit_002dparser_002dlanguage"><span class="category">Function: </span><span><strong>treesit-parser-language</strong> <em>parser</em><a href='#index-treesit_002dparser_002dlanguage' class='copiable-anchor'> &para;</a></span></dt>
112<dd><p>This function returns the language used by <var>parser</var>.
113</p></dd></dl>
114
115<dl class="def">
116<dt id="index-treesit_002dparser_002dp"><span class="category">Function: </span><span><strong>treesit-parser-p</strong> <em>object</em><a href='#index-treesit_002dparser_002dp' class='copiable-anchor'> &para;</a></span></dt>
117<dd><p>This function checks if <var>object</var> is a tree-sitter parser, and
118returns non-<code>nil</code> if it is, and <code>nil</code> otherwise.
119</p></dd></dl>
120
121<p>There is no need to explicitly parse a buffer, because parsing is done
122automatically and lazily. A parser only parses when a Lisp program
123queries for a node in its syntax tree. Therefore, when a parser is
124first created, it doesn&rsquo;t parse the buffer; it waits until the Lisp
125program queries for a node for the first time. Similarly, when some
126change is made in the buffer, a parser doesn&rsquo;t re-parse immediately.
127</p>
128<span id="index-treesit_002dbuffer_002dtoo_002dlarge"></span>
129<p>When a parser does parse, it checks for the size of the buffer.
130Tree-sitter can only handle buffer no larger than about 4GB. If the
131size exceeds that, Emacs signals the <code>treesit-buffer-too-large</code>
132error with signal data being the buffer size.
133</p>
134<p>Once a parser is created, Emacs automatically adds it to the
135internal parser list. Every time a change is made to the buffer,
136Emacs updates parsers in this list so they can update their syntax
137tree incrementally.
138</p>
139<dl class="def">
140<dt id="index-treesit_002dparser_002dlist"><span class="category">Function: </span><span><strong>treesit-parser-list</strong> <em>&amp;optional buffer</em><a href='#index-treesit_002dparser_002dlist' class='copiable-anchor'> &para;</a></span></dt>
141<dd><p>This function returns the parser list of <var>buffer</var>. If
142<var>buffer</var> is <code>nil</code> or omitted, it defaults to the current
143buffer.
144</p></dd></dl>
145
146<dl class="def">
147<dt id="index-treesit_002dparser_002ddelete"><span class="category">Function: </span><span><strong>treesit-parser-delete</strong> <em>parser</em><a href='#index-treesit_002dparser_002ddelete' class='copiable-anchor'> &para;</a></span></dt>
148<dd><p>This function deletes <var>parser</var>.
149</p></dd></dl>
150
151<span id="index-tree_002dsitter-narrowing"></span>
152<span id="tree_002dsitter-narrowing"></span><p>Normally, a parser &ldquo;sees&rdquo; the whole buffer, but when the buffer is
153narrowed (see <a href="Narrowing.html">Narrowing</a>), the parser will only see the accessible
154portion of the buffer. As far as the parser can tell, the hidden
155region was deleted. When the buffer is later widened, the parser
156thinks text is inserted at the beginning and at the end. Although
157parsers respect narrowing, modes should not use narrowing as a means
158to handle a multi-language buffer; instead, set the ranges in which the
159parser should operate. See <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>.
160</p>
161<p>Because a parser parses lazily, when the user or a Lisp program
162narrows the buffer, the parser is not affected immediately; as long as
163the mode doesn&rsquo;t query for a node while the buffer is narrowed, the
164parser is oblivious of the narrowing.
165</p>
166<span id="index-tree_002dsitter-parse-string"></span>
167<span id="index-parse-string_002c-tree_002dsitter"></span>
168<p>Besides creating a parser for a buffer, a Lisp program can also parse a
169string. Unlike a buffer, parsing a string is a one-off operation, and
170there is no way to update the result.
171</p>
172<dl class="def">
173<dt id="index-treesit_002dparse_002dstring"><span class="category">Function: </span><span><strong>treesit-parse-string</strong> <em>string language</em><a href='#index-treesit_002dparse_002dstring' class='copiable-anchor'> &para;</a></span></dt>
174<dd><p>This function parses <var>string</var> using <var>language</var>, and returns
175the root node of the generated syntax tree.
176</p></dd></dl>
177
178<span id="Be-notified-by-changes-to-the-parse-tree"></span><h3 class="heading">Be notified by changes to the parse tree</h3>
179<span id="index-update-callback_002c-for-tree_002dsitter-parse_002dtree"></span>
180<span id="index-after_002dchange-notifier_002c-for-tree_002dsitter-parse_002dtree"></span>
181<span id="index-tree_002dsitter-parse_002dtree_002c-update-and-after_002dchange-callback"></span>
182<span id="index-notifiers_002c-tree_002dsitter"></span>
183
184<p>A Lisp program might want to be notified of text affected by
185incremental parsing. For example, inserting a comment-closing token
186converts text before that token into a comment. Even
187though the text is not directly edited, it is deemed to be &ldquo;changed&rdquo;
188nevertheless.
189</p>
190<p>Emacs lets a Lisp program to register callback functions
191(a.k.a. <em>notifiers</em>) for this kind of changes. A notifier
192function takes two arguments: <var>ranges</var> and <var>parser</var>.
193<var>ranges</var> is a list of cons cells of the form <code>(<var>start</var>&nbsp;.&nbsp;<var>end</var>)</code><!-- /@w -->, where <var>start</var> and <var>end</var> mark the start and the
194end positions of a range. <var>parser</var> is the parser issuing the
195notification.
196</p>
197<p>Every time a parser reparses a buffer, it compares the old and new
198parse-tree, computes the ranges in which nodes have changed, and
199passes the ranges to notifier functions.
200</p>
201<dl class="def">
202<dt id="index-treesit_002dparser_002dadd_002dnotifier"><span class="category">Function: </span><span><strong>treesit-parser-add-notifier</strong> <em>parser function</em><a href='#index-treesit_002dparser_002dadd_002dnotifier' class='copiable-anchor'> &para;</a></span></dt>
203<dd><p>This function adds <var>function</var> to <var>parser</var>&rsquo;s list of
204after-change notifier functions. <var>function</var> must be a function
205symbol, not a lambda function (see <a href="Anonymous-Functions.html">Anonymous Functions</a>).
206</p></dd></dl>
207
208<dl class="def">
209<dt id="index-treesit_002dparser_002dremove_002dnotifier"><span class="category">Function: </span><span><strong>treesit-parser-remove-notifier</strong> <em>parser function</em><a href='#index-treesit_002dparser_002dremove_002dnotifier' class='copiable-anchor'> &para;</a></span></dt>
210<dd><p>This function removes <var>function</var> from the list of <var>parser</var>&rsquo;s
211after-change notifier functions. <var>function</var> must be a function
212symbol, rather than a lambda function.
213</p></dd></dl>
214
215<dl class="def">
216<dt id="index-treesit_002dparser_002dnotifiers"><span class="category">Function: </span><span><strong>treesit-parser-notifiers</strong> <em>parser</em><a href='#index-treesit_002dparser_002dnotifiers' class='copiable-anchor'> &para;</a></span></dt>
217<dd><p>This function returns the list of <var>parser</var>&rsquo;s notifier functions.
218</p></dd></dl>
219
220</div>
221<hr>
222<div class="header">
223<p>
224Next: <a href="Retrieving-Nodes.html">Retrieving Nodes</a>, Previous: <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<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>
225</div>
226
227
228
229</body>
230</html>
diff --git a/admin/notes/tree-sitter/html-manual/build-manual.sh b/admin/notes/tree-sitter/html-manual/build-manual.sh
deleted file mode 100755
index 8d931b143b2..00000000000
--- a/admin/notes/tree-sitter/html-manual/build-manual.sh
+++ /dev/null
@@ -1,23 +0,0 @@
1#!/bin/bash
2
3MANUAL_DIR="../../../../doc/lispref"
4THIS_DIR=$(pwd)
5
6echo "Build manual"
7cd "${MANUAL_DIR}"
8make elisp.html HTML_OPTS="--html --css-ref=./manual.css"
9
10cd "${THIS_DIR}"
11
12echo "Copy manual"
13cp -f "${MANUAL_DIR}/elisp.html/Parsing-Program-Source.html" .
14cp -f "${MANUAL_DIR}/elisp.html/Language-Definitions.html" .
15cp -f "${MANUAL_DIR}/elisp.html/Using-Parser.html" .
16cp -f "${MANUAL_DIR}/elisp.html/Retrieving-Node.html" .
17cp -f "${MANUAL_DIR}/elisp.html/Accessing-Node.html" .
18cp -f "${MANUAL_DIR}/elisp.html/Pattern-Matching.html" .
19cp -f "${MANUAL_DIR}/elisp.html/Multiple-Languages.html" .
20cp -f "${MANUAL_DIR}/elisp.html/Tree_002dsitter-C-API.html" .
21
22cp -f "${MANUAL_DIR}/elisp.html/Parser_002dbased-Font-Lock.html" .
23cp -f "${MANUAL_DIR}/elisp.html/Parser_002dbased-Indentation.html" .
diff --git a/admin/notes/tree-sitter/html-manual/manual.css b/admin/notes/tree-sitter/html-manual/manual.css
deleted file mode 100644
index c03e0d37009..00000000000
--- a/admin/notes/tree-sitter/html-manual/manual.css
+++ /dev/null
@@ -1,374 +0,0 @@
1/* Style-sheet to use for Emacs manuals */
2
3/* Copyright (C) 2013-2014, 2023 Free Software Foundation, Inc.
4
5Copying and distribution of this file, with or without modification,
6are permitted in any medium without royalty provided the copyright
7notice and this notice are preserved. This file is offered as-is,
8without any warranty.
9*/
10
11/* style.css begins here */
12
13/* This stylesheet is used by manuals and a few older resources. */
14
15/* reset.css begins here */
16
17/*
18Software License Agreement (BSD License)
19
20Copyright (c) 2006, Yahoo! Inc.
21All rights reserved.
22
23Redistribution and use of this software in source and
24binary forms, with or without modification, arepermitted
25provided that the following conditions are met:
26
27* Redistributions of source code must retain the above
28copyright notice, this list of conditions and the
29following disclaimer.
30
31* Redistributions in binary form must reproduce the above
32copyright notice, this list of conditions and the
33following disclaimer in the documentation and/or other
34materials provided with the distribution.
35
36* Neither the name of Yahoo! Inc. nor the names of its
37contributors may be used to endorse or promote products
38derived from this software without specific prior
39written permission of Yahoo! Inc.
40
41THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
42CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
43INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
44MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
45DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
46CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
47SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
48NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
49LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
50HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
51IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
52NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
53OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
54SUCH DAMAGE.
55*/
56
57html {
58 color: #000;
59 background: #FFF;
60}
61
62body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4,
63h5, h6, pre, code, form, fieldset, legend, input,
64button, textarea, p, blockquote, th, td {
65 margin: 0;
66 padding: 0;
67}
68
69table {
70 border-collapse: collapse;
71 border-spacing: 0;
72}
73
74fieldset, img {
75 border: 0;
76}
77
78address, caption, cite, code, dfn, em, strong,
79th, var, optgroup {
80 font-style: inherit;
81 font-weight: inherit;
82}
83
84del, ins {
85 text-decoration: none;
86}
87
88li {
89 list-style:none;
90}
91
92caption, th {
93 text-align: left;
94}
95
96h1, h2, h3, h4, h5, h6 {
97 font-size: 100%;
98 font-weight: normal;
99}
100
101q:before, q:after {
102 content:'';
103}
104
105abbr, acronym {
106 border: 0;
107 font-variant: normal;
108}
109
110sup {
111 vertical-align: baseline;
112}
113sub {
114 vertical-align: baseline;
115}
116
117legend {
118 color: #000;
119}
120
121input, button, textarea, select, optgroup, option {
122 font-family: inherit;
123 font-size: inherit;
124 font-style: inherit;
125 font-weight: inherit;
126}
127
128input, button, textarea, select {
129 *font-size: 100%;
130}
131
132
133/* reset.css ends here */
134
135/*** PAGE LAYOUT ***/
136
137html, body {
138 font-size: 1em;
139 text-align: left;
140 text-decoration: none;
141}
142html { background-color: #e7e7e7; }
143
144body {
145 max-width: 74.92em;
146 margin: 0 auto;
147 padding: .5em 1em 1em 1em;
148 background-color: white;
149 border: .1em solid #c0c0c0;
150}
151
152
153/*** BASIC ELEMENTS ***/
154
155/* Size and positioning */
156
157p, pre, li, dt, dd, table, code, address { line-height: 1.3em; }
158
159h1 { font-size: 2em; margin: 1em 0 }
160h2 { font-size: 1.50em; margin: 1.0em 0 0.87em 0; }
161h3 { font-size: 1.30em; margin: 1.0em 0 0.87em 0; }
162h4 { font-size: 1.13em; margin: 1.0em 0 0.88em 0; }
163h5 { font-size: 1.00em; margin: 1.0em 0 1.00em 0; }
164
165p, pre { margin: 1em 0; }
166pre { overflow: auto; padding-bottom: .3em; }
167
168ul, ol, blockquote { margin-left: 1.5%; margin-right: 1.5%; }
169hr { margin: 1em 0; }
170/* Lists of underlined links are difficult to read. The top margin
171 gives a little more spacing between entries. */
172ul li { margin: .5em 1em; }
173ol li { margin: 1em; }
174ol ul li { margin: .5em 1em; }
175ul li p, ul ul li { margin-top: .3em; margin-bottom: .3em; }
176ul ul, ol ul { margin-top: 0; margin-bottom: 0; }
177
178/* Separate description lists from preceding text */
179dl { margin: 1em 0 0 0; }
180/* separate the "term" from subsequent "description" */
181dt { margin: .5em 0; }
182/* separate the "description" from subsequent list item
183 when the final <dd> child is an anonymous box */
184dd { margin: .5em 3% 1em 3%; }
185/* separate anonymous box (used to be the first element in <dd>)
186 from subsequent <p> */
187dd p { margin: .5em 0; }
188
189table {
190 display: block; overflow: auto;
191 margin-top: 1.5em; margin-bottom: 1.5em;
192}
193th { padding: .3em .5em; text-align: center; }
194td { padding: .2em .5em; }
195
196address { margin-bottom: 1em; }
197caption { margin-bottom: .5em; text-align: center; }
198sup { vertical-align: super; }
199sub { vertical-align: sub; }
200
201/* Style */
202
203h1, h2, h3, h4, h5, h6, strong, dt, th { font-weight: bold; }
204
205/* The default color (black) is too dark for large text in
206 bold font. */
207h1, h2, h3, h4 { color: #333; }
208h5, h6, dt { color: #222; }
209
210a[href] { color: #005090; }
211a[href]:visited { color: #100070; }
212a[href]:active, a[href]:hover {
213 color: #100070;
214 text-decoration: none;
215}
216
217h1 a[href]:visited, h2 a[href]:visited, h3 a[href]:visited,
218h4 a[href]:visited { color: #005090; }
219h1 a[href]:hover, h2 a[href]:hover, h3 a[href]:hover,
220h4 a[href]:hover { color: #100070; }
221
222ol { list-style: decimal outside;}
223ul { list-style: square outside; }
224ul ul, ol ul { list-style: circle; }
225li { list-style: inherit; }
226
227hr { background-color: #ede6d5; }
228table { border: 0; }
229
230abbr,acronym {
231 border-bottom:1px dotted #000;
232 text-decoration: none;
233 cursor:help;
234}
235del { text-decoration: line-through; }
236em { font-style: italic; }
237small { font-size: .9em; }
238
239img { max-width: 100%}
240
241
242/*** SIMPLE CLASSES ***/
243
244.center, .c { text-align: center; }
245.nocenter{ text-align: left; }
246
247.underline { text-decoration: underline; }
248.nounderline { text-decoration: none; }
249
250.no-bullet { list-style: none; }
251.inline-list li { display: inline }
252
253.netscape4, .no-display { display: none; }
254
255
256/*** MANUAL PAGES ***/
257
258/* This makes the very long tables of contents in Gnulib and other
259 manuals easier to read. */
260.contents ul, .shortcontents ul { font-weight: bold; }
261.contents ul ul, .shortcontents ul ul { font-weight: normal; }
262.contents ul { list-style: none; }
263
264/* For colored navigation bars (Emacs manual): make the bar extend
265 across the whole width of the page and give it a decent height. */
266.header, .node { margin: 0 -1em; padding: 0 1em; }
267.header p, .node p { line-height: 2em; }
268
269/* For navigation links */
270.node a, .header a { display: inline-block; line-height: 2em; }
271.node a:hover, .header a:hover { background: #f2efe4; }
272
273/* Inserts */
274table.cartouche td { padding: 1.5em; }
275
276div.display, div.lisp, div.smalldisplay,
277div.smallexample, div.smalllisp { margin-left: 3%; }
278
279div.example { padding: .8em 1.2em .4em; }
280pre.example { padding: .8em 1.2em; }
281div.example, pre.example {
282 margin: 1em 0 1em 3% ;
283 -webkit-border-radius: .3em;
284 -moz-border-radius: .3em;
285 border-radius: .3em;
286 border: 1px solid #d4cbb6;
287 background-color: #f2efe4;
288}
289div.example > pre.example {
290 padding: 0 0 .4em;
291 margin: 0;
292 border: none;
293}
294
295pre.menu-comment { padding-top: 1.3em; margin: 0; }
296
297
298/*** FOR WIDE SCREENS ***/
299
300@media (min-width: 40em) {
301 body { padding: .5em 3em 1em 3em; }
302 div.header, div.node { margin: 0 -3em; padding: 0 3em; }
303}
304
305/* style.css ends here */
306
307/* makeinfo convert @deffn and similar functions to something inside
308 <blockquote>. style.css uses italic for blockquote. This looks poor
309 in the Emacs manuals, which make extensive use of @defun (etc).
310 In particular, references to function arguments appear as <var>
311 inside <blockquote>. Since <var> is also italic, it makes it
312 impossible to distinguish variables. We could change <var> to
313 e.g. bold-italic, or normal, or a different color, but that does
314 not look as good IMO. So we just override blockquote to be non-italic.
315 */
316blockquote { font-style: normal; }
317
318var { font-style: italic; }
319
320div.header {
321 background-color: #DDDDFF;
322 padding-top: 0.2em;
323}
324
325
326/*** Customization ***/
327
328body {
329 font-family: Charter, serif;
330 font-size: 14pt;
331 line-height: 1.4;
332 background-color: #fefefc;
333 color: #202010;
334}
335
336pre.menu-comment {
337 font-family: Charter, serif;
338 font-size: 14pt;
339}
340
341body > *, body > div.display, body > div.lisp, body > div.smalldisplay,
342body > div.example, body > div.smallexample, body > div.smalllisp {
343 width: 700px;
344 margin-left: auto;
345 margin-right: auto;
346}
347
348div.header {
349 width: 100%;
350 min-height: 3em;
351 font-size: 13pt;
352}
353
354/* Documentation block for functions and variables. Make then
355 narrower*/
356dd {
357 margin: .5em 6% 1em 6%
358}
359
360code, pre, kbd, samp, tt {
361 font-size: 12pt;
362 font-family: monospace;
363}
364
365/* In each node we have index table to all sub-nodes. Make more space
366 for the first column, which is the name to each sub-node. */
367table.menu tbody tr td:nth-child(1) {
368 white-space: nowrap;
369}
370
371div.header p {
372 text-align: center;
373 margin: 0.5em auto 0.5em auto;
374}
generated by cgit v1.2.1 (git 2.18.0) at 2026-03-06 20:26:55 +0000