diff options
Diffstat (limited to 'doc/lispref/parsing.texi')
| -rw-r--r-- | doc/lispref/parsing.texi | 127 |
1 files changed, 97 insertions, 30 deletions
diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi index adb4c5e6e0c..86b3bd54e7c 100644 --- a/doc/lispref/parsing.texi +++ b/doc/lispref/parsing.texi @@ -393,12 +393,6 @@ tree-sitter can be activated. Major modes should check this value when deciding whether to enable tree-sitter features. @end defvar -@defun treesit-can-enable-p -This function checks whether the current buffer is suitable for -activating tree-sitter features. It basically checks -@code{treesit-available-p} and @code{treesit-max-buffer-size}. -@end defun - @cindex creating tree-sitter parsers @cindex tree-sitter parser, creating @defun treesit-parser-create language &optional buffer no-reuse @@ -511,7 +505,9 @@ notification. 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. +passes the ranges to notifier functions. Note that the initial parse +is also considered a ``change'', so notifier functions are called on +the initial parse, with range being the whole buffer. @defun treesit-parser-add-notifier parser function This function adds @var{function} to @var{parser}'s list of @@ -576,12 +572,12 @@ leaf node after @var{pos}. Finally, if there is no leaf node after @var{pos}, return the first leaf node before @var{pos}. -When @var{parser-or-lang} is @code{nil} or omitted, this function uses -the first parser in @code{(treesit-parser-list)} of the current -buffer. If @var{parser-or-lang} is a parser object, it uses that -parser; if @var{parser-or-lang} is a language, it finds the first -parser using that language in @code{(treesit-parser-list)}, and uses -that. +If @var{parser-or-lang} is a parser object, this function uses that +parser; if @var{parser-or-lang} is a language, this function uses the +first parser for that language in the current buffer, or creates one +if none exists; if @var{parser-or-lang} is @code{nil}, this function +tries to guess the language at @var{pos} by calling +@code{treesit-language-at} (@pxref{Multiple Languages}). If this function cannot find a suitable node to return, it returns @code{nil}. @@ -610,13 +606,14 @@ is at or after @var{end}. 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}, described above, instead. +to use @code{treesit-node-at} instead. -When @var{parser-or-lang} is @code{nil}, this function uses the first -parser in @code{(treesit-parser-list)} of the current buffer. If -@var{parser-or-lang} is a parser object, it uses that parser; if -@var{parser-or-lang} is a language, it finds the first parser using -that language in @code{(treesit-parser-list)}, and uses that. +If @var{parser-or-lang} is a parser object, this function uses that +parser; if @var{parser-or-lang} is a language, this function uses the +first parser for that language in the current buffer, or creates one +if none exists; if @var{parser-or-lang} is @code{nil}, this function +tries to guess the language at @var{beg} by calling +@code{treesit-language-at}. If @var{named} is non-@code{nil}, this function looks for a named node only (@pxref{tree-sitter named node, named node}). @@ -628,9 +625,10 @@ This function returns the root node of the syntax tree generated by @end defun @defun treesit-buffer-root-node &optional language -This function finds the first parser that uses @var{language} in -@code{(treesit-parser-list)} of the current buffer, and returns the -root node generated by that parser. If it cannot find an appropriate +This function finds the first parser for @var{language} in the current +buffer, or creates one if none exists, and returns the root node +generated by that parser. If @var{language} is omitted, it uses the +first parser in the parser list. If it cannot find an appropriate parser, it returns @code{nil}. @end defun @@ -647,6 +645,10 @@ it, or query for information about this node. @defun treesit-node-parent node This function returns the immediate parent of @var{node}. + +If @var{node} is more than 1000 levels deep in a parse tree, the +return value is undefined. Currently it returns @var{nil}, but that +could change in the future. @end defun @defun treesit-node-child node n &optional named @@ -1266,10 +1268,11 @@ example, with the following pattern: @end example @noindent -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{#}. -Currently there are two predicates, @code{#equal} and @code{#match}. +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{#}. Currently +there are three predicates, @code{#equal}, @code{#match}, and +@code{#pred}. @deffn Predicate equal arg1 arg2 Matches if @var{arg1} equals to @var{arg2}. Arguments can be either @@ -1282,6 +1285,11 @@ Matches if the text that @var{capture-name}'s node spans in the buffer matches regular expression @var{regexp}. Matching is case-sensitive. @end deffn +@deffn Predicate pred fn &rest nodes +Matches if function @var{fn} returns non-@code{nil} when passed each +node in @var{nodes} as arguments. +@end deffn + 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. @@ -1716,15 +1724,25 @@ This function activates some tree-sitter features for a major mode. Currently, it sets up the following features: @itemize @item -If @code{treesit-font-lock-settings} is non-@code{nil}, it sets up -fontification. +If @code{treesit-font-lock-settings} (@pxref{Parser-based Font Lock}) +is non-@code{nil}, it sets up fontification. + @item -If @code{treesit-simple-indent-rules} is non-@code{nil}, it sets up -indentation. +If @code{treesit-simple-indent-rules} (@pxref{Parser-based Font Lock}) +is non-@code{nil}, it sets up indentation. + @item If @code{treesit-defun-type-regexp} is non-@code{nil}, it sets up navigation functions for @code{beginning-of-defun} and @code{end-of-defun}. + +@item +If @code{treesit-defun-name-function} is non-@code{nil}, it sets up +add-log functions used by @code{add-log-current-defun}. + +@item +If @code{treesit-simple-imenu-settings} (@pxref{Imenu}) is +non-@code{nil}, it sets up Imenu. @end itemize @end defun @@ -1735,6 +1753,55 @@ For more information of these built-in tree-sitter features, For supporting mixing of multiple languages in a major mode, @pxref{Multiple Languages}. +Besides @code{beginning-of-defun} and @code{end-of-defun}, Emacs +provides some additional functions for working with defuns: +@code{treesit-defun-at-point} returns the defun node at point, and +@code{treesit-defun-name} returns the name of a defun node. + +@c FIXME: Cross-reference to treesit-defun-tactic once we have it in +@c the user manual. +@defun treesit-defun-at-point +This function returns the defun node at point, or @code{nil} if none +is found. It respects @code{treesit-defun-tactic}: if its value is +@code{top-level}, this function returns the top-level defun, and if +its value is @code{nested}, it returns the immediate enclosing defun. + +This function requires @code{treesit-defun-type-regexp} to work. If +it is @code{nil}, this function simply returns @code{nil}. +@end defun + +@defun treesit-defun-name node +This function returns the defun name of @var{node}. It returns +@code{nil} if there is no defun name for @var{node}, or if @var{node} +is not a defun node, or if @var{node} is @code{nil}. + +Depending on the language and major mode, the defun names are names +like function name, class name, struct name, etc. + +If @code{treesit-defun-name-function} is @code{nil}, this function +always returns @code{nil}. +@end defun + +@defvar treesit-defun-name-function +If non-@code{nil}, this variable's value should be a function that is +called with a node as its argument, and returns the defun name of the +node. The function should have the same semantic as +@code{treesit-defun-name}: if the node is not a defun node, or the +node is a defun node but doesn't have a name, or the node is +@code{nil}, it should return @code{nil}. +@end defvar + +@defvar treesit-defun-type-regexp +This variable determines which nodes are considered defuns by Emacs. +It can be a regexp that matches the type of defun nodes. + +Sometimes not all nodes matched by the regexp are valid defuns. +Therefore, this variable can also be a cons cell of the form +@w{(@var{regexp} . @var{pred})}, where @var{pred} should be a function +that takes a node as its argument, and returns @code{t} if the node is +valid defun, or @code{nil} if it is not valid. +@end defvar + @node Tree-sitter C API @section Tree-sitter C API Correspondence |