procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge from origin/emacs-29

Browse source 
b7f0333355 Improve warning about changing the string returned by sym...
e62f8b0239 Fix visiting XBM/XPM files when 'c-ts-mode' is active
94d1c81cf0 * lisp/mpc.el (mpc-format): Fix oversight in commit 48b6c...
a4d97811ed Bail early from eglot--apply-text-edits if nothing to do
61d571760b ; Clarify in-code commentary of eglot--after-change
5bbbd70f56 Improve ergonomics of Eglot's inlay hints
c3a543123a Protect against too large size of 'recent-keys' vector
231190b37f * lisp/net/tramp.el (tramp-yn-prompt-regexp): Fix regexp.
0bebd0e5f0 ; Remove 'build-module' and 'html-manual' directories fro...
6674c362ad Merge branch 'emacs-29' of git.savannah.gnu.org:/srv/git/...
829e5dfabe Update to Org 9.6.1-48-g92471e
e84f878e19 ; * admin/notes/tree-sitter/starter-guide: Update starter...
ea0949853f Merge branch 'emacs-29' of git.savannah.gnu.org:/srv/git/...
11592bcfda ; * lisp/nxml/xmltok.el (xmltok-scan-attributes): Fix las...
e388a77cf0 ; Minor copyedits of recent changes in ELisp reference ma...
33a2670368 ; Minor fixes in recent Eglot changes
d2cf1386fa ; * doc/misc/eglot.texi (Eglot Commands): Improve indexing.
b75e489362 ; Again correct node reference casing in doc/misc/eglot.texi
a55d2edc5a ; Remove overly verbose commentary
22a70451f3 Merge confusing duplicate sections on commands in Eglot m...
3293f93988 Don't take over mouse-1 binding on Eglot diagnostics (bug...
013057e351 ; Prefer "language server" to "LSP server" in Eglot manual
94a21c8864 * lisp/progmodes/eglot.el (eglot--connect): Improve Tramp...
0eddfa28eb Avoid slowdowns in xmltok-scan-attributes
647c6bf2a6 ; * test/lisp/abbrev-tests.el (abbrev--possibly-save-test...
531f8f7103 ; * admin/git-bisect-start: Update failing commits

# Conflicts:
#	admin/notes/tree-sitter/build-module/batch.sh
#	admin/notes/tree-sitter/build-module/build.sh
This commit is contained in:
Stefan Kangas 2023-03-20 06:30:40 +01:00
commit 42fba8f36b
39 changed files with 287 additions and 3560 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
admin/git-bisect-start
View file

@ -82,7 +82,7 @@ done
# SKIP-BRANCH 58cc931e92ece70c3e64131ee12a799d65409100
## The list below is the exhaustive list of all commits between Dec 1
## 2016 and Jan 31 2023 on which building Emacs with the default
## 2016 and Feb 28 2023 on which building Emacs with the default
## options, on a GNU/Linux computer and with GCC, fails. It is
## possible (though unlikely) that building Emacs with non-default
## options, with other compilers, or on other platforms, would succeed
@ -1707,3 +1707,16 @@ $REAL_GIT bisect skip $(cat $0 | grep '^# SKIP-SINGLE ' | sed 's/^# SKIP-SINGLE
# SKIP-SINGLE 1c3ca3bb649b7e812a84b4a559463462d4357080
# SKIP-SINGLE 48ed4228a75907ae1bb7a2d4314ffb3277c75e3a
# SKIP-SINGLE b9025c507a3a7dae4de19b18cafaa09b18183832
# SKIP-SINGLE 8d8464bd5a98598e7a6fe63370545c7f07574926
# SKIP-SINGLE 11c4177430230ef41cb700c48afecf475cf39893
# SKIP-SINGLE cf3c89423fabc2c5a7891a5b5465fa995e461218
# SKIP-SINGLE 8d5d7509b0a2c248084fa349b0b188d4de4af804
# SKIP-SINGLE b6e2799aa1c3887c2995e115e6ff2f69d59f0e44
# SKIP-SINGLE 1795839babcf8572a79aaee3c76ca5b357937a59
# SKIP-SINGLE abfd00e5c02ec0aed8bbac1eca0d0db1874f020a
# SKIP-SINGLE 8aef401b4f66a64ddfa9390590fb2cae1f96d522
# SKIP-SINGLE d5bf26f488b7968feed9f43e612a90da2aab15a8
# SKIP-SINGLE 5d0912f1445e33f1ccf23a84f0dc6d08c4ee2b60
# SKIP-SINGLE 95692f6754c3a8f55a90df2d6f7ce62be55cdcfc
# SKIP-SINGLE a3edacd3f547195740304139cb68aaa94d7b18ee
# SKIP-SINGLE ae4ff4f25fbf704446f8f38d8e818f223b79042b

17
admin/notes/tree-sitter/build-module/README
View file

@ -1,17 +0,0 @@
To build the language definition for a particular language, run
./build.sh <language>
eg,
./build.sh html
The dynamic module will be in /dist directory
To build all modules at once, run
./batch.sh
This gives you C, JSON, Go, HTML, Javascript, CSS, Python, Typescript
(tsx), C# (csharp), C++ (cpp), Rust. More can be added to batch.sh
unless it's directory structure is not standard.

205
admin/notes/tree-sitter/html-manual/Accessing-Node.html
View file

@ -1,205 +0,0 @@
<!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>Accessing Node (GNU Emacs Lisp Reference Manual)</title>
<meta name="description" content="Accessing Node (GNU Emacs Lisp Reference Manual)">
<meta name="keywords" content="Accessing Node (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="Pattern-Matching.html" rel="next" title="Pattern Matching">
<link href="Retrieving-Node.html" rel="prev" title="Retrieving Node">
<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="Accessing-Node">
<div class="header">
<p>
Next: <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>
</div>
<hr>
<span id="Accessing-Node-Information"></span><h3 class="section">37.4 Accessing Node Information</h3>
<p>Before going further, make sure you have read the basic conventions
about tree-sitter nodes in the previous node.
</p>
<span id="Basic-information"></span><h3 class="heading">Basic information</h3>
<p>Every node is associated with a parser, and that parser is associated
with a buffer. The following functions let you retrieve them.
</p>
<dl class="def">
<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>
<dd><p>This function returns <var>node</var>&rsquo;s associated parser.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function returns <var>node</var>&rsquo;s parser&rsquo;s associated buffer.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function returns <var>node</var>&rsquo;s parser&rsquo;s associated language.
</p></dd></dl>
<p>Each node represents a piece of text in the buffer. Functions below
finds relevant information about that text.
</p>
<dl class="def">
<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>
<dd><p>Return the start position of <var>node</var>.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>Return the end position of <var>node</var>.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>Returns the buffer text that <var>node</var> represents. (If <var>node</var> is
retrieved from parsing a string, it will be text from that string.)
</p></dd></dl>
<p>Here are some basic checks on tree-sitter nodes.
</p>
<dl class="def">
<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>
<dd><p>Checks if <var>object</var> is a tree-sitter syntax node.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>Checks if <var>node1</var> and <var>node2</var> are the same node in a syntax
tree.
</p></dd></dl>
<span id="Property-information"></span><h3 class="heading">Property information</h3>
<p>In general, nodes in a concrete syntax tree fall into two categories:
<em>named nodes</em> and <em>anonymous nodes</em>. Whether a node is named
or anonymous is determined by the language definition
(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
</p>
<span id="index-tree_002dsitter-missing-node"></span>
<p>Apart from being named/anonymous, a node can have other properties. A
node can be &ldquo;missing&rdquo;: missing nodes are inserted by the parser in
order to recover from certain kinds of syntax errors, i.e., something
should probably be there according to the grammar, but not there.
</p>
<span id="index-tree_002dsitter-extra-node"></span>
<p>A node can be &ldquo;extra&rdquo;: extra nodes represent things like comments,
which can appear anywhere in the text.
</p>
<span id="index-tree_002dsitter-node-that-has-changes"></span>
<p>A node &ldquo;has changes&rdquo; if the buffer changed since when the node is
retrieved, i.e., outdated.
</p>
<span id="index-tree_002dsitter-node-that-has-error"></span>
<p>A node &ldquo;has error&rdquo; if the text it spans contains a syntax error. It
can be the node itself has an error, or one of its
children/grandchildren... has an error.
</p>
<dl class="def">
<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>
<dd><p>This function checks if <var>node</var> has <var>property</var>. <var>property</var>
can be <code>'named</code>, <code>'missing</code>, <code>'extra</code>,
<code>'has-changes</code>, or <code>'has-error</code>.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>Named nodes have &ldquo;types&rdquo; (see <a href="Language-Definitions.html#tree_002dsitter-node-type">node type</a>).
For example, a named node can be a <code>string_literal</code> node, where
<code>string_literal</code> is its type.
</p>
<p>This function returns <var>node</var>&rsquo;s type as a string.
</p></dd></dl>
<span id="Information-as-a-child-or-parent"></span><h3 class="heading">Information as a child or parent</h3>
<dl class="def">
<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>
<dd><p>This function returns the index of <var>node</var> as a child node of its
parent. If <var>named</var> is non-nil, it only count named nodes
(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
</p></dd></dl>
<dl class="def">
<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>
<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
of <var>node</var> as a child of its parent.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function returns the field name of the <var>n</var>&rsquo;th child of
<var>node</var>.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function finds the number of children of <var>node</var>. If
<var>named</var> is non-nil, it only counts named child (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
</p></dd></dl>
</div>
<hr>
<div class="header">
<p>
Next: <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>
</div>
</body>
</html>

401
admin/notes/tree-sitter/html-manual/Language-Definitions.html
View file

@ -1,401 +0,0 @@
<!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>Language Definitions (GNU Emacs Lisp Reference Manual)</title>
<meta name="description" content="Language Definitions (GNU Emacs Lisp Reference Manual)">
<meta name="keywords" content="Language Definitions (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="Using-Parser.html" rel="next" title="Using Parser">
<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="Language-Definitions">
<div class="header">
<p>
Next: <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>
</div>
<hr>
<span id="Tree_002dsitter-Language-Definitions"></span><h3 class="section">37.1 Tree-sitter Language Definitions</h3>
<span id="index-language-definitions_002c-for-tree_002dsitter"></span>
<span id="Loading-a-language-definition"></span><h3 class="heading">Loading a language definition</h3>
<span id="index-loading-language-definition-for-tree_002dsitter"></span>
<span id="index-language-argument_002c-for-tree_002dsitter"></span>
<p>Tree-sitter relies on language definitions to parse text in that
language. In Emacs, a language definition is represented by a symbol.
For example, the C language definition is represented as the symbol
<code>c</code>, and <code>c</code> can be passed to tree-sitter functions as the
<var>language</var> argument.
</p>
<span id="index-treesit_002dextra_002dload_002dpath"></span>
<span id="index-treesit_002dload_002dlanguage_002derror"></span>
<span id="index-treesit_002dload_002dsuffixes"></span>
<p>Tree-sitter language definitions are distributed as dynamic libraries.
In order to use a language definition in Emacs, you need to make sure
that the dynamic library is installed on the system. Emacs looks for
language definitions in several places, in the following order:
</p>
<ul>
<li> first, in the list of directories specified by the variable
<code>treesit-extra-load-path</code>;
</li><li> then, in the <samp>tree-sitter</samp> subdirectory of the directory
specified by <code>user-emacs-directory</code> (see <a href="Init-File.html">The Init File</a>);
</li><li> and finally, in the system&rsquo;s default locations for dynamic libraries.
</li></ul>
<p>In each of these directories, Emacs looks for a file with file-name
extensions specified by the variable <code>dynamic-library-suffixes</code>.
</p>
<p>If Emacs cannot find the library or has problems loading it, Emacs
signals the <code>treesit-load-language-error</code> error. The data of
that signal could be one of the following:
</p>
<dl compact="compact">
<dt><span><code>(not-found <var>error-msg</var> &hellip;)</code></span></dt>
<dd><p>This means that Emacs could not find the language definition library.
</p></dd>
<dt><span><code>(symbol-error <var>error-msg</var>)</code></span></dt>
<dd><p>This means that Emacs could not find in the library the expected function
that every language definition library should export.
</p></dd>
<dt><span><code>(version-mismatch <var>error-msg</var>)</code></span></dt>
<dd><p>This means that the version of language definition library is incompatible
with that of the tree-sitter library.
</p></dd>
</dl>
<p>In all of these cases, <var>error-msg</var> might provide additional
details about the failure.
</p>
<dl class="def">
<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>
<dd><p>This function returns non-<code>nil</code> if the language definitions for
<var>language</var> exist and can be loaded.
</p>
<p>If <var>detail</var> is non-<code>nil</code>, return <code>(t . nil)</code> when
<var>language</var> is available, and <code>(nil . <var>data</var>)</code> when it&rsquo;s
unavailable. <var>data</var> is the signal data of
<code>treesit-load-language-error</code>.
</p></dd></dl>
<span id="index-treesit_002dload_002dname_002doverride_002dlist"></span>
<p>By convention, the file name of the dynamic library for <var>language</var> is
<samp>libtree-sitter-<var>language</var>.<var>ext</var></samp>, where <var>ext</var> is the
system-specific extension for dynamic libraries. Also by convention,
the function provided by that library is named
<code>tree_sitter_<var>language</var></code>. If a language definition library
doesn&rsquo;t follow this convention, you should add an entry
</p>
<div class="example">
<pre class="example">(<var>language</var> <var>library-base-name</var> <var>function-name</var>)
</pre></div>
<p>to the list in the variable <code>treesit-load-name-override-list</code>, where
<var>library-base-name</var> is the basename of the dynamic library&rsquo;s file name,
(usually, <samp>libtree-sitter-<var>language</var></samp>), and
<var>function-name</var> is the function provided by the library
(usually, <code>tree_sitter_<var>language</var></code>). For example,
</p>
<div class="example">
<pre class="example">(cool-lang &quot;libtree-sitter-coool&quot; &quot;tree_sitter_cooool&quot;)
</pre></div>
<p>for a language that considers itself too &ldquo;cool&rdquo; to abide by
conventions.
</p>
<span id="index-language_002ddefinition-version_002c-compatibility"></span>
<dl class="def">
<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>
<dd><p>This function returns the version of the language-definition
Application Binary Interface (<acronym>ABI</acronym>) supported by the
tree-sitter library. By default, it returns the latest ABI version
supported by the library, but if <var>min-compatible</var> is
non-<code>nil</code>, it returns the oldest ABI version which the library
still can support. Language definition libraries must be built for
ABI versions between the oldest and the latest versions supported by
the tree-sitter library, otherwise the library will be unable to load
them.
</p></dd></dl>
<span id="Concrete-syntax-tree"></span><h3 class="heading">Concrete syntax tree</h3>
<span id="index-syntax-tree_002c-concrete"></span>
<p>A syntax tree is what a parser generates. In a syntax tree, each node
represents a piece of text, and is connected to each other by a
parent-child relationship. For example, if the source text is
</p>
<div class="example">
<pre class="example">1 + 2
</pre></div>
<p>its syntax tree could be
</p>
<div class="example">
<pre class="example"> +--------------+
| root &quot;1 + 2&quot; |
+--------------+
|
+--------------------------------+
| expression &quot;1 + 2&quot; |
+--------------------------------+
| | |
+------------+ +--------------+ +------------+
| number &quot;1&quot; | | operator &quot;+&quot; | | number &quot;2&quot; |
+------------+ +--------------+ +------------+
</pre></div>
<p>We can also represent it as an s-expression:
</p>
<div class="example">
<pre class="example">(root (expression (number) (operator) (number)))
</pre></div>
<span id="Node-types"></span><h4 class="subheading">Node types</h4>
<span id="index-node-types_002c-in-a-syntax-tree"></span>
<span id="index-type-of-node_002c-tree_002dsitter"></span>
<span id="tree_002dsitter-node-type"></span><span id="index-named-node_002c-tree_002dsitter"></span>
<span id="tree_002dsitter-named-node"></span><span id="index-anonymous-node_002c-tree_002dsitter"></span>
<p>Names like <code>root</code>, <code>expression</code>, <code>number</code>, and
<code>operator</code> specify the <em>type</em> of the nodes. However, not all
nodes in a syntax tree have a type. Nodes that don&rsquo;t have a type are
known as <em>anonymous nodes</em>, and nodes with a type are <em>named
nodes</em>. Anonymous nodes are tokens with fixed spellings, including
punctuation characters like bracket &lsquo;<samp>]</samp>&rsquo;, and keywords like
<code>return</code>.
</p>
<span id="Field-names"></span><h4 class="subheading">Field names</h4>
<span id="index-field-name_002c-tree_002dsitter"></span>
<span id="index-tree_002dsitter-node-field-name"></span>
<span id="tree_002dsitter-node-field-name"></span><p>To make the syntax tree easier to analyze, many language definitions
assign <em>field names</em> to child nodes. For example, a
<code>function_definition</code> node could have a <code>declarator</code> and a
<code>body</code>:
</p>
<div class="example">
<pre class="example">(function_definition
declarator: (declaration)
body: (compound_statement))
</pre></div>
<span id="Exploring-the-syntax-tree"></span><h3 class="heading">Exploring the syntax tree</h3>
<span id="index-explore-tree_002dsitter-syntax-tree"></span>
<span id="index-inspection-of-tree_002dsitter-parse-tree-nodes"></span>
<p>To aid in understanding the syntax of a language and in debugging of
Lisp program that use the syntax tree, Emacs provides an &ldquo;explore&rdquo;
mode, which displays the syntax tree of the source in the current
buffer in real time. Emacs also comes with an &ldquo;inspect mode&rdquo;, which
displays information of the nodes at point in the mode-line.
</p>
<dl class="def">
<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>
<dd><p>This mode pops up a window displaying the syntax tree of the source in
the current buffer. Selecting text in the source buffer highlights
the corresponding nodes in the syntax tree display. Clicking
on nodes in the syntax tree highlights the corresponding text in the
source buffer.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This minor mode displays on the mode-line the node that <em>starts</em>
at point. For example, the mode-line can display
</p>
<div class="example">
<pre class="example"><var>parent</var> <var>field</var>: (<var>node</var> (<var>child</var> (&hellip;)))
</pre></div>
<p>where <var>node</var>, <var>child</var>, etc., are nodes which begin at point.
<var>parent</var> is the parent of <var>node</var>. <var>node</var> is displayed in
a bold typeface. <var>field-name</var>s are field names of <var>node</var> and
of <var>child</var>, etc.
</p>
<p>If no node starts at point, i.e., point is in the middle of a node,
then the mode line displays the earliest node that spans point, and
its immediate parent.
</p>
<p>This minor mode doesn&rsquo;t create parsers on its own. It uses the first
parser in <code>(treesit-parser-list)</code> (see <a href="Using-Parser.html">Using Tree-sitter Parser</a>).
</p></dd></dl>
<span id="Reading-the-grammar-definition"></span><h3 class="heading">Reading the grammar definition</h3>
<span id="index-reading-grammar-definition_002c-tree_002dsitter"></span>
<p>Authors of language definitions define the <em>grammar</em> of a
programming language, which determines how a parser constructs a
concrete syntax tree out of the program text. In order to use the
syntax tree effectively, you need to consult the <em>grammar file</em>.
</p>
<p>The grammar file is usually <samp>grammar.js</samp> in a language
definition&rsquo;s project repository. The link to a language definition&rsquo;s
home page can be found on
<a href="https://tree-sitter.github.io/tree-sitter">tree-sitter&rsquo;s
homepage</a>.
</p>
<p>The grammar definition is written in JavaScript. For example, the
rule matching a <code>function_definition</code> node looks like
</p>
<div class="example">
<pre class="example">function_definition: $ =&gt; seq(
$.declaration_specifiers,
field('declarator', $.declaration),
field('body', $.compound_statement)
)
</pre></div>
<p>The rules are represented by functions that take a single argument
<var>$</var>, representing the whole grammar. The function itself is
constructed by other functions: the <code>seq</code> function puts together
a sequence of children; the <code>field</code> function annotates a child
with a field name. If we write the above definition in the so-called
<em>Backus-Naur Form</em> (<acronym>BNF</acronym>) syntax, it would look like
</p>
<div class="example">
<pre class="example">function_definition :=
&lt;declaration_specifiers&gt; &lt;declaration&gt; &lt;compound_statement&gt;
</pre></div>
<p>and the node returned by the parser would look like
</p>
<div class="example">
<pre class="example">(function_definition
(declaration_specifier)
declarator: (declaration)
body: (compound_statement))
</pre></div>
<p>Below is a list of functions that one can see in a grammar definition.
Each function takes other rules as arguments and returns a new rule.
</p>
<dl compact="compact">
<dt><span><code>seq(<var>rule1</var>, <var>rule2</var>, &hellip;)</code></span></dt>
<dd><p>matches each rule one after another.
</p></dd>
<dt><span><code>choice(<var>rule1</var>, <var>rule2</var>, &hellip;)</code></span></dt>
<dd><p>matches one of the rules in its arguments.
</p></dd>
<dt><span><code>repeat(<var>rule</var>)</code></span></dt>
<dd><p>matches <var>rule</var> for <em>zero or more</em> times.
This is like the &lsquo;<samp>*</samp>&rsquo; operator in regular expressions.
</p></dd>
<dt><span><code>repeat1(<var>rule</var>)</code></span></dt>
<dd><p>matches <var>rule</var> for <em>one or more</em> times.
This is like the &lsquo;<samp>+</samp>&rsquo; operator in regular expressions.
</p></dd>
<dt><span><code>optional(<var>rule</var>)</code></span></dt>
<dd><p>matches <var>rule</var> for <em>zero or one</em> time.
This is like the &lsquo;<samp>?</samp>&rsquo; operator in regular expressions.
</p></dd>
<dt><span><code>field(<var>name</var>, <var>rule</var>)</code></span></dt>
<dd><p>assigns field name <var>name</var> to the child node matched by <var>rule</var>.
</p></dd>
<dt><span><code>alias(<var>rule</var>, <var>alias</var>)</code></span></dt>
<dd><p>makes nodes matched by <var>rule</var> appear as <var>alias</var> in the syntax
tree generated by the parser. For example,
</p>
<div class="example">
<pre class="example">alias(preprocessor_call_exp, call_expression)
</pre></div>
<p>makes any node matched by <code>preprocessor_call_exp</code> appear as
<code>call_expression</code>.
</p></dd>
</dl>
<p>Below are grammar functions of lesser importance for reading a
language definition.
</p>
<dl compact="compact">
<dt><span><code>token(<var>rule</var>)</code></span></dt>
<dd><p>marks <var>rule</var> to produce a single leaf node. That is, instead of
generating a parent node with individual child nodes under it,
everything is combined into a single leaf node. See <a href="Retrieving-Nodes.html">Retrieving Nodes</a>.
</p></dd>
<dt><span><code>token.immediate(<var>rule</var>)</code></span></dt>
<dd><p>Normally, grammar rules ignore preceding whitespace; this
changes <var>rule</var> to match only when there is no preceding
whitespaces.
</p></dd>
<dt><span><code>prec(<var>n</var>, <var>rule</var>)</code></span></dt>
<dd><p>gives <var>rule</var> the level-<var>n</var> precedence.
</p></dd>
<dt><span><code>prec.left([<var>n</var>,] <var>rule</var>)</code></span></dt>
<dd><p>marks <var>rule</var> as left-associative, optionally with level <var>n</var>.
</p></dd>
<dt><span><code>prec.right([<var>n</var>,] <var>rule</var>)</code></span></dt>
<dd><p>marks <var>rule</var> as right-associative, optionally with level <var>n</var>.
</p></dd>
<dt><span><code>prec.dynamic(<var>n</var>, <var>rule</var>)</code></span></dt>
<dd><p>this is like <code>prec</code>, but the precedence is applied at runtime
instead.
</p></dd>
</dl>
<p>The documentation of the tree-sitter project has
<a href="https://tree-sitter.github.io/tree-sitter/creating-parsers">more
about writing a grammar</a>. Read especially &ldquo;The Grammar DSL&rdquo;
section.
</p>
</div>
<hr>
<div class="header">
<p>
Next: <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>
</div>
</body>
</html>

327
admin/notes/tree-sitter/html-manual/Multiple-Languages.html
View file

@ -1,327 +0,0 @@
<!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>Multiple Languages (GNU Emacs Lisp Reference Manual)</title>
<meta name="description" content="Multiple Languages (GNU Emacs Lisp Reference Manual)">
<meta name="keywords" content="Multiple Languages (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="Tree_002dsitter-major-modes.html" rel="next" title="Tree-sitter major modes">
<link href="Pattern-Matching.html" rel="prev" title="Pattern Matching">
<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="Multiple-Languages">
<div class="header">
<p>
Next: <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>
</div>
<hr>
<span id="Parsing-Text-in-Multiple-Languages"></span><h3 class="section">37.6 Parsing Text in Multiple Languages</h3>
<span id="index-multiple-languages_002c-parsing-with-tree_002dsitter"></span>
<span id="index-parsing-multiple-languages-with-tree_002dsitter"></span>
<p>Sometimes, the source of a programming language could contain snippets
of other languages; <acronym>HTML</acronym> + <acronym>CSS</acronym> + JavaScript is one
example. In that case, text segments written in different languages
need to be assigned different parsers. Traditionally, this is
achieved by using narrowing. While tree-sitter works with narrowing
(see <a href="Using-Parser.html#tree_002dsitter-narrowing">narrowing</a>), the recommended way is
instead to set regions of buffer text (i.e., ranges) in which a parser
will operate. This section describes functions for setting and
getting ranges for a parser.
</p>
<p>Lisp programs should call <code>treesit-update-ranges</code> to make sure
the ranges for each parser are correct before using parsers in a
buffer, and call <code>treesit-language-at</code> to figure out the language
responsible for the text at some position. These two functions don&rsquo;t
work by themselves, they need major modes to set
<code>treesit-range-settings</code> and
<code>treesit-language-at-point-function</code>, which do the actual work.
These functions and variables are explained in more detail towards the
end of the section.
</p>
<span id="Getting-and-setting-ranges"></span><h3 class="heading">Getting and setting ranges</h3>
<dl class="def">
<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>
<dd><p>This function sets up <var>parser</var> to operate on <var>ranges</var>. The
<var>parser</var> will only read the text of the specified ranges. Each
range in <var>ranges</var> is a list of the form <code>(<var>beg</var>&nbsp;.&nbsp;<var>end</var>)</code><!-- /@w -->.
</p>
<p>The ranges in <var>ranges</var> must come in order and must not overlap.
That is, in pseudo code:
</p>
<div class="example">
<pre class="example">(cl-loop for idx from 1 to (1- (length ranges))
for prev = (nth (1- idx) ranges)
for next = (nth idx ranges)
should (&lt;= (car prev) (cdr prev)
(car next) (cdr next)))
</pre></div>
<span id="index-treesit_002drange_002dinvalid"></span>
<p>If <var>ranges</var> violates this constraint, or something else went
wrong, this function signals the <code>treesit-range-invalid</code> error.
The signal data contains a specific error message and the ranges we
are trying to set.
</p>
<p>This function can also be used for disabling ranges. If <var>ranges</var>
is <code>nil</code>, the parser is set to parse the whole buffer.
</p>
<p>Example:
</p>
<div class="example">
<pre class="example">(treesit-parser-set-included-ranges
parser '((1 . 9) (16 . 24) (24 . 25)))
</pre></div>
</dd></dl>
<dl class="def">
<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>
<dd><p>This function returns the ranges set for <var>parser</var>. The return
value is the same as the <var>ranges</var> argument of
<code>treesit-parser-included-ranges</code>: a list of cons cells of the form
<code>(<var>beg</var>&nbsp;.&nbsp;<var>end</var>)</code><!-- /@w -->. If <var>parser</var> doesn&rsquo;t have any
ranges, the return value is <code>nil</code>.
</p>
<div class="example">
<pre class="example">(treesit-parser-included-ranges parser)
&rArr; ((1 . 9) (16 . 24) (24 . 25))
</pre></div>
</dd></dl>
<dl class="def">
<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>
<dd><p>This function matches <var>source</var> with <var>query</var> and returns the
ranges of captured nodes. The return value is a list of cons cells of
the form <code>(<var>beg</var>&nbsp;.&nbsp;<var>end</var>)</code><!-- /@w -->, where <var>beg</var> and
<var>end</var> specify the beginning and the end of a region of text.
</p>
<p>For convenience, <var>source</var> can be a language symbol, a parser, or a
node. If it&rsquo;s a language symbol, this function matches in the root
node of the first parser using that language; if a parser, this
function matches in the root node of that parser; if a node, this
function matches in that node.
</p>
<p>The argument <var>query</var> is the query used to capture nodes
(see <a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>). The capture names don&rsquo;t matter. The
arguments <var>beg</var> and <var>end</var>, if both non-<code>nil</code>, limit the
range in which this function queries.
</p>
<p>Like other query functions, this function raises the
<code>treesit-query-error</code> error if <var>query</var> is malformed.
</p></dd></dl>
<span id="Supporting-multiple-languages-in-Lisp-programs"></span><h3 class="heading">Supporting multiple languages in Lisp programs</h3>
<p>It should suffice for general Lisp programs to call the following two
functions in order to support program sources that mixes multiple
languages.
</p>
<dl class="def">
<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>
<dd><p>This function updates ranges for parsers in the buffer. It makes sure
the parsers&rsquo; ranges are set correctly between <var>beg</var> and <var>end</var>,
according to <code>treesit-range-settings</code>. If omitted, <var>beg</var>
defaults to the beginning of the buffer, and <var>end</var> defaults to the
end of the buffer.
</p>
<p>For example, fontification functions use this function before querying
for nodes in a region.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function returns the language of the text at buffer position
<var>pos</var>. Under the hood it calls
<code>treesit-language-at-point-function</code> and returns its return
value. If <code>treesit-language-at-point-function</code> is <code>nil</code>,
this function returns the language of the first parser in the returned
value of <code>treesit-parser-list</code>. If there is no parser in the
buffer, it returns <code>nil</code>.
</p></dd></dl>
<span id="Supporting-multiple-languages-in-major-modes"></span><h3 class="heading">Supporting multiple languages in major modes</h3>
<span id="index-host-language_002c-tree_002dsitter"></span>
<span id="index-tree_002dsitter-host-and-embedded-languages"></span>
<span id="index-embedded-language_002c-tree_002dsitter"></span>
<p>Normally, in a set of languages that can be mixed together, there is a
<em>host language</em> and one or more <em>embedded languages</em>. A Lisp
program usually first parses the whole document with the host
language&rsquo;s parser, retrieves some information, sets ranges for the
embedded languages with that information, and then parses the embedded
languages.
</p>
<p>Take a buffer containing <acronym>HTML</acronym>, <acronym>CSS</acronym> and JavaScript
as an example. A Lisp program will first parse the whole buffer with
an <acronym>HTML</acronym> parser, then query the parser for
<code>style_element</code> and <code>script_element</code> nodes, which
correspond to <acronym>CSS</acronym> and JavaScript text, respectively. Then
it sets the range of the <acronym>CSS</acronym> and JavaScript parser to the
ranges in which their corresponding nodes span.
</p>
<p>Given a simple <acronym>HTML</acronym> document:
</p>
<div class="example">
<pre class="example">&lt;html&gt;
&lt;script&gt;1 + 2&lt;/script&gt;
&lt;style&gt;body { color: &quot;blue&quot;; }&lt;/style&gt;
&lt;/html&gt;
</pre></div>
<p>a Lisp program will first parse with a <acronym>HTML</acronym> parser, then set
ranges for <acronym>CSS</acronym> and JavaScript parsers:
</p>
<div class="example">
<pre class="example">;; Create parsers.
(setq html (treesit-parser-create 'html))
(setq css (treesit-parser-create 'css))
(setq js (treesit-parser-create 'javascript))
</pre><pre class="example">
</pre><pre class="example">;; Set CSS ranges.
(setq css-range
(treesit-query-range
'html
&quot;(style_element (raw_text) @capture)&quot;))
(treesit-parser-set-included-ranges css css-range)
</pre><pre class="example">
</pre><pre class="example">;; Set JavaScript ranges.
(setq js-range
(treesit-query-range
'html
&quot;(script_element (raw_text) @capture)&quot;))
(treesit-parser-set-included-ranges js js-range)
</pre></div>
<p>Emacs automates this process in <code>treesit-update-ranges</code>. A
multi-language major mode should set <code>treesit-range-settings</code> so
that <code>treesit-update-ranges</code> knows how to perform this process
automatically. Major modes should use the helper function
<code>treesit-range-rules</code> to generate a value that can be assigned to
<code>treesit-range-settings</code>. The settings in the following example
directly translate into operations shown above.
</p>
<div class="example">
<pre class="example">(setq-local treesit-range-settings
(treesit-range-rules
:embed 'javascript
:host 'html
'((script_element (raw_text) @capture))
</pre><pre class="example">
</pre><pre class="example"> :embed 'css
:host 'html
'((style_element (raw_text) @capture))))
</pre></div>
<dl class="def">
<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>
<dd><p>This function is used to set <var>treesit-range-settings</var>. It
takes care of compiling queries and other post-processing, and outputs
a value that <var>treesit-range-settings</var> can have.
</p>
<p>It takes a series of <var>query-spec</var>s, where each <var>query-spec</var> is
a <var>query</var> preceded by zero or more <var>keyword</var>/<var>value</var>
pairs. Each <var>query</var> is a tree-sitter query in either the
string, s-expression or compiled form, or a function.
</p>
<p>If <var>query</var> is a tree-sitter query, it should be preceded by two
<var>:keyword</var>/<var>value</var> pairs, where the <code>:embed</code> keyword
specifies the embedded language, and the <code>:host</code> keyword
specified the host language.
</p>
<p><code>treesit-update-ranges</code> uses <var>query</var> to figure out how to set
the ranges for parsers for the embedded language. It queries
<var>query</var> in a host language parser, computes the ranges in which
the captured nodes span, and applies these ranges to embedded
language parsers.
</p>
<p>If <var>query</var> is a function, it doesn&rsquo;t need any <var>:keyword</var> and
<var>value</var> pair. It should be a function that takes 2 arguments,
<var>start</var> and <var>end</var>, and sets the ranges for parsers in the
current buffer in the region between <var>start</var> and <var>end</var>. It is
fine for this function to set ranges in a larger region that
encompasses the region between <var>start</var> and <var>end</var>.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This variable helps <code>treesit-update-ranges</code> in updating the
ranges for parsers in the buffer. It is a list of <var>setting</var>s
where the exact format of a <var>setting</var> is considered internal. You
should use <code>treesit-range-rules</code> to generate a value that this
variable can have.
</p>
</dd></dl>
<dl class="def">
<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>
<dd><p>This variable&rsquo;s value should be a function that takes a single
argument, <var>pos</var>, which is a buffer position, and returns the
language of the buffer text at <var>pos</var>. This variable is used by
<code>treesit-language-at</code>.
</p></dd></dl>
</div>
<hr>
<div class="header">
<p>
Next: <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>
</div>
</body>
</html>

247
admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html
View file

@ -1,247 +0,0 @@
<!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>Parser-based Font Lock (GNU Emacs Lisp Reference Manual)</title>
<meta name="description" content="Parser-based Font Lock (GNU Emacs Lisp Reference Manual)">
<meta name="keywords" content="Parser-based Font Lock (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="Font-Lock-Mode.html" rel="up" title="Font Lock Mode">
<link href="Multiline-Font-Lock.html" rel="prev" title="Multiline Font Lock">
<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="subsection" id="Parser_002dbased-Font-Lock">
<div class="header">
<p>
Previous: <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>
</div>
<hr>
<span id="Parser_002dbased-Font-Lock-1"></span><h4 class="subsection">24.6.10 Parser-based Font Lock</h4>
<span id="index-parser_002dbased-font_002dlock"></span>
<p>Besides simple syntactic font lock and regexp-based font lock, Emacs
also provides complete syntactic font lock with the help of a parser.
Currently, Emacs uses the tree-sitter library (see <a href="Parsing-Program-Source.html">Parsing Program Source</a>) for this purpose.
</p>
<p>Parser-based font lock and other font lock mechanisms are not mutually
exclusive. By default, if enabled, parser-based font lock runs first,
replacing syntactic font lock, then the regexp-based font lock.
</p>
<p>Although parser-based font lock doesn&rsquo;t share the same customization
variables with regexp-based font lock, it uses similar customization
schemes. The tree-sitter counterpart of <var>font-lock-keywords</var> is
<var>treesit-font-lock-settings</var>.
</p>
<span id="index-tree_002dsitter-fontifications_002c-overview"></span>
<span id="index-fontifications-with-tree_002dsitter_002c-overview"></span>
<p>In general, tree-sitter fontification works as follows:
</p>
<ul>
<li> A Lisp program (usually, part of a major mode) provides a <em>query</em>
consisting of <em>patterns</em>, each pattern associated with a
<em>capture name</em>.
</li><li> The tree-sitter library finds the nodes in the parse tree
that match these patterns, tags the nodes with the corresponding
capture names, and returns them to the Lisp program.
</li><li> The Lisp program uses the returned nodes to highlight the portions of
buffer text corresponding to each node as appropriate, using the
tagged capture names of the nodes to determine the correct
fontification. For example, a node tagged <code>font-lock-keyword</code>
would be highlighted in <code>font-lock-keyword</code> face.
</li></ul>
<p>For more information about queries, patterns, and capture names, see
<a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>.
</p>
<p>To setup tree-sitter fontification, a major mode should first set
<code>treesit-font-lock-settings</code> with the output of
<code>treesit-font-lock-rules</code>, then call
<code>treesit-major-mode-setup</code>.
</p>
<dl class="def">
<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>
<dd><p>This function is used to set <var>treesit-font-lock-settings</var>. It
takes care of compiling queries and other post-processing, and outputs
a value that <var>treesit-font-lock-settings</var> accepts. Here&rsquo;s an
example:
</p>
<div class="example">
<pre class="example">(treesit-font-lock-rules
:language 'javascript
:feature 'constant
:override t
'((true) @font-lock-constant-face
(false) @font-lock-constant-face)
:language 'html
:feature 'script
&quot;(script_element) @font-lock-builtin-face&quot;)
</pre></div>
<p>This function takes a series of <var>query-spec</var>s, where each
<var>query-spec</var> is a <var>query</var> preceded by one or more
<var>:keyword</var>/<var>value</var> pairs. Each <var>query</var> is a
tree-sitter query in either the string, s-expression or compiled form.
</p>
<p>For each <var>query</var>, the <var>:keyword</var>/<var>value</var> pairs that
precede it add meta information to it. The <code>:language</code> keyword
declares <var>query</var>&rsquo;s language. The <code>:feature</code> keyword sets the
feature name of <var>query</var>. Users can control which features are
enabled with <code>font-lock-maximum-decoration</code> and
<code>treesit-font-lock-feature-list</code> (described below). These two
keywords are mandatory.
</p>
<p>Other keywords are optional:
</p>
<table>
<thead><tr><th width="15%">Keyword</th><th width="15%">Value</th><th width="60%">Description</th></tr></thead>
<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>
<tr><td width="15%"></td><td width="15%">t</td><td width="60%">Always apply the new face</td></tr>
<tr><td width="15%"></td><td width="15%"><code>append</code></td><td width="60%">Append the new face to existing ones</td></tr>
<tr><td width="15%"></td><td width="15%"><code>prepend</code></td><td width="60%">Prepend the new face to existing ones</td></tr>
<tr><td width="15%"></td><td width="15%"><code>keep</code></td><td width="60%">Fill-in regions without an existing face</td></tr>
</table>
<p>Lisp programs mark patterns in <var>query</var> with capture names (names
that starts with <code>@</code>), and tree-sitter will return matched nodes
tagged with those same capture names. For the purpose of
fontification, capture names in <var>query</var> should be face names like
<code>font-lock-keyword-face</code>. The captured node will be fontified
with that face.
</p>
<span id="index-treesit_002dfontify_002dwith_002doverride"></span>
<p>Capture names can also be function names, in which case the function
is called with 4 arguments: <var>node</var> and <var>override</var>, <var>start</var>
and <var>end</var>, where <var>node</var> is the node itself, <var>override</var> is
the override property of the rule which captured this node, and
<var>start</var> and <var>end</var> limits the region in which this function
should fontify. (If this function wants to respect the <var>override</var>
argument, it can use <code>treesit-fontify-with-override</code>.)
</p>
<p>Beyond the 4 arguments presented, this function should accept more
arguments as optional arguments for future extensibility.
</p>
<p>If a capture name is both a face and a function, the face takes
priority. If a capture name is neither a face nor a function, it is
ignored.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This is a list of lists of feature symbols. Each element of the list
is a list that represents a decoration level.
<code>font-lock-maximum-decoration</code> controls which levels are
activated.
</p>
<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
<code>:feature</code> value of a query defined in
<code>treesit-font-lock-rules</code>. Removing a feature symbol from this
list disables the corresponding query during font-lock.
</p>
<p>Common feature names, for many programming languages, include
<code>definition</code>, <code>type</code>, <code>assignment</code>, <code>builtin</code>,
<code>constant</code>, <code>keyword</code>, <code>string-interpolation</code>,
<code>comment</code>, <code>doc</code>, <code>string</code>, <code>operator</code>,
<code>preprocessor</code>, <code>escape-sequence</code>, and <code>key</code>. Major
modes are free to subdivide or extend these common features.
</p>
<p>Some of these features warrant some explanation: <code>definition</code>
highlights whatever is being defined, e.g., the function name in a
function definition, the struct name in a struct definition, the
variable name in a variable definition; <code>assignment</code> highlights
the whatever is being assigned to, e.g., the variable or field in an
assignment statement; <code>key</code> highlights keys in key-value pairs,
e.g., keys in a JSON object, or a Python dictionary; <code>doc</code>
highlights docstrings or doc-comments.
</p>
<p>For example, the value of this variable could be:
</p><div class="example">
<pre class="example">((comment string doc) ; level 1
(function-name keyword type builtin constant) ; level 2
(variable-name string-interpolation key)) ; level 3
</pre></div>
<p>Major modes should set this variable before calling
<code>treesit-major-mode-setup</code>.
</p>
<span id="index-treesit_002dfont_002dlock_002drecompute_002dfeatures"></span>
<p>For this variable to take effect, a Lisp program should call
<code>treesit-font-lock-recompute-features</code> (which resets
<code>treesit-font-lock-settings</code> accordingly), or
<code>treesit-major-mode-setup</code> (which calls
<code>treesit-font-lock-recompute-features</code>).
</p></dd></dl>
<dl class="def">
<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>
<dd><p>A list of settings for tree-sitter based font lock. The exact format
of each setting is considered internal. One should always use
<code>treesit-font-lock-rules</code> to set this variable.
</p>
</dd></dl>
<p>Multi-language major modes should provide range functions in
<code>treesit-range-functions</code>, and Emacs will set the ranges
accordingly before fontifing a region (see <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>).
</p>
</div>
<hr>
<div class="header">
<p>
Previous: <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>
</div>
</body>
</html>

280
admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html
View file

@ -1,280 +0,0 @@
<!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>Parser-based Indentation (GNU Emacs Lisp Reference Manual)</title>
<meta name="description" content="Parser-based Indentation (GNU Emacs Lisp Reference Manual)">
<meta name="keywords" content="Parser-based Indentation (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="Auto_002dIndentation.html" rel="up" title="Auto-Indentation">
<link href="SMIE.html" rel="prev" title="SMIE">
<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="subsection" id="Parser_002dbased-Indentation">
<div class="header">
<p>
Previous: <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>
</div>
<hr>
<span id="Parser_002dbased-Indentation-1"></span><h4 class="subsection">24.7.2 Parser-based Indentation</h4>
<span id="index-parser_002dbased-indentation"></span>
<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
a syntax tree. This syntax tree can be used for guiding the program
source indentation commands. For maximum flexibility, it is possible
to write a custom indentation function that queries the syntax tree
and indents accordingly for each language, but that is a lot of work.
It is more convenient to use the simple indentation engine described
below: then the major mode needs only to write some indentation rules
and the engine takes care of the rest.
</p>
<p>To enable the parser-based indentation engine, either set
<var>treesit-simple-indent-rules</var> and call
<code>treesit-major-mode-setup</code>, or equivalently, set the value of
<code>indent-line-function</code> to <code>treesit-indent</code>.
</p>
<dl class="def">
<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>
<dd><p>This variable stores the actual function called by
<code>treesit-indent</code>. By default, its value is
<code>treesit-simple-indent</code>. In the future we might add other,
more complex indentation engines.
</p></dd></dl>
<span id="Writing-indentation-rules"></span><h3 class="heading">Writing indentation rules</h3>
<span id="index-indentation-rules_002c-for-parser_002dbased-indentation"></span>
<dl class="def">
<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>
<dd><p>This local variable stores indentation rules for every language. It is
a list of the form: <code>(<var>language</var>&nbsp;.&nbsp;<var>rules</var>)</code><!-- /@w -->, where
<var>language</var> is a language symbol, and <var>rules</var> is a list of the
form <code>(<var>matcher</var>&nbsp;<var>anchor</var>&nbsp;<var>offset</var>)</code><!-- /@w -->.
</p>
<p>First, Emacs passes the smallest tree-sitter node at the beginning of
the current line to <var>matcher</var>; if it returns non-<code>nil</code>, this
rule is applicable. Then Emacs passes the node to <var>anchor</var>, which
returns a buffer position. Emacs takes the column number of that
position, adds <var>offset</var> to it, and the result is the indentation
column for the current line. <var>offset</var> can be an integer or a
variable whose value is an integer.
</p>
<p>The <var>matcher</var> and <var>anchor</var> are functions, and Emacs provides
convenient defaults for them.
</p>
<p>Each <var>matcher</var> or <var>anchor</var> is a function that takes three
arguments: <var>node</var>, <var>parent</var>, and <var>bol</var>. The argument
<var>bol</var> is the buffer position whose indentation is required: the
position of the first non-whitespace character after the beginning of
the line. The argument <var>node</var> is the largest (highest-in-tree)
node that starts at that position; and <var>parent</var> is the parent of
<var>node</var>. However, when that position is in a whitespace or inside
a multi-line string, no node can start at that position, so
<var>node</var> is <code>nil</code>. In that case, <var>parent</var> would be the
smallest node that spans that position.
</p>
<p>Emacs finds <var>bol</var>, <var>node</var> and <var>parent</var> and
passes them to each <var>matcher</var> and <var>anchor</var>. <var>matcher</var>
should return non-<code>nil</code> if the rule is applicable, and
<var>anchor</var> should return a buffer position.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This is a list of defaults for <var>matcher</var>s and <var>anchor</var>s in
<code>treesit-simple-indent-rules</code>. Each of them represents a function
that takes 3 arguments: <var>node</var>, <var>parent</var> and <var>bol</var>. The
available default functions are:
</p>
<dl compact="compact">
<dt id='index-no_002dnode'><span><code>no-node</code><a href='#index-no_002dnode' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This matcher is a function that is called with 3 arguments:
<var>node</var>, <var>parent</var>, and <var>bol</var>, and returns non-<code>nil</code>,
indicating a match, if <var>node</var> is <code>nil</code>, i.e., there is no
node that starts at <var>bol</var>. This is the case when <var>bol</var> is on
an empty line or inside a multi-line string, etc.
</p>
</dd>
<dt id='index-parent_002dis'><span><code>parent-is</code><a href='#index-parent_002dis' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This matcher is a function of one argument, <var>type</var>; it returns a
function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
and <var>bol</var>, and returns non-<code>nil</code> (i.e., a match) if
<var>parent</var>&rsquo;s type matches regexp <var>type</var>.
</p>
</dd>
<dt id='index-node_002dis'><span><code>node-is</code><a href='#index-node_002dis' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This matcher is a function of one argument, <var>type</var>; it returns a
function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
and <var>bol</var>, and returns non-<code>nil</code> if <var>node</var>&rsquo;s type matches
regexp <var>type</var>.
</p>
</dd>
<dt id='index-query'><span><code>query</code><a href='#index-query' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This matcher is a function of one argument, <var>query</var>; it returns a
function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
and <var>bol</var>, and returns non-<code>nil</code> if querying <var>parent</var>
with <var>query</var> captures <var>node</var> (see <a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>).
</p>
</dd>
<dt id='index-match'><span><code>match</code><a href='#index-match' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This matcher is a function of 5 arguments: <var>node-type</var>,
<var>parent-type</var>, <var>node-field</var>, <var>node-index-min</var>, and
<var>node-index-max</var>). It returns a function that is called with 3
arguments: <var>node</var>, <var>parent</var>, and <var>bol</var>, and returns
non-<code>nil</code> if <var>node</var>&rsquo;s type matches regexp <var>node-type</var>,
<var>parent</var>&rsquo;s type matches regexp <var>parent-type</var>, <var>node</var>&rsquo;s
field name in <var>parent</var> matches regexp <var>node-field</var>, and
<var>node</var>&rsquo;s index among its siblings is between <var>node-index-min</var>
and <var>node-index-max</var>. If the value of an argument is <code>nil</code>,
this matcher doesn&rsquo;t check that argument. For example, to match the
first child where parent is <code>argument_list</code>, use
</p>
<div class="example">
<pre class="example">(match nil &quot;argument_list&quot; nil nil 0 0)
</pre></div>
</dd>
<dt id='index-comment_002dend'><span><code>comment-end</code><a href='#index-comment_002dend' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This matcher is a function that is called with 3 arguments:
<var>node</var>, <var>parent</var>, and <var>bol</var>, and returns non-<code>nil</code> if
point is before a comment ending token. Comment ending tokens are
defined by regular expression <code>treesit-comment-end</code>
(see <a href="Tree_002dsitter-major-modes.html">treesit-comment-end</a>).
</p>
</dd>
<dt id='index-first_002dsibling'><span><code>first-sibling</code><a href='#index-first_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the start of the first child
of <var>parent</var>.
</p>
</dd>
<dt id='index-parent'><span><code>parent</code><a href='#index-parent' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the start of <var>parent</var>.
</p>
</dd>
<dt id='index-parent_002dbol'><span><code>parent-bol</code><a href='#index-parent_002dbol' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the first non-space character
on the line of <var>parent</var>.
</p>
</dd>
<dt id='index-prev_002dsibling'><span><code>prev-sibling</code><a href='#index-prev_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the start of the previous
sibling of <var>node</var>.
</p>
</dd>
<dt id='index-no_002dindent'><span><code>no-indent</code><a href='#index-no_002dindent' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the start of <var>node</var>.
</p>
</dd>
<dt id='index-prev_002dline'><span><code>prev-line</code><a href='#index-prev_002dline' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the first non-whitespace
character on the previous line.
</p>
</dd>
<dt id='index-point_002dmin'><span><code>point-min</code><a href='#index-point_002dmin' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the beginning of the buffer.
This is useful as the beginning of the buffer is always at column 0.
</p>
</dd>
<dt id='index-comment_002dstart'><span><code>comment-start</code><a href='#index-comment_002dstart' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the position right after the
comment-start token. Comment-start tokens are defined by regular
expression <code>treesit-comment-start</code> (see <a href="Tree_002dsitter-major-modes.html">treesit-comment-start</a>). This function assumes <var>parent</var> is
the comment node.
</p>
</dd>
<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>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the position after the
comment-start token and any whitespace characters following that
token. Comment-start tokens are defined by regular expression
<code>treesit-comment-start</code>. This function assumes <var>parent</var> is
the comment node.
</p></dd>
</dl>
</dd></dl>
<span id="Indentation-utilities"></span><h3 class="heading">Indentation utilities</h3>
<span id="index-utility-functions-for-parser_002dbased-indentation"></span>
<p>Here are some utility functions that can help writing parser-based
indentation rules.
</p>
<dl class="def">
<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>
<dd><p>This function checks the current buffer&rsquo;s indentation against major
mode <var>mode</var>. It indents the current buffer according to
<var>mode</var> and compares the results with the current indentation.
Then it pops up a buffer showing the differences. Correct
indentation (target) is shown in green color, current indentation is
shown in red color. </p></dd></dl>
<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.
</p>
</div>
<hr>
<div class="header">
<p>
Previous: <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>
</div>
</body>
</html>

125
admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html
View file

@ -1,125 +0,0 @@
<!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>Parsing Program Source (GNU Emacs Lisp Reference Manual)</title>
<meta name="description" content="Parsing Program Source (GNU Emacs Lisp Reference Manual)">
<meta name="keywords" content="Parsing Program Source (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="index.html" rel="up" title="Top">
<link href="Abbrevs.html" rel="next" title="Abbrevs">
<link href="Syntax-Tables.html" rel="prev" title="Syntax Tables">
<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="chapter" id="Parsing-Program-Source">
<div class="header">
<p>
Next: <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>
</div>
<hr>
<span id="Parsing-Program-Source-1"></span><h2 class="chapter">37 Parsing Program Source</h2>
<span id="index-syntax-tree_002c-from-parsing-program-source"></span>
<p>Emacs provides various ways to parse program source text and produce a
<em>syntax tree</em>. In a syntax tree, text is no longer considered a
one-dimensional stream of characters, but a structured tree of nodes,
where each node representing a piece of text. Thus, a syntax tree can
enable interesting features like precise fontification, indentation,
navigation, structured editing, etc.
</p>
<p>Emacs has a simple facility for parsing balanced expressions
(see <a href="Parsing-Expressions.html">Parsing Expressions</a>). There is also the SMIE library for
generic navigation and indentation (see <a href="SMIE.html">Simple Minded Indentation Engine</a>).
</p>
<p>In addition to those, Emacs also provides integration with
<a href="https://tree-sitter.github.io/tree-sitter">the tree-sitter
library</a>) if support for it was compiled in. The tree-sitter library
implements an incremental parser and has support from a wide range of
programming languages.
</p>
<dl class="def">
<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>
<dd><p>This function returns non-<code>nil</code> if tree-sitter features are
available for the current Emacs session.
</p></dd></dl>
<p>To be able to parse the program source using the tree-sitter library
and access the syntax tree of the program, a Lisp program needs to
load a language definition library, and create a parser for that
language and the current buffer. After that, the Lisp program can
query the parser about specific nodes of the syntax tree. Then, it
can access various kinds of information about each node, and search
for nodes using a powerful pattern-matching syntax. This chapter
explains how to do all this, and also how a Lisp program can work with
source files that mix multiple programming languages.
</p>
<ul class="section-toc">
<li><a href="Language-Definitions.html" accesskey="1">Tree-sitter Language Definitions</a></li>
<li><a href="Using-Parser.html" accesskey="2">Using Tree-sitter Parser</a></li>
<li><a href="Retrieving-Nodes.html" accesskey="3">Retrieving Nodes</a></li>
<li><a href="Accessing-Node-Information.html" accesskey="4">Accessing Node Information</a></li>
<li><a href="Pattern-Matching.html" accesskey="5">Pattern Matching Tree-sitter Nodes</a></li>
<li><a href="Multiple-Languages.html" accesskey="6">Parsing Text in Multiple Languages</a></li>
<li><a href="Tree_002dsitter-major-modes.html" accesskey="7">Developing major modes with tree-sitter</a></li>
<li><a href="Tree_002dsitter-C-API.html" accesskey="8">Tree-sitter C API Correspondence</a></li>
</ul>
</div>
<hr>
<div class="header">
<p>
Next: <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>
</div>
</body>
</html>

450
admin/notes/tree-sitter/html-manual/Pattern-Matching.html
View file

@ -1,450 +0,0 @@
<!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>Pattern Matching (GNU Emacs Lisp Reference Manual)</title>
<meta name="description" content="Pattern Matching (GNU Emacs Lisp Reference Manual)">
<meta name="keywords" content="Pattern Matching (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="Multiple-Languages.html" rel="next" title="Multiple Languages">
<link href="Accessing-Node-Information.html" rel="prev" title="Accessing Node Information">
<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="Pattern-Matching">
<div class="header">
<p>
Next: <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>
</div>
<hr>
<span id="Pattern-Matching-Tree_002dsitter-Nodes"></span><h3 class="section">37.5 Pattern Matching Tree-sitter Nodes</h3>
<span id="index-pattern-matching-with-tree_002dsitter-nodes"></span>
<span id="index-capturing_002c-tree_002dsitter-node"></span>
<p>Tree-sitter lets Lisp programs match patterns using a small
declarative language. This pattern matching consists of two steps:
first tree-sitter matches a <em>pattern</em> against nodes in the syntax
tree, then it <em>captures</em> specific nodes that matched the pattern
and returns the captured nodes.
</p>
<p>We describe first how to write the most basic query pattern and how to
capture nodes in a pattern, then the pattern-matching function, and
finally the more advanced pattern syntax.
</p>
<span id="Basic-query-syntax"></span><h3 class="heading">Basic query syntax</h3>
<span id="index-tree_002dsitter-query-pattern-syntax"></span>
<span id="index-pattern-syntax_002c-tree_002dsitter-query"></span>
<span id="index-query_002c-tree_002dsitter"></span>
<p>A <em>query</em> consists of multiple <em>patterns</em>. Each pattern is an
s-expression that matches a certain node in the syntax node. A
pattern has the form <code>(<var>type</var>&nbsp;(<var>child</var>&hellip;))</code><!-- /@w -->
</p>
<p>For example, a pattern that matches a <code>binary_expression</code> node that
contains <code>number_literal</code> child nodes would look like
</p>
<div class="example">
<pre class="example">(binary_expression (number_literal))
</pre></div>
<p>To <em>capture</em> a node using the query pattern above, append
<code>@<var>capture-name</var></code> after the node pattern you want to
capture. For example,
</p>
<div class="example">
<pre class="example">(binary_expression (number_literal) @number-in-exp)
</pre></div>
<p>captures <code>number_literal</code> nodes that are inside a
<code>binary_expression</code> node with the capture name
<code>number-in-exp</code>.
</p>
<p>We can capture the <code>binary_expression</code> node as well, with, for
example, the capture name <code>biexp</code>:
</p>
<div class="example">
<pre class="example">(binary_expression
(number_literal) @number-in-exp) @biexp
</pre></div>
<span id="Query-function"></span><h3 class="heading">Query function</h3>
<span id="index-query-functions_002c-tree_002dsitter"></span>
<p>Now we can introduce the <em>query functions</em>.
</p>
<dl class="def">
<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>
<dd><p>This function matches patterns in <var>query</var> within <var>node</var>.
The argument <var>query</var> can be either a string, a s-expression, or a
compiled query object. For now, we focus on the string syntax;
s-expression syntax and compiled query are described at the end of the
section.
</p>
<p>The argument <var>node</var> can also be a parser or a language symbol. A
parser means using its root node, a language symbol means find or
create a parser for that language in the current buffer, and use the
root node.
</p>
<p>The function returns all the captured nodes in a list of the form
<code>(<var><span class="nolinebreak">capture_name</span></var>&nbsp;.&nbsp;<var>node</var>)</code><!-- /@w -->. If <var>node-only</var> is
non-<code>nil</code>, it returns the list of nodes instead. By default the
entire text of <var>node</var> is searched, but if <var>beg</var> and <var>end</var>
are both non-<code>nil</code>, they specify the region of buffer text where
this function should match nodes. Any matching node whose span
overlaps with the region between <var>beg</var> and <var>end</var> are captured,
it doesn&rsquo;t have to be completely in the region.
</p>
<span id="index-treesit_002dquery_002derror"></span>
<span id="index-treesit_002dquery_002dvalidate"></span>
<p>This function raises the <code>treesit-query-error</code> error if
<var>query</var> is malformed. The signal data contains a description of
the specific error. You can use <code>treesit-query-validate</code> to
validate and debug the query.
</p></dd></dl>
<p>For example, suppose <var>node</var>&rsquo;s text is <code>1 + 2</code>, and
<var>query</var> is
</p>
<div class="example">
<pre class="example">(setq query
&quot;(binary_expression
(number_literal) @number-in-exp) @biexp&quot;)
</pre></div>
<p>Matching that query would return
</p>
<div class="example">
<pre class="example">(treesit-query-capture node query)
&rArr; ((biexp . <var>&lt;node for &quot;1 + 2&quot;&gt;</var>)
(number-in-exp . <var>&lt;node for &quot;1&quot;&gt;</var>)
(number-in-exp . <var>&lt;node for &quot;2&quot;&gt;</var>))
</pre></div>
<p>As mentioned earlier, <var>query</var> could contain multiple patterns.
For example, it could have two top-level patterns:
</p>
<div class="example">
<pre class="example">(setq query
&quot;(binary_expression) @biexp
(number_literal) @number @biexp&quot;)
</pre></div>
<dl class="def">
<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>
<dd><p>This function parses <var>string</var> with <var>language</var>, matches its
root node with <var>query</var>, and returns the result.
</p></dd></dl>
<span id="More-query-syntax"></span><h3 class="heading">More query syntax</h3>
<p>Besides node type and capture, tree-sitter&rsquo;s pattern syntax can
express anonymous node, field name, wildcard, quantification,
grouping, alternation, anchor, and predicate.
</p>
<span id="Anonymous-node"></span><h4 class="subheading">Anonymous node</h4>
<p>An anonymous node is written verbatim, surrounded by quotes. A
pattern matching (and capturing) keyword <code>return</code> would be
</p>
<div class="example">
<pre class="example">&quot;return&quot; @keyword
</pre></div>
<span id="Wild-card"></span><h4 class="subheading">Wild card</h4>
<p>In a pattern, &lsquo;<samp>(_)</samp>&rsquo; matches any named node, and &lsquo;<samp>_</samp>&rsquo; matches
any named and anonymous node. For example, to capture any named child
of a <code>binary_expression</code> node, the pattern would be
</p>
<div class="example">
<pre class="example">(binary_expression (_) @in_biexp)
</pre></div>
<span id="Field-name"></span><h4 class="subheading">Field name</h4>
<p>It is possible to capture child nodes that have specific field names.
In the pattern below, <code>declarator</code> and <code>body</code> are field
names, indicated by the colon following them.
</p>
<div class="example">
<pre class="example">(function_definition
declarator: (_) @func-declarator
body: (_) @func-body)
</pre></div>
<p>It is also possible to capture a node that doesn&rsquo;t have a certain
field, say, a <code>function_definition</code> without a <code>body</code> field.
</p>
<div class="example">
<pre class="example">(function_definition !body) @func-no-body
</pre></div>
<span id="Quantify-node"></span><h4 class="subheading">Quantify node</h4>
<span id="index-quantify-node_002c-tree_002dsitter"></span>
<p>Tree-sitter recognizes quantification operators &lsquo;<samp>*</samp>&rsquo;, &lsquo;<samp>+</samp>&rsquo; and
&lsquo;<samp>?</samp>&rsquo;. Their meanings are the same as in regular expressions:
&lsquo;<samp>*</samp>&rsquo; matches the preceding pattern zero or more times, &lsquo;<samp>+</samp>&rsquo;
matches one or more times, and &lsquo;<samp>?</samp>&rsquo; matches zero or one time.
</p>
<p>For example, the following pattern matches <code>type_declaration</code>
nodes that has <em>zero or more</em> <code>long</code> keyword.
</p>
<div class="example">
<pre class="example">(type_declaration &quot;long&quot;*) @long-type
</pre></div>
<p>The following pattern matches a type declaration that has zero or one
<code>long</code> keyword:
</p>
<div class="example">
<pre class="example">(type_declaration &quot;long&quot;?) @long-type
</pre></div>
<span id="Grouping"></span><h4 class="subheading">Grouping</h4>
<p>Similar to groups in regular expression, we can bundle patterns into
groups and apply quantification operators to them. For example, to
express a comma separated list of identifiers, one could write
</p>
<div class="example">
<pre class="example">(identifier) (&quot;,&quot; (identifier))*
</pre></div>
<span id="Alternation"></span><h4 class="subheading">Alternation</h4>
<p>Again, similar to regular expressions, we can express &ldquo;match anyone
from this group of patterns&rdquo; in a pattern. The syntax is a list of
patterns enclosed in square brackets. For example, to capture some
keywords in C, the pattern would be
</p>
<div class="example">
<pre class="example">[
&quot;return&quot;
&quot;break&quot;
&quot;if&quot;
&quot;else&quot;
] @keyword
</pre></div>
<span id="Anchor"></span><h4 class="subheading">Anchor</h4>
<p>The anchor operator &lsquo;<samp>.</samp>&rsquo; can be used to enforce juxtaposition,
i.e., to enforce two things to be directly next to each other. The
two &ldquo;things&rdquo; can be two nodes, or a child and the end of its parent.
For example, to capture the first child, the last child, or two
adjacent children:
</p>
<div class="example">
<pre class="example">;; Anchor the child with the end of its parent.
(compound_expression (_) @last-child .)
</pre><pre class="example">
</pre><pre class="example">;; Anchor the child with the beginning of its parent.
(compound_expression . (_) @first-child)
</pre><pre class="example">
</pre><pre class="example">;; Anchor two adjacent children.
(compound_expression
(_) @prev-child
.
(_) @next-child)
</pre></div>
<p>Note that the enforcement of juxtaposition ignores any anonymous
nodes.
</p>
<span id="Predicate"></span><h4 class="subheading">Predicate</h4>
<p>It is possible to add predicate constraints to a pattern. For
example, with the following pattern:
</p>
<div class="example">
<pre class="example">(
(array . (_) @first (_) @last .)
(#equal @first @last)
)
</pre></div>
<p>tree-sitter only matches arrays where the first element equals to
the last element. To attach a predicate to a pattern, we need to
group them together. A predicate always starts with a &lsquo;<samp>#</samp>&rsquo;.
Currently there are two predicates, <code>#equal</code> and <code>#match</code>.
</p>
<dl class="def">
<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>
<dd><p>Matches if <var>arg1</var> equals to <var>arg2</var>. Arguments can be either
strings or capture names. Capture names represent the text that the
captured node spans in the buffer.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>Matches if the text that <var>capture-name</var>&rsquo;s node spans in the buffer
matches regular expression <var>regexp</var>. Matching is case-sensitive.
</p></dd></dl>
<p>Note that a predicate can only refer to capture names that appear in
the same pattern. Indeed, it makes little sense to refer to capture
names in other patterns.
</p>
<span id="S_002dexpression-patterns"></span><h3 class="heading">S-expression patterns</h3>
<span id="index-tree_002dsitter-patterns-as-sexps"></span>
<span id="index-patterns_002c-tree_002dsitter_002c-in-sexp-form"></span>
<p>Besides strings, Emacs provides a s-expression based syntax for
tree-sitter patterns. It largely resembles the string-based syntax.
For example, the following query
</p>
<div class="example">
<pre class="example">(treesit-query-capture
node &quot;(addition_expression
left: (_) @left
\&quot;+\&quot; @plus-sign
right: (_) @right) @addition
[\&quot;return\&quot; \&quot;break\&quot;] @keyword&quot;)
</pre></div>
<p>is equivalent to
</p>
<div class="example">
<pre class="example">(treesit-query-capture
node '((addition_expression
left: (_) @left
&quot;+&quot; @plus-sign
right: (_) @right) @addition
[&quot;return&quot; &quot;break&quot;] @keyword))
</pre></div>
<p>Most patterns can be written directly as strange but nevertheless
valid s-expressions. Only a few of them needs modification:
</p>
<ul>
<li> Anchor &lsquo;<samp>.</samp>&rsquo; is written as <code>:anchor</code>.
</li><li> &lsquo;<samp>?</samp>&rsquo; is written as &lsquo;<samp>:?</samp>&rsquo;.
</li><li> &lsquo;<samp>*</samp>&rsquo; is written as &lsquo;<samp>:*</samp>&rsquo;.
</li><li> &lsquo;<samp>+</samp>&rsquo; is written as &lsquo;<samp>:+</samp>&rsquo;.
</li><li> <code>#equal</code> is written as <code>:equal</code>. In general, predicates
change their &lsquo;<samp>#</samp>&rsquo; to &lsquo;<samp>:</samp>&rsquo;.
</li></ul>
<p>For example,
</p>
<div class="example">
<pre class="example">&quot;(
(compound_expression . (_) @first (_)* @rest)
(#match \&quot;love\&quot; @first)
)&quot;
</pre></div>
<p>is written in s-expression as
</p>
<div class="example">
<pre class="example">'((
(compound_expression :anchor (_) @first (_) :* @rest)
(:match &quot;love&quot; @first)
))
</pre></div>
<span id="Compiling-queries"></span><h3 class="heading">Compiling queries</h3>
<span id="index-compiling-tree_002dsitter-queries"></span>
<span id="index-queries_002c-compiling"></span>
<p>If a query is intended to be used repeatedly, especially in tight
loops, it is important to compile that query, because a compiled query
is much faster than an uncompiled one. A compiled query can be used
anywhere a query is accepted.
</p>
<dl class="def">
<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>
<dd><p>This function compiles <var>query</var> for <var>language</var> into a compiled
query object and returns it.
</p>
<p>This function raises the <code>treesit-query-error</code> error if
<var>query</var> is malformed. The signal data contains a description of
the specific error. You can use <code>treesit-query-validate</code> to
validate and debug the query.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function return the language of <var>query</var>.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function converts the s-expression <var>query</var> into the string
format.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function converts the s-expression <var>pattern</var> into the string
format.
</p></dd></dl>
<p>For more details, read the tree-sitter project&rsquo;s documentation about
pattern-matching, which can be found at
<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>.
</p>
</div>
<hr>
<div class="header">
<p>
Next: <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>
</div>
</body>
</html>

420
admin/notes/tree-sitter/html-manual/Retrieving-Node.html
View file

@ -1,420 +0,0 @@
<!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>Retrieving Node (GNU Emacs Lisp Reference Manual)</title>
<meta name="description" content="Retrieving Node (GNU Emacs Lisp Reference Manual)">
<meta name="keywords" content="Retrieving Node (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="Accessing-Node-Information.html" rel="next" title="Accessing Node Information">
<link href="Using-Parser.html" rel="prev" title="Using Parser">
<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="Retrieving-Node">
<div class="header">
<p>
Next: <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>
</div>
<hr>
<span id="Retrieving-Node-1"></span><h3 class="section">37.3 Retrieving Node</h3>
<span id="index-retrieve-node_002c-tree_002dsitter"></span>
<span id="index-tree_002dsitter_002c-find-node"></span>
<span id="index-get-node_002c-tree_002dsitter"></span>
<span id="index-terminology_002c-for-tree_002dsitter-functions"></span>
<p>Here&rsquo;s some terminology and conventions we use when documenting
tree-sitter functions.
</p>
<p>We talk about a node being &ldquo;smaller&rdquo; or &ldquo;larger&rdquo;, and &ldquo;lower&rdquo; or
&ldquo;higher&rdquo;. A smaller and lower node is lower in the syntax tree and
therefore spans a smaller portion of buffer text; a larger and higher
node is higher up in the syntax tree, it contains many smaller nodes
as its children, and therefore spans a larger portion of text.
</p>
<p>When a function cannot find a node, it returns <code>nil</code>. For
convenience, all functions that take a node as argument and return
a node, also accept the node argument of <code>nil</code> and in that case
just return <code>nil</code>.
</p>
<span id="index-treesit_002dnode_002doutdated"></span>
<p>Nodes are not automatically updated when the associated buffer is
modified, and there is no way to update a node once it is retrieved.
Using an outdated node signals the <code>treesit-node-outdated</code> error.
</p>
<span id="Retrieving-node-from-syntax-tree"></span><h3 class="heading">Retrieving node from syntax tree</h3>
<span id="index-retrieving-tree_002dsitter-nodes"></span>
<span id="index-syntax-tree_002c-retrieving-nodes"></span>
<dl class="def">
<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>
<dd><p>This function returns the <em>smallest</em> node that starts at or after
the buffer position <var>pos</var>. In other words, the start of the node
is greater or equal to <var>pos</var>.
</p>
<p>When <var>parser-or-lang</var> is <code>nil</code> or omitted, this function uses
the first parser in <code>(treesit-parser-list)</code> of the current
buffer. If <var>parser-or-lang</var> is a parser object, it uses that
parser; if <var>parser-or-lang</var> is a language, it finds the first
parser using that language in <code>(treesit-parser-list)</code>, and uses
that.
</p>
<p>If <var>named</var> is non-<code>nil</code>, this function looks for a named node
only (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
</p>
<p>When <var>pos</var> is after all the text in the buffer, technically there
is no node after <var>pos</var>. But for convenience, this function will
return the last leaf node in the parse tree. If <var>strict</var> is
non-<code>nil</code>, this function will strictly comply to the semantics and
return <var>nil</var>.
</p>
<p>Example:
</p>
<div class="example">
<pre class="example">;; Find the node at point in a C parser's syntax tree.
(treesit-node-at (point) 'c)
&rArr; #&lt;treesit-node (primitive_type) in 23-27&gt;
</pre></div>
</dd></dl>
<dl class="def">
<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>
<dd><p>This function returns the <em>smallest</em> node that covers the region
of buffer text between <var>beg</var> and <var>end</var>. In other words, the
start of the node is before or at <var>beg</var>, and the end of the node
is at or after <var>end</var>.
</p>
<p><em>Beware:</em> calling this function on an empty line that is not
inside any top-level construct (function definition, etc.) most
probably will give you the root node, because the root node is the
smallest node that covers that empty line. Most of the time, you want
to use <code>treesit-node-at</code>, described above, instead.
</p>
<p>When <var>parser-or-lang</var> is <code>nil</code>, this function uses the first
parser in <code>(treesit-parser-list)</code> of the current buffer. If
<var>parser-or-lang</var> is a parser object, it uses that parser; if
<var>parser-or-lang</var> is a language, it finds the first parser using
that language in <code>(treesit-parser-list)</code>, and uses that.
</p>
<p>If <var>named</var> is non-<code>nil</code>, this function looks for a named node
only (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function returns the root node of the syntax tree generated by
<var>parser</var>.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function finds the first parser that uses <var>language</var> in
<code>(treesit-parser-list)</code> of the current buffer, and returns the
root node generated by that parser. If it cannot find an appropriate
parser, it returns <code>nil</code>.
</p></dd></dl>
<p>Given a node, a Lisp program can retrieve other nodes starting from
it, or query for information about this node.
</p>
<span id="Retrieving-node-from-other-nodes"></span><h3 class="heading">Retrieving node from other nodes</h3>
<span id="index-syntax-tree-nodes_002c-retrieving-from-other-nodes"></span>
<span id="By-kinship"></span><h4 class="subheading">By kinship</h4>
<span id="index-kinship_002c-syntax-tree-nodes"></span>
<span id="index-nodes_002c-by-kinship"></span>
<span id="index-syntax-tree-nodes_002c-by-kinship"></span>
<dl class="def">
<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>
<dd><p>This function returns the immediate parent of <var>node</var>.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function returns the <var>n</var>&rsquo;th child of <var>node</var>. If
<var>named</var> is non-<code>nil</code>, it counts only named nodes
(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
</p>
<p>For example, in a node that represents a string <code>&quot;text&quot;</code>, there
are three children nodes: the opening quote <code>&quot;</code>, the string text
<code>text</code>, and the closing quote <code>&quot;</code>. Among these nodes, the
first child is the opening quote <code>&quot;</code>, and the first named child
is the string text.
</p>
<p>This function returns <code>nil</code> if there is no <var>n</var>&rsquo;th child.
<var>n</var> could be negative, e.g., <code>-1</code> represents the last child.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function returns all of <var>node</var>&rsquo;s children as a list. If
<var>named</var> is non-<code>nil</code>, it retrieves only named nodes.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function finds the next sibling of <var>node</var>. If <var>named</var> is
non-<code>nil</code>, it finds the next named sibling.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function finds the previous sibling of <var>node</var>. If
<var>named</var> is non-<code>nil</code>, it finds the previous named sibling.
</p></dd></dl>
<span id="By-field-name"></span><h4 class="subheading">By field name</h4>
<span id="index-nodes_002c-by-field-name"></span>
<span id="index-syntax-tree-nodes_002c-by-field-name"></span>
<p>To make the syntax tree easier to analyze, many language definitions
assign <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
could have a <code>declarator</code> node and a <code>body</code> node.
</p>
<dl class="def">
<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>
<dd><p>This function finds the child of <var>node</var> whose field name is
<var>field-name</var>, a string.
</p>
<div class="example">
<pre class="example">;; Get the child that has &quot;body&quot; as its field name.
(treesit-node-child-by-field-name node &quot;body&quot;)
&rArr; #&lt;treesit-node (compound_statement) in 45-89&gt;
</pre></div>
</dd></dl>
<span id="By-position"></span><h4 class="subheading">By position</h4>
<span id="index-nodes_002c-by-position"></span>
<span id="index-syntax-tree-nodes_002c-by-position"></span>
<dl class="def">
<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>
<dd><p>This function finds the first child of <var>node</var> that extends beyond
buffer position <var>pos</var>. &ldquo;Extends beyond&rdquo; means the end of the
child node is greater or equal to <var>pos</var>. This function only looks
for immediate children of <var>node</var>, and doesn&rsquo;t look in its
grandchildren. If <var>named</var> is non-<code>nil</code>, it looks for the
first named child (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function finds the <em>smallest</em> descendant node of <var>node</var>
that spans the region of text between positions <var>beg</var> and
<var>end</var>. It is similar to <code>treesit-node-at</code>. If <var>named</var>
is non-<code>nil</code>, it looks for smallest named child.
</p></dd></dl>
<span id="Searching-for-node"></span><h3 class="heading">Searching for node</h3>
<dl class="def">
<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>
<dd><p>This function traverses the subtree of <var>node</var> (including
<var>node</var> itself), looking for a node for which <var>predicate</var>
returns non-<code>nil</code>. <var>predicate</var> is a regexp that is matched
against each node&rsquo;s type, or a predicate function that takes a node
and returns non-<code>nil</code> if the node matches. The function returns
the first node that matches, or <code>nil</code> if none does.
</p>
<p>By default, this function only traverses named nodes, but if <var>all</var>
is non-<code>nil</code>, it traverses all the nodes. If <var>backward</var> is
non-<code>nil</code>, it traverses backwards (i.e., it visits the last child first
when traversing down the tree). If <var>limit</var> is non-<code>nil</code>, it
must be a number that limits the tree traversal to that many levels
down the tree.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>Like <code>treesit-search-subtree</code>, this function also traverses the
parse tree and matches each node with <var>predicate</var> (except for
<var>start</var>), where <var>predicate</var> can be a regexp or a function.
For a tree like the below where <var>start</var> is marked S, this function
traverses as numbered from 1 to 12:
</p>
<div class="example">
<pre class="example"> 12
|
S--------3----------11
| | |
o--o-+--o 1--+--2 6--+-----10
| | | |
o o +-+-+ +--+--+
| | | | |
4 5 7 8 9
</pre></div>
<p>Note that this function doesn&rsquo;t traverse the subtree of <var>start</var>,
and it always traverse leaf nodes first, then upwards.
</p>
<p>Like <code>treesit-search-subtree</code>, this function only searches for
named nodes by default, but if <var>all</var> is non-<code>nil</code>, it
searches for all nodes. If <var>backward</var> is non-<code>nil</code>, it
searches backwards.
</p>
<p>While <code>treesit-search-subtree</code> traverses the subtree of a node,
this function starts with node <var>start</var> and traverses every node
that comes after it in the buffer position order, i.e., nodes with
start positions greater than the end position of <var>start</var>.
</p>
<p>In the tree shown above, <code>treesit-search-subtree</code> traverses node
S (<var>start</var>) and nodes marked with <code>o</code>, where this function
traverses the nodes marked with numbers. This function is useful for
answering questions like &ldquo;what is the first node after <var>start</var> in
the buffer that satisfies some condition?&rdquo;
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function moves point to the start or end of the next node after
<var>node</var> in the buffer that matches <var>predicate</var>. If <var>start</var>
is non-<code>nil</code>, stop at the beginning rather than the end of a node.
</p>
<p>This function guarantees that the matched node it returns makes
progress in terms of buffer position: the start/end position of the
returned node is always greater than that of <var>node</var>.
</p>
<p>Arguments <var>predicate</var>, <var>backward</var> and <var>all</var> are the same
as in <code>treesit-search-forward</code>.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function creates a sparse tree from <var>root</var>&rsquo;s subtree.
</p>
<p>It takes the subtree under <var>root</var>, and combs it so only the nodes
that match <var>predicate</var> are left. Like previous functions, the
<var>predicate</var> can be a regexp string that matches against each
node&rsquo;s type, or a function that takes a node and return non-<code>nil</code>
if it matches.
</p>
<p>For example, for a subtree on the left that consist of both numbers
and letters, if <var>predicate</var> is &ldquo;letter only&rdquo;, the returned tree
is the one on the right.
</p>
<div class="example">
<pre class="example"> a a a
| | |
+---+---+ +---+---+ +---+---+
| | | | | | | | |
b 1 2 b | | b c d
| | =&gt; | | =&gt; |
c +--+ c + e
| | | | |
+--+ d 4 +--+ d
| | |
e 5 e
</pre></div>
<p>If <var>process-fn</var> is non-<code>nil</code>, instead of returning the matched
nodes, this function passes each node to <var>process-fn</var> and uses the
returned value instead. If non-<code>nil</code>, <var>limit</var> is the number of
levels to go down from <var>root</var>.
</p>
<p>Each node in the returned tree looks like
<code>(<var><span class="nolinebreak">tree-sitter-node</span></var>&nbsp;.&nbsp;(<var>child</var>&nbsp;&hellip;))</code><!-- /@w -->. The
<var>tree-sitter-node</var> of the root of this tree will be nil if
<var>root</var> doesn&rsquo;t match <var>predicate</var>. If no node matches
<var>predicate</var>, the function returns <code>nil</code>.
</p></dd></dl>
<span id="More-convenience-functions"></span><h3 class="heading">More convenience functions</h3>
<dl class="def">
<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>
<dd><p>This function finds immediate children of <var>node</var> that satisfy
<var>predicate</var>.
</p>
<p>The <var>predicate</var> function takes a node as the argument and should
return non-<code>nil</code> to indicate that the node should be kept. If
<var>named</var> is non-<code>nil</code>, this function only examines the named
nodes.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function repeatedly finds the parents of <var>node</var>, and returns
the parent that satisfies <var>predicate</var>, a function that takes a
node as the argument. If no parent satisfies <var>predicate</var>, this
function returns <code>nil</code>.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function repeatedly finds the parent of <var>node</var>, and keeps
doing so as long as the nodes satisfy <var>predicate</var>, a function that
takes a node as the argument. That is, this function returns the
farthest parent that still satisfies <var>predicate</var>.
</p></dd></dl>
<dl class="def">
<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>
<dd><p>This function returns the highest parent of <var>node</var> that has the
same type as <var>node</var>. If no such parent exists, it returns
<code>nil</code>. Therefore this function is also useful for testing
whether <var>node</var> is top-level.
</p>
<p>If <var>type</var> is non-<code>nil</code>, this function matches each parent&rsquo;s
type with <var>type</var> as a regexp, rather than using <var>node</var>&rsquo;s type.
</p></dd></dl>
</div>
<hr>
<div class="header">
<p>
Next: <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>
</div>
</body>
</html>

211
admin/notes/tree-sitter/html-manual/Tree_002dsitter-C-API.html
View file

@ -1,211 +0,0 @@
<!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>Tree-sitter C API (GNU Emacs Lisp Reference Manual)</title>
<meta name="description" content="Tree-sitter C API (GNU Emacs Lisp Reference Manual)">
<meta name="keywords" content="Tree-sitter C API (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="Tree_002dsitter-major-modes.html" rel="prev" title="Tree-sitter major modes">
<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="Tree_002dsitter-C-API">
<div class="header">
<p>
Previous: <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>
</div>
<hr>
<span id="Tree_002dsitter-C-API-Correspondence"></span><h3 class="section">37.8 Tree-sitter C API Correspondence</h3>
<p>Emacs&rsquo; tree-sitter integration doesn&rsquo;t expose every feature
provided by tree-sitter&rsquo;s C API. Missing features include:
</p>
<ul>
<li> Creating a tree cursor and navigating the syntax tree with it.
</li><li> Setting timeout and cancellation flag for a parser.
</li><li> Setting the logger for a parser.
</li><li> Printing a <acronym>DOT</acronym> graph of the syntax tree to a file.
</li><li> Copying and modifying a syntax tree. (Emacs doesn&rsquo;t expose a tree
object.)
</li><li> Using (row, column) coordinates as position.
</li><li> Updating a node with changes. (In Emacs, retrieve a new node instead
of updating the existing one.)
</li><li> Querying statics of a language definition.
</li></ul>
<p>In addition, Emacs makes some changes to the C API to make the API more
convenient and idiomatic:
</p>
<ul>
<li> Instead of using byte positions, the Emacs Lisp API uses character
positions.
</li><li> Null nodes are converted to nil.
</li></ul>
<p>Below is the correspondence between all C API functions and their
ELisp counterparts. Sometimes one ELisp function corresponds to
multiple C functions, and many C functions don&rsquo;t have an ELisp
counterpart.
</p>
<div class="example">
<pre class="example">ts_parser_new treesit-parser-create
ts_parser_delete
ts_parser_set_language
ts_parser_language treesit-parser-language
ts_parser_set_included_ranges treesit-parser-set-included-ranges
ts_parser_included_ranges treesit-parser-included-ranges
ts_parser_parse
ts_parser_parse_string treesit-parse-string
ts_parser_parse_string_encoding
ts_parser_reset
ts_parser_set_timeout_micros
ts_parser_timeout_micros
ts_parser_set_cancellation_flag
ts_parser_cancellation_flag
ts_parser_set_logger
ts_parser_logger
ts_parser_print_dot_graphs
ts_tree_copy
ts_tree_delete
ts_tree_root_node
ts_tree_language
ts_tree_edit
ts_tree_get_changed_ranges
ts_tree_print_dot_graph
ts_node_type treesit-node-type
ts_node_symbol
ts_node_start_byte treesit-node-start
ts_node_start_point
ts_node_end_byte treesit-node-end
ts_node_end_point
ts_node_string treesit-node-string
ts_node_is_null
ts_node_is_named treesit-node-check
ts_node_is_missing treesit-node-check
ts_node_is_extra treesit-node-check
ts_node_has_changes
ts_node_has_error treesit-node-check
ts_node_parent treesit-node-parent
ts_node_child treesit-node-child
ts_node_field_name_for_child treesit-node-field-name-for-child
ts_node_child_count treesit-node-child-count
ts_node_named_child treesit-node-child
ts_node_named_child_count treesit-node-child-count
ts_node_child_by_field_name treesit-node-by-field-name
ts_node_child_by_field_id
ts_node_next_sibling treesit-node-next-sibling
ts_node_prev_sibling treesit-node-prev-sibling
ts_node_next_named_sibling treesit-node-next-sibling
ts_node_prev_named_sibling treesit-node-prev-sibling
ts_node_first_child_for_byte treesit-node-first-child-for-pos
ts_node_first_named_child_for_byte treesit-node-first-child-for-pos
ts_node_descendant_for_byte_range treesit-descendant-for-range
ts_node_descendant_for_point_range
ts_node_named_descendant_for_byte_range treesit-descendant-for-range
ts_node_named_descendant_for_point_range
ts_node_edit
ts_node_eq treesit-node-eq
ts_tree_cursor_new
ts_tree_cursor_delete
ts_tree_cursor_reset
ts_tree_cursor_current_node
ts_tree_cursor_current_field_name
ts_tree_cursor_current_field_id
ts_tree_cursor_goto_parent
ts_tree_cursor_goto_next_sibling
ts_tree_cursor_goto_first_child
ts_tree_cursor_goto_first_child_for_byte
ts_tree_cursor_goto_first_child_for_point
ts_tree_cursor_copy
ts_query_new
ts_query_delete
ts_query_pattern_count
ts_query_capture_count
ts_query_string_count
ts_query_start_byte_for_pattern
ts_query_predicates_for_pattern
ts_query_step_is_definite
ts_query_capture_name_for_id
ts_query_string_value_for_id
ts_query_disable_capture
ts_query_disable_pattern
ts_query_cursor_new
ts_query_cursor_delete
ts_query_cursor_exec treesit-query-capture
ts_query_cursor_did_exceed_match_limit
ts_query_cursor_match_limit
ts_query_cursor_set_match_limit
ts_query_cursor_set_byte_range
ts_query_cursor_set_point_range
ts_query_cursor_next_match
ts_query_cursor_remove_match
ts_query_cursor_next_capture
ts_language_symbol_count
ts_language_symbol_name
ts_language_symbol_for_name
ts_language_field_count
ts_language_field_name_for_id
ts_language_field_id_for_name
ts_language_symbol_type
ts_language_version
</pre></div>
</div>
<hr>
<div class="header">
<p>
Previous: <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>
</div>
</body>
</html>

230
admin/notes/tree-sitter/html-manual/Using-Parser.html
View file

@ -1,230 +0,0 @@
<!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> &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>
</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'> &para;</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'> &para;</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 &amp;optional buffer no-reuse</em><a href='#index-treesit_002dparser_002dcreate' class='copiable-anchor'> &para;</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'> &para;</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'> &para;</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'> &para;</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&rsquo;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&rsquo;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>&amp;optional buffer</em><a href='#index-treesit_002dparser_002dlist' class='copiable-anchor'> &para;</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'> &para;</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 &ldquo;sees&rdquo; 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&rsquo;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'> &para;</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 &ldquo;changed&rdquo;
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>&nbsp;.&nbsp;<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'> &para;</a></span></dt>
<dd><p>This function adds <var>function</var> to <var>parser</var>&rsquo;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'> &para;</a></span></dt>
<dd><p>This function removes <var>function</var> from the list of <var>parser</var>&rsquo;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'> &para;</a></span></dt>
<dd><p>This function returns the list of <var>parser</var>&rsquo;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> &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>
</div>
</body>
</html>

23
admin/notes/tree-sitter/html-manual/build-manual.sh
View file

@ -1,23 +0,0 @@
#!/bin/bash
MANUAL_DIR="../../../../doc/lispref"
THIS_DIR=$(pwd)
echo "Build manual"
cd "${MANUAL_DIR}"
make elisp.html HTML_OPTS="--html --css-ref=./manual.css"
cd "${THIS_DIR}"
echo "Copy manual"
cp -f "${MANUAL_DIR}/elisp.html/Parsing-Program-Source.html" .
cp -f "${MANUAL_DIR}/elisp.html/Language-Definitions.html" .
cp -f "${MANUAL_DIR}/elisp.html/Using-Parser.html" .
cp -f "${MANUAL_DIR}/elisp.html/Retrieving-Node.html" .
cp -f "${MANUAL_DIR}/elisp.html/Accessing-Node.html" .
cp -f "${MANUAL_DIR}/elisp.html/Pattern-Matching.html" .
cp -f "${MANUAL_DIR}/elisp.html/Multiple-Languages.html" .
cp -f "${MANUAL_DIR}/elisp.html/Tree_002dsitter-C-API.html" .
cp -f "${MANUAL_DIR}/elisp.html/Parser_002dbased-Font-Lock.html" .
cp -f "${MANUAL_DIR}/elisp.html/Parser_002dbased-Indentation.html" .

374
admin/notes/tree-sitter/html-manual/manual.css
View file

@ -1,374 +0,0 @@
/* Style-sheet to use for Emacs manuals */
/* Copyright (C) 2013-2014, 2023 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. This file is offered as-is,
without any warranty.
*/
/* style.css begins here */
/* This stylesheet is used by manuals and a few older resources. */
/* reset.css begins here */
/*
Software License Agreement (BSD License)
Copyright (c) 2006, Yahoo! Inc.
All rights reserved.
Redistribution and use of this software in source and
binary forms, with or without modification, arepermitted
provided that the following conditions are met:
* Redistributions of source code must retain the above
copyright notice, this list of conditions and the
following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other
materials provided with the distribution.
* Neither the name of Yahoo! Inc. nor the names of its
contributors may be used to endorse or promote products
derived from this software without specific prior
written permission of Yahoo! Inc.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
*/
html {
color: #000;
background: #FFF;
}
body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4,
h5, h6, pre, code, form, fieldset, legend, input,
button, textarea, p, blockquote, th, td {
margin: 0;
padding: 0;
}
table {
border-collapse: collapse;
border-spacing: 0;
}
fieldset, img {
border: 0;
}
address, caption, cite, code, dfn, em, strong,
th, var, optgroup {
font-style: inherit;
font-weight: inherit;
}
del, ins {
text-decoration: none;
}
li {
list-style:none;
}
caption, th {
text-align: left;
}
h1, h2, h3, h4, h5, h6 {
font-size: 100%;
font-weight: normal;
}
q:before, q:after {
content:'';
}
abbr, acronym {
border: 0;
font-variant: normal;
}
sup {
vertical-align: baseline;
}
sub {
vertical-align: baseline;
}
legend {
color: #000;
}
input, button, textarea, select, optgroup, option {
font-family: inherit;
font-size: inherit;
font-style: inherit;
font-weight: inherit;
}
input, button, textarea, select {
*font-size: 100%;
}
/* reset.css ends here */
/*** PAGE LAYOUT ***/
html, body {
font-size: 1em;
text-align: left;
text-decoration: none;
}
html { background-color: #e7e7e7; }
body {
max-width: 74.92em;
margin: 0 auto;
padding: .5em 1em 1em 1em;
background-color: white;
border: .1em solid #c0c0c0;
}
/*** BASIC ELEMENTS ***/
/* Size and positioning */
p, pre, li, dt, dd, table, code, address { line-height: 1.3em; }
h1 { font-size: 2em; margin: 1em 0 }
h2 { font-size: 1.50em; margin: 1.0em 0 0.87em 0; }
h3 { font-size: 1.30em; margin: 1.0em 0 0.87em 0; }
h4 { font-size: 1.13em; margin: 1.0em 0 0.88em 0; }
h5 { font-size: 1.00em; margin: 1.0em 0 1.00em 0; }
p, pre { margin: 1em 0; }
pre { overflow: auto; padding-bottom: .3em; }
ul, ol, blockquote { margin-left: 1.5%; margin-right: 1.5%; }
hr { margin: 1em 0; }
/* Lists of underlined links are difficult to read. The top margin
gives a little more spacing between entries. */
ul li { margin: .5em 1em; }
ol li { margin: 1em; }
ol ul li { margin: .5em 1em; }
ul li p, ul ul li { margin-top: .3em; margin-bottom: .3em; }
ul ul, ol ul { margin-top: 0; margin-bottom: 0; }
/* Separate description lists from preceding text */
dl { margin: 1em 0 0 0; }
/* separate the "term" from subsequent "description" */
dt { margin: .5em 0; }
/* separate the "description" from subsequent list item
when the final <dd> child is an anonymous box */
dd { margin: .5em 3% 1em 3%; }
/* separate anonymous box (used to be the first element in <dd>)
from subsequent <p> */
dd p { margin: .5em 0; }
table {
display: block; overflow: auto;
margin-top: 1.5em; margin-bottom: 1.5em;
}
th { padding: .3em .5em; text-align: center; }
td { padding: .2em .5em; }
address { margin-bottom: 1em; }
caption { margin-bottom: .5em; text-align: center; }
sup { vertical-align: super; }
sub { vertical-align: sub; }
/* Style */
h1, h2, h3, h4, h5, h6, strong, dt, th { font-weight: bold; }
/* The default color (black) is too dark for large text in
bold font. */
h1, h2, h3, h4 { color: #333; }
h5, h6, dt { color: #222; }
a[href] { color: #005090; }
a[href]:visited { color: #100070; }
a[href]:active, a[href]:hover {
color: #100070;
text-decoration: none;
}
h1 a[href]:visited, h2 a[href]:visited, h3 a[href]:visited,
h4 a[href]:visited { color: #005090; }
h1 a[href]:hover, h2 a[href]:hover, h3 a[href]:hover,
h4 a[href]:hover { color: #100070; }
ol { list-style: decimal outside;}
ul { list-style: square outside; }
ul ul, ol ul { list-style: circle; }
li { list-style: inherit; }
hr { background-color: #ede6d5; }
table { border: 0; }
abbr,acronym {
border-bottom:1px dotted #000;
text-decoration: none;
cursor:help;
}
del { text-decoration: line-through; }
em { font-style: italic; }
small { font-size: .9em; }
img { max-width: 100%}
/*** SIMPLE CLASSES ***/
.center, .c { text-align: center; }
.nocenter{ text-align: left; }
.underline { text-decoration: underline; }
.nounderline { text-decoration: none; }
.no-bullet { list-style: none; }
.inline-list li { display: inline }
.netscape4, .no-display { display: none; }
/*** MANUAL PAGES ***/
/* This makes the very long tables of contents in Gnulib and other
manuals easier to read. */
.contents ul, .shortcontents ul { font-weight: bold; }
.contents ul ul, .shortcontents ul ul { font-weight: normal; }
.contents ul { list-style: none; }
/* For colored navigation bars (Emacs manual): make the bar extend
across the whole width of the page and give it a decent height. */
.header, .node { margin: 0 -1em; padding: 0 1em; }
.header p, .node p { line-height: 2em; }
/* For navigation links */
.node a, .header a { display: inline-block; line-height: 2em; }
.node a:hover, .header a:hover { background: #f2efe4; }
/* Inserts */
table.cartouche td { padding: 1.5em; }
div.display, div.lisp, div.smalldisplay,
div.smallexample, div.smalllisp { margin-left: 3%; }
div.example { padding: .8em 1.2em .4em; }
pre.example { padding: .8em 1.2em; }
div.example, pre.example {
margin: 1em 0 1em 3% ;
-webkit-border-radius: .3em;
-moz-border-radius: .3em;
border-radius: .3em;
border: 1px solid #d4cbb6;
background-color: #f2efe4;
}
div.example > pre.example {
padding: 0 0 .4em;
margin: 0;
border: none;
}
pre.menu-comment { padding-top: 1.3em; margin: 0; }
/*** FOR WIDE SCREENS ***/
@media (min-width: 40em) {
body { padding: .5em 3em 1em 3em; }
div.header, div.node { margin: 0 -3em; padding: 0 3em; }
}
/* style.css ends here */
/* makeinfo convert @deffn and similar functions to something inside
<blockquote>. style.css uses italic for blockquote. This looks poor
in the Emacs manuals, which make extensive use of @defun (etc).
In particular, references to function arguments appear as <var>
inside <blockquote>. Since <var> is also italic, it makes it
impossible to distinguish variables. We could change <var> to
e.g. bold-italic, or normal, or a different color, but that does
not look as good IMO. So we just override blockquote to be non-italic.
*/
blockquote { font-style: normal; }
var { font-style: italic; }
div.header {
background-color: #DDDDFF;
padding-top: 0.2em;
}
/*** Customization ***/
body {
font-family: Charter, serif;
font-size: 14pt;
line-height: 1.4;
background-color: #fefefc;
color: #202010;
}
pre.menu-comment {
font-family: Charter, serif;
font-size: 14pt;
}
body > *, body > div.display, body > div.lisp, body > div.smalldisplay,
body > div.example, body > div.smallexample, body > div.smalllisp {
width: 700px;
margin-left: auto;
margin-right: auto;
}
div.header {
width: 100%;
min-height: 3em;
font-size: 13pt;
}
/* Documentation block for functions and variables. Make then
narrower*/
dd {
margin: .5em 6% 1em 6%
}
code, pre, kbd, samp, tt {
font-size: 12pt;
font-family: monospace;
}
/* In each node we have index table to all sub-nodes. Make more space
for the first column, which is the name to each sub-node. */
table.menu tbody tr td:nth-child(1) {
white-space: nowrap;
}
div.header p {
text-align: center;
margin: 0.5em auto 0.5em auto;
}

157
admin/notes/tree-sitter/starter-guide
View file

@ -17,6 +17,7 @@ TOC:
- More features?
- Common tasks (code snippets)
- Manual
- Appendix 1
* Building Emacs with tree-sitter
@ -42,11 +43,9 @@ You can use this script that I put together here:
https://github.com/casouri/tree-sitter-module
You can also find them under this directory in /build-modules.
This script automatically pulls and builds language definitions for C,
C++, Rust, JSON, Go, HTML, JavaScript, CSS, Python, Typescript,
and C#. Better yet, I pre-built these language definitions for
C#, etc. Better yet, I pre-built these language definitions for
GNU/Linux and macOS, they can be downloaded here:
https://github.com/casouri/tree-sitter-module/releases/tag/v2.1
@ -68,6 +67,10 @@ organization has all the "official" language definitions:
https://github.com/tree-sitter
Alternatively, you can use treesit-install-language-grammar command
and follow its instructions. If everything goes right, it should
automatically download and compile the language grammar for you.
* Setting up for adding major mode features
Start Emacs and load tree-sitter with
@ -78,6 +81,10 @@ Now check if Emacs is built with tree-sitter library
(treesit-available-p)
Make sure Emacs can find the language grammar you want to use
(treesit-language-available-p 'lang)
* Tree-sitter major modes
Tree-sitter modes should be separate major modes, so other modes
@ -89,12 +96,15 @@ modes.
If the tree-sitter variant and the "native" variant could share some
setup, you can create a "base mode", which only contains the common
setup. For example, there is python-base-mode (shared), python-mode
(native), and python-ts-mode (tree-sitter).
setup. For example, python.el defines python-base-mode (shared),
python-mode (native), and python-ts-mode (tree-sitter).
In the tree-sitter mode, check if we can use tree-sitter with
treesit-ready-p, it will error out if tree-sitter is not ready.
In Emacs 30 we'll introduce some mechanism to more gracefully inherit
modes and fallback to other modes.
* Naming convention
Use tree-sitter for text (documentation, comment), use treesit for
@ -180,18 +190,17 @@ mark the offending part in red.
To enable tree-sitter font-lock, set ‘treesit-font-lock-settings’ and
‘treesit-font-lock-feature-list’ buffer-locally and call
‘treesit-major-mode-setup’. For example, see
‘python--treesit-settings’ in python.el. Below I paste a snippet of
it.
‘python--treesit-settings’ in python.el. Below is a snippet of it.
Note that like the current font-lock, if the to-be-fontified region
already has a face (ie, an earlier match fontified part/all of the
region), the new face is discarded rather than applied. If you want
later matches always override earlier matches, use the :override
keyword.
Just like the current font-lock, if the to-be-fontified region already
has a face (ie, an earlier match fontified part/all of the region),
the new face is discarded rather than applied. If you want later
matches always override earlier matches, use the :override keyword.
Each rule should have a :feature, like function-name,
string-interpolation, builtin, etc. Users can then enable/disable each
feature individually.
feature individually. See Appendix 1 at the bottom for a set of common
features names.
#+begin_src elisp
(defvar python--treesit-settings
@ -247,8 +256,7 @@ Concretely, something like this:
(string-interpolation decorator)))
(treesit-major-mode-setup))
(t
;; No tree-sitter
(setq-local font-lock-defaults ...)
;; No tree-sitter, do nothing or fallback to another mode.
...)))
#+end_src
@ -289,6 +297,7 @@ For ANCHOR we have
first-sibling => start of the first sibling
parent => start of parent
parent-bol => BOL of the line parent is on.
standalone-parent => Like parent-bol but handles more edge cases
prev-sibling => start of previous sibling
no-indent => current position (don’t indent)
prev-line => start of previous line
@ -329,7 +338,8 @@ tells you which rule is applied in the echo area.
...))))
#+end_src
Then you set ‘treesit-simple-indent-rules’ to your rules, and call
To setup indentation for your major mode, set
‘treesit-simple-indent-rules’ to your rules, and call
‘treesit-major-mode-setup’:
#+begin_src elisp
@ -339,36 +349,14 @@ Then you set ‘treesit-simple-indent-rules’ to your rules, and call
* Imenu
Not much to say except for utilizing ‘treesit-induce-sparse-tree’ (and
explicitly pass a LIMIT argument: most of the time you don't need more
than 10). See ‘js--treesit-imenu-1’ in js.el for an example.
Once you have the index builder, set ‘imenu-create-index-function’ to
it.
Set ‘treesit-simple-imenu-settings’ and call
‘treesit-major-mode-setup’.
* Navigation
Mainly ‘beginning-of-defun-function’ and ‘end-of-defun-function’.
You can find the end of a defun with something like
(treesit-search-forward-goto "function_definition" 'end)
where "function_definition" matches the node type of a function
definition node, and ’end means we want to go to the end of that node.
Tree-sitter has default implementations for
‘beginning-of-defun-function’ and ‘end-of-defun-function’. So for
ordinary languages, it is enough to set ‘treesit-defun-type-regexp’
to something that matches all the defun struct types in the language,
and call ‘treesit-major-mode-setup’. For example,
#+begin_src emacs-lisp
(setq-local treesit-defun-type-regexp (rx bol
(or "function" "class")
"_definition"
eol))
(treesit-major-mode-setup)
#+end_src>
Set ‘treesit-defun-type-regexp’ and call
‘treesit-major-mode-setup’. You can additionally set
‘treesit-defun-name-function’.
* Which-func
@ -376,36 +364,7 @@ If you have an imenu implementation, set ‘which-func-functions’ to
nil, and which-func will automatically use imenu’s data.
If you want an independent implementation for which-func, you can
find the current function by going up the tree and looking for the
function_definition node. See the function below for an example.
Since Python allows nested function definitions, that function keeps
going until it reaches the root node, and records all the function
names along the way.
#+begin_src elisp
(defun python-info-treesit-current-defun (&optional include-type)
"Identical to `python-info-current-defun' but use tree-sitter.
For INCLUDE-TYPE see `python-info-current-defun'."
(let ((node (treesit-node-at (point)))
(name-list ())
(type nil))
(cl-loop while node
if (pcase (treesit-node-type node)
("function_definition"
(setq type 'def))
("class_definition"
(setq type 'class))
(_ nil))
do (push (treesit-node-text
(treesit-node-child-by-field-name node "name")
t)
name-list)
do (setq node (treesit-node-parent node))
finally return (concat (if include-type
(format "%s " type)
"")
(string-join name-list ".")))))
#+end_src
find the current function by ‘treesit-defun-at-point’.
* More features?
@ -449,7 +408,51 @@ section is Parsing Program Source. Typing
C-h i d m elisp RET g Parsing Program Source RET
will bring you to that section. You can also read the HTML version
under /html-manual in this directory. I find the HTML version easier
to read. You don’t need to read through every sentence, just read the
text paragraphs and glance over function names.
will bring you to that section. You don’t need to read through every
sentence, just read the text paragraphs and glance over function
names.
* Appendix 1
Below is a set of common features used by built-in major mode.
Basic tokens:
delimiter ,.; (delimit things)
operator == != || (produces a value)
bracket []{}()
misc-punctuation (other punctuation that you want to highlight)
constant true, false, null
number
keyword
comment (includes doc-comments)
string (includes chars and docstrings)
string-interpolation f"text {variable}"
escape-sequence "\n\t\\"
function every function identifier
variable every variable identifier
type every type identifier
property a.b <--- highlight b
key { a: b, c: d } <--- highlight a, c
error highlight parse error
Abstract features:
assignment: the LHS of an assignment (thing being assigned to), eg:
a = b <--- highlight a
a.b = c <--- highlight b
a[1] = d <--- highlight a
definition: the thing being defined, eg:
int a(int b) { <--- highlight a
return 0
}
int a; <-- highlight a
struct a { <--- highlight a
int b; <--- highlight b
}

6
doc/lispref/keymaps.texi
View file

@ -1445,10 +1445,10 @@ does matter for menu keymaps (@pxref{Menu Keymaps}).
This function is the inverse of @code{keymap-set}, it unsets the
binding for @var{key} in @var{keymap}, which is the same as setting
the binding to @code{nil}. In order to instead remove the binding
completely, specify @var{remove} as non-nil. This only makes a
difference if @var{keymap} has a parent keymap. When unsetting a key
completely, specify @var{remove} as non-@code{nil}. This only makes a
difference if @var{keymap} has a parent keymap: if you just unset a key
in a child map, it will still shadow the same key in the parent
keymap. Removing the binding will allow the key in the parent keymap
keymap; using @var{remove} instead will allow the key in the parent keymap
to be used.
@end defun

5
doc/lispref/symbols.texi
View file

@ -276,9 +276,8 @@ This function returns the string that is @var{symbol}'s name. For example:
@end group
@end example
@strong{Warning:} Changing the string by substituting characters does
change the name of the symbol, but fails to update the obarray, so don't
do it!
@strong{Warning:} Never alter the string returned by that function.
Doing that might make Emacs dysfunctional, and might even crash Emacs.
@end defun
@cindex uninterned symbol, and generating Lisp code

124
doc/misc/eglot.texi
View file

@ -154,11 +154,11 @@ Use Eglot.
Most Eglot facilities are integrated into Emacs features, such as
ElDoc, Flymake, Xref, and Imenu. However, Eglot also provides
commands of its own, mainly to perform tasks by the LSP server, such
as @kbd{M-x eglot-rename} (to rename an identifier across the entire
project), @kbd{M-x eglot-format} (to reformat and reindent code), and
some others. @xref{Eglot Commands}, for the detailed list of Eglot
commands.
commands of its own, mainly to perform tasks by the language server,
such as @kbd{M-x eglot-rename} (to rename an identifier across the
entire project), @kbd{M-x eglot-format} (to reformat and reindent
code), and some others. @xref{Eglot Commands}, for the detailed list
of Eglot commands.
@item
That's it!
@ -465,52 +465,10 @@ ElDoc look nicer on display.
@item
In addition to enabling and enhancing other features and packages,
Eglot also provides a small number of user commands based directly on
the capabilities of language servers. These commands are:
@table @kbd
@item M-x eglot-rename
This prompts for a new name for the symbol at point, and then modifies
all the project source files to rename the symbol to the new name,
based on editing data received from the language-server. @xref{Eglot
and Buffers}, for the details of how project files are defined.
@item M-x eglot-format
This reformats and prettifies the current active region according to
source formatting rules of the language-server. If the region is not
active, it reformats the entire buffer instead.
@item M-x eglot-format-buffer
This reformats and prettifies the current buffer according to source
formatting rules of the language-server.
@cindex code actions
@item M-x eglot-code-actions
@itemx M-x eglot-code-action-organize-imports
@itemx M-x eglot-code-action-quickfix
@itemx M-x eglot-code-action-extract
@itemx M-x eglot-code-action-inline
@itemx M-x eglot-code-action-rewrite
These command allow you to invoke the so-called @dfn{code actions}:
requests for the language-server to provide editing commands for
various code fixes, typically either to fix an error diagnostic or to
beautify/refactor code. For example,
@code{eglot-code-action-organize-imports} rearranges the program
@dfn{imports}---declarations of modules whose capabilities the program
uses. These commands affect all the files that belong to the
project. The command @kbd{M-x eglot-code-actions} will pop up a menu
of code applicable actions at point.
@end table
@item M-x eglot-inlay-hints-mode
This command toggles LSP ``inlay hints'' on and off for the current
buffer. Inlay hints are small text annotations to specific parts of
the whole buffer, not unlike diagnostics, but designed to help
readability instead of indicating problems. For example, a C++ LSP
server can serve hints about positional parameter names in function
calls and a variable's automatically deduced type. Inlay hints help
the user not have to remember these things by heart.
Eglot also provides a number of user commands based on the
capabilities of language servers. Examples include renaming symbols
with @kbd{eglot-rename} and asking to automatically correct problems
with @kbd{eglot-code-actions}. @xref{Eglot Commands}.
@end itemize
Not all servers support the full set of LSP capabilities, but most of
@ -713,20 +671,44 @@ entire current buffer.
This command reformats the current buffer, in the same manner as
@code{eglot-format} does.
@cindex code actions
@item M-x eglot-code-actions
@itemx mouse-1
This command asks the server for any @dfn{code actions} applicable at
point. It can also be invoked by @kbd{mouse-1} clicking on
diagnostics provided by the server.
@item M-x eglot-code-action-organize-imports
@itemx M-x eglot-code-action-organize-imports
@itemx M-x eglot-code-action-quickfix
@itemx M-x eglot-code-action-extract
@itemx M-x eglot-code-action-inline
@itemx M-x eglot-code-action-rewrite
These commands invoke specific code actions supported by the language
server.
@c FIXME: Need more detailed description of each action.
These commands allow you to invoke the so-called @dfn{code actions}:
requests for the language server to provide editing commands for
correcting, refactoring or beautifying your code. These commands may
affect more than one visited file belong to the project.
The command @code{eglot-code-actions} asks the server if there any
code actions for any point in the buffer or contained in the active
region. If there are, you the choice to execute one of them via the
minibuffer.
A common use of code actions is fixing the Flymake error diagnostics
issued by Eglot (@pxref{Top,,, flymake, GNU Flymake manual}).
Clicking on a diagnostic with @kbd{mouse-2} invokes
@code{eglot-code-actions-at-mouse} which pops up a menu of available
code actions. The variable @code{eglot-diagnostics-map} can be used
to control the mouse binding.
Other commands execute a specific code action. For example,
@code{eglot-code-action-organize-imports} rearranges the program's
@dfn{imports}---declarations of modules whose capabilities the program
uses.
@cindex inlay hints
@item M-x eglot-inlay-hints-mode
This command toggles LSP @dfn{inlay hints} on and off for the current
buffer. Inlay hints are small text annotations to specific parts of
the whole buffer, not unlike diagnostics, but designed to help
readability instead of indicating problems. For example, a C++
language server can serve hints about positional parameter names in
function calls and a variable's automatically deduced type. Inlay
hints help the user not have to remember these things by heart.
@end ftable
The following Eglot commands are used less commonly, mostly for
@ -968,7 +950,7 @@ mechanism.
@cindex progress
@item eglot-report-progress
Set this variable to true if you'd like progress notifications coming
from the LSP server to be handled as Emacs's progress reporting
from the language server to be handled as Emacs's progress reporting
facilities.
@end table
@ -1079,10 +1061,11 @@ plists. Some examples are useful.
Let's say you want to configure two language servers to be used in a
project written in a combination of the Python and Go languages. You
want to use the @command{pylsp} and @command{gopls} LSP servers. In
the documentation of the servers in question (or in some other editor's
configuration file, or in some blog article), you find the following
configuration options in informal dotted-notation syntax:
want to use the @command{pylsp} and @command{gopls} languages
servers. In the documentation of the servers in question (or in some
other editor's configuration file, or in some blog article), you find
the following configuration options in informal dotted-notation
syntax:
@example
pylsp.plugins.jedi_completion.include_params: true
@ -1300,13 +1283,14 @@ slowly, try to customize the variable @code{eglot-events-buffer-size}
(@pxref{Eglot Variables}) to 0. This will disable any debug logging
and may speed things up.
In other situations, the cause of poor performance lies in the LSP
server itself. Servers use aggressive caching and other techniques to
improve their performance. Often, this can be tweaked by changing the
server configuration (@pxref{Advanced server configuration}).
In other situations, the cause of poor performance lies in the
language server itself. Servers use aggressive caching and other
techniques to improve their performance. Often, this can be tweaked
by changing the server configuration (@pxref{Advanced server
configuration}).
If you think you have found a bug, we want to hear about it. Before
reporting a bug, keep in mind that interaction with LSP servers
reporting a bug, keep in mind that interaction with language servers
represents a large quantity of unknown variables. Therefore, it is
generally both @emph{difficult} and @emph{absolutely essential} that
the maintainers reproduce bugs exactly as they happened to you, the

6
etc/ORG-NEWS
View file

@ -332,7 +332,7 @@ When the block type starts from the upper case, structure template
will now insert =#+BEGIN_TYPE=. Previously, lower-case =#+begin_type= was inserted unconditionally.
*** New ox-latex tabbing support for tables.
Latex tables can now be exported to the latex tabbing environment
LaTeX tables can now be exported to the latex tabbing environment
tabbing environment]].
This is done by adding =#+ATTR_LATEX: :mode tabbing= at the top
of the table.
@ -4284,7 +4284,7 @@ parameters specific to some pre-defined translators, e.g.,
~:environment~ and ~:booktabs~ for ~orgtbl-to-latex~. See translators
docstrings (including ~orgtbl-to-generic~) for details.
*** Non-floating minted listings in Latex export
*** Non-floating minted listings in LaTeX export
It is not possible to specify =#+attr_latex: :float nil= in conjunction
with source blocks exported by the minted package.
@ -6540,7 +6540,7 @@ that Calc formulas can operate on them.
*** Hyperlinks
**** Org-Bibtex -- major improvements
**** Org-BibTeX -- major improvements
Provides support for managing bibtex bibliographical references
data in headline properties. Each headline corresponds to a

2
lisp/mpc.el
View file

@ -1104,7 +1104,7 @@ If PLAYLIST is t or nil or missing, use the main playlist."
(interactive)
(mpc-constraints-push 'noerror)
(mpc-constraints-restore
',(list (list tag text)))))))))
(list (list tag text)))))))))
(funcall insert
(concat (when size
(propertize " " 'display

2
lisp/net/tramp.el
View file

@ -685,7 +685,7 @@ See also `tramp-yn-prompt-regexp'."
:type 'regexp)
(defcustom tramp-yn-prompt-regexp
(rx (| "Store key in cache? (y/n)"
(rx (| (: "Store key in cache? (y/n" (* nonl) ")")
"Update cached key? (y/n, Return cancels connection)")
(* blank))
"Regular expression matching all y/n queries which need to be confirmed.

9
lisp/nxml/xmltok.el
View file

@ -734,8 +734,13 @@ and VALUE-END, otherwise a STRING giving the value."
(atts-needing-normalization nil))
(while (cond ((or (looking-at (xmltok-attribute regexp))
;; use non-greedy group
(when (looking-at (concat "[^<>\n]+?"
(xmltok-attribute regexp)))
;; Limit the search to 10000 characters, to
;; avoid slowdowns due to the quadratic
;; complexity of the regexp. See bug#61514.
(when (with-restriction
(point) (min (+ (point) 10000) (point-max))
(looking-at (concat "[^<>\n]+?"
(xmltok-attribute regexp))))
(unless recovering
(xmltok-add-error "Malformed attribute"
(point)

17
lisp/org/ob-latex.el
View file

@ -141,7 +141,7 @@ exporting the literal LaTeX source."
(org-trim body))
(defun org-babel-execute:latex (body params)
"Execute a block of Latex code with Babel.
"Execute a block of LaTeX code with Babel.
This function is called by `org-babel-execute-src-block'."
(setq body (org-babel-expand-body:latex body params))
(if (cdr (assq :file params))
@ -180,7 +180,7 @@ This function is called by `org-babel-execute-src-block'."
tmp-pdf
(list org-babel-latex-pdf-svg-process)
extension err-msg log-buf)))
(shell-command (format "mv %s %s" img-out out-file)))))
(rename-file img-out out-file t))))
((string-suffix-p ".tikz" out-file)
(when (file-exists-p out-file) (delete-file out-file))
(with-temp-file out-file
@ -218,17 +218,14 @@ This function is called by `org-babel-execute-src-block'."
(if (string-suffix-p ".svg" out-file)
(progn
(shell-command "pwd")
(shell-command (format "mv %s %s"
(concat (file-name-sans-extension tex-file) "-1.svg")
out-file)))
(rename-file (concat (file-name-sans-extension tex-file) "-1.svg")
out-file t))
(error "SVG file produced but HTML file requested")))
((file-exists-p (concat (file-name-sans-extension tex-file) ".html"))
(if (string-suffix-p ".html" out-file)
(shell-command "mv %s %s"
(concat (file-name-sans-extension tex-file)
".html")
out-file)
(error "HTML file produced but SVG file requested")))))
(rename-file (concat (file-name-sans-extension tex-file) ".html")
out-file t)
(error "HTML file produced but SVG file requested")))))
((or (string= "pdf" extension) imagemagick)
(with-temp-file tex-file
(require 'ox-latex)

22
lisp/org/ol-bibtex.el
View file

@ -86,8 +86,8 @@
;; the active region, then call `org-bibtex-write' in a .org file to
;; insert a heading for the read bibtex entry
;;
;; - All Bibtex information is taken from the document compiled by
;; Andrew Roberts from the Bibtex manual, available at
;; - All BibTeX information is taken from the document compiled by
;; Andrew Roberts from the BibTeX manual, available at
;; https://www.andy-roberts.net/res/writing/latex/bibentries.pdf
;;
;;; History:
@ -99,7 +99,7 @@
;; and then implemented by Bastien Guerry.
;;
;; Eric Schulte eventually added the functions for translating between
;; Org headlines and Bibtex entries, and for fleshing out the Bibtex
;; Org headlines and BibTeX entries, and for fleshing out the BibTeX
;; fields of existing Org headlines.
;;
;; Org mode loads this module by default - if this is not what you want,
@ -144,7 +144,7 @@
(declare-function org-search-view "org-agenda" (&optional todo-only string edit-at))
;;; Bibtex data
;;; BibTeX data
(defvar org-bibtex-types
'((:article
(:description . "An article from a journal or magazine")
@ -202,7 +202,7 @@
(:description . "A document having an author and title, but not formally published.")
(:required :author :title :note)
(:optional :month :year :doi :url)))
"Bibtex entry types with required and optional parameters.")
"BibTeX entry types with required and optional parameters.")
(defvar org-bibtex-fields
'((:address . "Usually the address of the publisher or other type of institution. For major publishing houses, van Leunen recommends omitting the information entirely. For small publishers, on the other hand, you can help the reader by giving the complete address.")
@ -231,7 +231,7 @@
(:url . "Uniform resource locator.")
(:volume . "The volume of a journal or multi-volume book.")
(:year . "The year of publication or, for an unpublished work, the year it was written. Generally it should consist of four numerals, such as 1984, although the standard styles can handle any year whose last four nonpunctuation characters are numerals, such as '(about 1984)'"))
"Bibtex fields with descriptions.")
"BibTeX fields with descriptions.")
(defvar org-bibtex-entries nil
"List to hold parsed bibtex entries.")
@ -439,7 +439,7 @@ at point."
(error "Field:%s is not known" field))
(save-window-excursion
(let* ((name (substring (symbol-name field) 1))
(buf-name (format "*Bibtex Help %s*" name)))
(buf-name (format "*BibTeX Help %s*" name)))
(with-output-to-temp-buffer buf-name
(princ (cdr (assoc field org-bibtex-fields))))
(with-current-buffer buf-name (visual-line-mode 1))
@ -496,7 +496,7 @@ With optional argument OPTIONAL, also prompt for optional fields."
(org-bibtex-autokey)))
;;; Bibtex link functions
;;; BibTeX link functions
(org-link-set-parameters "bibtex"
:follow #'org-bibtex-open
:store #'org-bibtex-store-link)
@ -593,13 +593,13 @@ ARG, when non-nil, is a universal prefix argument. See
(add-hook 'org-execute-file-search-functions 'org-execute-file-search-in-bibtex)
;;; Bibtex <-> Org headline translation functions
;;; BibTeX <-> Org headline translation functions
(defun org-bibtex (filename)
"Export each headline in the current file to a bibtex entry.
Headlines are exported using `org-bibtex-headline'."
(interactive
(list (read-file-name
"Bibtex file: " nil nil nil
"BibTeX file: " nil nil nil
(let ((file (buffer-file-name (buffer-base-buffer))))
(and file
(file-name-nondirectory
@ -619,7 +619,7 @@ Headlines are exported using `org-bibtex-headline'."
nil))))
(when error-point
(goto-char error-point)
(message "Bibtex error at %S" (nth 4 (org-heading-components))))))
(message "BibTeX error at %S" (nth 4 (org-heading-components))))))
(defun org-bibtex-check (&optional optional)
"Check the current headline for required fields.

2
lisp/org/org-agenda.el
View file

@ -3348,7 +3348,7 @@ s Search for keywords M Like m, but only TODO entries
(`agenda
(call-interactively 'org-agenda-list))
(`agenda*
(funcall 'org-agenda-list nil nil t))
(funcall 'org-agenda-list nil nil nil t))
(`alltodo
(call-interactively 'org-todo-list))
(`search

4
lisp/org/org-element.el
View file

@ -2462,7 +2462,7 @@ CDR is a plist containing `:key', `:value', `:begin', `:end',
(org-element-property :value keyword)))
;;;; Latex Environment
;;;; LaTeX Environment
(defconst org-element--latex-begin-environment
"^[ \t]*\\\\begin{\\([A-Za-z0-9*]+\\)}"
@ -3412,7 +3412,7 @@ CONTENTS is the contents of the object."
(format "/%s/" contents))
;;;; Latex Fragment
;;;; LaTeX Fragment
(defun org-element-latex-fragment-parser ()
"Parse LaTeX fragment at point, if any.

8
lisp/org/org-persist.el
View file

@ -540,13 +540,13 @@ COLLECTION is the plist holding data collection."
(defun org-persist-read:file (_ path __)
"Read file container from PATH."
(when (and path (file-exists-p (concat org-persist-directory path)))
(concat org-persist-directory path)))
(when (and path (file-exists-p (org-file-name-concat org-persist-directory path)))
(org-file-name-concat org-persist-directory path)))
(defun org-persist-read:url (_ path __)
"Read file container from PATH."
(when (and path (file-exists-p (concat org-persist-directory path)))
(concat org-persist-directory path)))
(when (and path (file-exists-p (org-file-name-concat org-persist-directory path)))
(org-file-name-concat org-persist-directory path)))
(defun org-persist-read:index (cont index-file _)
"Read index container CONT from INDEX-FILE."

2
lisp/org/org-src.el
View file

@ -315,7 +315,7 @@ is 0.")
(defun org-src--construct-edit-buffer-name (org-buffer-name lang)
"Construct the buffer name for a source editing buffer.
Format is \"*Org Src ORG-BUFFER-NAME [ LANG ]*\"."
Format is \"*Org Src ORG-BUFFER-NAME[ LANG ]*\"."
(concat "*Org Src " org-buffer-name "[ " lang " ]*"))
(defun org-src--edit-buffer (beg end)

2
lisp/org/org-version.el
View file

@ -11,7 +11,7 @@ Inserted by installing Org mode or when a release is made."
(defun org-git-version ()
"The Git version of Org mode.
Inserted by installing Org or when a release is made."
(let ((org-git-version "release_9.6.1-40-g3d817c"))
(let ((org-git-version "release_9.6.1-48-g92471e"))
org-git-version))
(provide 'org-version)

4
lisp/org/ox-ascii.el
View file

@ -1549,7 +1549,7 @@ information."
keyword info)))))
;;;; Latex Environment
;;;; LaTeX Environment
(defun org-ascii-latex-environment (latex-environment _contents info)
"Transcode a LATEX-ENVIRONMENT element from Org to ASCII.
@ -1561,7 +1561,7 @@ information."
latex-environment info)))
;;;; Latex Fragment
;;;; LaTeX Fragment
(defun org-ascii-latex-fragment (latex-fragment _contents info)
"Transcode a LATEX-FRAGMENT object from Org to ASCII.

4
lisp/org/ox-html.el
View file

@ -2969,7 +2969,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
((string= "listings" value) (org-html-list-of-listings info))
((string= "tables" value) (org-html-list-of-tables info))))))))
;;;; Latex Environment
;;;; LaTeX Environment
(defun org-html-format-latex (latex-frag processing-type info)
"Format a LaTeX fragment LATEX-FRAG into HTML.
@ -3086,7 +3086,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
info caption label)))))
(t (org-html--wrap-latex-environment latex-frag info caption label)))))
;;;; Latex Fragment
;;;; LaTeX Fragment
(defun org-html-latex-fragment (latex-fragment _contents info)
"Transcode a LATEX-FRAGMENT object from Org to HTML.

6
lisp/org/ox-latex.el
View file

@ -1272,7 +1272,7 @@ used. When nil, no theme is applied."
(defun org-latex-generate-engraved-preamble (info)
"Generate the preamble to setup engraved code.
The result is constructed from the :latex-engraved-preamble and
:latex-engraved-optionsn export options, the default values of
:latex-engraved-options export options, the default values of
which are given by `org-latex-engraved-preamble' and
`org-latex-engraved-options' respectively."
(let* ((engraved-options
@ -2600,7 +2600,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
(otherwise "\\lstlistoflistings")))))))))
;;;; Latex Environment
;;;; LaTeX Environment
(defun org-latex--environment-type (latex-environment)
"Return the TYPE of LATEX-ENVIRONMENT.
@ -2658,7 +2658,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
(insert caption)
(buffer-string))))))
;;;; Latex Fragment
;;;; LaTeX Fragment
(defun org-latex-latex-fragment (latex-fragment _contents _info)
"Transcode a LATEX-FRAGMENT object from Org to LaTeX.

4
lisp/org/ox-md.el
View file

@ -486,7 +486,7 @@ channel."
(_ (org-export-with-backend 'html keyword contents info))))
;;;; Latex Environment
;;;; LaTeX Environment
(defun org-md-latex-environment (latex-environment _contents info)
"Transcode a LATEX-ENVIRONMENT object from Org to Markdown.
@ -501,7 +501,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
latex-frag)
latex-frag))))
;;;; Latex Fragment
;;;; LaTeX Fragment
(defun org-md-latex-fragment (latex-fragment _contents info)
"Transcode a LATEX-FRAGMENT object from Org to Markdown.

4
lisp/org/ox-odt.el
View file

@ -1986,7 +1986,7 @@ information."
(ignore))))))))
;;;; Latex Environment
;;;; LaTeX Environment
;; (eval-after-load 'ox-odt '(ad-deactivate 'org-format-latex-as-mathml))
;; (advice-add 'org-format-latex-as-mathml ; FIXME
@ -2007,7 +2007,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
(org-odt-do-format-code latex-frag info)))
;;;; Latex Fragment
;;;; LaTeX Fragment
;; (when latex-frag ; FIXME
;; (setq href (propertize href :title "LaTeX Fragment"

13
lisp/progmodes/c-ts-mode.el
View file

@ -1100,10 +1100,15 @@ the code is C or C++ and based on that chooses whether to enable
'("\\(\\.ii\\|\\.\\(CC?\\|HH?\\)\\|\\.[ch]\\(pp\\|xx\\|\\+\\+\\)\\|\\.\\(cc\\|hh\\)\\)\\'"
. c++-ts-mode)))
(if (treesit-ready-p 'c)
(add-to-list 'auto-mode-alist
'("\\(\\.[chi]\\|\\.lex\\|\\.y\\(acc\\)?\\|\\.x[bp]m\\)\\'"
. c-ts-mode)))
(when (treesit-ready-p 'c)
(add-to-list 'auto-mode-alist
'("\\(\\.[chi]\\|\\.lex\\|\\.y\\(acc\\)?\\)\\'" . c-ts-mode))
(add-to-list 'auto-mode-alist '("\\.x[pb]m\\'" . c-ts-mode))
;; image-mode's association must be before the C mode, otherwise XPM
;; images will be initially visited as C files. Also note that the
;; regexp must be different from what files.el does, or else
;; add-to-list will not add the association where we want it.
(add-to-list 'auto-mode-alist '("\\.x[pb]m\\'" . image-mode)))
(if (and (treesit-ready-p 'cpp)
(treesit-ready-p 'c))

95
lisp/progmodes/eglot.el
View file

@ -1259,7 +1259,7 @@ This docstring appeases checkdoc, that's all."
;; very much data so we turn it off
;; unconditionally -- just for our
;; process.
(tramp-use-ssh-controlmaster-options t)
(tramp-use-ssh-controlmaster-options 'suppress)
(tramp-ssh-controlmaster-options
"-o ControlMaster=no -o ControlPath=none"))
(make-process
@ -1944,8 +1944,8 @@ If it is activated, also signal textDocument/didOpen."
(put 'eglot--mode-line-format 'risky-local-variable t)
(defun eglot--mouse-call (what)
"Make an interactive lambda for calling WHAT from mode-line."
(defun eglot--mouse-call (what &optional update-mode-line)
"Make an interactive lambda for calling WHAT with the mouse."
(lambda (event)
(interactive "e")
(let ((start (event-start event))) (with-selected-window (posn-window start)
@ -1953,7 +1953,8 @@ If it is activated, also signal textDocument/didOpen."
(goto-char (or (posn-point start)
(point)))
(call-interactively what)
(force-mode-line-update t))))))
(when update-mode-line
(force-mode-line-update t)))))))
(defun eglot-manual () "Open documentation."
(declare (obsolete info "29.1"))
@ -2027,7 +2028,7 @@ Uses THING, FACE, DEFS and PREPEND."
(cl-loop with map = (make-sparse-keymap)
for (elem . rest) on defs
for (key def help) = elem
do (define-key map `[mode-line ,key] (eglot--mouse-call def))
do (define-key map `[mode-line ,key] (eglot--mouse-call def t))
concat (format "%s: %s" key help) into blurb
when rest concat "\n" into blurb
finally (return `(:propertize ,thing
@ -2088,15 +2089,18 @@ still unanswered LSP requests to the server\n"))))))))
(defalias 'eglot--make-diag 'flymake-make-diagnostic)
(defalias 'eglot--diag-data 'flymake-diagnostic-data)
(defvar eglot-diagnostics-map
(let ((map (make-sparse-keymap)))
(define-key map [mouse-2] 'eglot-code-actions-at-mouse)
map)
"Keymap active in Eglot-backed Flymake diagnostic overlays.")
(cl-loop for i from 1
for type in '(eglot-note eglot-warning eglot-error)
do (put type 'flymake-overlay-control
`((mouse-face . highlight)
(priority . ,(+ 50 i))
(keymap . ,(let ((map (make-sparse-keymap)))
(define-key map [mouse-1]
(eglot--mouse-call 'eglot-code-actions))
map)))))
(keymap . ,eglot-diagnostics-map))))
;;; Protocol implementation (Requests, notifications, etc)
@ -2357,7 +2361,6 @@ THINGS are either registrations or unregisterations (sic)."
(defun eglot--before-change (beg end)
"Hook onto `before-change-functions' with BEG and END."
(remove-overlays beg end 'eglot--overlay t)
(when (listp eglot--recent-changes)
;; Records BEG and END, crucially convert them into LSP
;; (line/char) positions before that information is lost (because
@ -2377,25 +2380,23 @@ THINGS are either registrations or unregisterations (sic)."
"Hook onto `after-change-functions'.
Records BEG, END and PRE-CHANGE-LENGTH locally."
(cl-incf eglot--versioned-identifier)
(pcase (and (listp eglot--recent-changes)
(car eglot--recent-changes))
(pcase (car-safe eglot--recent-changes)
(`(,lsp-beg ,lsp-end
(,b-beg . ,b-beg-marker)
(,b-end . ,b-end-marker))
;; github#259 and github#367: With `capitalize-word' or somesuch,
;; `before-change-functions' always records the whole word's
;; `b-beg' and `b-end'. Similarly, when coalescing two lines
;; into one, `fill-paragraph' they mark the end of the first line
;; up to the end of the second line. In both situations, args
;; received here contradict that information: `beg' and `end'
;; will differ by 1 and will likely only encompass the letter
;; that was capitalized or, in the sentence-joining situation,
;; the replacement of the newline with a space. That's we keep
;; markers _and_ positions so we're able to detect and correct
;; this. We ignore `beg', `len' and `pre-change-len' and send
;; "fuller" information about the region from the markers. I've
;; also experimented with doing this unconditionally but it seems
;; to break when newlines are added.
;; github#259 and github#367: with `capitalize-word' & friends,
;; `before-change-functions' records the whole word's `b-beg' and
;; `b-end'. Similarly, when `fill-paragraph' coalesces two
;; lines, `b-beg' and `b-end' mark end of first line and end of
;; second line, resp. In both situations, `beg' and `end'
;; received here seemingly contradict that: they will differ by 1
;; and encompass the capitalized character or, in the coalescing
;; case, the replacement of the newline with a space. We keep
;; both markers and positions to detect and correct this. In
;; this specific case, we ignore `beg', `len' and
;; `pre-change-len' and send richer information about the region
;; from the markers. I've also experimented with doing this
;; unconditionally but it seems to break when newlines are added.
(if (and (= b-end b-end-marker) (= b-beg b-beg-marker)
(or (/= beg b-beg) (/= end b-end)))
(setcar eglot--recent-changes
@ -3223,8 +3224,9 @@ Returns a list as described in docstring of `imenu--index-alist'."
,(eglot--TextDocumentIdentifier))
:cancel-on-input non-essential))))))
(defun eglot--apply-text-edits (edits &optional version)
(cl-defun eglot--apply-text-edits (edits &optional version)
"Apply EDITS for current buffer if at VERSION, or if it's nil."
(unless edits (cl-return-from eglot--apply-text-edits))
(unless (or (not version) (equal version eglot--versioned-identifier))
(jsonrpc-error "Edits on `%s' require version %d, you have %d"
(current-buffer) version eglot--versioned-identifier))
@ -3342,6 +3344,9 @@ at point. With prefix argument, prompt for ACTION-KIND."
(eglot--read-execute-code-action actions server action-kind)
actions)))
(defalias 'eglot-code-actions-at-mouse (eglot--mouse-call 'eglot-code-actions)
"Like `eglot-code-actions', but intended for mouse events.")
(defun eglot--read-execute-code-action (actions server &optional action-kind)
"Helper for interactive calls to `eglot-code-actions'."
(let* ((menu-items
@ -3610,31 +3615,41 @@ If NOERROR, return predicate, else erroring function."
(eglot--lambda ((InlayHint) position kind label paddingLeft paddingRight)
(goto-char (eglot--lsp-position-to-point position))
(when (or (> (point) to) (< (point) from)) (cl-return))
(let ((left-pad (and paddingLeft
(not (eq paddingLeft :json-false))
(not (memq (char-before) '(32 9))) " "))
(right-pad (and paddingRight
(not (eq paddingRight :json-false))
(not (memq (char-after) '(32 9))) " ")))
(cl-flet
((do-it (text lpad rpad)
(let ((ov (make-overlay (point) (point))))
(overlay-put ov 'before-string
(let* ((left-pad (and paddingLeft
(not (eq paddingLeft :json-false))
(not (memq (char-before) '(32 9))) " "))
(right-pad (and paddingRight
(not (eq paddingRight :json-false))
(not (memq (char-after) '(32 9))) " "))
(peg-after-p (eql kind 1)))
(cl-labels
((make-ov ()
(if peg-after-p
(make-overlay (point) (1+ (point)) nil t)
(make-overlay (1- (point)) (point) nil nil nil)))
(do-it (label lpad rpad firstp)
(let* ((tweak-cursor-p (and firstp peg-after-p))
(ov (make-ov))
(text (concat lpad label rpad)))
(when tweak-cursor-p (put-text-property 0 1 'cursor 1 text))
(overlay-put ov (if peg-after-p 'before-string 'after-string)
(propertize
(concat lpad text rpad)
text
'face (pcase kind
(1 'eglot-type-hint-face)
(2 'eglot-parameter-hint-face)
(_ 'eglot-inlay-hint-face))))
(overlay-put ov 'eglot--inlay-hint t)
(overlay-put ov 'evaporate t)
(overlay-put ov 'eglot--overlay t))))
(if (stringp label) (do-it label left-pad right-pad)
(if (stringp label) (do-it label left-pad right-pad t)
(cl-loop
for i from 0 for ldetail across label
do (eglot--dbind ((InlayHintLabelPart) value) ldetail
(do-it value
(and (zerop i) left-pad)
(and (= i (1- (length label))) right-pad))))))))))
(and (= i (1- (length label))) right-pad)
(zerop i))))))))))
(jsonrpc-async-request
(eglot--current-server-or-lose)
:textDocument/inlayHint

5
src/data.c
View file

@ -773,7 +773,10 @@ DEFUN ("symbol-plist", Fsymbol_plist, Ssymbol_plist, 1, 1, 0,
}
DEFUN ("symbol-name", Fsymbol_name, Ssymbol_name, 1, 1, 0,
doc: /* Return SYMBOL's name, a string. */)
doc: /* Return SYMBOL's name, a string.
Warning: never alter the string returned by `symbol-name'.
Doing that might make Emacs dysfunctional, and might even crash Emacs. */)
(register Lisp_Object symbol)
{
register Lisp_Object name;

17
src/keyboard.c
View file

@ -105,6 +105,13 @@ static bool single_kboard;
/* Minimum allowed size of the recent_keys vector. */
#define MIN_NUM_RECENT_KEYS (100)
/* Maximum allowed size of the recent_keys vector. */
#if INTPTR_MAX <= INT_MAX
# define MAX_NUM_RECENT_KEYS (INT_MAX / EMACS_INT_WIDTH / 10)
#else
# define MAX_NUM_RECENT_KEYS (INT_MAX / EMACS_INT_WIDTH)
#endif
/* Index for storing next element into recent_keys. */
static int recent_keys_index;
@ -10984,10 +10991,10 @@ The saved keystrokes are shown by `view-lossage'. */)
if (!FIXNATP (arg))
user_error ("Value must be a positive integer");
int osize = ASIZE (recent_keys);
ptrdiff_t osize = ASIZE (recent_keys);
eassert (lossage_limit == osize);
int min_size = MIN_NUM_RECENT_KEYS;
int new_size = XFIXNAT (arg);
EMACS_INT new_size = XFIXNAT (arg);
if (new_size == osize)
return make_fixnum (lossage_limit);
@ -10997,6 +11004,12 @@ The saved keystrokes are shown by `view-lossage'. */)
AUTO_STRING (fmt, "Value must be >= %d");
Fsignal (Quser_error, list1 (CALLN (Fformat, fmt, make_fixnum (min_size))));
}
if (new_size > MAX_NUM_RECENT_KEYS)
{
AUTO_STRING (fmt, "Value must be <= %d");
Fsignal (Quser_error, list1 (CALLN (Fformat, fmt,
make_fixnum (MAX_NUM_RECENT_KEYS))));
}
int kept_keys = new_size > osize ? total_keys : min (new_size, total_keys);
update_recent_keys (new_size, kept_keys);

2
test/lisp/abbrev-tests.el
View file

@ -317,7 +317,7 @@
(should-not abbrevs-changed))
;; Don't save
(let ((abbrevs-changed t))
(ert-simulate-keys '(?n)
(ert-simulate-keys '(?n ?\C-m)
(should (abbrev--possibly-save nil)))
(should-not abbrevs-changed)))))