procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; Minor copyedits of tree-sitter stuff in ELisp manual

Browse source 
* doc/lispref/parsing.texi (Pattern Matching):
* doc/lispref/modes.texi (Parser-based Font Lock)
(Parser-based Indentation): Fix wording and typos.
This commit is contained in:
Eli Zaretskii 2022-10-23 11:14:18 +03:00
parent 57b904f4ba
commit 31f7543099
2 changed files with 76 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

99
doc/lispref/modes.texi
View file

@ -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

29
doc/lispref/parsing.texi
View file

@ -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