; 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.
This commit is contained in:
Eli Zaretskii
parent
6674c362ad
commit
0bebd0e5f0
15 changed files with 0 additions and 3423 deletions
|
|
@ -1,17 +0,0 @@
|
|||
To build the language definition for a particular language, run
|
||||
|
||||
./build.sh <language>
|
||||
|
||||
eg,
|
||||
|
||||
./build.sh html
|
||||
|
||||
The dynamic module will be in /dist directory
|
||||
|
||||
To build all modules at once, run
|
||||
|
||||
./batch.sh
|
||||
|
||||
This gives you C, JSON, Go, HTML, Javascript, CSS, Python, Typescript
|
||||
(tsx), C# (csharp), C++ (cpp), Rust. More can be added to batch.sh
|
||||
unless it's directory structure is not standard.
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
#!/bin/bash
|
||||
|
||||
languages=(
|
||||
'bash'
|
||||
'c'
|
||||
'cmake'
|
||||
'cpp'
|
||||
'css'
|
||||
'c-sharp'
|
||||
'dockerfile'
|
||||
'go'
|
||||
'go-mod'
|
||||
'html'
|
||||
'javascript'
|
||||
'json'
|
||||
'python'
|
||||
'rust'
|
||||
'toml'
|
||||
'tsx'
|
||||
'typescript'
|
||||
'yaml'
|
||||
)
|
||||
|
||||
for language in "${languages[@]}"
|
||||
do
|
||||
./build.sh $language
|
||||
done
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
#!/bin/bash
|
||||
|
||||
lang=$1
|
||||
topdir="$PWD"
|
||||
|
||||
case $(uname) in
|
||||
"Darwin")
|
||||
soext="dylib"
|
||||
;;
|
||||
*"MINGW"*)
|
||||
soext="dll"
|
||||
;;
|
||||
*)
|
||||
soext="so"
|
||||
;;
|
||||
esac
|
||||
|
||||
echo "Building ${lang}"
|
||||
|
||||
### Retrieve sources
|
||||
|
||||
org="tree-sitter"
|
||||
repo="tree-sitter-${lang}"
|
||||
sourcedir="tree-sitter-${lang}/src"
|
||||
grammardir="tree-sitter-${lang}"
|
||||
|
||||
case "${lang}" in
|
||||
"dockerfile")
|
||||
org="camdencheek"
|
||||
;;
|
||||
"cmake")
|
||||
org="uyha"
|
||||
;;
|
||||
"go-mod")
|
||||
# The parser is called "gomod".
|
||||
lang="gomod"
|
||||
org="camdencheek"
|
||||
;;
|
||||
"typescript")
|
||||
sourcedir="tree-sitter-typescript/typescript/src"
|
||||
grammardir="tree-sitter-typescript/typescript"
|
||||
;;
|
||||
"tsx")
|
||||
repo="tree-sitter-typescript"
|
||||
sourcedir="tree-sitter-typescript/tsx/src"
|
||||
grammardir="tree-sitter-typescript/tsx"
|
||||
;;
|
||||
"yaml")
|
||||
org="ikatyang"
|
||||
;;
|
||||
esac
|
||||
|
||||
git clone "https://github.com/${org}/${repo}.git" \
|
||||
--depth 1 --quiet
|
||||
cp "${grammardir}"/grammar.js "${sourcedir}"
|
||||
# We have to go into the source directory to compile, because some
|
||||
# C files refer to files like "../../common/scanner.h".
|
||||
cd "${sourcedir}"
|
||||
|
||||
### Build
|
||||
|
||||
cc -fPIC -c -I. parser.c
|
||||
# Compile scanner.c.
|
||||
if test -f scanner.c
|
||||
then
|
||||
cc -fPIC -c -I. scanner.c
|
||||
fi
|
||||
# Compile scanner.cc.
|
||||
if test -f scanner.cc
|
||||
then
|
||||
c++ -fPIC -I. -c scanner.cc
|
||||
fi
|
||||
# Link.
|
||||
if test -f scanner.cc
|
||||
then
|
||||
c++ -fPIC -shared *.o -o "libtree-sitter-${lang}.${soext}"
|
||||
else
|
||||
cc -fPIC -shared *.o -o "libtree-sitter-${lang}.${soext}"
|
||||
fi
|
||||
|
||||
### Copy out
|
||||
|
||||
mkdir -p "${topdir}/dist"
|
||||
cp "libtree-sitter-${lang}.${soext}" "${topdir}/dist"
|
||||
cd "${topdir}"
|
||||
rm -rf "${repo}"
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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" .
|
||||
|
|
@ -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;
|
||||
}
|
||||
Loading…
Add table
Reference in a new issue