mirror of
git://git.sv.gnu.org/emacs.git
synced 2025-12-06 06:20:55 -08:00
230 lines
13 KiB
HTML
230 lines
13 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<!-- This is the GNU Emacs Lisp Reference Manual
|
|
corresponding to Emacs version 29.0.50.
|
|
|
|
Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with the
|
|
Invariant Sections being "GNU General Public License," with the
|
|
Front-Cover Texts being "A GNU Manual," and with the Back-Cover
|
|
Texts as in (a) below. A copy of the license is included in the
|
|
section entitled "GNU Free Documentation License."
|
|
|
|
(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
|
|
modify this GNU manual. Buying copies from the FSF supports it in
|
|
developing GNU and promoting software freedom." -->
|
|
<title>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>
|