diff options
Diffstat (limited to 'admin/notes/tree-sitter/html-manual/Using-Parser.html')
| -rw-r--r-- | admin/notes/tree-sitter/html-manual/Using-Parser.html | 230 |
1 files changed, 0 insertions, 230 deletions
diff --git a/admin/notes/tree-sitter/html-manual/Using-Parser.html b/admin/notes/tree-sitter/html-manual/Using-Parser.html deleted file mode 100644 index fd8fc482f46..00000000000 --- a/admin/notes/tree-sitter/html-manual/Using-Parser.html +++ /dev/null @@ -1,230 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html> -<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> -<!-- This is the GNU Emacs Lisp Reference Manual -corresponding to Emacs version 29.0.50. - -Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "GNU General Public License," with the -Front-Cover Texts being "A GNU Manual," and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the -section entitled "GNU Free Documentation License." - -(a) The FSF's Back-Cover Text is: "You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom." --> -<title>Using Parser (GNU Emacs Lisp Reference Manual)</title> - -<meta name="description" content="Using Parser (GNU Emacs Lisp Reference Manual)"> -<meta name="keywords" content="Using Parser (GNU Emacs Lisp Reference Manual)"> -<meta name="resource-type" content="document"> -<meta name="distribution" content="global"> -<meta name="Generator" content="makeinfo"> -<meta name="viewport" content="width=device-width,initial-scale=1"> - -<link href="index.html" rel="start" title="Top"> -<link href="Index.html" rel="index" title="Index"> -<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> -<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source"> -<link href="Retrieving-Nodes.html" rel="next" title="Retrieving Nodes"> -<link href="Language-Definitions.html" rel="prev" title="Language Definitions"> -<style type="text/css"> -<!-- -a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} -a.summary-letter {text-decoration: none} -blockquote.indentedblock {margin-right: 0em} -div.display {margin-left: 3.2em} -div.example {margin-left: 3.2em} -kbd {font-style: oblique} -pre.display {font-family: inherit} -pre.format {font-family: inherit} -pre.menu-comment {font-family: serif} -pre.menu-preformatted {font-family: serif} -span.nolinebreak {white-space: nowrap} -span.roman {font-family: initial; font-weight: normal} -span.sansserif {font-family: sans-serif; font-weight: normal} -span:hover a.copiable-anchor {visibility: visible} -ul.no-bullet {list-style: none} ---> -</style> -<link rel="stylesheet" type="text/css" href="./manual.css"> - - -</head> - -<body lang="en"> -<div class="section" id="Using-Parser"> -<div class="header"> -<p> -Next: <a href="Retrieving-Nodes.html" accesskey="n" rel="next">Retrieving Nodes</a>, Previous: <a href="Language-Definitions.html" accesskey="p" rel="prev">Tree-sitter Language Definitions</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> -</div> -<hr> -<span id="Using-Tree_002dsitter-Parser"></span><h3 class="section">37.2 Using Tree-sitter Parser</h3> -<span id="index-tree_002dsitter-parser_002c-using"></span> - -<p>This section describes how to create and configure a tree-sitter -parser. In Emacs, each tree-sitter parser is associated with a -buffer. As the user edits the buffer, the associated parser and -syntax tree are automatically kept up-to-date. -</p> -<dl class="def"> -<dt id="index-treesit_002dmax_002dbuffer_002dsize"><span class="category">Variable: </span><span><strong>treesit-max-buffer-size</strong><a href='#index-treesit_002dmax_002dbuffer_002dsize' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This variable contains the maximum size of buffers in which -tree-sitter can be activated. Major modes should check this value -when deciding whether to enable tree-sitter features. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dcan_002denable_002dp"><span class="category">Function: </span><span><strong>treesit-can-enable-p</strong><a href='#index-treesit_002dcan_002denable_002dp' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function checks whether the current buffer is suitable for -activating tree-sitter features. It basically checks -<code>treesit-available-p</code> and <code>treesit-max-buffer-size</code>. -</p></dd></dl> - -<span id="index-creating-tree_002dsitter-parsers"></span> -<span id="index-tree_002dsitter-parser_002c-creating"></span> -<dl class="def"> -<dt id="index-treesit_002dparser_002dcreate"><span class="category">Function: </span><span><strong>treesit-parser-create</strong> <em>language &optional buffer no-reuse</em><a href='#index-treesit_002dparser_002dcreate' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>Create a parser for the specified <var>buffer</var> and <var>language</var> -(see <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>). If <var>buffer</var> is omitted or -<code>nil</code>, it stands for the current buffer. -</p> -<p>By default, this function reuses a parser if one already exists for -<var>language</var> in <var>buffer</var>, but if <var>no-reuse</var> is -non-<code>nil</code>, this function always creates a new parser. -</p></dd></dl> - -<p>Given a parser, we can query information about it. -</p> -<dl class="def"> -<dt id="index-treesit_002dparser_002dbuffer"><span class="category">Function: </span><span><strong>treesit-parser-buffer</strong> <em>parser</em><a href='#index-treesit_002dparser_002dbuffer' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function returns the buffer associated with <var>parser</var>. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dparser_002dlanguage"><span class="category">Function: </span><span><strong>treesit-parser-language</strong> <em>parser</em><a href='#index-treesit_002dparser_002dlanguage' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function returns the language used by <var>parser</var>. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dparser_002dp"><span class="category">Function: </span><span><strong>treesit-parser-p</strong> <em>object</em><a href='#index-treesit_002dparser_002dp' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function checks if <var>object</var> is a tree-sitter parser, and -returns non-<code>nil</code> if it is, and <code>nil</code> otherwise. -</p></dd></dl> - -<p>There is no need to explicitly parse a buffer, because parsing is done -automatically and lazily. A parser only parses when a Lisp program -queries for a node in its syntax tree. Therefore, when a parser is -first created, it doesn’t parse the buffer; it waits until the Lisp -program queries for a node for the first time. Similarly, when some -change is made in the buffer, a parser doesn’t re-parse immediately. -</p> -<span id="index-treesit_002dbuffer_002dtoo_002dlarge"></span> -<p>When a parser does parse, it checks for the size of the buffer. -Tree-sitter can only handle buffer no larger than about 4GB. If the -size exceeds that, Emacs signals the <code>treesit-buffer-too-large</code> -error with signal data being the buffer size. -</p> -<p>Once a parser is created, Emacs automatically adds it to the -internal parser list. Every time a change is made to the buffer, -Emacs updates parsers in this list so they can update their syntax -tree incrementally. -</p> -<dl class="def"> -<dt id="index-treesit_002dparser_002dlist"><span class="category">Function: </span><span><strong>treesit-parser-list</strong> <em>&optional buffer</em><a href='#index-treesit_002dparser_002dlist' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function returns the parser list of <var>buffer</var>. If -<var>buffer</var> is <code>nil</code> or omitted, it defaults to the current -buffer. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dparser_002ddelete"><span class="category">Function: </span><span><strong>treesit-parser-delete</strong> <em>parser</em><a href='#index-treesit_002dparser_002ddelete' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function deletes <var>parser</var>. -</p></dd></dl> - -<span id="index-tree_002dsitter-narrowing"></span> -<span id="tree_002dsitter-narrowing"></span><p>Normally, a parser “sees” the whole buffer, but when the buffer is -narrowed (see <a href="Narrowing.html">Narrowing</a>), the parser will only see the accessible -portion of the buffer. As far as the parser can tell, the hidden -region was deleted. When the buffer is later widened, the parser -thinks text is inserted at the beginning and at the end. Although -parsers respect narrowing, modes should not use narrowing as a means -to handle a multi-language buffer; instead, set the ranges in which the -parser should operate. See <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>. -</p> -<p>Because a parser parses lazily, when the user or a Lisp program -narrows the buffer, the parser is not affected immediately; as long as -the mode doesn’t query for a node while the buffer is narrowed, the -parser is oblivious of the narrowing. -</p> -<span id="index-tree_002dsitter-parse-string"></span> -<span id="index-parse-string_002c-tree_002dsitter"></span> -<p>Besides creating a parser for a buffer, a Lisp program can also parse a -string. Unlike a buffer, parsing a string is a one-off operation, and -there is no way to update the result. -</p> -<dl class="def"> -<dt id="index-treesit_002dparse_002dstring"><span class="category">Function: </span><span><strong>treesit-parse-string</strong> <em>string language</em><a href='#index-treesit_002dparse_002dstring' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function parses <var>string</var> using <var>language</var>, and returns -the root node of the generated syntax tree. -</p></dd></dl> - -<span id="Be-notified-by-changes-to-the-parse-tree"></span><h3 class="heading">Be notified by changes to the parse tree</h3> -<span id="index-update-callback_002c-for-tree_002dsitter-parse_002dtree"></span> -<span id="index-after_002dchange-notifier_002c-for-tree_002dsitter-parse_002dtree"></span> -<span id="index-tree_002dsitter-parse_002dtree_002c-update-and-after_002dchange-callback"></span> -<span id="index-notifiers_002c-tree_002dsitter"></span> - -<p>A Lisp program might want to be notified of text affected by -incremental parsing. For example, inserting a comment-closing token -converts text before that token into a comment. Even -though the text is not directly edited, it is deemed to be “changed” -nevertheless. -</p> -<p>Emacs lets a Lisp program to register callback functions -(a.k.a. <em>notifiers</em>) for this kind of changes. A notifier -function takes two arguments: <var>ranges</var> and <var>parser</var>. -<var>ranges</var> is a list of cons cells of the form <code>(<var>start</var> . <var>end</var>)</code><!-- /@w -->, where <var>start</var> and <var>end</var> mark the start and the -end positions of a range. <var>parser</var> is the parser issuing the -notification. -</p> -<p>Every time a parser reparses a buffer, it compares the old and new -parse-tree, computes the ranges in which nodes have changed, and -passes the ranges to notifier functions. -</p> -<dl class="def"> -<dt id="index-treesit_002dparser_002dadd_002dnotifier"><span class="category">Function: </span><span><strong>treesit-parser-add-notifier</strong> <em>parser function</em><a href='#index-treesit_002dparser_002dadd_002dnotifier' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function adds <var>function</var> to <var>parser</var>’s list of -after-change notifier functions. <var>function</var> must be a function -symbol, not a lambda function (see <a href="Anonymous-Functions.html">Anonymous Functions</a>). -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dparser_002dremove_002dnotifier"><span class="category">Function: </span><span><strong>treesit-parser-remove-notifier</strong> <em>parser function</em><a href='#index-treesit_002dparser_002dremove_002dnotifier' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function removes <var>function</var> from the list of <var>parser</var>’s -after-change notifier functions. <var>function</var> must be a function -symbol, rather than a lambda function. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dparser_002dnotifiers"><span class="category">Function: </span><span><strong>treesit-parser-notifiers</strong> <em>parser</em><a href='#index-treesit_002dparser_002dnotifiers' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function returns the list of <var>parser</var>’s notifier functions. -</p></dd></dl> - -</div> -<hr> -<div class="header"> -<p> -Next: <a href="Retrieving-Nodes.html">Retrieving Nodes</a>, Previous: <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> -</div> - - - -</body> -</html> |