diff options
Diffstat (limited to 'doc/lispref')
| -rw-r--r-- | doc/lispref/ChangeLog.1 | 2 | ||||
| -rw-r--r-- | doc/lispref/compile.texi | 2 | ||||
| -rw-r--r-- | doc/lispref/display.texi | 44 | ||||
| -rw-r--r-- | doc/lispref/edebug.texi | 23 | ||||
| -rw-r--r-- | doc/lispref/eval.texi | 3 | ||||
| -rw-r--r-- | doc/lispref/modes.texi | 43 | ||||
| -rw-r--r-- | doc/lispref/parsing.texi | 127 | ||||
| -rw-r--r-- | doc/lispref/text.texi | 2 | ||||
| -rw-r--r-- | doc/lispref/tips.texi | 2 |
9 files changed, 185 insertions, 63 deletions
diff --git a/doc/lispref/ChangeLog.1 b/doc/lispref/ChangeLog.1 index 82840aed1d6..361e816bc37 100644 --- a/doc/lispref/ChangeLog.1 +++ b/doc/lispref/ChangeLog.1 @@ -5150,7 +5150,7 @@ * backups.texi (Making Backups): * modes.texi (Example Major Modes): Use recommended coding style. - (Major Mode Basics, Derived Modes): Encourge more strongly use of + (Major Mode Basics, Derived Modes): Encourage more strongly use of define-derived-mode. Mention completion-at-point-functions. 2010-12-13 Chong Yidong <cyd@stupidchicken.com> diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 3e397349995..ae4905bb1f9 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -930,7 +930,7 @@ used by Emacs to natively-compile any Lisp file or byte-compiled Lisp file that is loaded into Emacs, when no natively-compiled file for it is available. Note that because of this use of a subprocess, native compilation may produce warning and errors which byte-compilation does -not, and lisp code may thus need to be modified to work correctly. See +not, and Lisp code may thus need to be modified to work correctly. See @code{native-comp-async-report-warnings-errors} in @pxref{Native-Compilation Variables} for more details. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 4111a86aa7e..5397489e44f 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -346,6 +346,20 @@ The default value is the function that clears the message displayed in an active minibuffer. @end defvar +@defopt set-message-functions +The value of this user option is a list of functions to be called for +handling display of echo-area messages. Each function is called with +one argument, the text of the message to display. If the function +returns a string, that string replaces the original message, and the +next function in the list is called with the new message text. If the +function returns @code{nil}, the next function in the list is called +with the same text; if the last function in the list returns +@code{nil}, the message text is displayed in the echo area. If the +function returns a non-@code{nil} value that is not a string, the +message is considered to be handled, and no further functions in the +list are called. +@end defopt + @defvar inhibit-message When this variable is non-@code{nil}, @code{message} and related functions will not use the Echo Area to display messages. @@ -3043,17 +3057,23 @@ If @var{frame} is @code{t}, this function sets the default attributes for newly created frames; they will effectively override the attribute values specified by @code{defface}. If @var{frame} is @code{nil}, this function sets the attributes for all existing frames, as well as -for newly created frames. However, if you want to @emph{reset} the -value of an attribute to @code{unspecified} in a way that also affects -newly created frames, you @emph{must} explicitly call this function -with @var{frame} set to @code{t} and the value of the attribute set to -@code{unspecified} (@emph{not} @code{nil}!@:), in addition to the call -with @var{frame} set to @code{nil}. This is because the default -attributes for newly created frames are merged with the face's spec in -@code{defface} when a new frame is created, and so having -@code{unspecified} in the default attributes for new frames will be -unable to override @code{defface}; the special call to this function -as described above will arrange for @code{defface} to be overridden. +for newly created frames. + +To @emph{unset} the value of an attribute, that is, to indicate that +the face doesn't by itself specify a value for the attribute, the +special value @code{unspecified} (@emph{not} @code{nil}!@:) must be +used. + +Note that the attribute-value pairs are evaluated in the order they +are specified, except the @code{:family} and @code{:foundry} +attributes, which are evaluated first. This means both that only the +last value of a given attribute will be used, and that in some cases a +different order will give different results. For example, when +@code{:weight} is placed before @code{:font}, the weight value is +applied to the current font of the face, and might be rounded to the +closest available weight of that font, whereas when @code{:font} is +placed before @code{:weight} the weight value is applied to the +specified font. @end defun The following commands and functions mostly provide compatibility @@ -6280,7 +6300,7 @@ embedding large images, comparing to @code{svg-embed}, because all the work is done directly by librsvg. @lisp -;; Embeding /tmp/subdir/rms.jpg and /tmp/another/rms.jpg +;; Embedding /tmp/subdir/rms.jpg and /tmp/another/rms.jpg (svg-embed-base-uri-image svg "subdir/rms.jpg" :width "100px" :height "100px" :x "50px" :y "75px") diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 1562a378421..93bafce1f38 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -171,14 +171,13 @@ of the variable @code{edebug-all-defs}. @findex eval-region @r{(Edebug)} @findex eval-buffer @r{(Edebug)} -@findex eval-current-buffer @r{(Edebug)} If @code{edebug-all-defs} is non-@code{nil}, then the commands -@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer} -also instrument any definitions they evaluate. Similarly, -@code{edebug-all-forms} controls whether @code{eval-region} should -instrument @emph{any} form, even non-defining forms. This doesn't apply -to loading or evaluations in the minibuffer. The command @kbd{M-x -edebug-all-forms} toggles this option. +@code{eval-region}, and @code{eval-buffer} also instrument any +definitions they evaluate. Similarly, @code{edebug-all-forms} +controls whether @code{eval-region} should instrument @emph{any} form, +even non-defining forms. This doesn't apply to loading or evaluations +in the minibuffer. The command @kbd{M-x edebug-all-forms} toggles +this option. @findex edebug-eval-top-level-form @findex edebug-defun @@ -1635,8 +1634,8 @@ but only when you also use Edebug. @defopt edebug-all-defs If this is non-@code{nil}, normal evaluation of defining forms such as @code{defun} and @code{defmacro} instruments them for Edebug. This -applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer}, -and @code{eval-current-buffer}. +applies to @code{eval-defun}, @code{eval-region} and +@code{eval-buffer}. Use the command @kbd{M-x edebug-all-defs} to toggle the value of this option. @xref{Instrumenting}. @@ -1644,9 +1643,9 @@ option. @xref{Instrumenting}. @defopt edebug-all-forms If this is non-@code{nil}, the commands @code{eval-defun}, -@code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer} -instrument all forms, even those that don't define anything. -This doesn't apply to loading or evaluations in the minibuffer. +@code{eval-region} and @code{eval-buffer} instrument all forms, even +those that don't define anything. This doesn't apply to loading or +evaluations in the minibuffer. Use the command @kbd{M-x edebug-all-forms} to toggle the value of this option. @xref{Instrumenting}. diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 11c321b32ed..159e440a989 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -819,9 +819,6 @@ output of the output functions is printed in the echo area. (@pxref{Unloading}), and defaults to @code{buffer-file-name} (@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil}, @code{read} converts strings to unibyte whenever possible. - -@findex eval-current-buffer -@code{eval-current-buffer} is an alias for this command. @end deffn @defopt max-lisp-eval-depth diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index c44938f3929..de17969566d 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -2841,6 +2841,35 @@ function uses @code{imenu-generic-expression} instead. Setting this variable makes it buffer-local in the current buffer. @end defvar +If built with tree-sitter, Emacs can automatically generate an Imenu +index if the major mode sets relevant variables. + +@defvar treesit-simple-imenu-settings +This variable instructs Emacs how to generate Imenu indexes. It +should be a list of @w{(@var{category} @var{regexp} @var{pred} +@var{name-fn})}. + +@var{category} should be the name of a category, like "Function", +"Class", etc. @var{regexp} should be a regexp matching the type of +nodes that belong to @var{category}. @var{pred} should be either +@code{nil} or a function that takes a node as the argument. It should +return non-@code{nil} if the node is a valid node for @var{category}, +or @code{nil} if not. + +@var{category} could also be @code{nil}. In which case the entries +matched by @var{regexp} and @var{pred} are not grouped under +@var{category}. + +@var{name-fn} should be either @var{nil} or a function that takes a +defun node and returns the name of that defun, e.g., the function name +for a function definition. If @var{name-fn} is @var{nil}, +@code{treesit-defun-name} (@pxref{Tree-sitter major modes}) is used +instead. + +@code{treesit-major-mode-setup} (@pxref{Tree-sitter major modes}) +automatically sets up Imenu if this variable is non-@code{nil}. +@end defvar + @node Font Lock Mode @section Font Lock Mode @cindex Font Lock mode @@ -4023,11 +4052,12 @@ This function takes a series of @var{query-spec}s, where each @var{:keyword}/@var{value} pairs. Each @var{query} is a tree-sitter query in either the string, s-expression or compiled form. +@c FIXME: Cross-ref treesit-font-lock-level to user manual. For each @var{query}, the @var{:keyword}/@var{value} pairs that precede it add meta information to it. The @code{:lang} keyword declares @var{query}'s language. The @code{:feature} keyword sets the feature name of @var{query}. Users can control which features are -enabled with @code{font-lock-maximum-decoration} and +enabled with @code{treesit-font-lock-level} and @code{treesit-font-lock-feature-list} (described below). These two keywords are mandatory. @@ -4067,10 +4097,11 @@ priority. If a capture name is neither a face nor a function, it is ignored. @end defun +@c FIXME: Cross-ref treesit-font-lock-level to user manual. @defvar treesit-font-lock-feature-list This is a list of lists of feature symbols. Each element of the list is a list that represents a decoration level. -@code{font-lock-maximum-decoration} controls which levels are +@code{treesit-font-lock-level} controls which levels are activated. Each element of the list is a list of the form @w{@code{(@var{feature} @@ -5024,6 +5055,14 @@ comment-start token. Comment-start tokens are defined by regular expression @code{comment-start-skip}. This function assumes @var{parent} is the comment node. +@item prev-adaptive-prefix +This anchor is a function that is called with 3 arguments: @var{node}, +@var{parent}, and @var{bol}. It tries to go to the beginning of the +previous non-empty line, and matches @code{adaptive-fill-regexp}. If +there is a match, this function returns the end of the match, +otherwise it returns nil. This anchor is useful for a +@code{indent-relative}-like indent behavior for block comments. + @end ftable @end defvar 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 diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index ef938e88ecf..98349099930 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -5351,7 +5351,7 @@ called @var{gif}, you have to mark it specially to let @end defun -@defun sqlite-select db query &optional values result-type +@defun sqlite-select db query &optional values return-type Select some data from @var{db} and return them. For instance: @lisp diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 3a1f6de12b2..3216a353958 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -804,7 +804,7 @@ Finally, to create a hyperlink to URLs, write the single-quoted URL, preceded by @samp{URL}. For example, @smallexample -The GNU project wesite has more information (see URL +The GNU project website has more information (see URL `https://www.gnu.org/'). @end smallexample |