Merge from origin/emacs-29
8f62e7b85fDescribe primarily the Emacs s-exp dialect for treesit qu...eacd75df4e; Improve documentation of overlay prioritiesb3f11e94faFix documentation of :predicate in 'define-globalized-min...
This commit is contained in:
Eli Zaretskii
commit
5fa9458511
4 changed files with 123 additions and 108 deletions
|
|
@ -1792,34 +1792,43 @@ of them:
|
|||
@table @code
|
||||
@item priority
|
||||
@kindex priority @r{(overlay property)}
|
||||
This property's value determines the priority of the overlay.
|
||||
If you want to specify a priority value, use either @code{nil}
|
||||
(or zero), or a positive integer. Any other value has undefined behavior.
|
||||
This property's value determines the priority of the overlay. If you
|
||||
want to specify a priority value, use either @code{nil} (or zero), or
|
||||
a positive integer, or a cons of two values. Any other value triggers
|
||||
undefined behavior.
|
||||
|
||||
The priority matters when two or more overlays cover the same
|
||||
character and both specify the same property with different values;
|
||||
the one whose @code{priority} value is larger overrides the other.
|
||||
the one whose @code{priority} value is higher overrides the other.
|
||||
(For the @code{face} property, the higher priority overlay's value
|
||||
does not completely override the other value; instead, its face
|
||||
attributes override the face attributes of the @code{face} property
|
||||
whose priority is lower.) If two overlays have the same priority
|
||||
value, and one is nested in the other, then the inner one will prevail
|
||||
over the outer one. If neither is nested in the other then you should
|
||||
not make assumptions about which overlay will prevail.
|
||||
does not completely override the other value; instead, its individual
|
||||
face attributes override the corresponding face attributes of the
|
||||
@code{face} property whose priority is lower.) If two overlays have
|
||||
the same priority value, and one is ``nested'' in the other (i.e.,
|
||||
covers fewer buffer or string positions), then the inner one will
|
||||
prevail over the outer one. If neither is nested in the other then
|
||||
you should not make assumptions about which overlay will prevail.
|
||||
|
||||
When a Lisp program puts overlays with defined priorities on text that
|
||||
might have overlays without priorities, this could cause undesirable
|
||||
results, because any overlay with a positive priority value will
|
||||
override all the overlays without a priority. Since most Emacs
|
||||
features that use overlays don't specify priorities for their
|
||||
overlays, integer priorities should be used with care. Instead of
|
||||
using integer priorities and risk overriding other overlays, you can
|
||||
use priority values of the form @w{@code{(@var{primary} . @var{secondary})}},
|
||||
where the @var{primary} value is used as described above, and
|
||||
@var{secondary} is the fallback value used when @var{primary} and the
|
||||
nesting considerations fail to resolve the precedence between
|
||||
overlays. In particular, priority value @w{@code{(nil . @var{n})}},
|
||||
with @var{n} a positive integer, allows to have the overlays ordered
|
||||
by priority when necessary without completely overriding other
|
||||
overlays.
|
||||
|
||||
Currently, all overlays take priority over text properties.
|
||||
|
||||
Note that Emacs sometimes uses non-numeric priority values for some of
|
||||
its internal overlays, so do not try to do arithmetic on the priority
|
||||
of an overlay (unless it is one that you created). In particular, the
|
||||
overlay used for showing the region uses a priority value of the form
|
||||
@w{@code{(@var{primary} . @var{secondary})}}, where the @var{primary}
|
||||
value is used as described above, and @var{secondary} is the fallback
|
||||
value used when @var{primary} and the nesting considerations fail to
|
||||
resolve the precedence between overlays. However, you are advised not
|
||||
to design Lisp programs based on this implementation detail; if you
|
||||
need to put overlays in priority order, use the @var{sorted} argument
|
||||
of @code{overlays-at}. @xref{Finding Overlays}.
|
||||
If you need to put overlays in priority order, use the @var{sorted}
|
||||
argument of @code{overlays-at}. @xref{Finding Overlays}.
|
||||
|
||||
@item window
|
||||
@kindex window @r{(overlay property)}
|
||||
|
|
@ -3329,8 +3338,8 @@ enough to the overlay, Emacs applies the face or face attributes
|
|||
specified by the @code{mouse-face} property instead. @xref{Overlay
|
||||
Properties}.
|
||||
|
||||
When multiple overlays cover one character, an overlay with higher
|
||||
priority overrides those with lower priority. @xref{Overlays}.
|
||||
When multiple overlays cover the same character, an overlay with
|
||||
higher priority overrides those with lower priority. @xref{Overlays}.
|
||||
|
||||
@item
|
||||
If the text contains a @code{face} or @code{mouse-face} property,
|
||||
|
|
|
|||
|
|
@ -1888,11 +1888,14 @@ user option called the same as the global mode variable, but with
|
|||
@code{-modes} instead of @code{-mode} at the end, i.e.@:
|
||||
@code{@var{global-mode}s}. This variable will be used in a predicate
|
||||
function that determines whether the minor mode should be activated in
|
||||
a particular major mode. Valid values of @code{:predicate} include
|
||||
@code{t} (use in all major modes), @code{nil} (don't use in any major
|
||||
modes), or a list of mode names, optionally preceded with @code{not}
|
||||
(as in @w{@code{(not @var{mode-name} @dots{})}}). These elements can
|
||||
be mixed, as shown in the following examples.
|
||||
a particular major mode, and users can customize the value of the
|
||||
variable to control the modes in which the minor mode will be switched
|
||||
on. Valid values of @code{:predicate} (and thus valid values of the
|
||||
user option it creates) include @code{t} (use in all major modes),
|
||||
@code{nil} (don't use in any major modes), or a list of mode names,
|
||||
optionally preceded with @code{not} (as in @w{@code{(not
|
||||
@var{mode-name} @dots{})}}). These elements can be mixed, as shown in
|
||||
the following examples.
|
||||
|
||||
@example
|
||||
(c-mode (not mail-mode message-mode) text-mode)
|
||||
|
|
|
|||
|
|
@ -1131,9 +1131,9 @@ Now we can introduce the @dfn{query functions}.
|
|||
|
||||
@defun treesit-query-capture node query &optional beg end node-only
|
||||
This function matches patterns in @var{query} within @var{node}. The
|
||||
argument @var{query} can be either a string, an s-expression, or a
|
||||
compiled query object. For now, we focus on the string syntax;
|
||||
s-expression syntax and compiled queries are described at the end of
|
||||
argument @var{query} can be either an s-expression, a string, or a
|
||||
compiled query object. For now, we focus on the s-expression syntax;
|
||||
string syntax and compiled queries are described at the end of
|
||||
the section.
|
||||
|
||||
The argument @var{node} can also be a parser or a language symbol. A
|
||||
|
|
@ -1165,8 +1165,8 @@ For example, suppose @var{node}'s text is @code{1 + 2}, and
|
|||
@example
|
||||
@group
|
||||
(setq query
|
||||
"(binary_expression
|
||||
(number_literal) @@number-in-exp) @@biexp")
|
||||
'((binary_expression
|
||||
(number_literal) @@number-in-exp) @@biexp)
|
||||
@end group
|
||||
@end example
|
||||
|
||||
|
|
@ -1187,8 +1187,8 @@ For example, it could have two top-level patterns:
|
|||
@example
|
||||
@group
|
||||
(setq query
|
||||
"(binary_expression) @@biexp
|
||||
(number_literal) @@number @@biexp")
|
||||
'((binary_expression) @@biexp
|
||||
(number_literal) @@number @@biexp)
|
||||
@end group
|
||||
@end example
|
||||
|
||||
|
|
@ -1246,23 +1246,23 @@ field, say, a @code{function_definition} without a @code{body} field:
|
|||
@subheading Quantify node
|
||||
|
||||
@cindex quantify node, tree-sitter
|
||||
Tree-sitter recognizes quantification operators @samp{*}, @samp{+},
|
||||
and @samp{?}. Their meanings are the same as in regular expressions:
|
||||
@samp{*} matches the preceding pattern zero or more times, @samp{+}
|
||||
matches one or more times, and @samp{?} matches zero or one times.
|
||||
Tree-sitter recognizes quantification operators @samp{:*}, @samp{:+},
|
||||
and @samp{:?}. Their meanings are the same as in regular expressions:
|
||||
@samp{:*} matches the preceding pattern zero or more times, @samp{:+}
|
||||
matches one or more times, and @samp{:?} matches zero or one times.
|
||||
|
||||
For example, the following pattern matches @code{type_declaration}
|
||||
nodes that have @emph{zero or more} @code{long} keywords.
|
||||
|
||||
@example
|
||||
(type_declaration "long"*) @@long-type
|
||||
(type_declaration "long" :*) @@long-type
|
||||
@end example
|
||||
|
||||
The following pattern matches a type declaration that may or may not
|
||||
have a @code{long} keyword:
|
||||
|
||||
@example
|
||||
(type_declaration "long"?) @@long-type
|
||||
(type_declaration "long" :?) @@long-type
|
||||
@end example
|
||||
|
||||
@subheading Grouping
|
||||
|
|
@ -1272,15 +1272,14 @@ groups and apply quantification operators to them. For example, to
|
|||
express a comma-separated list of identifiers, one could write
|
||||
|
||||
@example
|
||||
(identifier) ("," (identifier))*
|
||||
(identifier) ("," (identifier)) :*
|
||||
@end example
|
||||
|
||||
@subheading Alternation
|
||||
|
||||
Again, similar to regular expressions, we can express ``match any one
|
||||
of these patterns'' in a pattern. The syntax is a list of patterns
|
||||
enclosed in square brackets. For example, to capture some keywords in
|
||||
C, the pattern would be
|
||||
of these patterns'' in a pattern. The syntax is a vector of patterns.
|
||||
For example, to capture some keywords in C, the pattern would be
|
||||
|
||||
@example
|
||||
@group
|
||||
|
|
@ -1295,7 +1294,7 @@ C, the pattern would be
|
|||
|
||||
@subheading Anchor
|
||||
|
||||
The anchor operator @samp{.} can be used to enforce juxtaposition,
|
||||
The anchor operator @code{:anchor} can be used to enforce juxtaposition,
|
||||
i.e., to enforce two things to be directly next to each other. The
|
||||
two ``things'' can be two nodes, or a child and the end of its parent.
|
||||
For example, to capture the first child, the last child, or two
|
||||
|
|
@ -1304,19 +1303,19 @@ adjacent children:
|
|||
@example
|
||||
@group
|
||||
;; Anchor the child with the end of its parent.
|
||||
(compound_expression (_) @@last-child .)
|
||||
(compound_expression (_) @@last-child :anchor)
|
||||
@end group
|
||||
|
||||
@group
|
||||
;; Anchor the child with the beginning of its parent.
|
||||
(compound_expression . (_) @@first-child)
|
||||
(compound_expression :anchor (_) @@first-child)
|
||||
@end group
|
||||
|
||||
@group
|
||||
;; Anchor two adjacent children.
|
||||
(compound_expression
|
||||
(_) @@prev-child
|
||||
.
|
||||
:anchor
|
||||
(_) @@next-child)
|
||||
@end group
|
||||
@end example
|
||||
|
|
@ -1332,8 +1331,8 @@ example, with the following pattern:
|
|||
@example
|
||||
@group
|
||||
(
|
||||
(array . (_) @@first (_) @@last .)
|
||||
(#equal @@first @@last)
|
||||
(array :anchor (_) @@first (_) @@last :anchor)
|
||||
(:equal @@first @@last)
|
||||
)
|
||||
@end group
|
||||
@end example
|
||||
|
|
@ -1341,22 +1340,22 @@ example, with the following pattern:
|
|||
@noindent
|
||||
tree-sitter only matches arrays where the first element is equal 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}.
|
||||
group them together. Currently there are three predicates:
|
||||
@code{:equal}, @code{:match}, and @code{:pred}.
|
||||
|
||||
@deffn Predicate equal arg1 arg2
|
||||
@deffn Predicate :equal arg1 arg2
|
||||
Matches if @var{arg1} is equal to @var{arg2}. Arguments can be either
|
||||
strings or capture names. Capture names represent the text that the
|
||||
captured node spans in the buffer.
|
||||
@end deffn
|
||||
|
||||
@deffn Predicate match regexp capture-name
|
||||
@deffn Predicate :match regexp capture-name
|
||||
Matches if the text that @var{capture-name}'s node spans in the buffer
|
||||
matches regular expression @var{regexp}. Matching is case-sensitive.
|
||||
matches regular expression @var{regexp}, given as a string literal.
|
||||
Matching is case-sensitive.
|
||||
@end deffn
|
||||
|
||||
@deffn Predicate pred fn &rest nodes
|
||||
@deffn Predicate :pred fn &rest nodes
|
||||
Matches if function @var{fn} returns non-@code{nil} when passed each
|
||||
node in @var{nodes} as arguments. The function runs with the current
|
||||
buffer set to the buffer of node being queried.
|
||||
|
|
@ -1366,28 +1365,13 @@ 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.
|
||||
|
||||
@heading S-expression patterns
|
||||
@heading String patterns
|
||||
|
||||
@cindex tree-sitter patterns as sexps
|
||||
@cindex patterns, tree-sitter, in sexp form
|
||||
Besides strings, Emacs provides an s-expression based syntax for
|
||||
tree-sitter patterns. It largely resembles the string-based syntax.
|
||||
For example, the following query
|
||||
|
||||
@example
|
||||
@group
|
||||
(treesit-query-capture
|
||||
node "(addition_expression
|
||||
left: (_) @@left
|
||||
\"+\" @@plus-sign
|
||||
right: (_) @@right) @@addition
|
||||
|
||||
[\"return\" \"break\"] @@keyword")
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
is equivalent to
|
||||
@cindex tree-sitter patterns as strings
|
||||
@cindex patterns, tree-sitter, in string form
|
||||
Besides s-expressions, Emacs allows the tree-sitter's native query
|
||||
syntax to be used by writing them as strings. It largely resembles
|
||||
the s-expression syntax. For example, the following query
|
||||
|
||||
@example
|
||||
@group
|
||||
|
|
@ -1401,36 +1385,40 @@ is equivalent to
|
|||
@end group
|
||||
@end example
|
||||
|
||||
Most patterns can be written directly as strange but nevertheless
|
||||
valid s-expressions. Only a few of them need modification:
|
||||
|
||||
@itemize
|
||||
@item
|
||||
Anchor @samp{.} is written as @code{:anchor}.
|
||||
@item
|
||||
@samp{?} is written as @samp{:?}.
|
||||
@item
|
||||
@samp{*} is written as @samp{:*}.
|
||||
@item
|
||||
@samp{+} is written as @samp{:+}.
|
||||
@item
|
||||
@code{#equal} is written as @code{:equal}. In general, predicates
|
||||
change their @samp{#} to @samp{:}.
|
||||
@end itemize
|
||||
|
||||
For example,
|
||||
@noindent
|
||||
is equivalent to
|
||||
|
||||
@example
|
||||
@group
|
||||
"(
|
||||
(compound_expression . (_) @@first (_)* @@rest)
|
||||
(#match \"love\" @@first)
|
||||
)"
|
||||
(treesit-query-capture
|
||||
node "(addition_expression
|
||||
left: (_) @@left
|
||||
\"+\" @@plus-sign
|
||||
right: (_) @@right) @@addition
|
||||
|
||||
[\"return\" \"break\"] @@keyword")
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
is written in s-expression syntax as
|
||||
Most patterns can be written directly as s-expressions inside a string.
|
||||
Only a few of them need modification:
|
||||
|
||||
@itemize
|
||||
@item
|
||||
Anchor @code{:anchor} is written as @samp{.}.
|
||||
@item
|
||||
@samp{:?} is written as @samp{?}.
|
||||
@item
|
||||
@samp{:*} is written as @samp{*}.
|
||||
@item
|
||||
@samp{:+} is written as @samp{+}.
|
||||
@item
|
||||
@code{:equal}, @code{:match} and @code{:pred} are written as
|
||||
@code{#equal}, @code{#match} and @code{#pred}, respectively.
|
||||
In general, predicates change their @samp{:} to @samp{#}.
|
||||
@end itemize
|
||||
|
||||
For example,
|
||||
|
||||
@example
|
||||
@group
|
||||
|
|
@ -1441,6 +1429,18 @@ is written in s-expression syntax as
|
|||
@end group
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
is written in string form as
|
||||
|
||||
@example
|
||||
@group
|
||||
"(
|
||||
(compound_expression . (_) @@first (_)* @@rest)
|
||||
(#match \"love\" @@first)
|
||||
)"
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@heading Compiling queries
|
||||
|
||||
@cindex compiling tree-sitter queries
|
||||
|
|
@ -1461,7 +1461,7 @@ validate and debug the query.
|
|||
@end defun
|
||||
|
||||
@defun treesit-query-language query
|
||||
This function return the language of @var{query}.
|
||||
This function returns the language of @var{query}.
|
||||
@end defun
|
||||
|
||||
@defun treesit-query-expand query
|
||||
|
|
@ -1653,7 +1653,7 @@ ranges for @acronym{CSS} and JavaScript parsers:
|
|||
(setq css-range
|
||||
(treesit-query-range
|
||||
'html
|
||||
"(style_element (raw_text) @@capture)"))
|
||||
'((style_element (raw_text) @@capture))))
|
||||
(treesit-parser-set-included-ranges css css-range)
|
||||
@end group
|
||||
|
||||
|
|
@ -1662,7 +1662,7 @@ ranges for @acronym{CSS} and JavaScript parsers:
|
|||
(setq js-range
|
||||
(treesit-query-range
|
||||
'html
|
||||
"(script_element (raw_text) @@capture)"))
|
||||
'((script_element (raw_text) @@capture))))
|
||||
(treesit-parser-set-included-ranges js js-range)
|
||||
@end group
|
||||
@end example
|
||||
|
|
|
|||
|
|
@ -453,14 +453,17 @@ TURN-ON is a function that will be called with no args in every buffer
|
|||
and that should try to turn MODE on if applicable for that buffer.
|
||||
|
||||
Each of KEY VALUE is a pair of CL-style keyword arguments.
|
||||
The :predicate argument specifies in which major modes should the
|
||||
The :predicate key specifies in which major modes should the
|
||||
globalized minor mode be switched on. The value should be t (meaning
|
||||
switch on the minor mode in all major modes), nil (meaning don't
|
||||
switch on in any major mode), a list of modes (meaning switch on only
|
||||
in those modes and their descendants), or a list (not MODES...),
|
||||
meaning switch on in any major mode except MODES. The value can also
|
||||
mix all of these forms, see the info node `Defining Minor Modes' for
|
||||
details.
|
||||
details. The :predicate key causes the macro to create a user option
|
||||
named the same as MODE, but ending with \"-modes\" instead of \"-mode\".
|
||||
That user option can then be used to customize in which modes this
|
||||
globalized minor mode will be switched on.
|
||||
As the minor mode defined by this function is always global, any
|
||||
:global keyword is ignored.
|
||||
Other keywords have the same meaning as in `define-minor-mode',
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue