diff options
| author | Eli Zaretskii <eliz@gnu.org> | 2023-03-19 08:09:33 +0200 |
|---|---|---|
| committer | Eli Zaretskii <eliz@gnu.org> | 2023-03-19 08:09:33 +0200 |
| commit | 0bebd0e5f09b6fbed2e54f9b8464e93bdd6ad11e (patch) | |
| tree | 41d19f431cd3e1e293d9f9a8f829e84ad100fa63 /admin/notes/tree-sitter/html-manual | |
| parent | 6674c362ad94373dacd22b7fd426406539e8d957 (diff) | |
| download | emacs-0bebd0e5f09b6fbed2e54f9b8464e93bdd6ad11e.tar.gz emacs-0bebd0e5f09b6fbed2e54f9b8464e93bdd6ad11e.tar.bz2 emacs-0bebd0e5f09b6fbed2e54f9b8464e93bdd6ad11e.zip | |
; Remove 'build-module' and 'html-manual' directories from 'admin'
These files were temporarily in the repository and are
no longer needed, once they fulfilled their job.
Diffstat (limited to 'admin/notes/tree-sitter/html-manual')
12 files changed, 0 insertions, 3293 deletions
diff --git a/admin/notes/tree-sitter/html-manual/Accessing-Node.html b/admin/notes/tree-sitter/html-manual/Accessing-Node.html deleted file mode 100644 index afbbdaa11b5..00000000000 --- a/admin/notes/tree-sitter/html-manual/Accessing-Node.html +++ /dev/null @@ -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> [<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'> ¶</a></span></dt> -<dd><p>This function returns <var>node</var>’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'> ¶</a></span></dt> -<dd><p>This function returns <var>node</var>’s parser’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'> ¶</a></span></dt> -<dd><p>This function returns <var>node</var>’s parser’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'> ¶</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'> ¶</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 &optional object</em><a href='#index-treesit_002dnode_002dtext' class='copiable-anchor'> ¶</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'> ¶</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'> ¶</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 “missing”: 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 “extra”: 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 “has changes” 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 “has error” 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'> ¶</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'> ¶</a></span></dt> -<dd><p>Named nodes have “types” (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>’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 &optional named</em><a href='#index-treesit_002dnode_002dindex' class='copiable-anchor'> ¶</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'> ¶</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'> ¶</a></span></dt> -<dd><p>This function returns the field name of the <var>n</var>’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 &optional named</em><a href='#index-treesit_002dchild_002dcount' class='copiable-anchor'> ¶</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> [<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> diff --git a/admin/notes/tree-sitter/html-manual/Language-Definitions.html b/admin/notes/tree-sitter/html-manual/Language-Definitions.html deleted file mode 100644 index 9b1e0021272..00000000000 --- a/admin/notes/tree-sitter/html-manual/Language-Definitions.html +++ /dev/null @@ -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> [<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’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> …)</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 &optional detail</em><a href='#index-treesit_002dlanguage_002davailable_002dp' class='copiable-anchor'> ¶</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’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’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’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 "libtree-sitter-coool" "tree_sitter_cooool") -</pre></div> - -<p>for a language that considers itself too “cool” 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>&optional min-compatible</em><a href='#index-treesit_002dlanguage_002dversion' class='copiable-anchor'> ¶</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 "1 + 2" | - +--------------+ - | - +--------------------------------+ - | expression "1 + 2" | - +--------------------------------+ - | | | -+------------+ +--------------+ +------------+ -| number "1" | | operator "+" | | number "2" | -+------------+ +--------------+ +------------+ -</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’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 ‘<samp>]</samp>’, 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 “explore” -mode, which displays the syntax tree of the source in the current -buffer in real time. Emacs also comes with an “inspect mode”, 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'> ¶</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'> ¶</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> (…))) -</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’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’s project repository. The link to a language definition’s -home page can be found on -<a href="https://tree-sitter.github.io/tree-sitter">tree-sitter’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: $ => 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 := - <declaration_specifiers> <declaration> <compound_statement> -</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>, …)</code></span></dt> -<dd><p>matches each rule one after another. -</p></dd> -<dt><span><code>choice(<var>rule1</var>, <var>rule2</var>, …)</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 ‘<samp>*</samp>’ 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 ‘<samp>+</samp>’ 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 ‘<samp>?</samp>’ 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 “The Grammar DSL” -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> [<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> diff --git a/admin/notes/tree-sitter/html-manual/Multiple-Languages.html b/admin/notes/tree-sitter/html-manual/Multiple-Languages.html deleted file mode 100644 index 390d9082590..00000000000 --- a/admin/notes/tree-sitter/html-manual/Multiple-Languages.html +++ /dev/null @@ -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> [<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’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'> ¶</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> . <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 (<= (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'> ¶</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> . <var>end</var>)</code><!-- /@w -->. If <var>parser</var> doesn’t have any -ranges, the return value is <code>nil</code>. -</p> -<div class="example"> -<pre class="example">(treesit-parser-included-ranges parser) - ⇒ ((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 &optional beg end</em><a href='#index-treesit_002dquery_002drange' class='copiable-anchor'> ¶</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> . <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’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’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>&optional beg end</em><a href='#index-treesit_002dupdate_002dranges' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function updates ranges for parsers in the buffer. It makes sure -the parsers’ 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'> ¶</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’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"><html> - <script>1 + 2</script> - <style>body { color: "blue"; }</style> -</html> -</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 - "(style_element (raw_text) @capture)")) -(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 - "(script_element (raw_text) @capture)")) -(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>&rest query-specs</em><a href='#index-treesit_002drange_002drules' class='copiable-anchor'> ¶</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’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'> ¶</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'> ¶</a></span></dt> -<dd><p>This variable’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> [<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> diff --git a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html b/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html deleted file mode 100644 index a3fe6622162..00000000000 --- a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html +++ /dev/null @@ -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> [<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’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>&rest query-specs</em><a href='#index-treesit_002dfont_002dlock_002drules' class='copiable-anchor'> ¶</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’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 - "(script_element) @font-lock-builtin-face") -</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>’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'> ¶</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> …)</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'> ¶</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> [<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> diff --git a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html b/admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html deleted file mode 100644 index cf1257f3102..00000000000 --- a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html +++ /dev/null @@ -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> [<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'> ¶</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'> ¶</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> . <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> <var>anchor</var> <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'> ¶</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'> ¶</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'> ¶</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>’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'> ¶</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>’s type matches -regexp <var>type</var>. -</p> -</dd> -<dt id='index-query'><span><code>query</code><a href='#index-query' class='copiable-anchor'> ¶</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'> ¶</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>’s type matches regexp <var>node-type</var>, -<var>parent</var>’s type matches regexp <var>parent-type</var>, <var>node</var>’s -field name in <var>parent</var> matches regexp <var>node-field</var>, and -<var>node</var>’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’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 "argument_list" 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'> ¶</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'> ¶</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'> ¶</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'> ¶</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'> ¶</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'> ¶</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'> ¶</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'> ¶</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'> ¶</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'> ¶</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'> ¶</a></span></dt> -<dd><p>This function checks the current buffer’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> [<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> diff --git a/admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html b/admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html deleted file mode 100644 index 58f6b4e9d5a..00000000000 --- a/admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html +++ /dev/null @@ -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> [<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'> ¶</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> [<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> diff --git a/admin/notes/tree-sitter/html-manual/Pattern-Matching.html b/admin/notes/tree-sitter/html-manual/Pattern-Matching.html deleted file mode 100644 index 9ef536b79dd..00000000000 --- a/admin/notes/tree-sitter/html-manual/Pattern-Matching.html +++ /dev/null @@ -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> [<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> (<var>child</var>…))</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 &optional beg end node-only</em><a href='#index-treesit_002dquery_002dcapture' class='copiable-anchor'> ¶</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> . <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’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>’s text is <code>1 + 2</code>, and -<var>query</var> is -</p> -<div class="example"> -<pre class="example">(setq query - "(binary_expression - (number_literal) @number-in-exp) @biexp") -</pre></div> - -<p>Matching that query would return -</p> -<div class="example"> -<pre class="example">(treesit-query-capture node query) - ⇒ ((biexp . <var><node for "1 + 2"></var>) - (number-in-exp . <var><node for "1"></var>) - (number-in-exp . <var><node for "2"></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 - "(binary_expression) @biexp - (number_literal) @number @biexp") -</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'> ¶</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’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">"return" @keyword -</pre></div> - -<span id="Wild-card"></span><h4 class="subheading">Wild card</h4> - -<p>In a pattern, ‘<samp>(_)</samp>’ matches any named node, and ‘<samp>_</samp>’ 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’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 ‘<samp>*</samp>’, ‘<samp>+</samp>’ and -‘<samp>?</samp>’. Their meanings are the same as in regular expressions: -‘<samp>*</samp>’ matches the preceding pattern zero or more times, ‘<samp>+</samp>’ -matches one or more times, and ‘<samp>?</samp>’ 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 "long"*) @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 "long"?) @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) ("," (identifier))* -</pre></div> - -<span id="Alternation"></span><h4 class="subheading">Alternation</h4> - -<p>Again, similar to regular expressions, we can express “match anyone -from this group of patterns” 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">[ - "return" - "break" - "if" - "else" -] @keyword -</pre></div> - -<span id="Anchor"></span><h4 class="subheading">Anchor</h4> - -<p>The anchor operator ‘<samp>.</samp>’ can be used to enforce juxtaposition, -i.e., to enforce two things to be directly next to each other. The -two “things” 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 ‘<samp>#</samp>’. -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'> ¶</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'> ¶</a></span></dt> -<dd><p>Matches if the text that <var>capture-name</var>’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 "(addition_expression - left: (_) @left - \"+\" @plus-sign - right: (_) @right) @addition - - [\"return\" \"break\"] @keyword") -</pre></div> - -<p>is equivalent to -</p> -<div class="example"> -<pre class="example">(treesit-query-capture - node '((addition_expression - left: (_) @left - "+" @plus-sign - right: (_) @right) @addition - - ["return" "break"] @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 ‘<samp>.</samp>’ is written as <code>:anchor</code>. -</li><li> ‘<samp>?</samp>’ is written as ‘<samp>:?</samp>’. -</li><li> ‘<samp>*</samp>’ is written as ‘<samp>:*</samp>’. -</li><li> ‘<samp>+</samp>’ is written as ‘<samp>:+</samp>’. -</li><li> <code>#equal</code> is written as <code>:equal</code>. In general, predicates -change their ‘<samp>#</samp>’ to ‘<samp>:</samp>’. -</li></ul> - -<p>For example, -</p> -<div class="example"> -<pre class="example">"( - (compound_expression . (_) @first (_)* @rest) - (#match \"love\" @first) - )" -</pre></div> - -<p>is written in s-expression as -</p> -<div class="example"> -<pre class="example">'(( - (compound_expression :anchor (_) @first (_) :* @rest) - (:match "love" @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'> ¶</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'> ¶</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'> ¶</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'> ¶</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’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> [<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> diff --git a/admin/notes/tree-sitter/html-manual/Retrieving-Node.html b/admin/notes/tree-sitter/html-manual/Retrieving-Node.html deleted file mode 100644 index 16eeb0b1091..00000000000 --- a/admin/notes/tree-sitter/html-manual/Retrieving-Node.html +++ /dev/null @@ -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> [<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’s some terminology and conventions we use when documenting -tree-sitter functions. -</p> -<p>We talk about a node being “smaller” or “larger”, and “lower” or -“higher”. 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 &optional parser-or-lang named</em><a href='#index-treesit_002dnode_002dat' class='copiable-anchor'> ¶</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) - ⇒ #<treesit-node (primitive_type) in 23-27> -</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 &optional parser-or-lang named</em><a href='#index-treesit_002dnode_002don' class='copiable-anchor'> ¶</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'> ¶</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>&optional language</em><a href='#index-treesit_002dbuffer_002droot_002dnode' class='copiable-anchor'> ¶</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'> ¶</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 &optional named</em><a href='#index-treesit_002dnode_002dchild' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function returns the <var>n</var>’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>"text"</code>, there -are three children nodes: the opening quote <code>"</code>, the string text -<code>text</code>, and the closing quote <code>"</code>. Among these nodes, the -first child is the opening quote <code>"</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>’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 &optional named</em><a href='#index-treesit_002dnode_002dchildren' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function returns all of <var>node</var>’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 &optional named</em><a href='#index-treesit_002dnext_002dsibling' class='copiable-anchor'> ¶</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 &optional named</em><a href='#index-treesit_002dprev_002dsibling' class='copiable-anchor'> ¶</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'> ¶</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 "body" as its field name. -(treesit-node-child-by-field-name node "body") - ⇒ #<treesit-node (compound_statement) in 45-89> -</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 &optional named</em><a href='#index-treesit_002dfirst_002dchild_002dfor_002dpos' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function finds the first child of <var>node</var> that extends beyond -buffer position <var>pos</var>. “Extends beyond” 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’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 &optional named</em><a href='#index-treesit_002dnode_002ddescendant_002dfor_002drange' class='copiable-anchor'> ¶</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 &optional backward all limit</em><a href='#index-treesit_002dsearch_002dsubtree' class='copiable-anchor'> ¶</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’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 &optional backward all</em><a href='#index-treesit_002dsearch_002dforward' class='copiable-anchor'> ¶</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’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 “what is the first node after <var>start</var> in -the buffer that satisfies some condition?” -</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 &optional start backward all</em><a href='#index-treesit_002dsearch_002dforward_002dgoto' class='copiable-anchor'> ¶</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 &optional process-fn limit</em><a href='#index-treesit_002dinduce_002dsparse_002dtree' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function creates a sparse tree from <var>root</var>’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’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 “letter only”, 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 - | | => | | => | - 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> . (<var>child</var> …))</code><!-- /@w -->. The -<var>tree-sitter-node</var> of the root of this tree will be nil if -<var>root</var> doesn’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 &optional named</em><a href='#index-treesit_002dfilter_002dchild' class='copiable-anchor'> ¶</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'> ¶</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'> ¶</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 &optional type</em><a href='#index-treesit_002dnode_002dtop_002dlevel' class='copiable-anchor'> ¶</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’s -type with <var>type</var> as a regexp, rather than using <var>node</var>’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> [<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> diff --git a/admin/notes/tree-sitter/html-manual/Tree_002dsitter-C-API.html b/admin/notes/tree-sitter/html-manual/Tree_002dsitter-C-API.html deleted file mode 100644 index 1d992b828ea..00000000000 --- a/admin/notes/tree-sitter/html-manual/Tree_002dsitter-C-API.html +++ /dev/null @@ -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> [<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’ tree-sitter integration doesn’t expose every feature -provided by tree-sitter’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’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’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> [<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> diff --git a/admin/notes/tree-sitter/html-manual/Using-Parser.html b/admin/notes/tree-sitter/html-manual/Using-Parser.html deleted file mode 100644 index fd8fc482f46..00000000000 --- a/admin/notes/tree-sitter/html-manual/Using-Parser.html +++ /dev/null @@ -1,230 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html> -<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> -<!-- This is the GNU Emacs Lisp Reference Manual -corresponding to Emacs version 29.0.50. - -Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "GNU General Public License," with the -Front-Cover Texts being "A GNU Manual," and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the -section entitled "GNU Free Documentation License." - -(a) The FSF's Back-Cover Text is: "You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom." --> -<title>Using Parser (GNU Emacs Lisp Reference Manual)</title> - -<meta name="description" content="Using Parser (GNU Emacs Lisp Reference Manual)"> -<meta name="keywords" content="Using Parser (GNU Emacs Lisp Reference Manual)"> -<meta name="resource-type" content="document"> -<meta name="distribution" content="global"> -<meta name="Generator" content="makeinfo"> -<meta name="viewport" content="width=device-width,initial-scale=1"> - -<link href="index.html" rel="start" title="Top"> -<link href="Index.html" rel="index" title="Index"> -<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> -<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source"> -<link href="Retrieving-Nodes.html" rel="next" title="Retrieving Nodes"> -<link href="Language-Definitions.html" rel="prev" title="Language Definitions"> -<style type="text/css"> -<!-- -a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} -a.summary-letter {text-decoration: none} -blockquote.indentedblock {margin-right: 0em} -div.display {margin-left: 3.2em} -div.example {margin-left: 3.2em} -kbd {font-style: oblique} -pre.display {font-family: inherit} -pre.format {font-family: inherit} -pre.menu-comment {font-family: serif} -pre.menu-preformatted {font-family: serif} -span.nolinebreak {white-space: nowrap} -span.roman {font-family: initial; font-weight: normal} -span.sansserif {font-family: sans-serif; font-weight: normal} -span:hover a.copiable-anchor {visibility: visible} -ul.no-bullet {list-style: none} ---> -</style> -<link rel="stylesheet" type="text/css" href="./manual.css"> - - -</head> - -<body lang="en"> -<div class="section" id="Using-Parser"> -<div class="header"> -<p> -Next: <a href="Retrieving-Nodes.html" accesskey="n" rel="next">Retrieving Nodes</a>, Previous: <a href="Language-Definitions.html" accesskey="p" rel="prev">Tree-sitter Language Definitions</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> -</div> -<hr> -<span id="Using-Tree_002dsitter-Parser"></span><h3 class="section">37.2 Using Tree-sitter Parser</h3> -<span id="index-tree_002dsitter-parser_002c-using"></span> - -<p>This section describes how to create and configure a tree-sitter -parser. In Emacs, each tree-sitter parser is associated with a -buffer. As the user edits the buffer, the associated parser and -syntax tree are automatically kept up-to-date. -</p> -<dl class="def"> -<dt id="index-treesit_002dmax_002dbuffer_002dsize"><span class="category">Variable: </span><span><strong>treesit-max-buffer-size</strong><a href='#index-treesit_002dmax_002dbuffer_002dsize' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This variable contains the maximum size of buffers in which -tree-sitter can be activated. Major modes should check this value -when deciding whether to enable tree-sitter features. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dcan_002denable_002dp"><span class="category">Function: </span><span><strong>treesit-can-enable-p</strong><a href='#index-treesit_002dcan_002denable_002dp' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function checks whether the current buffer is suitable for -activating tree-sitter features. It basically checks -<code>treesit-available-p</code> and <code>treesit-max-buffer-size</code>. -</p></dd></dl> - -<span id="index-creating-tree_002dsitter-parsers"></span> -<span id="index-tree_002dsitter-parser_002c-creating"></span> -<dl class="def"> -<dt id="index-treesit_002dparser_002dcreate"><span class="category">Function: </span><span><strong>treesit-parser-create</strong> <em>language &optional buffer no-reuse</em><a href='#index-treesit_002dparser_002dcreate' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>Create a parser for the specified <var>buffer</var> and <var>language</var> -(see <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>). If <var>buffer</var> is omitted or -<code>nil</code>, it stands for the current buffer. -</p> -<p>By default, this function reuses a parser if one already exists for -<var>language</var> in <var>buffer</var>, but if <var>no-reuse</var> is -non-<code>nil</code>, this function always creates a new parser. -</p></dd></dl> - -<p>Given a parser, we can query information about it. -</p> -<dl class="def"> -<dt id="index-treesit_002dparser_002dbuffer"><span class="category">Function: </span><span><strong>treesit-parser-buffer</strong> <em>parser</em><a href='#index-treesit_002dparser_002dbuffer' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function returns the buffer associated with <var>parser</var>. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dparser_002dlanguage"><span class="category">Function: </span><span><strong>treesit-parser-language</strong> <em>parser</em><a href='#index-treesit_002dparser_002dlanguage' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function returns the language used by <var>parser</var>. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dparser_002dp"><span class="category">Function: </span><span><strong>treesit-parser-p</strong> <em>object</em><a href='#index-treesit_002dparser_002dp' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function checks if <var>object</var> is a tree-sitter parser, and -returns non-<code>nil</code> if it is, and <code>nil</code> otherwise. -</p></dd></dl> - -<p>There is no need to explicitly parse a buffer, because parsing is done -automatically and lazily. A parser only parses when a Lisp program -queries for a node in its syntax tree. Therefore, when a parser is -first created, it doesn’t parse the buffer; it waits until the Lisp -program queries for a node for the first time. Similarly, when some -change is made in the buffer, a parser doesn’t re-parse immediately. -</p> -<span id="index-treesit_002dbuffer_002dtoo_002dlarge"></span> -<p>When a parser does parse, it checks for the size of the buffer. -Tree-sitter can only handle buffer no larger than about 4GB. If the -size exceeds that, Emacs signals the <code>treesit-buffer-too-large</code> -error with signal data being the buffer size. -</p> -<p>Once a parser is created, Emacs automatically adds it to the -internal parser list. Every time a change is made to the buffer, -Emacs updates parsers in this list so they can update their syntax -tree incrementally. -</p> -<dl class="def"> -<dt id="index-treesit_002dparser_002dlist"><span class="category">Function: </span><span><strong>treesit-parser-list</strong> <em>&optional buffer</em><a href='#index-treesit_002dparser_002dlist' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function returns the parser list of <var>buffer</var>. If -<var>buffer</var> is <code>nil</code> or omitted, it defaults to the current -buffer. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dparser_002ddelete"><span class="category">Function: </span><span><strong>treesit-parser-delete</strong> <em>parser</em><a href='#index-treesit_002dparser_002ddelete' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function deletes <var>parser</var>. -</p></dd></dl> - -<span id="index-tree_002dsitter-narrowing"></span> -<span id="tree_002dsitter-narrowing"></span><p>Normally, a parser “sees” the whole buffer, but when the buffer is -narrowed (see <a href="Narrowing.html">Narrowing</a>), the parser will only see the accessible -portion of the buffer. As far as the parser can tell, the hidden -region was deleted. When the buffer is later widened, the parser -thinks text is inserted at the beginning and at the end. Although -parsers respect narrowing, modes should not use narrowing as a means -to handle a multi-language buffer; instead, set the ranges in which the -parser should operate. See <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>. -</p> -<p>Because a parser parses lazily, when the user or a Lisp program -narrows the buffer, the parser is not affected immediately; as long as -the mode doesn’t query for a node while the buffer is narrowed, the -parser is oblivious of the narrowing. -</p> -<span id="index-tree_002dsitter-parse-string"></span> -<span id="index-parse-string_002c-tree_002dsitter"></span> -<p>Besides creating a parser for a buffer, a Lisp program can also parse a -string. Unlike a buffer, parsing a string is a one-off operation, and -there is no way to update the result. -</p> -<dl class="def"> -<dt id="index-treesit_002dparse_002dstring"><span class="category">Function: </span><span><strong>treesit-parse-string</strong> <em>string language</em><a href='#index-treesit_002dparse_002dstring' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function parses <var>string</var> using <var>language</var>, and returns -the root node of the generated syntax tree. -</p></dd></dl> - -<span id="Be-notified-by-changes-to-the-parse-tree"></span><h3 class="heading">Be notified by changes to the parse tree</h3> -<span id="index-update-callback_002c-for-tree_002dsitter-parse_002dtree"></span> -<span id="index-after_002dchange-notifier_002c-for-tree_002dsitter-parse_002dtree"></span> -<span id="index-tree_002dsitter-parse_002dtree_002c-update-and-after_002dchange-callback"></span> -<span id="index-notifiers_002c-tree_002dsitter"></span> - -<p>A Lisp program might want to be notified of text affected by -incremental parsing. For example, inserting a comment-closing token -converts text before that token into a comment. Even -though the text is not directly edited, it is deemed to be “changed” -nevertheless. -</p> -<p>Emacs lets a Lisp program to register callback functions -(a.k.a. <em>notifiers</em>) for this kind of changes. A notifier -function takes two arguments: <var>ranges</var> and <var>parser</var>. -<var>ranges</var> is a list of cons cells of the form <code>(<var>start</var> . <var>end</var>)</code><!-- /@w -->, where <var>start</var> and <var>end</var> mark the start and the -end positions of a range. <var>parser</var> is the parser issuing the -notification. -</p> -<p>Every time a parser reparses a buffer, it compares the old and new -parse-tree, computes the ranges in which nodes have changed, and -passes the ranges to notifier functions. -</p> -<dl class="def"> -<dt id="index-treesit_002dparser_002dadd_002dnotifier"><span class="category">Function: </span><span><strong>treesit-parser-add-notifier</strong> <em>parser function</em><a href='#index-treesit_002dparser_002dadd_002dnotifier' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function adds <var>function</var> to <var>parser</var>’s list of -after-change notifier functions. <var>function</var> must be a function -symbol, not a lambda function (see <a href="Anonymous-Functions.html">Anonymous Functions</a>). -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dparser_002dremove_002dnotifier"><span class="category">Function: </span><span><strong>treesit-parser-remove-notifier</strong> <em>parser function</em><a href='#index-treesit_002dparser_002dremove_002dnotifier' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function removes <var>function</var> from the list of <var>parser</var>’s -after-change notifier functions. <var>function</var> must be a function -symbol, rather than a lambda function. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dparser_002dnotifiers"><span class="category">Function: </span><span><strong>treesit-parser-notifiers</strong> <em>parser</em><a href='#index-treesit_002dparser_002dnotifiers' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function returns the list of <var>parser</var>’s notifier functions. -</p></dd></dl> - -</div> -<hr> -<div class="header"> -<p> -Next: <a href="Retrieving-Nodes.html">Retrieving Nodes</a>, Previous: <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> -</div> - - - -</body> -</html> diff --git a/admin/notes/tree-sitter/html-manual/build-manual.sh b/admin/notes/tree-sitter/html-manual/build-manual.sh deleted file mode 100755 index 8d931b143b2..00000000000 --- a/admin/notes/tree-sitter/html-manual/build-manual.sh +++ /dev/null @@ -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" . diff --git a/admin/notes/tree-sitter/html-manual/manual.css b/admin/notes/tree-sitter/html-manual/manual.css deleted file mode 100644 index c03e0d37009..00000000000 --- a/admin/notes/tree-sitter/html-manual/manual.css +++ /dev/null @@ -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; -} |