aboutsummaryrefslogtreecommitdiffstats
path: root/admin/notes/tree-sitter/html-manual/Using-Parser.html
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/notes/tree-sitter/html-manual/Using-Parser.html
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/notes/tree-sitter/html-manual/Using-Parser.html')
-rw-r--r--admin/notes/tree-sitter/html-manual/Using-Parser.html230
1 files changed, 0 insertions, 230 deletions
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>
generated by cgit v1.2.1 (git 2.18.0) at 2026-03-05 04:55:23 +0000