<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- This is the GNU Emacs Lisp Reference Manual
corresponding to Emacs version 29.0.50.
Copyright © 1990-1996, 1998-2022 Free Software Foundation,
Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License," with the
Front-Cover Texts being "A GNU Manual," and with the Back-Cover
Texts as in (a) below. A copy of the license is included in the
section entitled "GNU Free Documentation License."
(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
modify this GNU manual. Buying copies from the FSF supports it in
developing GNU and promoting software freedom." -->
<title>Using Parser (GNU Emacs Lisp Reference Manual)</title>
<meta name="description" content="Using Parser (GNU Emacs Lisp Reference Manual)">
<meta name="keywords" content="Using Parser (GNU Emacs Lisp Reference Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Index.html" rel="index" title="Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
<link href="Retrieving-Nodes.html" rel="next" title="Retrieving Nodes">
<link href="Language-Definitions.html" rel="prev" title="Language Definitions">
<style type="text/css">
<!--
a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
span:hover a.copiable-anchor {visibility: visible}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="./manual.css">
</head>
<body lang="en">
<div class="section" id="Using-Parser">
<div class="header">
<p>
Next: <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> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<span id="Using-Tree_002dsitter-Parser"></span><h3 class="section">37.2 Using Tree-sitter Parser</h3>
<span id="index-tree_002dsitter-parser_002c-using"></span>
<p>This section describes how to create and configure a tree-sitter
parser. In Emacs, each tree-sitter parser is associated with a
buffer. As the user edits the buffer, the associated parser and
syntax tree are automatically kept up-to-date.
</p>
<dl class="def">
<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'> ¶</a></span></dt>
<dd><p>This variable contains the maximum size of buffers in which
tree-sitter can be activated. Major modes should check this value
when deciding whether to enable tree-sitter features.
</p></dd></dl>
<dl class="def">
<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'> ¶</a></span></dt>
<dd><p>This function checks whether the current buffer is suitable for
activating tree-sitter features. It basically checks
<code>treesit-available-p</code> and <code>treesit-max-buffer-size</code>.
</p></dd></dl>
<span id="index-creating-tree_002dsitter-parsers"></span>
<span id="index-tree_002dsitter-parser_002c-creating"></span>
<dl class="def">
<dt id="index-treesit_002dparser_002dcreate"><span class="category">Function: </span><span><strong>treesit-parser-create</strong> <em>language &optional buffer no-reuse</em><a href='#index-treesit_002dparser_002dcreate' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>Create a parser for the specified <var>buffer</var> and <var>language</var>
(see <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>). If <var>buffer</var> is omitted or
<code>nil</code>, it stands for the current buffer.
</p>
<p>By default, this function reuses a parser if one already exists for
<var>language</var> in <var>buffer</var>, but if <var>no-reuse</var> is
non-<code>nil</code>, this function always creates a new parser.
</p></dd></dl>
<p>Given a parser, we can query information about it.
</p>
<dl class="def">
<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'> ¶</a></span></dt>
<dd><p>This function returns the buffer associated with <var>parser</var>.
</p></dd></dl>
<dl class="def">
<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'> ¶</a></span></dt>
<dd><p>This function returns the language used by <var>parser</var>.
</p></dd></dl>
<dl class="def">
<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'> ¶</a></span></dt>
<dd><p>This function checks if <var>object</var> is a tree-sitter parser, and
returns non-<code>nil</code> if it is, and <code>nil</code> otherwise.
</p></dd></dl>
<p>There is no need to explicitly parse a buffer, because parsing is done
automatically and lazily. A parser only parses when a Lisp program
queries for a node in its syntax tree. Therefore, when a parser is
first created, it doesn’t parse the buffer; it waits until the Lisp
program queries for a node for the first time. Similarly, when some
change is made in the buffer, a parser doesn’t re-parse immediately.
</p>
<span id="index-treesit_002dbuffer_002dtoo_002dlarge"></span>
<p>When a parser does parse, it checks for the size of the buffer.
Tree-sitter can only handle buffer no larger than about 4GB. If the
size exceeds that, Emacs signals the <code>treesit-buffer-too-large</code>
error with signal data being the buffer size.
</p>
<p>Once a parser is created, Emacs automatically adds it to the
internal parser list. Every time a change is made to the buffer,
Emacs updates parsers in this list so they can update their syntax
tree incrementally.
</p>
<dl class="def">
<dt id="index-treesit_002dparser_002dlist"><span class="category">Function: </span><span><strong>treesit-parser-list</strong> <em>&optional buffer</em><a href='#index-treesit_002dparser_002dlist' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This function returns the parser list of <var>buffer</var>. If
<var>buffer</var> is <code>nil</code> or omitted, it defaults to the current
buffer.
</p></dd></dl>
<dl class="def">
<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'> ¶</a></span></dt>
<dd><p>This function deletes <var>parser</var>.
</p></dd></dl>
<span id="index-tree_002dsitter-narrowing"></span>
<span id="tree_002dsitter-narrowing"></span><p>Normally, a parser “sees” the whole buffer, but when the buffer is
narrowed (see <a href="Narrowing.html">Narrowing</a>), the parser will only see the accessible
portion of the buffer. As far as the parser can tell, the hidden
region was deleted. When the buffer is later widened, the parser
thinks text is inserted at the beginning and at the end. Although
parsers respect narrowing, modes should not use narrowing as a means
to handle a multi-language buffer; instead, set the ranges in which the
parser should operate. See <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>.
</p>
<p>Because a parser parses lazily, when the user or a Lisp program
narrows the buffer, the parser is not affected immediately; as long as
the mode doesn’t query for a node while the buffer is narrowed, the
parser is oblivious of the narrowing.
</p>
<span id="index-tree_002dsitter-parse-string"></span>
<span id="index-parse-string_002c-tree_002dsitter"></span>
<p>Besides creating a parser for a buffer, a Lisp program can also parse a
string. Unlike a buffer, parsing a string is a one-off operation, and
there is no way to update the result.
</p>
<dl class="def">
<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'> ¶</a></span></dt>
<dd><p>This function parses <var>string</var> using <var>language</var>, and returns
the root node of the generated syntax tree.
</p></dd></dl>
<span id="Be-notified-by-changes-to-the-parse-tree"></span><h3 class="heading">Be notified by changes to the parse tree</h3>
<span id="index-update-callback_002c-for-tree_002dsitter-parse_002dtree"></span>
<span id="index-after_002dchange-notifier_002c-for-tree_002dsitter-parse_002dtree"></span>
<span id="index-tree_002dsitter-parse_002dtree_002c-update-and-after_002dchange-callback"></span>
<span id="index-notifiers_002c-tree_002dsitter"></span>
<p>A Lisp program might want to be notified of text affected by
incremental parsing. For example, inserting a comment-closing token
converts text before that token into a comment. Even
though the text is not directly edited, it is deemed to be “changed”
nevertheless.
</p>
<p>Emacs lets a Lisp program to register callback functions
(a.k.a. <em>notifiers</em>) for this kind of changes. A notifier
function takes two arguments: <var>ranges</var> and <var>parser</var>.
<var>ranges</var> is a list of cons cells of the form <code>(<var>start</var> . <var>end</var>)</code><!-- /@w -->, where <var>start</var> and <var>end</var> mark the start and the
end positions of a range. <var>parser</var> is the parser issuing the
notification.
</p>
<p>Every time a parser reparses a buffer, it compares the old and new
parse-tree, computes the ranges in which nodes have changed, and
passes the ranges to notifier functions.
</p>
<dl class="def">
<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'> ¶</a></span></dt>
<dd><p>This function adds <var>function</var> to <var>parser</var>’s list of
after-change notifier functions. <var>function</var> must be a function
symbol, not a lambda function (see <a href="Anonymous-Functions.html">Anonymous Functions</a>).
</p></dd></dl>
<dl class="def">
<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'> ¶</a></span></dt>
<dd><p>This function removes <var>function</var> from the list of <var>parser</var>’s
after-change notifier functions. <var>function</var> must be a function
symbol, rather than a lambda function.
</p></dd></dl>
<dl class="def">
<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'> ¶</a></span></dt>
<dd><p>This function returns the list of <var>parser</var>’s notifier functions.
</p></dd></dl>
</div>
<hr>
<div class="header">
<p>
Next: <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> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>