From 31f75430999b9021fc68739af231261608aac255 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 23 Oct 2022 11:14:18 +0300 Subject: [PATCH] ; Minor copyedits of tree-sitter stuff in ELisp manual * doc/lispref/parsing.texi (Pattern Matching): * doc/lispref/modes.texi (Parser-based Font Lock) (Parser-based Indentation): Fix wording and typos. --- doc/lispref/modes.texi | 99 ++++++++++++++++++++++++---------------- doc/lispref/parsing.texi | 29 ++++++------ 2 files changed, 76 insertions(+), 52 deletions(-) diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 3537d312f2f..c6269b46ba0 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -3904,16 +3904,31 @@ variables with regexp-based font lock, it uses similar customization schemes. The tree-sitter counterpart of @var{font-lock-keywords} is @var{treesit-font-lock-settings}. -In general, tree-sitter fontification works like the following: a Lisp -program provides a @dfn{query} consisting of @dfn{patterns} with -@dfn{capture names}. Tree-sitter finds the nodes in the parse tree -that match these patterns, tags the corresponding capture names onto -the nodes, and returns them to the Lisp program. The Lisp program -takes theses nodes and highlights the corresponding buffer text of -each node depending on the tagged capture name of the node. For -example, a node tagged @code{font-lock-keyword} would simply be -highlighted in @code{font-lock-keyword} face. For more information on -queries, patterns and capture names, @pref{Pattern Matching}. +@cindex tree-sitter fontifications, overview +@cindex fontifications with tree-sitter, overview +In general, tree-sitter fontification works as follows: + +@itemize @bullet +@item +A Lisp program (usually, part of a major mode) provides a @dfn{query} +consisting of @dfn{patterns}, each pattern associated with a +@dfn{capture name}. + +@item +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. + +@item +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} +would be highlighted in @code{font-lock-keyword} face. +@end itemize + +For more information about queries, patterns, and capture names, see +@ref{Pattern Matching}. @defun treesit-font-lock-rules :keyword value query... This function is used to set @var{treesit-font-lock-settings}. It @@ -3957,7 +3972,7 @@ Other keywords are optional: Lisp programs mark patterns in the query with capture names (names that starts with @code{@@}), and tree-sitter will return matched nodes -with capture names tagged onto them. For the purpose of +tagged with those same capture names. For the purpose of fontification, capture names in @var{query} should be face names like @code{font-lock-keyword-face}. The captured node will be fontified with that face. Capture names can also be function names, in which @@ -4010,7 +4025,7 @@ A list of settings for tree-sitter based font lock. The exact format of this variable is considered internal. One should always use @code{treesit-font-lock-rules} to set this variable. @c Because the format is internal, we don't document them here. -@c Though We do have explanations in the docstring. +@c Though we do have it explained in the docstring. @end defvar Multi-language major modes should provide range functions in @@ -4805,37 +4820,41 @@ available default functions are: @ftable @code @item no-node +@c FIXME: How many arguments does no-node accept, and what are thos +@c arguments? This matcher is a function that matches the case where @var{node} is @code{nil}, i.e., there is no node that starts at @var{bol}. This is the case when @var{bol} is on an empty line or inside a multi-line string, etc. @item parent-is -This matcher is a function of one argument, @var{type}; it return a -function that given @w{@code{(@var{node} @var{parent} @var{bol})}}, -matches if @var{parent}'s type is @var{type}. +This matcher is a function of one argument, @var{type}; it returns a +function that is called with 3 arguments: @var{node}, @var{parent}, +and @var{bol}, and returns non-@code{nil} (i.e., a match) if +@var{parent}'s type is @var{type}. @item node-is This matcher is a function of one argument, @var{type}; it returns a -function that given @w{@code{(@var{node} @var{parent} @var{bol})}}, -matches if @var{node}'s type is @var{type}. +function that is called with 3 arguments: @var{node}, @var{parent}, +and @var{bol}, and returns non-@code{nil} if @var{node}'s type is +@var{type}. @item query This matcher is a function of one argument, @var{query}; it returns a -function that given @w{@code{(@var{node} @var{parent} @var{bol})}}, -matches if querying @var{parent} with @var{query} captures @var{node} -(@pxref{Pattern Matching}). +function that is called with 3 arguments: @var{node}, @var{parent}, +and @var{bol}, and returns non-@code{nil} if querying @var{parent} +with @var{query} captures @var{node} (@pxref{Pattern Matching}). @item match This matcher is a function of 5 arguments: @var{node-type}, @var{parent-type}, @var{node-field}, @var{node-index-min}, and -@var{node-index-max}). It returns a function that given -@w{@code{(@var{node} @var{parent} @var{bol})}}, matches if -@var{node}'s type is @var{node-type}, @var{parent}'s type is -@var{parent-type}, @var{node}'s field name in @var{parent} is +@var{node-index-max}). It returns a function that is called with 3 +arguments: @var{node}, @var{parent}, and @var{bol}, and returns +non-@code{nil} if @var{node}'s type is @var{node-type}, @var{parent}'s +type is @var{parent-type}, @var{node}'s field name in @var{parent} is @var{node-field}, and @var{node}'s index among its siblings is between @var{node-index-min} and @var{node-index-max}. If the value of an -argument is @code{nil}, this matcher doesn't check for that argument. +argument is @code{nil}, this matcher doesn't check that argument. For example, to match the first child where parent is @code{argument_list}, use @@ -4844,30 +4863,32 @@ For example, to match the first child where parent is @end example @item first-sibling -This anchor is a function that given @w{@code{(@var{node} @var{parent} -@var{bol})}}, returns the start of the first child of @var{parent}. +This anchor is a function that is called with 3 arguments: @var{node}, +@var{parent}, and @var{bol}, and returns the start of the first child +of @var{parent}. @item parent -This anchor is a function that given @w{@code{(@var{node} @var{parent} -@var{bol})}}, returns the start of @var{parent}. +This anchor is a function that is called with 3 arguments: @var{node}, +@var{parent}, and @var{bol}, and returns the start of @var{parent}. @item parent-bol -This anchor is a function that given @w{@code{(@var{node} @var{parent} -@var{bol})}}, returns the first non-space character on the line of -@var{parent}. +This anchor is a function that is called with 3 arguments: @var{node}, +@var{parent}, and @var{bol}, and returns the first non-space character +on the line of @var{parent}. @item prev-sibling -This anchor is a function that given @w{@code{(@var{node} @var{parent} -@var{bol})}}, returns the start of the previous sibling of @var{node}. +This anchor is a function that is called with 3 arguments: @var{node}, +@var{parent}, and @var{bol}, and returns the start of the previous +sibling of @var{node}. @item no-indent -This anchor is a function that given @w{@code{(@var{node} @var{parent} -@var{bol})}}, returns the start of @var{node}. +This anchor is a function that is called with 3 arguments: @var{node}, +@var{parent}, and @var{bol}, and returns the start of @var{node}. @item prev-line -This anchor is a function that given @w{@code{(@var{node} @var{parent} -@var{bol})}}, returns the first non-whitespace charater on the -previous line. +This anchor is a function that is called with 3 arguments: @var{node}, +@var{parent}, and @var{bol}, and returns the first non-whitespace +charater on the previous line. @end ftable @end defvar diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi index bb0b8c61ee4..aaa8f0f64dd 100644 --- a/doc/lispref/parsing.texi +++ b/doc/lispref/parsing.texi @@ -406,7 +406,7 @@ returns non-@code{nil} if it is, @code{nil} otherwise. There is no need to explicitly parse a buffer, because parsing is done automatically and lazily. A parser only parses when a Lisp program -queris for a node in its syntax tree. Therefore, when a parser is +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. @@ -644,20 +644,14 @@ does. By default, this function only traverses named nodes, but if @var{all} is non-@code{nil}, it traverses all the nodes. If @var{backward} is -non-nil, it traverses backwards (meaning visiting the last child first +non-@code{nil}, it traverses backwards (i.e., it visits the last child first when traversing down the tree). If @var{limit} is non-@code{nil}, it must be a number that limits the tree traversal to that many levels down the tree. @end defun @defun treesit-search-forward start predicate &optional all backward -While @code{treesit-search-subtree} traverses the subtree of a node, -this function usually starts with a leaf node and traverses every node -comes after it in terms of buffer position. It is useful for -answering questions like ``what is the first node after @var{start} in -the buffer that satisfies some condition?'' - -Like @code{treesit-search-subtree}, this function also traverse the +Like @code{treesit-search-subtree}, this function also traverses the parse tree and matches each node with @var{predicate} (except for @var{start}), where @var{predicate} can be a (case-insensitive) regexp or a function. For a tree like the below where @var{start} is marked @@ -675,15 +669,24 @@ o o 5 +-+-+ +--+--+ | | | | | 8 9 11 12 13 @end group +@end example Note that this function doesn't traverse the subtree of @var{start}, and it always traverse leaf nodes first, then upwards. -@end example Like @code{treesit-search-subtree}, this function only searches for named nodes by default, but if @var{all} is non-@code{nil}, it searches for all nodes. If @var{backward} is non-@code{nil}, it searches backwards. + +@c FIXME: Still not very clear: the difference between ``traverse +@c a subtree of a node'' and ``traverse every node that comes after +@c it''. +While @code{treesit-search-subtree} traverses the subtree of a node, +this function usually starts with a leaf node and traverses every node +that comes after it in the buffer position order. It is useful for +answering questions like ``what is the first node after @var{start} in +the buffer that satisfies some condition?'' @end defun @defun treesit-search-forward-goto predicate side &optional all backward @@ -1172,11 +1175,11 @@ names in other patterns. @heading S-expression patterns -@cindex patterns as sexps +@cindex tree-sitter patterns as sexps @cindex patterns, tree-sitter, in sexp form Besides strings, Emacs provides a s-expression based syntax for -patterns. It largely resembles the string-based syntax. For example, -the following query +tree-sitter patterns. It largely resembles the string-based syntax. +For example, the following query @example @group -- 2.39.2