diff options
Diffstat (limited to 'admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html')
| -rw-r--r-- | admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html | 247 |
1 files changed, 0 insertions, 247 deletions
diff --git a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html b/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html deleted file mode 100644 index a3fe6622162..00000000000 --- a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html +++ /dev/null @@ -1,247 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html> -<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> -<!-- This is the GNU Emacs Lisp Reference Manual -corresponding to Emacs version 29.0.50. - -Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "GNU General Public License," with the -Front-Cover Texts being "A GNU Manual," and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the -section entitled "GNU Free Documentation License." - -(a) The FSF's Back-Cover Text is: "You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom." --> -<title>Parser-based Font Lock (GNU Emacs Lisp Reference Manual)</title> - -<meta name="description" content="Parser-based Font Lock (GNU Emacs Lisp Reference Manual)"> -<meta name="keywords" content="Parser-based Font Lock (GNU Emacs Lisp Reference Manual)"> -<meta name="resource-type" content="document"> -<meta name="distribution" content="global"> -<meta name="Generator" content="makeinfo"> -<meta name="viewport" content="width=device-width,initial-scale=1"> - -<link href="index.html" rel="start" title="Top"> -<link href="Index.html" rel="index" title="Index"> -<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> -<link href="Font-Lock-Mode.html" rel="up" title="Font Lock Mode"> -<link href="Multiline-Font-Lock.html" rel="prev" title="Multiline Font Lock"> -<style type="text/css"> -<!-- -a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} -a.summary-letter {text-decoration: none} -blockquote.indentedblock {margin-right: 0em} -div.display {margin-left: 3.2em} -div.example {margin-left: 3.2em} -kbd {font-style: oblique} -pre.display {font-family: inherit} -pre.format {font-family: inherit} -pre.menu-comment {font-family: serif} -pre.menu-preformatted {font-family: serif} -span.nolinebreak {white-space: nowrap} -span.roman {font-family: initial; font-weight: normal} -span.sansserif {font-family: sans-serif; font-weight: normal} -span:hover a.copiable-anchor {visibility: visible} -ul.no-bullet {list-style: none} ---> -</style> -<link rel="stylesheet" type="text/css" href="./manual.css"> - - -</head> - -<body lang="en"> -<div class="subsection" id="Parser_002dbased-Font-Lock"> -<div class="header"> -<p> -Previous: <a href="Multiline-Font-Lock.html" accesskey="p" rel="prev">Multiline Font Lock Constructs</a>, Up: <a href="Font-Lock-Mode.html" accesskey="u" rel="up">Font Lock Mode</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> -</div> -<hr> -<span id="Parser_002dbased-Font-Lock-1"></span><h4 class="subsection">24.6.10 Parser-based Font Lock</h4> -<span id="index-parser_002dbased-font_002dlock"></span> - - -<p>Besides simple syntactic font lock and regexp-based font lock, Emacs -also provides complete syntactic font lock with the help of a parser. -Currently, Emacs uses the tree-sitter library (see <a href="Parsing-Program-Source.html">Parsing Program Source</a>) for this purpose. -</p> -<p>Parser-based font lock and other font lock mechanisms are not mutually -exclusive. By default, if enabled, parser-based font lock runs first, -replacing syntactic font lock, then the regexp-based font lock. -</p> -<p>Although parser-based font lock doesn’t share the same customization -variables with regexp-based font lock, it uses similar customization -schemes. The tree-sitter counterpart of <var>font-lock-keywords</var> is -<var>treesit-font-lock-settings</var>. -</p> -<span id="index-tree_002dsitter-fontifications_002c-overview"></span> -<span id="index-fontifications-with-tree_002dsitter_002c-overview"></span> -<p>In general, tree-sitter fontification works as follows: -</p> -<ul> -<li> A Lisp program (usually, part of a major mode) provides a <em>query</em> -consisting of <em>patterns</em>, each pattern associated with a -<em>capture name</em>. - -</li><li> The tree-sitter library finds the nodes in the parse tree -that match these patterns, tags the nodes with the corresponding -capture names, and returns them to the Lisp program. - -</li><li> The Lisp program uses the returned nodes to highlight the portions of -buffer text corresponding to each node as appropriate, using the -tagged capture names of the nodes to determine the correct -fontification. For example, a node tagged <code>font-lock-keyword</code> -would be highlighted in <code>font-lock-keyword</code> face. -</li></ul> - -<p>For more information about queries, patterns, and capture names, see -<a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>. -</p> -<p>To setup tree-sitter fontification, a major mode should first set -<code>treesit-font-lock-settings</code> with the output of -<code>treesit-font-lock-rules</code>, then call -<code>treesit-major-mode-setup</code>. -</p> -<dl class="def"> -<dt id="index-treesit_002dfont_002dlock_002drules"><span class="category">Function: </span><span><strong>treesit-font-lock-rules</strong> <em>&rest query-specs</em><a href='#index-treesit_002dfont_002dlock_002drules' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function is used to set <var>treesit-font-lock-settings</var>. It -takes care of compiling queries and other post-processing, and outputs -a value that <var>treesit-font-lock-settings</var> accepts. Here’s an -example: -</p> -<div class="example"> -<pre class="example">(treesit-font-lock-rules - :language 'javascript - :feature 'constant - :override t - '((true) @font-lock-constant-face - (false) @font-lock-constant-face) - :language 'html - :feature 'script - "(script_element) @font-lock-builtin-face") -</pre></div> - -<p>This function takes a series of <var>query-spec</var>s, where each -<var>query-spec</var> is a <var>query</var> preceded by one or more -<var>:keyword</var>/<var>value</var> pairs. Each <var>query</var> is a -tree-sitter query in either the string, s-expression or compiled form. -</p> -<p>For each <var>query</var>, the <var>:keyword</var>/<var>value</var> pairs that -precede it add meta information to it. The <code>:language</code> keyword -declares <var>query</var>’s language. The <code>:feature</code> keyword sets the -feature name of <var>query</var>. Users can control which features are -enabled with <code>font-lock-maximum-decoration</code> and -<code>treesit-font-lock-feature-list</code> (described below). These two -keywords are mandatory. -</p> -<p>Other keywords are optional: -</p> -<table> -<thead><tr><th width="15%">Keyword</th><th width="15%">Value</th><th width="60%">Description</th></tr></thead> -<tr><td width="15%"><code>:override</code></td><td width="15%">nil</td><td width="60%">If the region already has a face, discard the new face</td></tr> -<tr><td width="15%"></td><td width="15%">t</td><td width="60%">Always apply the new face</td></tr> -<tr><td width="15%"></td><td width="15%"><code>append</code></td><td width="60%">Append the new face to existing ones</td></tr> -<tr><td width="15%"></td><td width="15%"><code>prepend</code></td><td width="60%">Prepend the new face to existing ones</td></tr> -<tr><td width="15%"></td><td width="15%"><code>keep</code></td><td width="60%">Fill-in regions without an existing face</td></tr> -</table> - -<p>Lisp programs mark patterns in <var>query</var> with capture names (names -that starts with <code>@</code>), and tree-sitter will return matched nodes -tagged with those same capture names. For the purpose of -fontification, capture names in <var>query</var> should be face names like -<code>font-lock-keyword-face</code>. The captured node will be fontified -with that face. -</p> -<span id="index-treesit_002dfontify_002dwith_002doverride"></span> -<p>Capture names can also be function names, in which case the function -is called with 4 arguments: <var>node</var> and <var>override</var>, <var>start</var> -and <var>end</var>, where <var>node</var> is the node itself, <var>override</var> is -the override property of the rule which captured this node, and -<var>start</var> and <var>end</var> limits the region in which this function -should fontify. (If this function wants to respect the <var>override</var> -argument, it can use <code>treesit-fontify-with-override</code>.) -</p> -<p>Beyond the 4 arguments presented, this function should accept more -arguments as optional arguments for future extensibility. -</p> -<p>If a capture name is both a face and a function, the face takes -priority. If a capture name is neither a face nor a function, it is -ignored. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dfont_002dlock_002dfeature_002dlist"><span class="category">Variable: </span><span><strong>treesit-font-lock-feature-list</strong><a href='#index-treesit_002dfont_002dlock_002dfeature_002dlist' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This is a list of lists of feature symbols. Each element of the list -is a list that represents a decoration level. -<code>font-lock-maximum-decoration</code> controls which levels are -activated. -</p> -<p>Each element of the list is a list of the form <code>(<var>feature</var> …)</code><!-- /@w -->, where each <var>feature</var> corresponds to the -<code>:feature</code> value of a query defined in -<code>treesit-font-lock-rules</code>. Removing a feature symbol from this -list disables the corresponding query during font-lock. -</p> -<p>Common feature names, for many programming languages, include -<code>definition</code>, <code>type</code>, <code>assignment</code>, <code>builtin</code>, -<code>constant</code>, <code>keyword</code>, <code>string-interpolation</code>, -<code>comment</code>, <code>doc</code>, <code>string</code>, <code>operator</code>, -<code>preprocessor</code>, <code>escape-sequence</code>, and <code>key</code>. Major -modes are free to subdivide or extend these common features. -</p> -<p>Some of these features warrant some explanation: <code>definition</code> -highlights whatever is being defined, e.g., the function name in a -function definition, the struct name in a struct definition, the -variable name in a variable definition; <code>assignment</code> highlights -the whatever is being assigned to, e.g., the variable or field in an -assignment statement; <code>key</code> highlights keys in key-value pairs, -e.g., keys in a JSON object, or a Python dictionary; <code>doc</code> -highlights docstrings or doc-comments. -</p> -<p>For example, the value of this variable could be: -</p><div class="example"> -<pre class="example">((comment string doc) ; level 1 - (function-name keyword type builtin constant) ; level 2 - (variable-name string-interpolation key)) ; level 3 -</pre></div> - -<p>Major modes should set this variable before calling -<code>treesit-major-mode-setup</code>. -</p> -<span id="index-treesit_002dfont_002dlock_002drecompute_002dfeatures"></span> -<p>For this variable to take effect, a Lisp program should call -<code>treesit-font-lock-recompute-features</code> (which resets -<code>treesit-font-lock-settings</code> accordingly), or -<code>treesit-major-mode-setup</code> (which calls -<code>treesit-font-lock-recompute-features</code>). -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dfont_002dlock_002dsettings"><span class="category">Variable: </span><span><strong>treesit-font-lock-settings</strong><a href='#index-treesit_002dfont_002dlock_002dsettings' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>A list of settings for tree-sitter based font lock. The exact format -of each setting is considered internal. One should always use -<code>treesit-font-lock-rules</code> to set this variable. -</p> -</dd></dl> - -<p>Multi-language major modes should provide range functions in -<code>treesit-range-functions</code>, and Emacs will set the ranges -accordingly before fontifing a region (see <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>). -</p> -</div> -<hr> -<div class="header"> -<p> -Previous: <a href="Multiline-Font-Lock.html">Multiline Font Lock Constructs</a>, Up: <a href="Font-Lock-Mode.html">Font Lock Mode</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> -</div> - - - -</body> -</html> |