aboutsummaryrefslogtreecommitdiffstats
path: root/admin/notes/tree-sitter/html-manual/Using-Parser.html
diff options
context:
space:
mode:
authorYuan Fu2022-10-05 14:11:33 -0700
committerYuan Fu2022-10-05 14:11:33 -0700
commitcb183f6467401fb5ed2b7fc98ca75be9d943cbe3 (patch)
treeef42ea6ae71e0829d900ffb46d8306fbba962a8e /admin/notes/tree-sitter/html-manual/Using-Parser.html
parent1ea503ed4b3a14b3dc0a597cfbfe57d73b871422 (diff)
downloademacs-cb183f6467401fb5ed2b7fc98ca75be9d943cbe3.tar.gz
emacs-cb183f6467401fb5ed2b7fc98ca75be9d943cbe3.zip
Add tree-sitter admin notes
starter-guide: Guide on writing major mode features. build-module: Script for building official language definitions. html-manual: HTML version of the manual for easy access. * admin/notes/tree-sitter/build-module/README: New file. * admin/notes/tree-sitter/build-module/batch.sh: New file. * admin/notes/tree-sitter/build-module/build.sh: New file. * admin/notes/tree-sitter/starter-guide: New file. * admin/notes/tree-sitter/html-manual/Accessing-Node.html: New file. * admin/notes/tree-sitter/html-manual/Language-Definitions.html: New file. * admin/notes/tree-sitter/html-manual/Multiple-Languages.html: New file. * admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html: New file. * admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html: New file. * admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html: New file. * admin/notes/tree-sitter/html-manual/Pattern-Matching.html: New file. * admin/notes/tree-sitter/html-manual/Retrieving-Node.html: New file. * admin/notes/tree-sitter/html-manual/Tree_002dsitter-C-API.html: New file. * admin/notes/tree-sitter/html-manual/Using-Parser.html: New file. * admin/notes/tree-sitter/html-manual/build-manual.sh: New file. * admin/notes/tree-sitter/html-manual/manual.css: New file.
Diffstat (limited to 'admin/notes/tree-sitter/html-manual/Using-Parser.html')
-rw-r--r--admin/notes/tree-sitter/html-manual/Using-Parser.html186
1 files changed, 186 insertions, 0 deletions
diff --git a/admin/notes/tree-sitter/html-manual/Using-Parser.html b/admin/notes/tree-sitter/html-manual/Using-Parser.html
new file mode 100644
index 00000000000..438e3858f1b
--- /dev/null
+++ b/admin/notes/tree-sitter/html-manual/Using-Parser.html
@@ -0,0 +1,186 @@
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-2022 Free Software Foundation,
10Inc.
11
12Permission is granted to copy, distribute and/or modify this document
13under the terms of the GNU Free Documentation License, Version 1.3 or
14any later version published by the Free Software Foundation; with the
15Invariant Sections being "GNU General Public License," with the
16Front-Cover Texts being "A GNU Manual," and with the Back-Cover
17Texts as in (a) below. A copy of the license is included in the
18section entitled "GNU Free Documentation License."
19
20(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
21modify this GNU manual. Buying copies from the FSF supports it in
22developing GNU and promoting software freedom." -->
23<title>Using Parser (GNU Emacs Lisp Reference Manual)</title>
24
25<meta name="description" content="Using Parser (GNU Emacs Lisp Reference Manual)">
26<meta name="keywords" content="Using Parser (GNU Emacs Lisp Reference Manual)">
27<meta name="resource-type" content="document">
28<meta name="distribution" content="global">
29<meta name="Generator" content="makeinfo">
30<meta name="viewport" content="width=device-width,initial-scale=1">
31
32<link href="index.html" rel="start" title="Top">
33<link href="Index.html" rel="index" title="Index">
34<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
35<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
36<link href="Retrieving-Node.html" rel="next" title="Retrieving Node">
37<link href="Language-Definitions.html" rel="prev" title="Language Definitions">
38<style type="text/css">
39<!--
40a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
41a.summary-letter {text-decoration: none}
42blockquote.indentedblock {margin-right: 0em}
43div.display {margin-left: 3.2em}
44div.example {margin-left: 3.2em}
45kbd {font-style: oblique}
46pre.display {font-family: inherit}
47pre.format {font-family: inherit}
48pre.menu-comment {font-family: serif}
49pre.menu-preformatted {font-family: serif}
50span.nolinebreak {white-space: nowrap}
51span.roman {font-family: initial; font-weight: normal}
52span.sansserif {font-family: sans-serif; font-weight: normal}
53span:hover a.copiable-anchor {visibility: visible}
54ul.no-bullet {list-style: none}
55-->
56</style>
57<link rel="stylesheet" type="text/css" href="./manual.css">
58
59
60</head>
61
62<body lang="en">
63<div class="section" id="Using-Parser">
64<div class="header">
65<p>
66Next: <a href="Retrieving-Node.html" accesskey="n" rel="next">Retrieving Node</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>
67</div>
68<hr>
69<span id="Using-Tree_002dsitter-Parser"></span><h3 class="section">37.2 Using Tree-sitter Parser</h3>
70<span id="index-Tree_002dsitter-parser"></span>
71
72<p>This section described how to create and configure a tree-sitter
73parser. In Emacs, each tree-sitter parser is associated with a
74buffer. As we edit the buffer, the associated parser and the syntax
75tree is automatically kept up-to-date.
76</p>
77<dl class="def">
78<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>
79<dd><p>This variable contains the maximum size of buffers in which
80tree-sitter can be activated. Major modes should check this value
81when deciding whether to enable tree-sitter features.
82</p></dd></dl>
83
84<dl class="def">
85<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>
86<dd><p>This function checks whether the current buffer is suitable for
87activating tree-sitter features. It basically checks
88<code>treesit-available-p</code> and <code>treesit-max-buffer-size</code>.
89</p></dd></dl>
90
91<span id="index-Creating-tree_002dsitter-parsers"></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>To create a parser, we provide a <var>buffer</var> and the <var>language</var>
95to use (see <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>). If <var>buffer</var> is nil, the
96current buffer is used.
97</p>
98<p>By default, this function reuses a parser if one already exists for
99<var>language</var> in <var>buffer</var>, if <var>no-reuse</var> is non-nil, this
100function 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>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>Returns the language that <var>parser</var> uses.
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>Checks if <var>object</var> is a tree-sitter parser. Return non-nil if it
118is, return nil 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 we query for a
123node in its syntax tree. Therefore, when a parser is first created,
124it doesn&rsquo;t parse the buffer; it waits until we query for a node for
125the first time. Similarly, when some change is made in the buffer, a
126parser doesn&rsquo;t re-parse immediately.
127</p>
128<span id="index-treesit_002dbuffer_002dtoo_002dlarge"></span>
129<p>When a parser do 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 <code>treesit-buffer-too-large</code>
132with 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>. And
142<var>buffer</var> defaults to the current buffer.
143</p></dd></dl>
144
145<dl class="def">
146<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>
147<dd><p>This function deletes <var>parser</var>.
148</p></dd></dl>
149
150<span id="index-tree_002dsitter-narrowing"></span>
151<span id="tree_002dsitter-narrowing"></span><p>Normally, a parser &ldquo;sees&rdquo; the whole
152buffer, but when the buffer is narrowed (see <a href="Narrowing.html">Narrowing</a>), the
153parser will only see the visible region. As far as the parser can
154tell, the hidden region is deleted. And when the buffer is later
155widened, the parser thinks text is inserted in the beginning and in
156the end. Although parsers respect narrowing, narrowing shouldn&rsquo;t be
157the mean to handle a multi-language buffer; instead, set the ranges in
158which a parser should operate in. See <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>.
159</p>
160<p>Because a parser parses lazily, when we narrow the buffer, the parser
161is not affected immediately; as long as we don&rsquo;t query for a node
162while the buffer is narrowed, the parser is oblivious of the
163narrowing.
164</p>
165<span id="index-tree_002dsitter-parse-string"></span>
166<dl class="def">
167<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>
168<dd><p>Besides creating a parser for a buffer, we can also just parse a
169string. Unlike a buffer, parsing a string is a one-time deal, and
170there is no way to update the result.
171</p>
172<p>This function parses <var>string</var> with <var>language</var>, and returns the
173root node of the generated syntax tree.
174</p></dd></dl>
175
176</div>
177<hr>
178<div class="header">
179<p>
180Next: <a href="Retrieving-Node.html">Retrieving Node</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>
181</div>
182
183
184
185</body>
186</html>
generated by cgit v1.2.1 (git 2.18.0) at 2026-01-29 20:27:22 +0000