diff options
Diffstat (limited to 'doc/lispref')
43 files changed, 1527 insertions, 636 deletions
diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 271f06edddc..a7701c5f98e 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -24,6 +24,7 @@ SHELL = @SHELL@ # Standard configure variables. srcdir = @srcdir@ +top_builddir = @top_builddir@ buildinfodir = $(srcdir)/../../info # Directory with the (customized) texinfo.tex file. @@ -59,13 +60,7 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips -# 'make' verbosity. -AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ - -AM_V_GEN = $(am__v_GEN_@AM_V@) -am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) -am__v_GEN_0 = @echo " GEN " $@; -am__v_GEN_1 = +-include ${top_builddir}/src/verbose.mk ENVADD = \ $(AM_V_GEN)TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ @@ -185,6 +180,7 @@ infoclean: $(buildinfodir)/elisp.info-[1-9][0-9] bootstrap-clean maintainer-clean: distclean infoclean + rm -f TAGS .PHONY: install-dvi install-html install-pdf install-ps install-doc @@ -232,5 +228,20 @@ uninstall-pdf: uninstall-doc: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps +ETAGS = ../../lib-src/etags${EXEEXT} + +${ETAGS}: FORCE + $(MAKE) -C $(dir $@) $(notdir $@) + +texifiles = $(wildcard ${srcdir}/*.texi) + +TAGS: ${ETAGS} $(texifiles) + $(AM_V_GEN)${ETAGS} $(texifiles) + +tags: TAGS +.PHONY: tags + +FORCE: +.PHONY: FORCE ### Makefile ends here diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index c0a4065bdbf..85a4f9e0acc 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -481,6 +481,12 @@ all directory separators were changed to @samp{!} to prevent clashes. (This will not work correctly if your filesystem truncates the resulting name.) +If @var{uniquify} is one of the members of +@code{secure-hash-algorithms}, Emacs constructs the nondirectory part +of the auto-save file name by applying that @code{secure-hash} to the +buffer file name. This avoids any risk of excessively long file +names. + All the transforms in the list are tried, in the order they are listed. When one transform applies, its result is final; no further transforms are tried. diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 69733f91c4a..55e9d00d8bf 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -309,7 +309,6 @@ foo This function renames the current buffer to @var{newname}. An error is signaled if @var{newname} is not a string. -@c Emacs 19 feature Ordinarily, @code{rename-buffer} signals an error if @var{newname} is already in use. However, if @var{unique} is non-@code{nil}, it modifies @var{newname} to make a name that is not in use. Interactively, you can @@ -344,7 +343,6 @@ a name. For example: See also the function @code{get-buffer-create} in @ref{Creating Buffers}. @end defun -@c Emacs 19 feature @defun generate-new-buffer-name starting-name &optional ignore This function returns a name that would be unique for a new buffer---but does not create the buffer. It starts with @var{starting-name}, and @@ -879,7 +877,6 @@ then @code{other-buffer} uses that predicate to decide which buffers to consider. It calls the predicate once for each buffer, and if the value is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. -@c Emacs 19 feature If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning a buffer visible in any window on any visible frame, except as a last resort. If @var{visible-ok} is non-@code{nil}, then it does not matter @@ -1186,7 +1183,7 @@ buffer. the base buffer effectively kills the indirect buffer in that it cannot ever again be the current buffer. -@deffn Command make-indirect-buffer base-buffer name &optional clone +@deffn Command make-indirect-buffer base-buffer name &optional clone inhibit-buffer-hooks This creates and returns an indirect buffer named @var{name} whose base buffer is @var{base-buffer}. The argument @var{base-buffer} may be a live buffer or the name (a string) of an existing buffer. If @@ -1202,6 +1199,8 @@ If @var{base-buffer} is an indirect buffer, its base buffer is used as the base for the new buffer. If, in addition, @var{clone} is non-@code{nil}, the initial state is copied from the actual base buffer, not from @var{base-buffer}. + +@xref{Creating Buffers}, for the meaning of @var{inhibit-buffer-hooks}. @end deffn @deffn Command clone-indirect-buffer newname display-flag &optional norecord diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 3a2c7d019ef..6d450998673 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -144,6 +144,7 @@ commands by adding the @code{interactive} form to them. * Interactive Codes:: The standard letter-codes for reading arguments in various ways. * Interactive Examples:: Examples of how to read interactive arguments. +* Command Modes:: Specifying that commands are for a specific mode. * Generic Commands:: Select among command alternatives. @end menu @@ -156,7 +157,7 @@ commands by adding the @code{interactive} form to them. makes a Lisp function an interactively-callable command, and how to examine a command's @code{interactive} form. -@defspec interactive arg-descriptor +@defspec interactive &optional arg-descriptor &rest modes This special form declares that a function is a command, and that it may therefore be called interactively (via @kbd{M-x} or by entering a key sequence bound to it). The argument @var{arg-descriptor} declares @@ -177,6 +178,10 @@ forms are executed; at this time, if the @code{interactive} form occurs within the body, the form simply returns @code{nil} without even evaluating its argument. +The @var{modes} list allows specifying which modes the command is +meant to be used in. See @ref{Command Modes} for more details about +the effect of specifying @var{modes}, and when to use it. + By convention, you should put the @code{interactive} form in the function body, as the first top-level form. If there is an @code{interactive} form in both the @code{interactive-form} symbol @@ -449,10 +454,13 @@ This kind of input is used by commands such as @code{describe-key} and @code{global-set-key}. @item K -A key sequence, whose definition you intend to change. This works like -@samp{k}, except that it suppresses, for the last input event in the key -sequence, the conversions that are normally used (when necessary) to -convert an undefined key into a defined one. +A key sequence on a form that can be used as input to functions like +@code{define-key}. This works like @samp{k}, except that it +suppresses, for the last input event in the key sequence, the +conversions that are normally used (when necessary) to convert an +undefined key into a defined one (@pxref{Key Sequence Input}), so this +form is usually used when prompting for a new key sequence that is to +be bound to a command. @item m @cindex marker argument @@ -488,7 +496,10 @@ I/O. Point and the mark, as two numeric arguments, smallest first. This is the only code letter that specifies two successive arguments rather than one. This will signal an error if the mark is not set in the buffer -which is current when the command is invoked. No I/O. +which is current when the command is invoked. If Transient Mark mode +is turned on (@pxref{The Mark}) --- as it is by default --- and user +option @code{mark-even-if-inactive} is @code{nil}, Emacs will signal +an error even if the mark @emph{is} set, but is inactive. No I/O. @item s Arbitrary text, read in the minibuffer and returned as a string @@ -588,6 +599,80 @@ Put them into three windows, selecting the last one." @end group @end example +@node Command Modes +@subsection Specifying Modes For Commands +@cindex commands, mode-specific +@cindex commands, specify as mode-specific +@cindex mode-specific commands + +Many commands in Emacs are general, and not tied to any specific mode. +For instance, @kbd{M-x kill-region} can be used in pretty much any +mode that has editable text, and commands that display information +(like @kbd{M-x list-buffers}) can be used in pretty much any context. + +Many other commands, however, are specifically tied to a mode, and +make no sense outside of that context. For instance, @code{M-x +dired-diff} will just signal an error if used outside of a Dired +buffer. + +Emacs therefore has a mechanism for specifying what mode (or modes) a +command ``belongs'' to: + +@lisp +(defun dired-diff (...) + ... + (interactive "p" dired-mode) + ...) +@end lisp + +This will mark the command as applicable to @code{dired-mode} only (or +any modes that are derived from @code{dired-mode}). Any number of +modes can be added to the @code{interactive} form. + +@vindex read-extended-command-predicate +Specifying modes may affect completion in @kbd{M-x}, depending on the +value of @code{read-extended-command-predicate}. + +For instance, when using the +@code{command-completion-default-include-p} predicate, @kbd{M-x} won't +list commands that have been marked as being applicable to a specific +mode (unless you are in a buffer that uses that mode, of course). +This goes for both major and minor modes. + +Marking commands this way will also make @kbd{C-h m} list these +commands (if they aren't bound to any keys). + +If using this extended @code{interactive} form isn't convenient +(because the code is supposed to work in older versions of Emacs that +don't support the extended @code{interactive} form), the following +equivalent declaration (@pxref{Declare Form}) can be used instead: + +@lisp +(declare (modes dired-mode)) +@end lisp + +Which commands to tag with modes is to some degree a matter of taste, +but commands that clearly do not work outside of the mode should be +tagged. This includes commands that will signal an error if called +from somewhere else, but also commands that are destructive when +called from an unexpected mode. (This usually includes most of the +commands that are written for special (i.e., non-editing) modes.) + +Some commands may be harmless, and ``work'' when called from other +modes, but should still be tagged with a mode if they don't actually +make much sense to use elsewhere. For instance, many special modes +have commands to exit the buffer bound to @kbd{q}, and may not do +anything but issue a message like "Goodbye from this mode" and then +call @code{kill-buffer}. This command will ``work'' from any mode, +but it is highly unlikely that anybody would actually want to use the +command outside the context of this special mode. + +Many modes have a set of different commands that start the mode in +different ways (e.g., @code{eww-open-in-new-buffer} and +@code{eww-open-file}). Commands like that should never be tagged as +mode-specific, as they can be issued by the user from pretty much any +context. + @node Generic Commands @subsection Select among Command Alternatives @cindex generic commands @@ -756,6 +841,29 @@ part of the prompt. @result{} t @end group @end example + +@vindex read-extended-command-predicate +@findex command-completion-default-include-p +This command heeds the @code{read-extended-command-predicate} +variable, which can filter out commands that are not applicable to the +current major mode (or enabled minor modes). By default, the value of +this variable is @code{nil}, and no commands are filtered out. +However, customizing it to invoke the function +@code{command-completion-default-include-p} will perform +mode-dependent filtering. @code{read-extended-command-predicate} can +be any predicate function; it will be called with two parameters: the +command's symbol and the current buffer. If should return +non-@code{nil} if the command is to be included when completing in +that buffer. +@end deffn + +@deffn Command execute-extended-command-for-buffer prefix-argument +This is like @code{execute-extended-command}, but limits the commands +offered for completion to those commands that are of particular +relevance to the current major mode (and enabled minor modes). This +includes commands that are tagged with the modes (@pxref{Using +Interactive}), and also commands that are bound to locally active +keymaps. @end deffn @node Distinguish Interactive @@ -3276,6 +3384,12 @@ nil)}. This is the same thing that quitting does. (See @code{signal} in @ref{Errors}.) @end deffn + To quit without aborting a keyboard macro definition or execution, +you can signal the @code{minibuffer-quit} condition. This has almost +the same effect as the @code{quit} condition except that the error +handling in the command loop handles it without exiting keyboard macro +definition or execution. + You can specify a character other than @kbd{C-g} to use for quitting. See the function @code{set-input-mode} in @ref{Input Modes}. @@ -3460,12 +3574,14 @@ commands. @code{recursive-edit}. This function contains the command loop; it also contains a call to @code{catch} with tag @code{exit}, which makes it possible to exit the recursive editing level by throwing to @code{exit} -(@pxref{Catch and Throw}). If you throw a value other than @code{t}, -then @code{recursive-edit} returns normally to the function that called -it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. +(@pxref{Catch and Throw}). If you throw a @code{nil} value, then +@code{recursive-edit} returns normally to the function that called it. +The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. Throwing a @code{t} value causes @code{recursive-edit} to quit, so that control returns to the command loop one level up. This is called @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). +You can also throw a function value. In that case, +@code{recursive-edit} will call it without arguments before returning. Most applications should not use recursive editing, except as part of using the minibuffer. Usually it is more convenient for the user if you diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 66242343157..f48f4f47e8b 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -361,7 +361,7 @@ it does nothing. It always returns @var{function}. These features permit you to write code to be evaluated during compilation of a program. -@defspec eval-and-compile body@dots{} +@defmac eval-and-compile body@dots{} This form marks @var{body} to be evaluated both when you compile the containing code and when you run it (whether compiled or not). @@ -386,9 +386,9 @@ If functions are defined programmatically (with @code{fset} say), then @code{eval-and-compile} can be used to have that done at compile-time as well as run-time, so calls to those functions are checked (and warnings about ``not known to be defined'' suppressed). -@end defspec +@end defmac -@defspec eval-when-compile body@dots{} +@defmac eval-when-compile body@dots{} This form marks @var{body} to be evaluated at compile time but not when the compiled program is loaded. The result of evaluation by the compiler becomes a constant which appears in the compiled program. If @@ -434,7 +434,7 @@ with other versions of Emacs. Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp @samp{#.} reader macro (but not when interpreting) is closer to what @code{eval-when-compile} does. -@end defspec +@end defmac @node Compiler Errors @section Compiler Errors @@ -793,3 +793,251 @@ The @code{silly-loop} function is somewhat more complex: 17 return ; @r{Return value of the top of stack.} @end group @end example + +@node Native Compilation +@chapter Compilation of Lisp to Native Code +@cindex native compilation +@cindex compilation to native code (Emacs Lisp) + +@cindex native code + In addition to the byte-compilation, described in @ref{Byte +Compilation, the previous chapter}, Emacs can also optionally compile +Lisp function definitions into a true compiled code, known as +@dfn{native code}. This feature uses the @file{libgccjit} library, +which is part of the GCC distribution, and requires that Emacs be +built with support for using that library. It also requires to have +GCC and Binutils (the assembler and linker) available on your system +for you to be able to native-compile Lisp code. + +@vindex native-compile@r{, a Lisp feature} + To determine whether the current Emacs process can produce and load +natively-compiled Lisp code, test whether the @code{native-compile} +feature is available (@pxref{Named Features}). Alternatively, call +@code{native-comp-available-p} (@pxref{Native-Compilation Functions}). + + Unlike byte-compiled code, natively-compiled Lisp code is executed +directly by the machine's hardware, and therefore runs at full speed +that the host CPU can provide. The resulting speedup generally +depends on what the Lisp code does, but is usually 2.5 to 5 times +faster than the corresponding byte-compiled code. + + Since native code is generally incompatible between different +systems, the natively-compiled code is @emph{not} transportable from +one machine to another, it can only be used on the same machine where +it was produced or on very similar ones (having the same CPU and +run-time libraries). The transportability of natively-compiled code +is the same as that of shared libraries (@file{.so} or @file{.dll} +files). + + Libraries of natively-compiled code include crucial dependencies on +Emacs Lisp primitives (@pxref{What Is a Function}) and their calling +conventions, and thus Emacs usually won't load natively-compiled code +produced by earlier or later Emacs versions; native compilation of the +same Lisp code by a different Emacs version will usually produce a +natively-compiled library under a unique file name that only that +version of Emacs will be able to load. However, the use of unique +file names allows to have in the same directory several versions of +the same Lisp library natively-compiled by several different versions +of Emacs. + +@vindex no-native-compile + A non-@code{nil} file-local variable binding of +@code{no-byte-compile} (@pxref{Byte Compilation}) also disables the +native compilation of that file. In addition, a similar variable +@code{no-native-compile} disables just the native compilation of the +file. If both @code{no-byte-compile} and @code{no-native-compile} are +specified, the former takes precedence. + +@menu +* Native-Compilation Functions:: Functions to natively-compile Lisp. +* Native-Compilation Variables:: Variables controlling native compilation. +@end menu + +@node Native-Compilation Functions +@section Native-Compilation Functions +@cindex native-compilation functions + + Native-Compilation is implemented as a side effect of +byte-compilation (@pxref{Byte Compilation}). Thus, compiling Lisp +code natively always produces its byte code as well, and therefore all +the rules and caveats of preparing Lisp code for byte compilation +(@pxref{Compilation Functions}) are valid for native-compilation as +well. + + You can natively-compile either a single function or macro +definition, or a whole file of Lisp code, with the +@code{native-compile} function. Natively-compiling a file will +produce both the corresponding @file{.elc} file with byte code and the +@file{.eln} file with native code. + +@findex native-comp-limple-mode +@vindex native-comp-verbose + Native compilation might produce warning or error messages; these +are normally recorded in the buffer called +@file{*Native-compile-Log*}. In interactive sessions, it uses the +special LIMPLE mode (@code{native-comp-limple-mode}), which sets up +@code{font-lock} as appropriate for this log, and is otherwise the +same as Fundamental mode. Logging of messages resulting from +native-compilation can be controlled by the @code{native-comp-verbose} +variable (@pxref{Native-Compilation Variables}). + + When Emacs is run non-interactively, messages produced by +native-compilation are reported by calling @code{message} +(@pxref{Displaying Messages}), and are usually displayed on the +standard error stream of the terminal from which Emacs was invoked. + +@defun native-compile function-or-file &optional output +This function compiles @var{function-or-file} into native code. The +argument @var{function-or-file} can be a function symbol, a Lisp form, +or a name (a string) of the file which contains the Emacs Lisp source +code to compile. If the optional argument @var{output} is provided, +it must be a string specifying the name of the file to write the +compiled code into. Otherwise, if @var{function-or-file} is a +function or a Lisp form, this function returns the compiled object, +and if @var{function-or-file} is a file name, the function returns the +full absolute name of the file it created for the compiled code. The +output file is by default given the @file{.eln} extension. + +This function runs the final phase of the native compilation, which +invokes GCC via @file{libgccjit}, in a separate subprocess, which +invokes the same Emacs executable as the process that called this +function. +@end defun + +@defun batch-native-compile +This function runs native-compilation on files specified on the Emacs +command line in batch mode. It must be used only in a batch execution +of Emacs, as it kills Emacs upon completion of the compilation. If +one or more of the files fail to compile, the Emacs process will +attempt to compile all the other files, and will terminate with a +non-zero status code. +@end defun + +Native compilation can be run entirely asynchronously, in a subprocess +of the main Emacs process. This leaves the main Emacs process free to +use while the compilation runs in the background. This is the method +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. + +@defun native-compile-async files &optional recursively load selector +This function compiles the named @var{files} asynchronously. The +argument @var{files} should be a single file name (a string) or a list +of one or more file and/or directory names. If directories are +present in the list, the optional argument @var{recursively} should be +non-@code{nil} to cause the compilation to recurse into those +directories. If @var{load} is non-@code{nil}, Emacs will load each +file that it succeeded to compile. The optional argument +@var{selector} allows control of which of @var{files} will be +compiled; it can have one of the following values: + +@table @asis +@item @code{nil} or omitted +Select all the files and directories in @var{files}. +@item a regular expression string +Select the files and directories whose names match the regexp. +@item a function +A predicate function, which will be called with each file and +directory in @var{files}, and should return non-@code{nil} if the file +or the directory should be selected for compilation. +@end table + +On systems with multiple CPU execution units, when @var{files} names +more than one file, this function will normally start several +compilation subprocesses in parallel, under the control of +@code{native-comp-async-jobs-number} (@pxref{Native-Compilation +Variables}). +@end defun + + The following function allows Lisp programs to test whether +native-compilation is available at runtime. + +@defun native-comp-available-p +This function returns non-@code{nil} if the running Emacs process has +the native-compilation support compiled into it. On systems that load +@file{libgccjit} dynamically, it also makes sure that library is +available and can be loaded. Lisp programs that need to know up front +whether native-compilation is available should use this predicate. +@end defun + +@node Native-Compilation Variables +@section Native-Compilation Variables +@cindex native-compilation variables + + This section documents the variables that control +native-compilation. + +@defopt native-comp-speed +This variable specifies the optimization level for native compilation. +Its value should be a number between @minus{}1 and 3. Values between +0 and 3 specify the optimization levels equivalent to the +corresponding compiler @option{-O0}, @option{-O1}, etc.@: command-line +options of the compiler. The value @minus{}1 means disable +native-compilation; functions and files will be only byte-compiled. +The default value is 2. +@end defopt + +@defopt native-comp-debug +This variable specifies the level of debugging information produced by +native-compilation. Its value should be a number between zero and 3, +with the following meaning: + +@table @asis +@item 0 +No debugging output. This is the default. +@item 1 +Emit debugging symbols with the native code. This allows easier +debugging of the native code with debuggers such as @command{gdb}. +@item 2 +Like 1, and in addition dump pseudo-C code. +@item 3 +Like 2, and in addition dump the GCC intermediate passes and +@file{libgccjit} log file. +@end table +@end defopt + +@defopt native-comp-verbose +This variable controls the verbosity of native-compilation by +suppressing some or all of the log messages emitted by it. If its +value is zero, the default, all of the log messages are suppressed. +Setting it to a value between 1 and 3 will allow logging of the +messages whose level is above the value. The values have the +following interpretations: + +@table @asis +@item 0 +No logging. This is the default. +@item 1 +Log the final @acronym{LIMPLE} representation of the code. +@item 2 +Log the @acronym{LAP}, the final @acronym{LIMPLE}, and some additional +pass info. +@item 3 +Maximum verbosity: log everything. +@end table +@end defopt + +@defopt native-comp-async-jobs-number +This variable determines the maximum number of native-compilation +subprocesses that will be started simultaneously. It should be a +non-negative number. The default value is zero, which means use half +the number of the CPU execution units, or 1 if the CPU has only one +execution unit. +@end defopt + +@defopt native-comp-async-report-warnings-errors +If this variable's value is non-@code{nil}, warnings and errors from +asynchronous native-compilation subprocesses are reported in the main +Emacs session in a buffer named @file{*Warnings*}. The default value +@code{t} means display the resulting buffer. To log warnings without +popping up the @file{*Warnings*} buffer, set this variable to +@code{silent}. +@end defopt + +@defopt native-comp-async-query-on-exit +If this variable's value is non-nil, Emacs will query upon exiting +whether to exit and kill any asynchronous native-compilation +subprocesses that are still running, thus preventing the corresponding +@file{.eln} files from being written. If the value is @code{nil}, the +default, Emacs will kill these subprocesses without querying. +@end defopt diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 80e9eb7dd8e..aacf66c5cf8 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -555,6 +555,16 @@ Two symbols to avoid are @code{t}, which behaves like @code{_} Likewise, it makes no sense to bind keyword symbols (@pxref{Constant Variables}). +@item (cl-type @var{type}) +Matches if @var{expval} is of type @var{type}, which is a type +descriptor as accepted by @code{cl-typep} (@pxref{cl-typep,,,cl,Common +Lisp Extensions}). Examples: + +@lisp +(cl-type integer) +(cl-type (integer 0 10)) +@end lisp + @item (pred @var{function}) Matches if the predicate @var{function} returns non-@code{nil} when called on @var{expval}. The test can be negated with the syntax @@ -617,17 +627,13 @@ match, @code{and} matches. @item (or @var{pattern1} @var{pattern2}@dots{}) Attempts to match @var{pattern1}, @var{pattern2}, @dots{}, in order, until one of them succeeds. In that case, @code{or} likewise matches, -and the rest of the sub-patterns are not tested. (Note that there -must be at least two sub-patterns. -Simply @w{@code{(or @var{pattern1})}} signals error.) -@c Issue: Is this correct and intended? -@c Are there exceptions, qualifications? -@c (Btw, ``Please avoid it'' is a poor error message.) +and the rest of the sub-patterns are not tested. To present a consistent environment (@pxref{Intro Eval}) to @var{body-forms} (thus avoiding an evaluation error on match), -if any of the sub-patterns let-binds a set of symbols, -they @emph{must} all bind the same set of symbols. +the set of variables bound by the pattern is the union of the +variables bound by each sub-pattern. If a variable is not bound by +the sub-pattern that matched, then it is bound to @code{nil}. @ifnottex @anchor{rx in pcase} @@ -1306,6 +1312,10 @@ element of @var{list}. The bindings are performed as if by up being equivalent to @code{dolist} (@pxref{Iteration}). @end defmac +@defmac pcase-setq pattern value@dots{} +Assign values to variables in a @code{setq} form, destructuring each +@var{value} according to its respective @var{pattern}. +@end defmac @node Iteration @section Iteration @@ -2016,7 +2026,8 @@ that can be handled). This special form establishes the error handlers @var{handlers} around the execution of @var{protected-form}. If @var{protected-form} executes without error, the value it returns becomes the value of the -@code{condition-case} form; in this case, the @code{condition-case} has +@code{condition-case} form (in the absence of a success handler; see below). +In this case, the @code{condition-case} has no effect. The @code{condition-case} form makes a difference when an error occurs during @var{protected-form}. @@ -2066,6 +2077,12 @@ error description. If @var{var} is @code{nil}, that means no variable is bound. Then the error symbol and associated data are not available to the handler. +@cindex success handler +As a special case, one of the @var{handlers} can be a list of the +form @code{(:success @var{body}@dots{})}, where @var{body} is executed +with @var{var} (if non-@code{nil}) bound to the return value of +@var{protected-form} when that expression terminates without error. + @cindex rethrow a signal Sometimes it is necessary to re-throw a signal caught by @code{condition-case}, for some outer-level handler to catch. Here's diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index 8fd12f79026..bc35982c172 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -1474,7 +1474,7 @@ To protect against loading themes containing malicious code, Emacs displays the source file and asks for confirmation from the user before loading any non-built-in theme for the first time. As such, themes are not ordinarily byte-compiled, and source files -always take precedence when Emacs is looking for a theme to load. +usually take precedence when Emacs is looking for a theme to load. The following functions are useful for programmatically enabling and disabling themes: @@ -1508,6 +1508,30 @@ confirmation before loading the theme, unless the optional argument @var{no-confirm} is non-@code{nil}. @end deffn +@defun require-theme feature &optional noerror +This function searches @code{custom-theme-load-path} for a file that +provides @var{feature} and then loads it. This is like the function +@code{require} (@pxref{Named Features}), except it searches +@code{custom-theme-load-path} instead of @code{load-path} +(@pxref{Library Search}). This can be useful in Custom themes that +need to load supporting Lisp files when @code{require} is unsuitable +for that. + +If @var{feature}, which should be a symbol, is not already present in +the current Emacs session according to @code{featurep}, then +@code{require-theme} searches for a file named @var{feature} with an +added @samp{.elc} or @samp{.el} suffix, in that order, in the +directories specified by @code{custom-theme-load-path}. + +If a file providing @var{feature} is successfully found and loaded, +then @code{require-theme} returns @var{feature}. The optional +argument @var{noerror} determines what happens if the search or +loading fails. If it is @code{nil}, the function signals an error; +otherwise, it returns @code{nil}. If the file loads successfully but +does not provide @var{feature}, then @code{require-theme} signals an +error; this cannot be suppressed. +@end defun + @deffn Command enable-theme theme This function enables the Custom theme named @var{theme}. It signals an error if no such theme has been loaded. diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 8e4b0ebfe96..e458d76d5d0 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -997,11 +997,12 @@ start looking for ways to optimize that piece. @findex profiler-report @findex profiler-stop Emacs has built-in support for this. To begin profiling, type -@kbd{M-x profiler-start}. You can choose to profile by processor -usage, memory usage, or both. Then run the code you'd like to speed -up. After that, type @kbd{M-x profiler-report} to display a summary -buffer for each resource (cpu and memory) that you chose to profile. -The names of the report buffers include the times at which the reports +@w{@kbd{M-x profiler-start}}. You can choose to sample CPU usage +periodically (@code{cpu}), when memory is allocated (@code{memory}), +or both. Then run the code you'd like to speed up. After that, type +@kbd{M-x profiler-report} to display a summary buffer for CPU usage +sampled by each type (cpu and memory) that you chose to profile. The +names of the report buffers include the times at which the reports were generated, so you can generate another report later on without erasing previous results. When you have finished profiling, type @kbd{M-x profiler-stop} (there is a small overhead associated with @@ -1009,7 +1010,7 @@ profiling, so we don't recommend leaving it active except when you are actually running the code you want to examine). The profiler report buffer shows, on each line, a function that was -called, preceded by how much resources (cpu or memory) it used in +called, preceded by how much CPU resources it used in absolute and percentage terms since profiling started. If a given line has a @samp{+} symbol to the left of the function name, you can expand that line by typing @kbd{@key{RET}}, in order to see the @@ -1041,7 +1042,8 @@ functions written in Lisp, it cannot profile Emacs primitives. @cindex @file{benchmark.el} @cindex benchmarking You can measure the time it takes to evaluate individual Emacs Lisp -forms using the @file{benchmark} library. See the macros +forms using the @file{benchmark} library. See the function +@code{benchmark-call} as well as the macros @code{benchmark-run}, @code{benchmark-run-compiled} and @code{benchmark-progn} in @file{benchmark.el}. You can also use the @code{benchmark} command for timing forms interactively. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 93e935ccf86..7ab2896778d 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -646,9 +646,9 @@ If the value is zero, then command input is not echoed. @defvar message-truncate-lines Normally, displaying a long message resizes the echo area to display -the entire message. But if the variable @code{message-truncate-lines} -is non-@code{nil}, the echo area does not resize, and the message is -truncated to fit it. +the entire message, wrapping long line as needed. But if the variable +@code{message-truncate-lines} is non-@code{nil}, long lines of +echo-area message are instead truncated to fit the mini-window width. @end defvar The variable @code{max-mini-window-height}, which specifies the @@ -1861,9 +1861,12 @@ from the buffer. @item keymap @cindex keymap of character (and overlays) @kindex keymap @r{(overlay property)} -If this property is non-@code{nil}, it specifies a keymap for a portion of the -text. This keymap is used when the character after point is within the -overlay, and takes precedence over most other keymaps. @xref{Active Keymaps}. +If this property is non-@code{nil}, it specifies a keymap for a +portion of the text. This keymap takes precedence over most other +keymaps (@pxref{Active Keymaps}), and it is used when point is within +the overlay, where the front- +and rear-advance properties define whether the boundaries are +considered as being @emph{within} or not. @item local-map @kindex local-map @r{(overlay property)} @@ -1914,7 +1917,8 @@ This function returns a list of the overlays that overlap the region contains one or more characters in the region; empty overlays (@pxref{Managing Overlays, empty overlay}) overlap if they are at @var{beg}, strictly between @var{beg} and @var{end}, or at @var{end} -when @var{end} denotes the position at the end of the buffer. +when @var{end} denotes the position at the end of the accessible part +of the buffer. @end defun @defun next-overlay-change pos @@ -1965,9 +1969,18 @@ Tables}). The width of a tab character is usually @code{tab-width} (@pxref{Usual Display}). @end defun -@defun string-width string +@defun string-width string &optional from to This function returns the width in columns of the string @var{string}, if it were displayed in the current buffer and the selected window. +Optional arguments @var{from} and @var{to} specify the substring of +@var{string} to consider, and are interpreted as in @code{substring} +(@pxref{Creating Strings}). + +The return value is an approximation: it only considers the values +returned by @code{char-width} for the constituent characters, always +takes a tab character as taking @code{tab-width} columns, ignores +display properties and fonts, etc. For these reasons, we recommend +using @code{window-text-pixel-size}, described below, instead. @end defun @defun truncate-string-to-width string width &optional start-column padding ellipsis ellipsis-text-property @@ -1997,7 +2010,7 @@ the beginning of the result if a multi-column character in If @var{ellipsis} is non-@code{nil}, it should be a string which will replace the end of @var{string} when it is truncated. In this case, -more charcaters will be removed from @var{string} to free enough space +more characters will be removed from @var{string} to free enough space for @var{ellipsis} to fit within @var{width} columns. However, if the display width of @var{string} is less than the display width of @var{ellipsis}, @var{ellipsis} will not be appended to the result. If @@ -2998,9 +3011,10 @@ This function returns non-@code{nil} if face @var{face} specifies a non-@code{nil} @code{:inverse-video} attribute. @end defun -@defun face-extend-p face &optional frame +@defun face-extend-p face &optional frame inherit This function returns non-@code{nil} if face @var{face} specifies -a non-@code{nil} @code{:extend} attribute. +a non-@code{nil} @code{:extend} attribute. The @var{inherit} argument +is passed to @code{face-attribute}. @end defun @@ -4752,6 +4766,7 @@ window on a minibuffer-less frame. @node Display Property @section The @code{display} Property @cindex display specification +@cindex display property @kindex display @r{(text property)} The @code{display} text property (or overlay property) is used to @@ -5289,6 +5304,16 @@ where @var{props} is a property list of alternating keyword symbols and values, including at least the pair @code{:type @var{type}} that specifies the image type. + Image descriptors which define image dimensions, @code{:width}, +@code{:height}, @code{:max-width} and @code{:max-height}, may take +either an integer, which represents the dimension in pixels, or a pair +@code{(@var{value} . em)}, where @var{value} is the dimension's +length in @dfn{ems}@footnote{In typography an em is a distance +equivalent to the height of the type. For example when using 12 point +type 1 em is equal to 12 points. Its use ensures distances and type +remain proportional.}. One em is equivalent to the height of the font +and @var{value} may be an integer or a float. + The following is a list of properties that are meaningful for all image types (there are also properties which are meaningful only for certain image types, as documented in the following subsections): @@ -5392,6 +5417,21 @@ are supported, unless the image type is @code{imagemagick}. Positive values rotate clockwise, negative values counter-clockwise. Rotation is performed after scaling and cropping. +@item :transform-smoothing @var{smooth} +If this is @code{t}, any image transform will have smoothing applied; +if @code{nil}, no smoothing will be applied. The exact algorithm used +is platform dependent, but should be equivalent to bilinear +filtering. Disabling smoothing will use the nearest neighbor +algorithm. + +If this property is not specified, @code{create-image} will use the +@code{image-transform-smoothing} user option to say whether scaling +should be done or not. This option can be @code{nil} (no smoothing), +@code{t} (use smoothing) or a predicate function that's called with +the image object as the only parameter, and should return either +@code{nil} or @code{t}. The default is for down-scaling to apply +smoothing, and for large up-scaling to not apply smoothing. + @item :index @var{frame} @xref{Multi-Frame Images}. @@ -5736,6 +5776,28 @@ Cropping is performed after scaling but before rotation. @cindex SVG images SVG (Scalable Vector Graphics) is an XML format for specifying images. +SVG images support the following additional image descriptor +properties: + +@table @code +@item :foreground @var{foreground} +@var{foreground}, if non-@code{nil}, should be a string specifying a +color, which is used as the image's foreground color. If the value is +@code{nil}, it defaults to the current face's foreground color. + +@item :background @var{background} +@var{background}, if non-@code{nil}, should be a string specifying a +color, which is used as the image's background color if the image +supports transparency. If the value is @code{nil}, it defaults to the +current face's background color. + +@item :css @var{css} +@var{css}, if non-@code{nil}, should be a string specifying the CSS to +override the default CSS used when generating the image. +@end table + +@subsubheading SVG library + If your Emacs build has SVG support, you can create and manipulate these images with the following functions from the @file{svg.el} library. @@ -7041,11 +7103,11 @@ end of the buffer continues from the other end. If @var{display-message} is non-@code{nil}, the button's help-echo string is displayed. Any button with a non-@code{nil} @code{skip} property is skipped over. Returns the button found, and signals an error if no -buttons can be found. If @var{no-error} in non-@code{nil}, return nil +buttons can be found. If @var{no-error} is non-@code{nil}, return nil instead of signaling the error. @end deffn -@deffn Command backward-button n &optional wrap display-message +@deffn Command backward-button n &optional wrap display-message no-error Move to the @var{n}th previous button, or @var{n}th next button if @var{n} is negative. If @var{n} is zero, move to the start of any button at point. If @var{wrap} is non-@code{nil}, moving past either @@ -7053,7 +7115,7 @@ end of the buffer continues from the other end. If @var{display-message} is non-@code{nil}, the button's help-echo string is displayed. Any button with a non-@code{nil} @code{skip} property is skipped over. Returns the button found, and signals an error if no -buttons can be found. If @var{no-error} in non-@code{nil}, return nil +buttons can be found. If @var{no-error} is non-@code{nil}, return nil instead of signaling the error. @end deffn @@ -7558,7 +7620,7 @@ Chars}. The above display conventions apply even when there is a display table, for any character whose entry in the active display table is @code{nil}. Thus, when you set up a display table, you need only -specify the characters for which you want special behavior. +specify the characters for which you want special display behavior. The following variables affect how certain characters are displayed on the screen. Since they change the number of columns the characters @@ -7592,7 +7654,8 @@ command @code{tab-to-tab-stop}. @xref{Indent Tabs}. (@pxref{Char-Tables}), with @code{display-table} as its subtype, which is used to override the usual character display conventions. This section describes how to make, inspect, and assign elements to a -display table object. +display table object. The next section (@pxref{Active Display Table}) +describes the various standard display tables and their precedence. @defun make-display-table This creates and returns a display table. The table initially has diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 569545d83f1..323130f2378 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1203,7 +1203,7 @@ define Edebug specifications for special forms implemented in C. @defmac def-edebug-spec macro specification Specify which expressions of a call to macro @var{macro} are forms to be -evaluated. @var{specification} should be the edebug specification. +evaluated. @var{specification} should be the Edebug specification. Neither argument is evaluated. The @var{macro} argument can actually be any symbol, not just a macro @@ -1290,14 +1290,6 @@ Short for @code{&rest form}. See @code{&rest} below. If your macro wraps its body of code with @code{lambda} before it is evaluated, use @code{def-body} instead. See @code{def-body} below. -@item function-form -A function form: either a quoted function symbol, a quoted lambda -expression, or a form (that should evaluate to a function symbol or -lambda expression). This is useful when an argument that's a lambda -expression might be quoted with @code{quote} rather than -@code{function}, since it instruments the body of the lambda expression -either way. - @item lambda-expr A lambda expression with no quoting. @@ -1370,6 +1362,21 @@ is primarily used to generate more specific syntax error messages. See edebug-spec; it aborts the instrumentation, displaying the message in the minibuffer. +@item &interpose +Lets a function control the parsing of the remaining code. +It takes the form @code{&interpose @var{spec} @var{fun} @var{args...}} +and means that Edebug will first match @var{spec} against the code and +then call @var{fun} with the code that matched @code{spec}, a parsing +function @var{pf}, and finally @var{args...}. The parsing +function expects a single argument indicating the specification list +to use to parse the remaining code. It should be called exactly once +and returns the instrumented code that @var{fun} is expected to return. +For example @code{(&interpose symbolp pcase--match-pat-args)} matches +sexps whose first element is a symbol and then lets +@code{pcase--match-pat-args} lookup the specs associated +with that head symbol according to @code{pcase--match-pat-args} and +pass them to the @var{pf} it received as argument. + @item @var{other-symbol} @cindex indirect specifications Any other symbol in a specification list may be a predicate or an @@ -1378,8 +1385,13 @@ indirect specification. If the symbol has an Edebug specification, this @dfn{indirect specification} should be either a list specification that is used in place of the symbol, or a function that is called to process the -arguments. The specification may be defined with @code{def-edebug-spec} -just as for macros. See the @code{defun} example. +arguments. The specification may be defined with +@code{def-edebug-elem-spec}: + +@defun def-edebug-elem-spec element specification +Define the @var{specification} to use in place of the symbol @var{element}. +@var{specification} has to be a list. +@end defun Otherwise, the symbol should be a predicate. The predicate is called with the argument, and if the predicate returns @code{nil}, the @@ -1428,29 +1440,23 @@ Here is a list of additional specifications that may appear only after @code{&define}. See the @code{defun} example. @table @code +@item &name +Extracts the name of the current defining form from the code. +It takes the form @code{&name [@var{prestring}] @var{spec} +[@var{poststring}] @var{fun} @var{args...}} and means that Edebug will +match @var{spec} against the code and then call @var{fun} with the +concatenation of the current name, @var{args...}, @var{prestring}, +the code that matched @code{spec}, and @var{poststring}. If @var{fun} +is absent, it defaults to a function that concatenates the arguments +(with an @code{@@} between the previous name and the new). + @item name The argument, a symbol, is the name of the defining form. +Shorthand for @code{[&name symbolp]}. A defining form is not required to have a name field; and it may have multiple name fields. -@item :name -This construct does not actually match an argument. The element -following @code{:name} should be a symbol; it is used as an additional -name component for the definition. You can use this to add a unique, -static component to the name of the definition. It may be used more -than once. - -@item :unique -This construct is like @code{:name}, but generates unique names. It -does not match an argument. The element following @code{:unique} -should be a string; it is used as the prefix for an additional name -component for the definition. You can use this to add a unique, -dynamic component to the name of the definition. This is useful for -macros that can define the same symbol multiple times in different -scopes, such as @code{cl-flet}; @ref{Function Bindings,,,cl}. It may -be used more than once. - @item arg The argument, a symbol, is the name of an argument of the defining form. However, lambda-list keywords (symbols starting with @samp{&}) @@ -1504,11 +1510,11 @@ form specifications (that is, @code{form}, @code{body}, @code{def-form}, and must be in the form itself rather than at a higher level. Backtracking is also disabled after successfully matching a quoted -symbol or string specification, since this usually indicates a -recognized construct. But if you have a set of alternative constructs that -all begin with the same symbol, you can usually work around this -constraint by factoring the symbol out of the alternatives, e.g., -@code{["foo" &or [first case] [second case] ...]}. +symbol, string specification, or @code{&define} keyword, since this +usually indicates a recognized construct. But if you have a set of +alternative constructs that all begin with the same symbol, you can +usually work around this constraint by factoring the symbol out of the +alternatives, e.g., @code{["foo" &or [first case] [second case] ...]}. Most needs are satisfied by these two ways that backtracking is automatically disabled, but occasionally it is useful to explicitly @@ -1557,14 +1563,14 @@ specification for @code{defmacro} is very similar to that for [&optional ("interactive" interactive)] def-body)) -(def-edebug-spec lambda-list - (([&rest arg] - [&optional ["&optional" arg &rest arg]] - &optional ["&rest" arg] - ))) +(def-edebug-elem-spec 'lambda-list + '(([&rest arg] + [&optional ["&optional" arg &rest arg]] + &optional ["&rest" arg] + ))) -(def-edebug-spec interactive - (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}} +(def-edebug-elem-spec 'interactive + '(&optional &or stringp def-form)) ; @r{Notice: @code{def-form}} @end smallexample The specification for backquote below illustrates how to match @@ -1577,11 +1583,11 @@ could fail.) @smallexample (def-edebug-spec \` (backquote-form)) ; @r{Alias just for clarity.} -(def-edebug-spec backquote-form - (&or ([&or "," ",@@"] &or ("quote" backquote-form) form) - (backquote-form . [&or nil backquote-form]) - (vector &rest backquote-form) - sexp)) +(def-edebug-elem-spec 'backquote-form + '(&or ([&or "," ",@@"] &or ("quote" backquote-form) form) + (backquote-form . [&or nil backquote-form]) + (vector &rest backquote-form) + sexp)) @end smallexample @@ -1624,10 +1630,10 @@ option. @xref{Instrumenting}. @defopt edebug-eval-macro-args When this is non-@code{nil}, all macro arguments will be instrumented -in the generated code. For any macro, an @code{edebug-form-spec} +in the generated code. For any macro, the @code{debug} declaration overrides this option. So to specify exceptions for macros that have -some arguments evaluated and some not, use @code{def-edebug-spec} to -specify an @code{edebug-form-spec}. +some arguments evaluated and some not, use the @code{debug} declaration +specify an Edebug form specification. @end defopt @defopt edebug-save-windows diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 12255d122f9..55bcf399d81 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -197,6 +197,7 @@ To view this manual in other formats, click * Loading:: Reading files of Lisp code into Lisp. * Byte Compilation:: Compilation makes programs run faster. +* Native Compilation:: Compile Lisp into native machine code. * Debugging:: Tools and tips for debugging Lisp programs. * Read and Print:: Converting Lisp objects to text and back. @@ -531,6 +532,7 @@ Scoping Rules for Variable Bindings * Dynamic Binding Tips:: Avoiding problems with dynamic binding. * Lexical Binding:: A different type of local variable binding. * Using Lexical Binding:: How to enable lexical binding. +* Converting to Lexical Binding:: Convert existing code to lexical binding. Buffer-Local Variables @@ -645,6 +647,11 @@ Byte Compilation * Byte-Code Objects:: The data type used for byte-compiled functions. * Disassembly:: Disassembling byte-code; how to read byte-code. +Native Compilation + +* Native-Compilation Functions:: Functions to natively-compile Lisp. +* Native-Compilation Variables:: Variables controlling native compilation. + Debugging Lisp Programs * Debugger:: A debugger for the Emacs Lisp evaluator. @@ -781,6 +788,7 @@ Defining Commands * Interactive Codes:: The standard letter-codes for reading arguments in various ways. * Interactive Examples:: Examples of how to read interactive arguments. +* Command Modes:: Specifying that commands are for a specific mode. * Generic Commands:: Select among command alternatives. @@ -1408,8 +1416,9 @@ Low-Level Network Access Packing and Unpacking Byte Arrays -* Bindat Spec:: Describing data layout. +* Bindat Types:: Describing data layout. * Bindat Functions:: Doing the unpacking and packing. +* Bindat Computed Types:: Advanced data layout specifications. Emacs Display diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index fb393b951f1..f848218e267 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -20,8 +20,9 @@ the errors in accessing files have the condition @code{file-error}. If we do not say here that a certain error symbol has additional error conditions, that means it has none. - As a special exception, the error symbol @code{quit} does not have the -condition @code{error}, because quitting is not considered an error. + As a special exception, the error symbols @code{quit} and +@code{minibuffer-quit} don't have the condition @code{error}, because +quitting is not considered an error. Most of these error symbols are defined in C (mainly @file{data.c}), but some are defined in Lisp. For example, the file @file{userlock.el} @@ -40,6 +41,10 @@ The message is @samp{error}. @xref{Errors}. @item quit The message is @samp{Quit}. @xref{Quitting}. +@item minibuffer-quit +The message is @samp{Quit}. This is a subcategory of @code{quit}. +@xref{Quitting}. + @item args-out-of-range The message is @samp{Args out of range}. This happens when trying to access an element beyond the range of a sequence, buffer, or other diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 80e038c96d9..7893895eee9 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -332,7 +332,6 @@ or just The built-in function @code{indirect-function} provides an easy way to perform symbol function indirection explicitly. -@c Emacs 19 feature @defun indirect-function function &optional noerror @anchor{Definition of indirect-function} This function returns the meaning of @var{function} as a function. If @@ -351,7 +350,8 @@ Here is how you could define @code{indirect-function} in Lisp: @example (defun indirect-function (function) - (if (symbolp function) + (if (and function + (symbolp function)) (indirect-function (symbol-function function)) function)) @end example diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 4110c51099d..266501d46d0 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -455,7 +455,6 @@ Even though this is not a normal hook, you can use @code{add-hook} and @code{remove-hook} to manipulate the list. @xref{Hooks}. @end defvar -@c Emacs 19 feature @defvar write-contents-functions This works just like @code{write-file-functions}, but it is intended for hooks that pertain to the buffer's contents, not to the particular @@ -486,7 +485,6 @@ this hook to make sure the file you are saving has the current year in its copyright notice. @end defopt -@c Emacs 19 feature @defopt after-save-hook This normal hook runs after a buffer has been saved in its visited file. @end defopt @@ -622,7 +620,6 @@ If @var{start} is @code{nil}, then the command writes the entire buffer contents (@emph{not} just the accessible portion) to the file and ignores @var{end}. -@c Emacs 19 feature If @var{start} is a string, then @code{write-region} writes or appends that string, rather than text from the buffer. @var{end} is ignored in this case. @@ -653,7 +650,6 @@ It also sets the last file modification time for the current buffer to feature is used by @code{save-buffer}, but you probably should not use it yourself. -@c Emacs 19 feature If @var{visit} is a string, it specifies the file name to visit. This way, you can write the data to one file (@var{filename}) while recording the buffer as visiting another file (@var{visit}). The argument @@ -722,7 +718,7 @@ Emacs can then detect the first attempt to modify a buffer visiting a file that is locked by another Emacs job, and ask the user what to do. The file lock is really a file, a symbolic link with a special name, stored in the same directory as the file you are editing. The name is -constructed by prepending @file{.#} to the filename of the buffer. +constructed by prepending @file{.#} to the file name of the buffer. The target of the symbolic link will be of the form @code{@var{user}@@@var{host}.@var{pid}:@var{boot}}, where @var{user} is replaced with the current username (from @code{user-login-name}), @@ -768,12 +764,28 @@ This function unlocks the file being visited in the current buffer, if the buffer is modified. If the buffer is not modified, then the file should not be locked, so this function does nothing. It also does nothing if the current buffer is not visiting a file, or is not locked. +This function handles file system errors by calling @code{display-warning} +and otherwise ignores the error. @end defun @defopt create-lockfiles If this variable is @code{nil}, Emacs does not lock files. @end defopt +@defopt lock-file-name-transforms +By default, Emacs creates the lock files in the same directory as the +files that are being locked. This can be changed by customizing this +variable. Is has the same syntax as +@code{auto-save-file-name-transforms} (@pxref{Auto-Saving}). For +instance, to make Emacs write all the lock files to @file{/var/tmp/}, +you could say something like: + +@lisp +(setq lock-file-name-transforms + '(("\\`/.*/\\([^/]+\\)\\'" "/var/tmp/\\1" t))) +@end lisp +@end defopt + @defun ask-user-about-lock file other-user This function is called when the user tries to modify @var{file}, but it is locked by another user named @var{other-user}. The default @@ -809,6 +821,16 @@ If you wish, you can replace the @code{ask-user-about-lock} function with your own version that makes the decision in another way. @end defun +@defopt remote-file-name-inhibit-locks +You can prevent the creation of remote lock files by setting the +variable @code{remote-file-name-inhibit-locks} to @code{t}. +@end defopt + +@deffn Command lock-file-mode +This command, called interactively, toggles the local value of +@code{create-lockfiles} in the current buffer. +@end deffn + @node Information about Files @section Information about Files @cindex file, information about @@ -1934,7 +1956,7 @@ is a symbolic link and @var{flag} is @code{nofollow}. @defun set-file-extended-attributes filename attribute-alist This function sets the Emacs-recognized extended file attributes for -@code{filename}. The second argument @var{attribute-alist} should be +@var{filename}. The second argument @var{attribute-alist} should be an alist of the same form returned by @code{file-extended-attributes}. The return value is @code{t} if the attributes are successfully set, otherwise it is @code{nil}. @@ -2131,6 +2153,25 @@ the period that delimits the extension, and if @var{filename} has no extension, the value is @code{""}. @end defun +@defun file-name-with-extension filename extension +This function returns @var{filename} with its extension set to +@var{extension}. A single leading dot in the @var{extension} will be +stripped if there is one. For example: + +@example +(file-name-with-extension "file" "el") + @result{} "file.el" +(file-name-with-extension "file" ".el") + @result{} "file.el" +(file-name-with-extension "file.c" "el") + @result{} "file.el" +@end example + +Note that this function will error if @var{filename} or +@var{extension} are empty, or if the @var{filename} is shaped like a +directory (i.e., if @code{directory-name-p} returns non-@code{nil}). +@end defun + @defun file-name-sans-extension filename This function returns @var{filename} minus its extension, if any. The version/backup part, if present, is only removed if the file has an @@ -2246,7 +2287,7 @@ form. A @dfn{directory name} is a string that must name a directory if it names any file at all. A directory is actually a kind of file, and it -has a file name (called the @dfn{directory file name}, which is +has a file name (called the @dfn{directory file name}), which is related to the directory name but is typically not identical. (This is not quite the same as the usual POSIX terminology.) These two names for the same entity are related by a syntactic transformation. @@ -2302,49 +2343,26 @@ entirely of directory separators. @end example @end defun - Given a directory name, you can combine it with a relative file name -using @code{concat}: +@defun file-name-concat directory &rest components +Concatenate @var{components} to @var{directory}, inserting a slash +before the components if @var{directory} or the preceding component +didn't end with a slash. @example -(concat @var{dirname} @var{relfile}) -@end example - -@noindent -Be sure to verify that the file name is relative before doing that. -If you use an absolute file name, the results could be syntactically -invalid or refer to the wrong file. - - If you want to use a directory file name in making such a -combination, you must first convert it to a directory name using -@code{file-name-as-directory}: - -@example -(concat (file-name-as-directory @var{dirfile}) @var{relfile}) -@end example - -@noindent -Don't try concatenating a slash by hand, as in - -@example -;;; @r{Wrong!} -(concat @var{dirfile} "/" @var{relfile}) +@group +(file-name-concat "/tmp" "foo") + @result{} "/tmp/foo" +@end group @end example -@noindent -because this is not portable. Always use -@code{file-name-as-directory}. - - To avoid the issues mentioned above, or if the @var{dirname} value -might be @code{nil} (for example, from an element of @code{load-path}), -use: - -@example -(expand-file-name @var{relfile} @var{dirname}) -@end example +A @var{directory} or components that are @code{nil} or the empty +string are ignored---they are filtered out first and do not affect the +results in any way. -However, @code{expand-file-name} expands leading @samp{~} in -@var{relfile}, which may not be what you want. @xref{File Name -Expansion}. +This is almost the same as using @code{concat}, but @var{dirname} (and +the non-final components) may or may not end with slash characters, +and this function will not double those characters. +@end defun To convert a directory name to its abbreviation, use this function: @@ -2417,7 +2435,7 @@ might begin with a literal @samp{~}, you can use @code{(concat (file-name-as-directory directory) filename)} instead of @code{(expand-file-name filename directory)}. -Filenames containing @samp{.} or @samp{..} are simplified to their +File names containing @samp{.} or @samp{..} are simplified to their canonical form: @example @@ -3094,7 +3112,6 @@ which generate the listing with Lisp code. @node Create/Delete Dirs @section Creating, Copying and Deleting Directories @cindex creating, copying and deleting directories -@c Emacs 19 features Most Emacs Lisp file-manipulation functions get errors when used on files that are directories. For example, you cannot delete a directory @@ -3257,7 +3274,7 @@ first, before handlers for jobs such as remote file access. @code{file-equal-p}, @code{file-executable-p}, @code{file-exists-p}, @code{file-in-directory-p}, -@code{file-local-copy}, +@code{file-local-copy}, @code{file-locked-p}, @code{file-modes}, @code{file-name-all-completions}, @code{file-name-as-directory}, @code{file-name-case-insensitive-p}, @@ -3276,10 +3293,11 @@ first, before handlers for jobs such as remote file access. @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents},@* -@code{load}, +@code{load}, @code{lock-file}, @code{make-auto-save-file-name}, @code{make-directory}, @code{make-directory-internal}, +@code{make-lock-file-name}, @code{make-nearby-temp-file}, @code{make-process}, @code{make-symbolic-link},@* @@ -3291,6 +3309,7 @@ first, before handlers for jobs such as remote file access. @code{substitute-in-file-name},@* @code{temporary-file-directory}, @code{unhandled-file-name-directory}, +@code{unlock-file}, @code{vc-registered}, @code{verify-visited-file-modtime},@* @code{write-region}. @@ -3315,7 +3334,7 @@ first, before handlers for jobs such as remote file access. @code{file-equal-p}, @code{file-executable-p}, @code{file-exists-p}, @code{file-in-directory-p}, -@code{file-local-copy}, +@code{file-local-copy}, @code{file-locked-p}, @code{file-modes}, @code{file-name-all-completions}, @code{file-name-as-directory}, @code{file-name-case-insensitive-p}, @@ -3334,10 +3353,12 @@ first, before handlers for jobs such as remote file access. @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents}, -@code{load}, +@code{load}, @code{lock-file}, @code{make-auto-save-file-name}, @code{make-direc@discretionary{}{}{}tory}, @code{make-direc@discretionary{}{}{}tory-internal}, +@code{make-lock-file-name}, +@code{make-nearby-temp-file}, @code{make-process}, @code{make-symbolic-link}, @code{process-file}, @@ -3346,7 +3367,9 @@ first, before handlers for jobs such as remote file access. @code{set-visited-file-modtime}, @code{shell-command}, @code{start-file-process}, @code{substitute-in-file-name}, +@code{temporary-file-directory}, @code{unhandled-file-name-directory}, +@code{unlock-file}, @code{vc-regis@discretionary{}{}{}tered}, @code{verify-visited-file-modtime}, @code{write-region}. @@ -3460,11 +3483,11 @@ identifies the remote system. This identifier string can include a host name and a user name, as well as characters designating the method used to access the remote -system. For example, the remote identifier string for the filename +system. For example, the remote identifier string for the file name @code{/sudo::/some/file} is @code{/sudo:root@@localhost:}. If @code{file-remote-p} returns the same identifier for two different -filenames, that means they are stored on the same file system and can +file names, that means they are stored on the same file system and can be accessed locally with respect to each other. This means, for example, that it is possible to start a remote process accessing both files at the same time. Implementers of file name handlers need to diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index f4316b753d8..25706befc8d 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1120,9 +1120,9 @@ The optional fourth argument @var{pixelwise} non-@code{nil} means that refuse to truly honor the request if it does not increase/decrease the frame height to a multiple of its character height. -When used interactively, this command will set the height of the -currently selected frame to the number of lines specified by the -numeric prefix. +When used interactively, this command will ask the user for the number +of lines to set the height of the currently selected frame. You can +also provide this value with a numeric prefix. @end defun @defun set-frame-width frame width &optional pretend pixelwise @@ -1136,9 +1136,9 @@ The optional fourth argument @var{pixelwise} non-@code{nil} means that refuse to fully honor the request if it does not increase/decrease the frame width to a multiple of its character width. -When used interactively, this command will set the width of the -currently selected frame to the number of columns specified by the -numeric prefix. +When used interactively, this command will ask the user for the number +of columns to set the width of the currently selected frame. You can +also provide this value with a numeric prefix. @end defun None of these three functions will make a frame smaller than needed to @@ -2023,8 +2023,8 @@ the @sc{cdr} of the cell is either @code{t} or @code{top-only}. The parameters described below provide support for resizing a frame by dragging its internal borders with the mouse. They also allow moving a -frame with the mouse by dragging the header line of its topmost or the -mode line of its bottommost window. +frame with the mouse by dragging the header or tab line of its topmost +or the mode line of its bottommost window. These parameters are mostly useful for child frames (@pxref{Child Frames}) that come without window manager decorations. If necessary, @@ -2041,6 +2041,11 @@ borders, if present, with the mouse. If non-@code{nil}, the frame can be moved with the mouse by dragging the header line of its topmost window. +@vindex drag-with-tab-line@r{, a frame parameter} +@item drag-with-tab-line +If non-@code{nil}, the frame can be moved with the mouse by dragging the +tab line of its topmost window. + @vindex drag-with-mode-line@r{, a frame parameter} @item drag-with-mode-line If non-@code{nil}, the frame can be moved with the mouse by dragging the @@ -2628,7 +2633,7 @@ When Emacs gets one of these commands, it generates a @code{delete-frame} event, whose normal definition is a command that calls the function @code{delete-frame}. @xref{Misc Events}. -@deffn Command delete-other-frames &optional frame +@deffn Command delete-other-frames &optional frame iconify This command deletes all frames on @var{frame}'s terminal, except @var{frame}. If @var{frame} uses another frame's minibuffer, that minibuffer frame is left untouched. The argument @var{frame} must @@ -2639,6 +2644,9 @@ this command works by calling @code{delete-frame} with @var{force} This function does not delete any of @var{frame}'s child frames (@pxref{Child Frames}). If @var{frame} is a child frame, it deletes @var{frame}'s siblings only. + +With the prefix argument @var{iconify}, the frames are iconified rather +than deleted. @end deffn diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 414035f684b..77d1465c876 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -863,6 +863,10 @@ This function returns @var{argument} and has no side effects. This function ignores any @var{arguments} and returns @code{nil}. @end defun +@defun always &rest arguments +This function ignores any @var{arguments} and returns @code{t}. +@end defun + Some functions are user-visible @dfn{commands}, which can be called interactively (usually by a key sequence). It is possible to invoke such a command exactly as though it was called interactively, by using @@ -1177,7 +1181,7 @@ This form defines a method like @code{cl-defmethod} does. @end table @end defmac -@defmac cl-defmethod name [qualifier] arguments [&context (expr spec)@dots{}] &rest [docstring] body +@defmac cl-defmethod name [extra] [qualifier] arguments [&context (expr spec)@dots{}] &rest [docstring] body This macro defines a particular implementation for the generic function called @var{name}. The implementation code is given by @var{body}. If present, @var{docstring} is the documentation string @@ -1263,6 +1267,10 @@ Parent type: @code{array}. @item font-object @end table +The optional @var{extra} element, expressed as @samp{:extra +@var{string}}, allows you to add more methods, distinguished by +@var{string}, for the same specializers and qualifiers. + The optional @var{qualifier} allows combining several applicable methods. If it is not present, the defined method is a @dfn{primary} method, responsible for providing the primary implementation of the @@ -1284,9 +1292,6 @@ This auxiliary method will run @emph{instead} of the primary method. The most specific of such methods will be run before any other method. Such methods normally use @code{cl-call-next-method}, described below, to invoke the other auxiliary or primary methods. -@item :extra @var{string} -This allows you to add more methods, distinguished by @var{string}, -for the same specializers and qualifiers. @end table Functions defined using @code{cl-defmethod} cannot be made @@ -2309,6 +2314,16 @@ form @code{(lambda (@var{arg}) @var{body})} in which case that function will additionally have access to the macro (or function)'s arguments and it will be passed to @code{gv-define-setter}. +@item (completion @var{completion-predicate}) +Declare @var{completion-predicate} as a function to determine whether +to include the symbol in the list of functions when asking for +completions in @kbd{M-x}. @var{completion-predicate} is called with +two parameters: The first parameter is the symbol, and the second is +the current buffer. + +@item (modes @var{modes}) +Specify that this command is meant to be applicable for @var{modes} +only. @end table @end defmac @@ -2406,11 +2421,12 @@ opposed to an unspecified one). @cindex safety of functions Some major modes, such as SES, call functions that are stored in user -files. (@inforef{Top, ,ses}, for more information on SES@.) User -files sometimes have poor pedigrees---you can get a spreadsheet from -someone you've just met, or you can get one through email from someone -you've never met. So it is risky to call a function whose source code -is stored in a user file until you have determined that it is safe. +files. (@xref{Top, Simple Emacs Spreadsheet,,ses}, for more +information on SES@.) User files sometimes have poor pedigrees---you +can get a spreadsheet from someone you've just met, or you can get one +through email from someone you've never met. So it is risky to call a +function whose source code is stored in a user file until you have +determined that it is safe. @defun unsafep form &optional unsafep-vars Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 298bec5230c..a788852de75 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -818,7 +818,7 @@ summaries of using those functions. The optional argument @var{functions} is a list whose elements are of the form: @lisp -(@var{func} @var{keyword} @var{val} @dots{}) +(@var{func} [@var{keyword} @var{val}]@dots{}) @end lisp The following keywords are recognized: @@ -839,7 +839,7 @@ evaluated, and the result used. For instance: @end example @noindent -will be printed as +will result in: @example (concat "foo" "bar" "zot") @@ -866,13 +866,14 @@ should be included. @end example @item :no-eval* -Like @code{:no-eval}, but alaways inserts @samp{[it depends]} as the -result. +Like @code{:no-eval}, but always inserts @samp{[it depends]} as the +result. For instance: @example :no-eval* (buffer-string) @end example +@noindent will result in: @example @@ -894,17 +895,26 @@ Used to output the result from non-evaluating example forms. @item :eg-result Used to output an example result from non-evaluating example forms. +For instance: @example :no-eval (looking-at "f[0-9]") :eg-result t @end example +@noindent +will result in: + +@example +(looking-at "f[0-9]") +eg. @click{} t +@end example + @item :result-string @itemx :eg-result-string These two are the same as @code{:result} and @code{:eg-result}, respectively, but are inserted as is. This is useful when the result -is unreadable or should be on a particular form: +is unreadable or should be of a particular form: @example :no-eval (find-file "/tmp/foo") @@ -951,7 +961,7 @@ sections. @defun shortdoc-add-function shortdoc-add-function group section elem Lisp packages can add functions to groups with this command. Each -@var{elem} should be a function descriptions, as described above. +@var{elem} should be a function description, as described above. @var{group} is the function group, and @var{section} is what section in the function group to insert the function into. diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index b1c7e613719..394928454b0 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -184,7 +184,7 @@ The command loop runs this soon after @code{post-command-hook} (q.v.). @item mouse-leave-buffer-hook @vindex mouse-leave-buffer-hook -Hook run when about to switch windows with a mouse command. +Hook run when the user mouse-clicks in a window. @item mouse-position-function @xref{Mouse Position}. diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 4150a2b21b8..0e250d0f59b 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -1429,7 +1429,7 @@ other words, if a module function wants to call Lisp functions or Emacs primitives, convert @code{emacs_value} objects to and from C datatypes (@pxref{Module Values}), or interact with Emacs in any other way, some call from Emacs to @code{emacs_module_init} or to a module -function must be in the call stack. Module function may not interact +function must be in the call stack. Module functions may not interact with Emacs while garbage collection is running; @pxref{Garbage Collection}. They may only interact with Emacs from Lisp interpreter threads (including the main thread) created by Emacs; @pxref{Threads}. diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 35f852b7e4b..c2ed96472b9 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -89,7 +89,7 @@ you are criticizing. @cindex suggestions Please send comments and corrections using @kbd{M-x report-emacs-bug}. If you wish to contribute new code (or send a -patch to fix a problem), use @kbd{M-x submit-emacs-patch}). +patch to fix a problem), use @kbd{M-x submit-emacs-patch}. @node Lisp History @section Lisp History diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 55d179b8753..4097c86f074 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -369,7 +369,6 @@ appear directly as bindings in @var{keymap} are also copied recursively, and so on to any number of levels. However, recursive copying does not take place when the definition of a character is a symbol whose function definition is a keymap; the same symbol appears in the new copy. -@c Emacs 19 feature @example @group @@ -574,12 +573,6 @@ key. key. @item -@cindex @kbd{M-o} -@vindex facemenu-keymap -@code{facemenu-keymap} is the global keymap used for the @kbd{M-o} -prefix key. - -@item The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x @key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps that have no special names. @@ -1146,7 +1139,6 @@ and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of @var{key} that compose a complete key. -@c Emacs 19 feature If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} considers default bindings as well as bindings for the specific events in @var{key}. Otherwise, @code{lookup-key} reports only bindings for @@ -1188,7 +1180,6 @@ not cause an error. This function returns the binding for @var{key} in the current local keymap, or @code{nil} if it is undefined there. -@c Emacs 19 feature The argument @var{accept-defaults} controls checking for default bindings, as in @code{lookup-key} (above). @end defun @@ -1197,12 +1188,10 @@ as in @code{lookup-key} (above). This function returns the binding for command @var{key} in the current global keymap, or @code{nil} if it is undefined there. -@c Emacs 19 feature The argument @var{accept-defaults} controls checking for default bindings, as in @code{lookup-key} (above). @end defun -@c Emacs 19 feature @defun minor-mode-key-binding key &optional accept-defaults This function returns a list of all the active minor mode bindings of @var{key}. More precisely, it returns an alist of pairs @@ -1420,7 +1409,6 @@ standard bindings: @end group @end smallexample -@c Emacs 19 feature If @var{oldmap} is non-@code{nil}, that changes the behavior of @code{substitute-key-definition}: the bindings in @var{oldmap} determine which keys to rebind. The rebindings still happen in @var{keymap}, not @@ -1698,7 +1686,7 @@ presence of such a binding can still prevent translation from taking place. For example, let us return to our VT100 example above and add a binding for @kbd{C-c @key{ESC}} to the global map; now when the user hits @kbd{C-c @key{PF1}} Emacs will fail to decode @kbd{C-c @key{ESC} O P} into @kbd{C-c -@key{PF1}} because it will stop reading keys right after @kbd{C-x @key{ESC}}, +@key{PF1}} because it will stop reading keys right after @kbd{C-c @key{ESC}}, leaving @kbd{O P} for later. This is in case the user really hit @kbd{C-c @key{ESC}}, in which case Emacs should not sit there waiting for the next key to decide whether the user really pressed @kbd{@key{ESC}} or @kbd{@key{PF1}}. @@ -2932,7 +2920,7 @@ menu item. @item :active @var{enable} @var{enable} is an expression; if it evaluates to @code{nil}, the item -is make unselectable.. @code{:enable} is an alias for @code{:active}. +is made unselectable. @code{:enable} is an alias for @code{:active}. @item :visible @var{include} @var{include} is an expression; if it evaluates to @code{nil}, the diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 2805b1f5fdc..bbe1dce42d8 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1557,10 +1557,12 @@ of property lists and association lists. @defun assoc key alist &optional testfn This function returns the first association for @var{key} in @var{alist}, comparing @var{key} against the alist elements using -@var{testfn} if it is non-@code{nil} and @code{equal} otherwise -(@pxref{Equality Predicates}). It returns @code{nil} if no -association in @var{alist} has a @sc{car} equal to @var{key}. For -example: +@var{testfn} if it is a function, and @code{equal} otherwise +(@pxref{Equality Predicates}). If @var{testfn} is a function, it is +called with two arguments: the @sc{car} of an element from @var{alist} +and @var{key}. The function returns @code{nil} if no +association in @var{alist} has a @sc{car} equal to @var{key}, as +tested by @var{testfn}. For example: @smallexample (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) @@ -1804,7 +1806,7 @@ through a simple example: (let-alist colors (if (eq .rose 'red) .lily)) -=> white + @result{} white @end lisp The @var{body} is inspected at compilation time, and only the symbols @@ -1820,7 +1822,7 @@ Nested association lists is supported: (let-alist colors (if (eq .rose 'red) .lily.belladonna)) -=> yellow + @result{} yellow @end lisp Nesting @code{let-alist} inside each other is allowed, but the code in diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 22f0dde593a..4d683da1ad3 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -71,7 +71,11 @@ forms in it, and closes the file. To find the file, @code{load} first looks for a file named @file{@var{filename}.elc}, that is, for a file whose name is @var{filename} with the extension @samp{.elc} appended. If such a -file exists, it is loaded. If there is no file by that name, then +file exists, and Emacs was compiled with native-compilation support +(@pxref{Native Compilation}), @code{load} attempts to find a +corresponding @samp{.eln} file, and if found, loads it instead of +@file{@var{filename}.elc}. Otherwise, it loads +@file{@var{filename}.elc}. If there is no file by that name, then @code{load} looks for a file named @file{@var{filename}.el}. If that file exists, it is loaded. If Emacs was compiled with support for dynamic modules (@pxref{Dynamic Modules}), @code{load} next looks for @@ -109,6 +113,8 @@ explicit directory name. If the option @code{load-prefer-newer} is non-@code{nil}, then when searching suffixes, @code{load} selects whichever version of a file (@samp{.elc}, @samp{.el}, etc.)@: has been modified most recently. +In this case, @code{load} doesn't load the @samp{.eln} +natively-compiled file even if it exists. If @var{filename} is a relative file name, such as @file{foo} or @file{baz/foo.bar}, @code{load} searches for the file using the variable @@ -153,7 +159,8 @@ during compilation. @xref{Compiling Macros}. Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear in the echo area during loading unless @var{nomessage} is -non-@code{nil}. +non-@code{nil}. If a natively-compiled @samp{.eln} file is loaded, +the message says so. @cindex load errors Any unhandled errors while loading a file terminate loading. If the @@ -430,6 +437,28 @@ optional argument @code{stringp} is non-@code{nil}, it instead returns the shadowed files as a string. @end deffn + If Emacs was compiled with support for native compilation +(@pxref{Native Compilation}), then when a @samp{.elc} byte-compiled +file is found by searching @code{load-path}, Emacs will try to look +for a corresponding @samp{.eln} file holding the corresponding +natively-compiled code. The natively-compiled files are looked up in +the directories listed by the @code{native-comp-eln-load-path}. + +@vindex comp-native-version-dir +@defvar native-comp-eln-load-path +This variable holds a list of directories where Emacs looks for +natively-compiled @samp{.eln} files. File names in the list that are +not absolute are interpreted as relative to @code{invocation-directory} +(@pxref{System Environment}). The last directory in the list is the +system directory, i.e.@: the directory with @samp{.eln} files +installed by the Emacs build and installation procedure. In each of +the directories in the list, Emacs looks for @samp{.eln} files in a +subdirectory whose name is constructed from the Emacs version and an +8-character hash that depends on the current native-compilation +@acronym{ABI}; the name of this subdirectory is stored in the variable +@code{comp-native-version-dir}. +@end defvar + @node Loading Non-ASCII @section Loading Non-@acronym{ASCII} Characters @cindex loading, and non-ASCII characters @@ -510,6 +539,9 @@ specification is not given here; it's not needed unless the user actually calls @var{function}, and when that happens, it's time to load the real definition. +If @var{interactive} is a list, it is interpreted as a list of modes +this command is applicable for. + You can autoload macros and keymaps as well as ordinary functions. Specify @var{type} as @code{macro} if @var{function} is really a macro. Specify @var{type} as @code{keymap} if @var{function} is really a @@ -1049,7 +1081,6 @@ rather than replacing that element. @xref{Eval}. @section Unloading @cindex unloading packages -@c Emacs 19 feature You can discard the functions and variables loaded by a library to reclaim memory for other Lisp objects. To do this, use the function @code{unload-feature}: @@ -1125,7 +1156,7 @@ You don't need to give a directory or extension in the file name @var{library}. Normally, you just give a bare file name, like this: @example -(with-eval-after-load "edebug" (def-edebug-spec c-point t)) +(with-eval-after-load "js" (define-key js-mode-map "\C-c\C-c" 'js-eval)) @end example To restrict which files can trigger the evaluation, include a diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index e56a85c7478..cf23ecb9d4e 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -241,7 +241,6 @@ of constants and nonconstant parts. To make this easier, use the @samp{`} syntax (@pxref{Backquote}). For example: @example -@example @group (defmacro t-becomes-nil (variable) `(if (eq ,variable t) @@ -253,7 +252,6 @@ of constants and nonconstant parts. To make this easier, use the @equiv{} (if (eq foo t) (setq foo nil)) @end group @end example -@end example @node Problems with Macros @section Common Problems Using Macros @@ -480,12 +478,16 @@ in expressions ordinarily. Another problem can happen if the macro definition itself evaluates any of the macro argument expressions, such as by calling -@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the -user's variables, you may have trouble if the user happens to use a -variable with the same name as one of the macro arguments. Inside the -macro body, the macro argument binding is the most local binding of this -variable, so any references inside the form being evaluated do refer to -it. Here is an example: +@code{eval} (@pxref{Eval}). You have to take into account that macro +expansion may take place long before the code is executed, when the +context of the caller (where the macro expansion will be evaluated) is +not yet accessible. + + Also, if your macro definition does not use @code{lexical-binding}, its +formal arguments may hide the user's variables of the same name. Inside +the macro body, the macro argument binding is the most local binding of +such variable, so any references inside the form being evaluated do refer +to it. Here is an example: @example @group @@ -508,12 +510,10 @@ it. Here is an example: @code{x}, because @code{a} conflicts with the macro argument variable @code{a}. - Another problem with calling @code{eval} in a macro definition is that -it probably won't do what you intend in a compiled program. The -byte compiler runs macro definitions while compiling the program, when -the program's own computations (which you might have wished to access -with @code{eval}) don't occur and its local variable bindings don't -exist. + Also, the expansion of @code{(foo x)} above will return something +different or signal an error when the code is compiled, since in that case +@code{(foo x)} is expanded during compilation, whereas the execution of +@code{(setq x 'b)} will only take place later when the code is executed. To avoid these problems, @strong{don't evaluate an argument expression while computing the macro expansion}. Instead, substitute the diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi index aea02424086..59c6e6f57ad 100644 --- a/doc/lispref/maps.texi +++ b/doc/lispref/maps.texi @@ -53,9 +53,6 @@ A sparse keymap for subcommands of the prefix @kbd{C-x r}.@* @item esc-map A full keymap for @key{ESC} (or @key{Meta}) commands. -@item facemenu-keymap -A sparse keymap used for the @kbd{M-o} prefix key. - @item function-key-map The parent keymap of all @code{local-function-key-map} (q.v.@:) instances. diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi index b39373f0727..80f79b67e52 100644 --- a/doc/lispref/markers.texi +++ b/doc/lispref/markers.texi @@ -609,8 +609,8 @@ the function @code{use-region-p} for that (@pxref{The Region}). @defvarx deactivate-mark-hook These normal hooks are run, respectively, when the mark becomes active and when it becomes inactive. The hook @code{activate-mark-hook} is -also run at the end of the command loop if the mark is active and it -is possible that the region may have changed. +also run when the region is reactivated, for instance after using a +command that switches back to a buffer that has an active mark. @ignore This piece of command_loop_1, run unless deactivating the mark: if (current_buffer != prev_buffer || MODIFF != prev_modiff) diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 185d355ba70..d54c654562f 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -97,6 +97,14 @@ to be done. @xref{Text from Minibuffer}, for the non-completion minibuffer local maps. @xref{Completion Commands}, for the minibuffer local maps for completion. +@cindex active minibuffer + An active minibuffer usually has major mode @code{minibuffer-mode}. +This is an Emacs internal mode without any special features. To +customize the setup of minibuffers, we suggest you use +@code{minibuffer-setup-hook} (@pxref{Minibuffer Misc}) rather than +@code{minibuffer-mode-hook}, since the former is run later, after the +minibuffer has been fully initialized. + @cindex inactive minibuffer When a minibuffer is inactive, its major mode is @code{minibuffer-inactive-mode}, with keymap @@ -167,8 +175,10 @@ various applications such as completion. The argument @var{history} specifies a history list variable to use for saving the input and for history commands used in the minibuffer. -It defaults to @code{minibuffer-history}. You can optionally specify -a starting position in the history list as well. @xref{Minibuffer History}. +It defaults to @code{minibuffer-history}. If @var{history} is the +symbol @code{t}, history is not recorded. You can optionally specify +a starting position in the history list as well. @xref{Minibuffer +History}. If the variable @code{minibuffer-allow-text-properties} is non-@code{nil}, then the string that is returned includes whatever text @@ -379,8 +389,6 @@ default, it makes the following bindings: @end table @end defvar -@c In version 18, initial is required -@c Emacs 19 feature @defun read-no-blanks-input prompt &optional initial inherit-input-method This function reads a string from the minibuffer, but does not allow whitespace characters as part of the input: instead, those characters @@ -461,6 +469,18 @@ If @var{default} is a non-@code{nil} list, the first element of the list is used in the prompt. @end defun +@defvar read-minibuffer-restore-windows +If this option is non-@code{nil} (the default), getting input from the +minibuffer will restore, on exit, the window configurations of the frame +where the minibuffer was entered from and, if it is different, the frame +that owns the minibuffer window. This means that if, for example, a +user splits a window while getting input from the minibuffer on the same +frame, that split will be undone when exiting the minibuffer. + +If this option is @code{nil}, no such restorations are done. Hence, the +window split mentioned above will persist after exiting the minibuffer. +@end defvar + @node Object from Minibuffer @section Reading Lisp Objects with the Minibuffer @cindex minibuffer input, reading lisp objects @@ -701,8 +721,9 @@ A history list for numbers read by @code{read-number}. @end defvar @defvar goto-line-history -A history list for arguments to @code{goto-line}. This variable is -buffer local. +A history list for arguments to @code{goto-line}. This variable can +be made local in every buffer by customizing the user option +@code{goto-line-history-local}. @end defvar @c Less common: coding-system-history, input-method-history, @@ -971,16 +992,19 @@ and @var{suffix} holds the text after point. Normally completion operates on the whole string, so for all normal collections, this will always return @code{(0 . (length -@var{suffix}))}. But more complex completion such as completion on -files is done one field at a time. For example, completion of +@var{suffix}))}. But more complex completion, such as completion on +files, is done one field at a time. For example, completion of @code{"/usr/sh"} will include @code{"/usr/share/"} but not @code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists. Also @code{all-completions} on @code{"/usr/sh"} will not include @code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is @code{"/usr/sh"} and @var{suffix} is @code{"e/doc"}, -@code{completion-boundaries} will return @code{(5 . 1)} which tells us +@code{completion-boundaries} will return @w{@code{(5 . 1)}} which tells us that the @var{collection} will only return completion information that pertains to the area after @code{"/usr/"} and before @code{"/doc"}. +@code{try-completion} is not affected by nontrivial boundaries; e.g., +@code{try-completion} on @code{"/usr/sh"} might still return +@code{"/usr/share/"}, not @code{"share/"}. @end defun If you store a completion alist in a variable, you should mark the @@ -1108,9 +1132,10 @@ The function @code{completing-read} uses @code{minibuffer-local-must-match-map} if @var{require-match} is non-@code{nil}. @xref{Completion Commands}. -The argument @var{history} specifies which history list variable to use for -saving the input and for minibuffer history commands. It defaults to -@code{minibuffer-history}. @xref{Minibuffer History}. +The argument @var{history} specifies which history list variable to +use for saving the input and for minibuffer history commands. It +defaults to @code{minibuffer-history}. If @var{history} is the symbol +@code{t}, history is not recorded. @xref{Minibuffer History}. The argument @var{initial} is mostly deprecated; we recommend using a non-@code{nil} value only in conjunction with specifying a cons cell @@ -1175,9 +1200,9 @@ in the minibuffer to do completion. @defvar minibuffer-completion-table The value of this variable is the completion table (@pxref{Basic Completion}) used for completion in the minibuffer. This is the -global variable that contains what @code{completing-read} passes to +buffer-local variable that contains what @code{completing-read} passes to @code{try-completion}. It is used by minibuffer completion commands -such as @code{minibuffer-complete-word}. +such as @code{minibuffer-complete}. @end defvar @defvar minibuffer-completion-predicate @@ -1188,7 +1213,7 @@ minibuffer completion functions. @defvar minibuffer-completion-confirm This variable determines whether Emacs asks for confirmation before -exiting the minibuffer; @code{completing-read} binds this variable, +exiting the minibuffer; @code{completing-read} sets this variable, and the function @code{minibuffer-complete-and-exit} checks the value before exiting. If the value is @code{nil}, confirmation is not required. If the value is @code{confirm}, the user may exit with an @@ -1806,12 +1831,10 @@ default to that string. @item :affixation-function The value should be a function to add prefixes and suffixes to completions. This function must accept one argument, a list of -completions, and should return such a list of completions where -each element contains a list of three elements: a completion, -a prefix string, and a suffix string. When this function -returns a list of two elements, it is interpreted as a list -of a completion and a suffix string like in @code{:annotation-function}. -This function takes priority over @code{:annotation-function}. +completions, and should return a list of annotated completions. Each +element of the returned list must be a three-element list, the +completion, a prefix string, and a suffix string. This function takes +priority over @code{:annotation-function}. @item :exit-function The value should be a function to run after performing completion. @@ -1884,6 +1907,13 @@ should return @code{(boundaries @var{start} . @var{end})}, where string, and @var{end} is the position of the end boundary in @var{suffix}. +If a Lisp program returns nontrivial boundaries, it should make sure that the +@code{all-completions} operation is consistent with them. The +completions returned by @code{all-completions} should only pertain to +the piece of the prefix and suffix covered by the completion +boundaries. @xref{Basic Completion}, for the precise expected semantics +of completion boundaries. + @item metadata This specifies a request for information about the state of the current completion. The return value should have the form @@ -1922,10 +1952,18 @@ completions. The function should take one argument, return such a list of @var{completions} where each element contains a list of three elements: a completion, a prefix which is displayed before the completion string in the @file{*Completions*} buffer, and -a suffix displayed after the completion string. When this function -returns a list of two elements, it is interpreted as a list of -a completion and a suffix string like in @code{annotation-function}. -This function takes priority over @code{annotation-function}. +a suffix displayed after the completion string. This function +takes priority over @code{annotation-function}. + +@item group-function +The value should be a function for grouping the completion candidates. +The function must take two arguments, @var{completion}, which is a +completion candidate and @var{transform}, which is a boolean flag. If +@var{transform} is @code{nil}, the function must return the group +title of the group to which the candidate belongs. The returned title +can also be @code{nil}. Otherwise the function must return the +transformed candidate. The transformation can for example remove a +redundant prefix, which is displayed in the group title. @item display-sort-function The value should be a function for sorting completions. The function @@ -1962,7 +2000,7 @@ was entered. The return value of @code{completion-table-dynamic} is a function that can be used as the 2nd argument to @code{try-completion} and @code{all-completions}. Note that this function will always return -empty metadata and trivial boundaries (@pxref{Programmed Completion}). +empty metadata and trivial boundaries. @end defun @defun completion-table-with-cache function &optional ignore-case @@ -2219,9 +2257,10 @@ This function asks the user a series of questions, reading a single-character answer in the echo area for each one. The value of @var{list} specifies the objects to ask questions about. -It should be either a list of objects or a generator function. If it is -a function, it should expect no arguments, and should return either the -next object to ask about, or @code{nil}, meaning to stop asking questions. +It should be either a list of objects or a generator function. If it +is a function, it will be called with no arguments, and should return +either the next object to ask about, or @code{nil}, meaning to stop +asking questions. The argument @var{prompter} specifies how to ask each question. If @var{prompter} is a string, the question text is computed like this: @@ -2232,19 +2271,20 @@ The argument @var{prompter} specifies how to ask each question. If @noindent where @var{object} is the next object to ask about (as obtained from -@var{list}). +@var{list}). @xref{Formatting Strings}, for more information about +@code{format}. -If not a string, @var{prompter} should be a function of one argument -(the next object to ask about) and should return the question text. If -the value is a string, that is the question to ask the user. The -function can also return @code{t}, meaning do act on this object (and -don't ask the user), or @code{nil}, meaning ignore this object (and don't -ask the user). +If @var{prompter} is not a string, it should be a function of one +argument (the object to ask about) and should return the question text +for that object. If the value @var{prompter} returns is a string, +that is the question to ask the user. The function can also return +@code{t}, meaning to act on this object without asking the user, or +@code{nil}, which means to silently ignore this object. -The argument @var{actor} says how to act on the answers that the user -gives. It should be a function of one argument, and it is called with -each object that the user says yes for. Its argument is always an -object obtained from @var{list}. +The argument @var{actor} says how to act on the objects for which the +user answers yes. It should be a function of one argument, and will +be called with each object from @var{list} for which the user answers +yes. If the argument @var{help} is given, it should be a list of this form: @@ -2254,34 +2294,49 @@ If the argument @var{help} is given, it should be a list of this form: @noindent where @var{singular} is a string containing a singular noun that -describes the objects conceptually being acted on, @var{plural} is the +describes a single object to be acted on, @var{plural} is the corresponding plural noun, and @var{action} is a transitive verb -describing what @var{actor} does. +describing what @var{actor} does with the objects. -If you don't specify @var{help}, the default is @code{("object" -"objects" "act on")}. +If you don't specify @var{help}, it defaults to the list +@w{@code{("object" "objects" "act on")}}. -Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or -@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip -that object; @kbd{!} to act on all following objects; @key{ESC} or -@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on -the current object and then exit; or @kbd{C-h} to get help. These are -the same answers that @code{query-replace} accepts. The keymap -@code{query-replace-map} defines their meaning for @code{map-y-or-n-p} -as well as for @code{query-replace}; see @ref{Search and Replace}. +Each time a question is asked, the user can answer as follows: + +@table @asis +@item @kbd{y}, @kbd{Y}, or @kbd{@key{SPC}} +act on the object +@item @kbd{n}, @kbd{N}, or @kbd{@key{DEL}} +skip the object +@item @kbd{!} +act on all the following objects +@item @kbd{@key{ESC}} or @kbd{q} +exit (skip all following objects) +@item @kbd{.} (period) +act on the object and then exit +@item @kbd{C-h} +get help +@end table + +@noindent +These are the same answers that @code{query-replace} accepts. The +keymap @code{query-replace-map} defines their meaning for +@code{map-y-or-n-p} as well as for @code{query-replace}; see +@ref{Search and Replace}. You can use @var{action-alist} to specify additional possible answers -and what they mean. It is an alist of elements of the form -@code{(@var{char} @var{function} @var{help})}, each of which defines one -additional answer. In this element, @var{char} is a character (the +and what they mean. If provided, @var{action-alist} should be an +alist whose elements are of the form @w{@code{(@var{char} +@var{function} @var{help})}}. Each of the alist elements defines one +additional answer. In each element, @var{char} is a character (the answer); @var{function} is a function of one argument (an object from -@var{list}); @var{help} is a string. - -When the user responds with @var{char}, @code{map-y-or-n-p} calls -@var{function}. If it returns non-@code{nil}, the object is considered -acted upon, and @code{map-y-or-n-p} advances to the next object in -@var{list}. If it returns @code{nil}, the prompt is repeated for the -same object. +@var{list}); and @var{help} is a string. When the user responds with +@var{char}, @code{map-y-or-n-p} calls @var{function}. If it returns +non-@code{nil}, the object is considered to have been acted upon, and +@code{map-y-or-n-p} advances to the next object in @var{list}. If it +returns @code{nil}, the prompt is repeated for the same object. If +the user requests help, the text in @var{help} is used to describe +these additional answers. Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it @@ -2393,7 +2448,7 @@ minibuffer. @deffn Command exit-minibuffer This command exits the active minibuffer. It is normally bound to keys in minibuffer local keymaps. The command throws an error if the -current buffer is not the active minibuffer. +current buffer is a minibuffer, but not the active minibuffer. @end deffn @deffn Command self-insert-and-exit @@ -2474,7 +2529,6 @@ usual minibuffer input functions because they all start by choosing the minibuffer window according to the selected frame. @end defun -@c Emacs 19 feature @defun window-minibuffer-p &optional window This function returns @code{t} if @var{window} is a minibuffer window. @var{window} defaults to the selected window. @@ -2618,7 +2672,6 @@ when the minibuffer is active, not even if you switch to another window to do it. @end defopt -@c Emacs 19 feature If a command name has a property @code{enable-recursive-minibuffers} that is non-@code{nil}, then the command can use the minibuffer to read arguments even if it is invoked from the minibuffer. A command can diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index ce7727b87eb..d9caeab3bc3 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -861,6 +861,13 @@ abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table} if @var{parent} is @code{nil}. (Again, a @code{nil} value is @emph{not} equivalent to not specifying this keyword.) +@item :interactive +Modes are interactive commands by default. If you specify a +@code{nil} value, the mode defined here won't be interactive. This is +useful for modes that are never meant to be activated by users +manually, but are only supposed to be used in some specially-formatted +buffer. + @item :group If this is specified, the value should be the customization group for this mode. (Not all major modes have one.) The command @@ -1454,6 +1461,16 @@ used only with Diff mode. other minor modes in effect. It should be possible to activate and deactivate minor modes in any order. +@defvar local-minor-modes +This buffer-local variable lists the currently enabled minor modes in +the current buffer, and is a list of symbols. +@end defvar + +@defvar global-minor-modes +This variable lists the currently enabled global minor modes, and is a +list of symbols. +@end defvar + @defvar minor-mode-list The value of this variable is a list of all minor mode commands. @end defvar @@ -1643,7 +1660,7 @@ reserved for users. @xref{Key Binding Conventions}. The macro @code{define-minor-mode} offers a convenient way of implementing a mode in one self-contained definition. -@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{} +@defmac define-minor-mode mode doc keyword-args@dots{} body@dots{} This macro defines a new minor mode whose name is @var{mode} (a symbol). It defines a command named @var{mode} to toggle the minor mode, with @var{doc} as its documentation string. @@ -1658,41 +1675,12 @@ If @var{doc} is @code{nil}, the macro supplies a default documentation string explaining the above. By default, it also defines a variable named @var{mode}, which is set to -@code{t} or @code{nil} by enabling or disabling the mode. The variable -is initialized to @var{init-value}. Except in unusual circumstances -(see below), this value must be @code{nil}. - -The string @var{lighter} says what to display in the mode line -when the mode is enabled; if it is @code{nil}, the mode is not displayed -in the mode line. - -The optional argument @var{keymap} specifies the keymap for the minor -mode. If non-@code{nil}, it should be a variable name (whose value is -a keymap), a keymap, or an alist of the form - -@example -(@var{key-sequence} . @var{definition}) -@end example - -@noindent -where each @var{key-sequence} and @var{definition} are arguments -suitable for passing to @code{define-key} (@pxref{Changing Key -Bindings}). If @var{keymap} is a keymap or an alist, this also -defines the variable @code{@var{mode}-map}. +@code{t} or @code{nil} by enabling or disabling the mode. -The above three arguments @var{init-value}, @var{lighter}, and -@var{keymap} can be (partially) omitted when @var{keyword-args} are -used. The @var{keyword-args} consist of keywords followed by +The @var{keyword-args} consist of keywords followed by corresponding values. A few keywords have special meanings: @table @code -@item :group @var{group} -Custom group name to use in all generated @code{defcustom} forms. -Defaults to @var{mode} without the possible trailing @samp{-mode}. -@strong{Warning:} don't use this default group name unless you have -written a @code{defgroup} to define that group properly. @xref{Group -Definitions}. - @item :global @var{global} If non-@code{nil}, this specifies that the minor mode should be global rather than buffer-local. It defaults to @code{nil}. @@ -1702,19 +1690,34 @@ One of the effects of making a minor mode global is that the through the Customize interface turns the mode on and off, and its value can be saved for future Emacs sessions (@pxref{Saving Customizations,,, emacs, The GNU Emacs Manual}. For the saved -variable to work, you should ensure that the @code{define-minor-mode} -form is evaluated each time Emacs starts; for packages that are not -part of Emacs, the easiest way to do this is to specify a -@code{:require} keyword. +variable to work, you should ensure that the minor mode function +is available each time Emacs starts; usually this is done by +marking the @code{define-minor-mode} form as autoloaded. @item :init-value @var{init-value} -This is equivalent to specifying @var{init-value} positionally. +This is the value to which the @var{mode} variable is initialized. +Except in unusual circumstances (see below), this value must be +@code{nil}. @item :lighter @var{lighter} -This is equivalent to specifying @var{lighter} positionally. +The string @var{lighter} says what to display in the mode line +when the mode is enabled; if it is @code{nil}, the mode is not displayed +in the mode line. @item :keymap @var{keymap} -This is equivalent to specifying @var{keymap} positionally. +The optional argument @var{keymap} specifies the keymap for the minor +mode. If non-@code{nil}, it should be a variable name (whose value is +a keymap), a keymap, or an alist of the form + +@example +(@var{key-sequence} . @var{definition}) +@end example + +@noindent +where each @var{key-sequence} and @var{definition} are arguments +suitable for passing to @code{define-key} (@pxref{Changing Key +Bindings}). If @var{keymap} is a keymap or an alist, this also +defines the variable @code{@var{mode}-map}. @item :variable @var{place} This replaces the default variable @var{mode}, used to store the state @@ -1725,11 +1728,17 @@ anything that can be used with the @code{setf} function (@pxref{Generalized Variables}). @var{place} can also be a cons @code{(@var{get} . @var{set})}, where @var{get} is an expression that returns the current state, -and @var{set} is a function of one argument (a state) that sets it. +and @var{set} is a function of one argument (a state) which should be +assigned to @var{place}. @item :after-hook @var{after-hook} This defines a single Lisp form which is evaluated after the mode hooks have run. It should not be quoted. + +@item :interactive @var{value} +Minor modes are interactive commands by default. If @var{value} is +@code{nil}, this is inhibited. If @var{value} is a list of symbols, +it's used to say which major modes this minor mode is useful in. @end table Any other keyword arguments are passed directly to the @@ -2243,16 +2252,15 @@ number. The format used to display column numbers when @code{column-number-mode} (@pxref{Optional Mode Line,,, emacs, The GNU Emacs Manual}) is switched on. @samp{%c} in the format will be -replaced with the column number, and this is zero-based if -@code{column-number-indicator-zero-based} is non-@code{nil}, and -one-based if @code{column-number-indicator-zero-based} is @code{nil}. +replaced with a zero-based column number, and @samp{%C} will be +replaced with a one-based column number. @end defvar @defvar mode-line-position-column-line-format The format used to display column numbers when both @code{line-number-mode} and @code{column-number-mode} are switched on. -See the previous two variables for the meaning of the @samp{%l} and -@samp{%c} format specs. +See the previous two variables for the meaning of the @samp{%l}, +@samp{%c} and @samp{%C} format specs. @end defvar @defvar minor-mode-alist @@ -2279,11 +2287,14 @@ enabled separately in each buffer. @defvar global-mode-string This variable holds a mode line construct that, by default, appears in -the mode line just after the @code{which-function-mode} minor mode if set, -else after @code{mode-line-modes}. The command @code{display-time} sets +the mode line just after the @code{which-function-mode} minor mode if +set, else after @code{mode-line-modes}. Elements that are added to +this construct should normally end in a space (to ensure that +consecutive @code{global-mode-string} elements display properly). For +instance, the command @code{display-time} sets @code{global-mode-string} to refer to the variable -@code{display-time-string}, which holds a string containing the time and -load information. +@code{display-time-string}, which holds a string containing the time +and load information. The @samp{%M} construct substitutes the value of @code{global-mode-string}, but that is obsolete, since the variable is @@ -2977,10 +2988,6 @@ highlighted (instead of the entire text that @var{matcher} matched). ("fu\\(bar\\)" . 1) @end example -If you use @code{regexp-opt} to produce the regular expression -@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp -Functions}) to calculate the value for @var{subexp}. - @item (@var{matcher} . @var{facespec}) In this kind of element, @var{facespec} is an expression whose value specifies the face to use for highlighting. In the simplest case, @@ -2996,7 +3003,8 @@ name. However, @var{facespec} can also evaluate to a list of this form: @example -(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) +(@var{subexp} +(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})) @end example @noindent @@ -3225,8 +3233,7 @@ set by means of @var{other-vars} in @code{font-lock-defaults} @defvar font-lock-mark-block-function If this variable is non-@code{nil}, it should be a function that is called with no arguments, to choose an enclosing range of text for -refontification for the command @kbd{M-o M-o} -(@code{font-lock-fontify-block}). +refontification for the command @kbd{M-x font-lock-fontify-block}. The function should report its choice by placing the region around it. A good choice is a range of text large enough to give proper results, @@ -3438,9 +3445,17 @@ for string constants. @item font-lock-doc-face @vindex font-lock-doc-face -for documentation strings in the code. This inherits, by default, from +for documentation embedded in program code inside specially-formed +comments or strings. This face inherits, by default, from @code{font-lock-string-face}. +@item font-lock-doc-markup-face +@vindex font-lock-doc-markup-face +for mark-up elements in text using @code{font-lock-doc-face}. +It is typically used for the mark-up constructs in documentation embedded +in program code, following conventions such as Haddock, Javadoc or Doxygen. +This face inherits, by default, from @code{font-lock-constant-face}. + @item font-lock-negation-char-face @vindex font-lock-negation-char-face for easily-overlooked negation characters. @@ -3547,7 +3562,7 @@ which will instruct font-lock not to start or end the scan in the middle of the construct. @end itemize - There are three ways to do rehighlighting of multiline constructs: + There are several ways to do rehighlighting of multiline constructs: @itemize @item @@ -3569,6 +3584,17 @@ This works only if @code{jit-lock-contextually} is used, and with the same delay before rehighlighting, but like @code{font-lock-multiline}, it also handles the case where highlighting depends on subsequent lines. +@item +If parsing the @emph{syntax} of a construct depends on it being parsed in one +single chunk, you can add the @code{syntax-multiline} text property +over the construct in question. The most common use for this is when +the syntax property to apply to @samp{FOO} depend on some later text +@samp{BAR}: By placing this text property over the whole of +@samp{FOO...BAR}, you make sure that any change of @samp{BAR} will +also cause the syntax property of @samp{FOO} to be recomputed. +Note: For this to work, the mode needs to add +@code{syntax-propertize-multiline} to +@code{syntax-propertize-extend-region-functions}. @end itemize @menu diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index 84f5d2f0819..c22930d624e 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -301,7 +301,7 @@ character, and returns that character. If @var{char} is neither @end defun @defun unibyte-char-to-multibyte char -This convert the unibyte character @var{char} to a multibyte +This converts the unibyte character @var{char} to a multibyte character, assuming @var{char} is either @acronym{ASCII} or raw 8-bit byte. @end defun @@ -676,7 +676,7 @@ This function returns the value of @var{char}'s @var{propname} property. @end group @group (get-char-code-property ?\( 'paired-bracket) - @result{} 41 ;; closing parenthesis + @result{} 41 ; closing parenthesis @end group @group (get-char-code-property ?\) 'bracket-type) @@ -955,13 +955,13 @@ translating the result. @defvar standard-translation-table-for-decode This is the default translation table for decoding. If a coding -systems specifies its own translation tables, the table that is the +system specifies its own translation tables, the table that is the value of this variable, if non-@code{nil}, is applied after them. @end defvar @defvar standard-translation-table-for-encode This is the default translation table for encoding. If a coding -systems specifies its own translation tables, the table that is the +system specifies its own translation tables, the table that is the value of this variable, if non-@code{nil}, is applied after them. @end defvar @@ -1258,7 +1258,7 @@ name or @code{nil}. @defun check-coding-system coding-system This function checks the validity of @var{coding-system}. If that is valid, it returns @var{coding-system}. If @var{coding-system} is -@code{nil}, the function return @code{nil}. For any other values, it +@code{nil}, the function returns @code{nil}. For any other values, it signals an error whose @code{error-symbol} is @code{coding-system-error} (@pxref{Signaling Errors, signal}). @end defun diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index 63e3e0bace5..d28e15869aa 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -237,7 +237,8 @@ precede the number and its exponent. For example, @samp{1500.0}, @samp{+15e2}, @samp{15.0e+2}, @samp{+1500000e-3}, and @samp{.15e4} are five ways of writing a floating-point number whose value is 1500. They are all equivalent. Like Common Lisp, Emacs Lisp requires at -least one digit after any decimal point in a floating-point number; +least one digit after a decimal point in a floating-point number that +does not have an exponent; @samp{1500.} is an integer, not a floating-point number. Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero @@ -1250,7 +1251,7 @@ other strings to choose various seed values. This function returns a pseudo-random integer. Repeated calls return a series of pseudo-random integers. -If @var{limit} is a positive fixnum, the value is chosen to be +If @var{limit} is a positive integer, the value is chosen to be nonnegative and less than @var{limit}. Otherwise, the value might be any fixnum, i.e., any integer from @code{most-negative-fixnum} through @code{most-positive-fixnum} (@pxref{Integer Basics}). diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 64e7d53d935..365d5ac8d61 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -148,9 +148,6 @@ starting list count: object, so when reading back the object, they will be the same object instead of copies (@pxref{Circular Objects}). -@item #@@N -Skip the next @samp{N} characters (@pxref{Comments}). - @item #xN @samp{N} represented as a hexadecimal number (@samp{#x2a}). @@ -1004,6 +1001,13 @@ It looks like this: @end example @end ifnottex + As a somewhat peculiar side effect of @code{(a b . c)} and +@code{(a . (b . c))} being equivalent, for consistency this means +that if you replace @code{b} here with the empty sequence, then it +follows that @code{(a . c)} and @code{(a . ( . c))} are equivalent, +too. This also means that @code{( . c)} is equivalent to @code{c}, +but this is seldom used. + @node Association List Type @subsubsection Association List Type @@ -2414,7 +2418,7 @@ that is evaluated. For example: @noindent Although the list @code{(0.5)} was mutable when it was created, it should not -have been changed via @code{setcar} because it given to @code{eval}. The +have been changed via @code{setcar} because it was given to @code{eval}. The reverse does not occur: an object that should not be changed never becomes mutable afterwards. diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 37fde0a953d..12ddaf04b6a 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -2167,6 +2167,11 @@ if @var{time} is @code{t}, then the timer runs whenever the time is a multiple of @var{repeat} seconds after the epoch. This is useful for functions like @code{display-time}. +If Emacs didn't get any CPU time when the timer would have run (for +example if the system was busy running another process or if the +computer was sleeping or in a suspended state), the timer will run as +soon as Emacs resumes and is idle. + The function @code{run-at-time} returns a timer value that identifies the particular scheduled future action. You can use this value to call @code{cancel-timer} (see below). @@ -2369,11 +2374,17 @@ has no effect except in @sc{cbreak} mode. The argument @var{meta} controls support for input character codes above 127. If @var{meta} is @code{t}, Emacs converts characters with -the 8th bit set into Meta characters. If @var{meta} is @code{nil}, +the 8th bit set into Meta characters, before it decodes them as needed +(@pxref{Terminal I/O Encoding}). If @var{meta} is @code{nil}, Emacs disregards the 8th bit; this is necessary when the terminal uses -it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil}, -Emacs uses all 8 bits of input unchanged. This is good for terminals -that use 8-bit character sets. +it as a parity bit. If @var{meta} is the symbol @code{encoded}, Emacs +first decodes the characters using all the 8 bits of each byte, and +then converts the decoded single-byte characters into Meta characters +if they have their eighth bit set. Finally, if @var{meta} is neither +@code{t} nor @code{nil} nor @code{encoded}, Emacs uses all 8 bits of +input unchanged, both before and after decoding them. This is good +for terminals that use 8-bit character sets and don't encode the Meta +modifier as the eighth bit. If @var{quit-char} is non-@code{nil}, it specifies the character to use for quitting. Normally this character is @kbd{C-g}. @@ -2398,9 +2409,11 @@ flow control for output to the terminal. This value is meaningful only when @var{interrupt} is @code{nil}. @item meta is @code{t} if Emacs treats the eighth bit of input characters as -the meta bit; @code{nil} means Emacs clears the eighth bit of every -input character; any other value means Emacs uses all eight bits as the -basic character code. +the Meta bit before decoding input; @code{encoded} if Emacs treats the +eighth bit of the decoded single-byte characters as the Meta bit; +@code{nil} if Emacs clears the eighth bit of every input character; +any other value means Emacs uses all eight bits as the basic character +code. @item quit is the character Emacs currently uses for quitting, usually @kbd{C-g}. @end table diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index e8aaa3ae1d1..9c033fe3df8 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -283,11 +283,14 @@ variable @code{load-file-name} (@pxref{Loading}). Here is an example: @section Creating and Maintaining Package Archives @cindex package archive +@cindex GNU ELPA +@cindex non-GNU ELPA Via the Package Menu, users may download packages from @dfn{package archives}. Such archives are specified by the variable -@code{package-archives}, whose default value contains a single entry: -the archive hosted by the GNU project at @url{https://elpa.gnu.org}. This -section describes how to set up and maintain a package archive. +@code{package-archives}, whose default value lists the archives +hosted on @url{https://elpa.gnu.org, GNU ELPA} and +@url{https://elpa.nongnu.org, non-GNU ELPA}. This section describes +how to set up and maintain a package archive. @cindex base location, package archive @defopt package-archives diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index dc0c7442d8d..769aeed75f8 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -232,7 +232,6 @@ backward until encountering the front of a word, rather than forward. @end deffn @defopt words-include-escapes -@c Emacs 19 feature This variable affects the behavior of @code{forward-word} and @code{backward-word}, and everything that uses them. If it is non-@code{nil}, then characters in the escape and character-quote diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 83461656063..90c42156372 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -247,6 +247,16 @@ protected by @code{shell-quote-argument}; @code{combine-and-quote-strings} is @emph{not} intended to protect special characters from shell evaluation. +@defun split-string-shell-command string +This function splits @var{string} into substrings, respecting double +and single quotes, as well as backslash quoting. + +@smallexample +(split-string-shell-command "ls /tmp/'foo bar'") + @result{} ("ls" "/tmp/foo bar") +@end smallexample +@end defun + @defun split-string-and-unquote string &optional separators This function splits @var{string} into substrings at matches for the regular expression @var{separators}, like @code{split-string} does @@ -1325,7 +1335,7 @@ the numeric ID of the foreground process group of @var{process}; it returns @code{nil} if Emacs can be certain that this is not so. The value is @code{t} if Emacs cannot tell whether this is true. This function signals an error if @var{process} is a network, serial, or -pipe connection, or is the subprocess is not active. +pipe connection, or if the subprocess is not active. @end defun @node Signals to Processes @@ -3354,24 +3364,37 @@ To use the functions referred to in this section, load the direction is also known as @dfn{serializing} or @dfn{packing}. @menu -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. +* Bindat Types:: Describing data layout. +* Bindat Functions:: Doing the unpacking and packing. +* Bindat Computed Types:: Advanced data layout specifications. @end menu -@node Bindat Spec +@node Bindat Types @subsection Describing Data Layout +@cindex bindat types +@cindex data layout specification +@cindex bindat type expression +@cindex base type, in bindat specification +@cindex composite type, in bindat specification To control unpacking and packing, you write a @dfn{data layout -specification}, a special nested list describing named and typed -@dfn{fields}. This specification controls the length of each field to be -processed, and how to pack or unpack it. We normally keep bindat specs -in variables whose names end in @samp{-bindat-spec}; that kind of name -is automatically recognized as risky. - -@cindex endianness -@cindex big endian -@cindex little endian -@cindex network byte ordering +specification}, also called a @dfn{Bindat type expression}. This can +be a @dfn{base type} or a @dfn{composite type} made of several fields, +where the specification controls the length of each field to be +processed, and how to pack or unpack it. We normally keep bindat type +values in variables whose names end in @code{-bindat-spec}; that kind +of name is automatically recognized as risky (@pxref{File Local +Variables}). + +@defmac bindat-type &rest type +Creates a Bindat type @emph{value} object according to the Bindat type +@emph{expression} @var{type}. +@end defmac + +@cindex endianness, in bindat specification +@cindex big endian, in bindat specification +@cindex little endian, in bindat specification +@cindex network byte ordering, in Bindat specification A field's @dfn{type} describes the size (in bytes) of the object that the field represents and, in the case of multibyte fields, how the bytes are ordered within the field. The two possible orderings @@ -3386,164 +3409,92 @@ type values: @itemx byte Unsigned byte, with length 1. -@item u16 -@itemx word -@itemx short -Unsigned integer in network byte order, with length 2. - -@item u24 -Unsigned integer in network byte order, with length 3. +@item uint @var{bitlen} +Unsigned integer in network byte order, with @var{bitlen} bits. +@var{bitlen} has to be a multiple of 8. -@item u32 -@itemx dword -@itemx long -Unsigned integer in network byte order, with length 4. -Note: These values may be limited by Emacs's integer implementation limits. - -@item u16r -@itemx u24r -@itemx u32r -Unsigned integer in little endian order, with length 2, 3 and 4, respectively. +@item uintr @var{bitlen} +Unsigned integer in little endian order, with @var{bitlen} bits. +@var{bitlen} has to be a multiple of 8. @item str @var{len} -String of length @var{len}. +String of bytes of length @var{len}. -@item strz @var{len} -Zero-terminated string, in a fixed-size field with length @var{len}. +@item strz &optional @var{len} +Zero-terminated string of bytes, can be of arbitrary length or in a fixed-size +field with length @var{len}. @item vec @var{len} [@var{type}] -Vector of @var{len} elements of type @var{type}, defaulting to bytes. -The @var{type} is any of the simple types above, or another vector -specified as a list of the form @code{(vec @var{len} [@var{type}])}. +Vector of @var{len} elements. The type of the elements is given by +@var{type}, defaulting to bytes. The @var{type} can be any Bindat +type expression. -@item ip -@c FIXME? IPv6? -Four-byte vector representing an Internet address. For example: -@code{[127 0 0 1]} for localhost. +@item repeat @var{len} [@var{type}] +Like @code{vec}, but it unpacks to and packs from lists, whereas +@code{vec} unpacks to vectors. @item bits @var{len} -List of set bits in @var{len} bytes. The bytes are taken in big -endian order and the bits are numbered starting with @code{8 * -@var{len} @minus{} 1} and ending with zero. For example: @code{bits -2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and -@code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}. - -@item (eval @var{form}) -@var{form} is a Lisp expression evaluated at the moment the field is -unpacked or packed. The result of the evaluation should be one of the -above-listed type specifications. -@end table - -For a fixed-size field, the length @var{len} is given as an integer -specifying the number of bytes in the field. - -When the length of a field is not fixed, it typically depends on the -value of a preceding field. In this case, the length @var{len} can be -given either as a list @code{(@var{name} ...)} identifying a -@dfn{field name} in the format specified for @code{bindat-get-field} -below, or by an expression @code{(eval @var{form})} where @var{form} -should evaluate to an integer, specifying the field length. - -A field specification generally has the form @code{([@var{name}] -@var{handler})}, where @var{name} is optional. Don't use names that -are symbols meaningful as type specifications (above) or handler -specifications (below), since that would be ambiguous. @var{name} can -be a symbol or an expression @code{(eval @var{form})}, in which case -@var{form} should evaluate to a symbol. - -@var{handler} describes how to unpack or pack the field and can be one -of the following: - -@table @code -@item @var{type} -Unpack/pack this field according to the type specification @var{type}. - -@item eval @var{form} -Evaluate @var{form}, a Lisp expression, for side-effect only. If the -field name is specified, the value is bound to that field name. +List of bits that are set to 1 in @var{len} bytes. The bytes are +taken in big-endian order, and the bits are numbered starting with +@code{8 * @var{len} @minus{} 1} and ending with zero. For example: +@code{bits 2} unpacks @code{#x28} @code{#x1c} to @w{@code{(2 3 4 11 13)}} +and @code{#x1c} @code{#x28} to @w{@code{(3 5 10 11 12)}}. @item fill @var{len} -Skip @var{len} bytes. In packing, this leaves them unchanged, -which normally means they remain zero. In unpacking, this means -they are ignored. +@var{len} bytes used as a mere filler. In packing, these bytes are +are left unchanged, which normally means they remain zero. +When unpacking, this just returns nil. @item align @var{len} -Skip to the next multiple of @var{len} bytes. - -@item struct @var{spec-name} -Process @var{spec-name} as a sub-specification. This describes a -structure nested within another structure. - -@item union @var{form} (@var{tag} @var{spec})@dots{} -@c ??? I don't see how one would actually use this. -@c ??? what kind of expression would be useful for @var{form}? -Evaluate @var{form}, a Lisp expression, find the first @var{tag} -that matches it, and process its associated data layout specification -@var{spec}. Matching can occur in one of three ways: - -@itemize -@item -If a @var{tag} has the form @code{(eval @var{expr})}, evaluate -@var{expr} with the variable @code{tag} dynamically bound to the value -of @var{form}. A non-@code{nil} result indicates a match. - -@item -@var{tag} matches if it is @code{equal} to the value of @var{form}. - -@item -@var{tag} matches unconditionally if it is @code{t}. -@end itemize - -@item repeat @var{count} @var{field-specs}@dots{} -Process the @var{field-specs} recursively, in order, then repeat -starting from the first one, processing all the specifications @var{count} -times overall. The @var{count} is given using the same formats as a -field length---if an @code{eval} form is used, it is evaluated just once. -For correct operation, each specification in @var{field-specs} must -include a name. +Same as @code{fill} except the number of bytes is that needed to skip +to the next multiple of @var{len} bytes. + +@item type @var{exp} +This lets you refer to a type indirectly: @var{exp} is a Lisp +expression which should return a Bindat type @emph{value}. + +@item unit @var{exp} +This is a trivial type which uses up 0 bits of space. @var{exp} +describes the value returned when we try to ``unpack'' such a field. + +@item struct @var{fields}... +Composite type made of several fields. Every field is of the form +@code{(@var{name} @var{type})} where @var{type} can be any Bindat +type expression. @var{name} can be @code{_} when the field's value +does not deserve to be named, as is often the case for @code{align} +and @code{fill} fields. +When the context makes it clear that this is a Bindat type expression, +the symbol @code{struct} can be omitted. @end table -For the @code{(eval @var{form})} forms used in a bindat specification, -the @var{form} can access and update these dynamically bound variables -during evaluation: +In the types above, @var{len} and @var{bitlen} are given as an integer +specifying the number of bytes (or bits) in the field. When the +length of a field is not fixed, it typically depends on the value of +preceding fields. For this reason, the length @var{len} does not have +to be a constant but can be any Lisp expression and it can refer to +the value of previous fields via their name. -@table @code -@item last -Value of the last field processed. - -@item bindat-raw -The data as a byte array. - -@item bindat-idx -Current index (within @code{bindat-raw}) for unpacking or packing. - -@item struct -The alist containing the structured data that have been unpacked so -far, or the entire structure being packed. You can use -@code{bindat-get-field} to access specific fields of this structure. - -@item count -@itemx index -Inside a @code{repeat} block, these contain the maximum number of -repetitions (as specified by the @var{count} parameter), and the -current repetition number (counting from 0). Setting @code{count} to -zero will terminate the inner-most repeat block after the current -repetition has completed. -@end table +For example, the specification of a data layout where a leading byte gives +the size of a subsequent vector of 16 bit integers could be: +@example +(bindat-type + (len u8) + (payload vec (1+ len) uint 16)) +@end example @node Bindat Functions @subsection Functions to Unpack and Pack Bytes +@cindex bindat functions - In the following documentation, @var{spec} refers to a data layout -specification, @code{bindat-raw} to a byte array, and @var{struct} to an -alist representing unpacked field data. + In the following documentation, @var{type} refers to a Bindat type +value as returned from @code{bindat-type}, @var{raw} to a byte +array, and @var{struct} to an alist representing unpacked field data. -@defun bindat-unpack spec bindat-raw &optional bindat-idx -@c FIXME? Again, no multibyte? +@defun bindat-unpack type raw &optional idx This function unpacks data from the unibyte string or byte -array @code{bindat-raw} -according to @var{spec}. Normally, this starts unpacking at the -beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it +array @var{raw} +according to @var{type}. Normally, this starts unpacking at the +beginning of the byte array, but if @var{idx} is non-@code{nil}, it specifies a zero-based starting position to use instead. The value is an alist or nested alist in which each element describes @@ -3555,12 +3506,13 @@ This function selects a field's data from the nested alist @var{struct}. Usually @var{struct} was returned by @code{bindat-unpack}. If @var{name} corresponds to just one argument, that means to extract a top-level field value. Multiple @var{name} -arguments specify repeated lookup of sub-structures. An integer name -acts as an array index. +arguments specify repeated lookup of sub-structures. An integer +@var{name} acts as an array index. -For example, if @var{name} is @code{(a b 2 c)}, that means to find -field @code{c} in the third element of subfield @code{b} of field -@code{a}. (This corresponds to @code{struct.a.b[2].c} in C.) +For example, @w{@code{(bindat-get-field @var{struct} a b 2 c)}} means +to find field @code{c} in the third element of subfield @code{b} of +field @code{a}. (This corresponds to @code{@var{struct}.a.b[2].c} in +the C programming language syntax.) @end defun Although packing and unpacking operations change the organization of @@ -3571,20 +3523,20 @@ both pieces of information contribute to its calculation. Likewise, the length of a string or array being unpacked may be longer than the data's total length as described by the specification. -@defun bindat-length spec struct +@defun bindat-length type struct This function returns the total length of the data in @var{struct}, -according to @var{spec}. +according to @var{type}. @end defun -@defun bindat-pack spec struct &optional bindat-raw bindat-idx -This function returns a byte array packed according to @var{spec} from +@defun bindat-pack type struct &optional raw idx +This function returns a byte array packed according to @var{type} from the data in the alist @var{struct}. It normally creates and fills a -new byte array starting at the beginning. However, if @var{bindat-raw} +new byte array starting at the beginning. However, if @var{raw} is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to -pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting -offset for packing into @code{bindat-raw}. +pack into. If @var{idx} is non-@code{nil}, it specifies the starting +offset for packing into @var{raw}. -When pre-allocating, you should make sure @code{(length @var{bindat-raw})} +When pre-allocating, you should make sure @code{(length @var{raw})} meets or exceeds the total length to avoid an out-of-range error. @end defun @@ -3598,3 +3550,74 @@ dotted notation. @result{} "127.0.0.1" @end example @end defun + +@node Bindat Computed Types +@subsection Advanced data layout specifications +@cindex bindat computed types + +Bindat type expressions are not limited to the types described +earlier. They can also be arbitrary Lisp forms returning Bindat +type expressions. For example, the type below describes data which +can either contain a 24-bit error code or a vector of bytes: + +@example +(bindat-type + (len u8) + (payload . (if (zerop len) (uint 24) (vec (1- len))))) +@end example + +@cindex bindat packing and unpacking into arbitrary types +Furthermore, while composite types are normally unpacked to (and +packed from) association lists, this can be changed via the use of +the following special keyword arguments: + +@table @code +@item :unpack-val @var{exp} +When the list of fields ends with this keyword argument, then the value +returned when unpacking is the value of @var{exp} instead of the +standard alist. @var{exp} can refer to all the previous fields by +their name. + +@item :pack-val @var{exp} +If a field's type is followed by this keyword argument, then the value +packed into this field is returned by @var{exp} instead of being +extracted from the alist. + +@item :pack-var @var{name} +If the list of fields is preceded by this keyword argument, then all +the subsequent @code{:pack-val} arguments can refer to the overall +value to pack into this composite type via the variable named +@var{name}. +@end table + +For example, one could describe a 16-bit signed integer as follows: + +@example +(defconst sint16-bindat-spec + (let* ((max (ash 1 15)) + (wrap (+ max max))) + (bindat-type :pack-var v + (n uint 16 :pack-val (if (< v 0) (+ v wrap) v)) + :unpack-val (if (>= n max) (- n wrap) n)))) +@end example + +Which would then behave as follows: +@example +(bindat-pack sint16-bindat-spec -8) + @result{} "\377\370" + +(bindat-unpack sint16-bindat-spec "\300\100") + @result{} -16320 +@end example + +@cindex define new bindat type forms +@cindex bindat, define new type forms +Finally, you can define new Bindat type forms to use in Bindat type +expressions with @code{bindat-defmacro}: + +@defmac bindat-defmacro name args &rest body +Define a new Bindat type expression named @var{name} and taking +arguments @var{args}. Its behavior follows that of @code{defmacro}, +which the important difference that the new forms can only be used +within Bindat type expressions. +@end defmac diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 16a8e56e90a..4d5ae3cb437 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -251,6 +251,11 @@ matches in the target buffer are highlighted. Each parenthesized sub-expression of the regexp is shown in a distinct face, which makes it easier to verify even very complex regexps. + Note that by default Emacs search ignores case (@pxref{Searching and +Case}). To enable case-sensitive regexp search and match, bind +@code{case-fold-search} to @code{nil} around the code you want to be +case-sensitive. + @menu * Syntax of Regexps:: Rules for writing regular expressions. * Regexp Example:: Illustrates regular expression syntax. @@ -363,7 +368,7 @@ preceding expression either once or not at all. For example, @anchor{Non-greedy repetition} @item @samp{*?}, @samp{+?}, @samp{??} @cindex non-greedy repetition characters in regexp -These are @dfn{non-greedy} variants of the operators @samp{*}, @samp{+} +are @dfn{non-greedy} variants of the operators @samp{*}, @samp{+} and @samp{?}. Where those operators match the largest possible substring (consistent with matching the entire containing expression), the non-greedy variants match the smallest possible substring @@ -438,6 +443,13 @@ including newline. However, a reversed range should always be from the letter @samp{z} to the letter @samp{a} to make it clear that it is not a typo; for example, @samp{[+-*/]} should be avoided, because it matches only @samp{/} rather than the likely-intended four characters. + +@item +If the end points of a range are raw 8-bit bytes (@pxref{Text +Representations}), or if the range start is ASCII and the end is a raw +byte (as in @samp{[a-\377]}), the range will match only ASCII +characters and raw 8-bit bytes, but not non-ASCII characters. This +feature is intended for searching text in unibyte buffers and strings. @end enumerate Some kinds of character alternatives are not the best style even @@ -2528,9 +2540,9 @@ associated with it still exists. @cindex replacement after search @cindex searching and replacing - If you want to find all matches for a regexp in part of the buffer, -and replace them, the best way is to write an explicit loop using -@code{re-search-forward} and @code{replace-match}, like this: + If you want to find all matches for a regexp in part of the buffer +and replace them, the most flexible way is to write an explicit loop +using @code{re-search-forward} and @code{replace-match}, like this: @example (while (re-search-forward "foo[ \t]+bar" nil t) @@ -2541,9 +2553,33 @@ and replace them, the best way is to write an explicit loop using @xref{Replacing Match,, Replacing the Text that Matched}, for a description of @code{replace-match}. - However, replacing matches in a string is more complex, especially -if you want to do it efficiently. So Emacs provides two functions to do -this. + It may be more convenient to limit the replacements to a specific +region. The function @code{replace-regexp-in-region} does that. + +@defun replace-regexp-in-region regexp replacement &optional start end +This function replaces all the occurrences of @var{regexp} with +@var{replacement} in the region of buffer text between @var{start} and +@var{end}; @var{start} defaults to position of point, and @var{end} +defaults to the last accessible position of the buffer. The search +for @var{regexp} is case-sensitive, and @var{replacement} is inserted +without changing its letter-case. The @var{replacement} string can +use the same special elements starting with @samp{\} as +@code{replace-match} does. The function returns the number of +replaced occurrences, or @code{nil} if @var{regexp} is not found. The +function preserves the position of point. + +@example +(replace-regexp-in-region "foo[ \t]+bar" "foobar") +@end example +@end defun + +@defun replace-string-in-region string replacement &optional start end + This function works similarly to @code{replace-regexp-in-region}, +but searches for, and replaces, literal @var{string}s instead of +regular expressions. +@end defun + + Emacs also has special functions for replacing matches in a string. @defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start This function copies @var{string} and searches it for matches for diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 0c74dbe2aa4..20816ce8ca2 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -609,7 +609,7 @@ returned value is a list. (seq-map-indexed (lambda (elt idx) (list idx elt)) '(a b c)) -@result{} ((0 a) (b 1) (c 2)) +@result{} ((0 a) (1 b) (2 c)) @end group @end example @end defun @@ -1111,6 +1111,23 @@ The @code{pcase} patterns provide an alternative facility for destructuring binding, see @ref{Destructuring with pcase Patterns}. @end defmac +@defmac seq-setq var-sequence val-sequence +@cindex sequence destructuring + This macro works similarly to @code{seq-let}, except that values are +assigned to variables as if by @code{setq} instead of as in a +@code{let} binding. + +@example +@group +(let ((a nil) + (b nil)) + (seq-setq (_ a _ b) '(1 2 3 4)) + (list a b)) +@result{} (2 4) +@end group +@end example +@end defmac + @defun seq-random-elt sequence This function returns an element of @var{sequence} taken at random. diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 5cae939b7bf..b4d7bc729f5 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -390,6 +390,22 @@ whitespace to a single space character, as well as removing all whitespace from the start and the end of @var{string}. @end defun +@defun string-trim-left string &optional regexp +Remove the leading text that matches @var{regexp} from @var{string}. +@var{regexp} defaults to @samp{[ \t\n\r]+}. +@end defun + +@defun string-trim-right string &optional regexp +Remove the trailing text that matches @var{regexp} from @var{string}. +@var{regexp} defaults to @samp{[ \t\n\r]+}. +@end defun + +@defun string-trim string &optional trim-left trim-right +Remove the leading text that matches @var{trim-left} and trailing text +that matches @var{trim-right} from from @var{string}. Both regexps +default to @samp{[ \t\n\r]+}. +@end defun + @defun string-fill string length Attempt to Word-wrap @var{string} so that no lines are longer than @var{length}. Filling is done on whitespace boundaries only. If diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 2df6c15c4ca..deec3f44c08 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -572,12 +572,14 @@ The function is called by @code{syntax-ppss} (@pxref{Position Parse}), and by Font Lock mode during syntactic fontification (@pxref{Syntactic Font Lock}). It is called with two arguments, @var{start} and @var{end}, which are the starting and ending positions of the text on -which it should act. It is allowed to call @code{syntax-ppss} on any -position before @var{end}, but if a Lisp program calls -@code{syntax-ppss} on some position and later modifies the buffer at -some earlier position, then it is that program's responsibility to -call @code{syntax-ppss-flush-cache} to flush the now obsolete info -from the cache. +which it should act. It is allowed to arbitrarily move point within +the region delimited by @var{start} and @var{end}; such motions don't +need to use @code{save-excursion} (@pxref{Excursions}). It is also +allowed to call @code{syntax-ppss} on any position before @var{end}, +but if a Lisp program calls @code{syntax-ppss} on some position and +later modifies the buffer at some earlier position, then it is that +program's responsibility to call @code{syntax-ppss-flush-cache} to +flush the now obsolete info from the cache. @strong{Caution:} When this variable is non-@code{nil}, Emacs removes @code{syntax-table} text properties arbitrarily and relies on @@ -1045,6 +1047,11 @@ Given a syntax descriptor @var{desc} (a string), this function returns the corresponding raw syntax descriptor. @end defun +@defun syntax-class-to-char syntax +Given a raw syntax descriptor @var{syntax} (an integer), this function +returns the corresponding syntax descriptor (a character). +@end defun + @defun syntax-after pos This function returns the raw syntax descriptor for the character in the buffer after position @var{pos}, taking account of syntax diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index b3673465240..9e0401fffb9 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -222,7 +222,9 @@ properties, just the characters themselves. @xref{Text Properties}. @defun buffer-string This function returns the contents of the entire accessible portion of -the current buffer, as a string. +the current buffer, as a string. If the text being copied has any +text properties, these are copied into the string along with the +characters they belong to. @end defun If you need to make sure the resulting string, when copied to a @@ -313,10 +315,11 @@ word on the same line is acceptable. @defun thing-at-point thing &optional no-properties Return the @var{thing} around or next to point, as a string. -The argument @var{thing} is a symbol which specifies a kind of syntactic -entity. Possibilities include @code{symbol}, @code{list}, @code{sexp}, -@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence}, -@code{whitespace}, @code{line}, @code{page}, and others. +The argument @var{thing} is a symbol which specifies a kind of +syntactic entity. Possibilities include @code{symbol}, @code{list}, +@code{sexp}, @code{defun}, @code{filename}, @code{existing-filename}, +@code{url}, @code{word}, @code{sentence}, @code{whitespace}, +@code{line}, @code{page}, and others. When the optional argument @var{no-properties} is non-@code{nil}, this function strips text properties from the return value. @@ -500,6 +503,15 @@ This is like @code{insert-buffer-substring} except that it does not copy any text properties. @end defun +@defun insert-into-buffer to-buffer &optional start end +This is like @code{insert-buffer-substring}, but works in the opposite +direction: The text is copied from the current buffer into +@var{to-buffer}. The block of text is copied to the current point in +@var{to-buffer}, and point (in that buffer) is advanced to after the +end of the copied text. Is @code{start}/@code{end} is @code{nil}, the +entire text in the current buffer is copied over. +@end defun + @xref{Sticky Properties}, for other insertion functions that inherit text properties from the nearby text in addition to inserting it. Whitespace inserted by indentation functions also inherits text @@ -1116,25 +1128,32 @@ one, it rotates the kill ring to place the yanked string at the front. @end deffn @deffn Command yank-pop &optional arg -This command replaces the just-yanked entry from the kill ring with a -different entry from the kill ring. - -This works only immediately after a @code{yank} or another -@code{yank-pop}. At such a time, the region contains text that was just -inserted by yanking. @code{yank-pop} deletes that text and inserts in -its place a different piece of killed text. It does not add the deleted -text to the kill ring, since it is already in the kill ring somewhere. -It does however rotate the kill ring to place the newly yanked string at -the front. +When invoked immediately after a @code{yank} or another +@code{yank-pop}, this command replaces the just-yanked entry from the +kill ring with a different entry from the kill ring. When this +command is invoked like that, the region contains text that was just +inserted by another yank command. @code{yank-pop} deletes that text +and inserts in its place a different piece of killed text. It does +not add the deleted text to the kill ring, since it is already in the +kill ring somewhere. It does however rotate the kill ring to place +the newly yanked string at the front. If @var{arg} is @code{nil}, then the replacement text is the previous element of the kill ring. If @var{arg} is numeric, the replacement is the @var{arg}th previous kill. If @var{arg} is negative, a more recent kill is the replacement. -The sequence of kills in the kill ring wraps around, so that after the -oldest one comes the newest one, and before the newest one goes the -oldest. +The sequence of kills in the kill ring wraps around, so if +@code{yank-pop} is invoked repeatedly and reaches the oldest kill, the +one that comes after it is the newest one, and the one before the +newest one is the oldest one. + +This command can also be invoked after a command that is not a yank +command. In that case, it prompts in the minibuffer for a kill-ring +entry, with completion, and uses the kill ring elements as the +minibuffer history (@pxref{Minibuffer History}). This allows the user +to interactively select one of the previous kills recorded in the kill +ring. The return value is always @code{nil}. @end deffn @@ -4157,7 +4176,7 @@ file names only: If the condition value is anything else, then the position is inside a link and the condition itself is the action code. Clearly, you should specify this kind of condition only when applying the condition via a -text or property overlay on the link text (so that it does not apply +text or overlay property on the link text (so that it does not apply to the entire buffer). @end table @@ -4390,7 +4409,8 @@ based on their character codes. @cindex replace characters This function replaces all occurrences of the character @var{old-char} with the character @var{new-char} in the region of the current buffer -defined by @var{start} and @var{end}. +defined by @var{start} and @var{end}. Both characters must have the +same length of their multibyte form. @cindex undo avoidance If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does @@ -4419,6 +4439,16 @@ ThXs Xs the contents of the buffer before. @end example @end defun + +@defun subst-char-in-string fromchar tochar string &optional inplace +@cindex replace characters in string +This function replaces all occurrences of the character @var{fromchar} +with @var{tochar} in @var{string}. By default, substitution occurs in +a copy of @var{string}, but if the optional argument @var{inplace} is +non-@code{nil}, the function modifies the @var{string} itself. In any +case, the function returns the resulting string. +@end defun + @deffn Command translate-region start end table This function applies a translation table to the characters in the buffer between positions @var{start} and @var{end}. @@ -5272,11 +5302,20 @@ represents @code{@{@}}, the empty JSON object; not @code{null}, @code{false}, or an empty array, all of which are different JSON values. +@defun json-available-p +This predicate returns non-@code{nil} if Emacs has been built with +@acronym{JSON} support, and the library is available on the current +system. +@end defun + If some Lisp object can't be represented in JSON, the serialization functions will signal an error of type @code{wrong-type-argument}. The parsing functions can also signal the following errors: @table @code +@item json-unavailable +Signaled when the parsing library isn't available. + @item json-end-of-file Signaled when encountering a premature end of the input text. @@ -5288,10 +5327,9 @@ object parsed. Signaled when encountering invalid JSON syntax. @end table - Only top-level values (arrays and objects) can be serialized to -JSON@. The subobjects within these top-level values can be of any -type. Likewise, the parsing functions will only return vectors, -hashtables, alists, and plists. + Top-level values and the subobjects within these top-level values +can be serialized to JSON@. Likewise, the parsing functions will +return any of the possible types described above. @defun json-serialize object &rest args This function returns a new Lisp string which contains the JSON diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 4a7793a976d..8aa225a00c3 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -75,8 +75,8 @@ example, it is our convention to have commands that list objects named as @samp{list-@var{something}}, e.g., a package called @samp{frob} could have a command @samp{list-frobs}, when its other global symbols begin with @samp{frob-}. Also, constructs that define functions, -variables, etc., work better if they start with @samp{defun} or -@samp{defvar}, so put the name prefix later on in the name. +variables, etc., work better if they start with @samp{define-}, so put +the name prefix later on in the name. This recommendation applies even to names for traditional Lisp primitives that are not primitives in Emacs Lisp---such as @@ -168,11 +168,12 @@ follow the naming conventions for hooks. @xref{Hooks}. @item @cindex unloading packages, preparing for -If loading the file adds functions to hooks, define a function -@code{@var{feature}-unload-function}, where @var{feature} is the name -of the feature the package provides, and make it undo any such -changes. Using @code{unload-feature} to unload the file will run this -function. @xref{Unloading}. +Using @code{unload-feature} will undo the changes usually done by +loading a feature (like adding functions to hooks). However, if +loading @var{feature} does something unusual and more complex, you can +define a function named @code{@var{feature}-unload-function}, and make +it undo any such special changes. @code{unload-feature} will then +automatically run this function if it exists. @xref{Unloading}. @item It is a bad idea to define aliases for the Emacs primitives. Normally @@ -1034,7 +1035,7 @@ the conventional possibilities for @var{header-name}: @table @samp @item Author -This line states the name and email address of at least the principal +This header states the name and email address of at least the principal author of the library. If there are multiple authors, list them on continuation lines led by @code{;;} and a tab or at least two spaces. We recommend including a contact email address, of the form @@ -1053,8 +1054,8 @@ This header has the same format as the Author header. It lists the person(s) who currently maintain(s) the file (respond to bug reports, etc.). -If there is no maintainer line, the person(s) in the Author field -is/are presumed to be the maintainers. Some files in Emacs use +If there is no Maintainer header, the person(s) in the Author header +is/are presumed to be the maintainer(s). Some files in Emacs use @samp{emacs-devel@@gnu.org} for the maintainer, which means the author is no longer responsible for the file, and that it is maintained as part of Emacs. diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 63438170d1a..9356fb9f699 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1010,6 +1010,9 @@ a dynamic local binding, Emacs records the contents of the value cell value cell. When the binding construct finishes executing, Emacs pops the old value off the stack, and puts it in the value cell. + Note that when code using Dynamic Binding is native compiled the +native compiler will not perform any Lisp specific optimization. + @node Dynamic Binding Tips @subsection Proper Use of Dynamic Binding @@ -1579,6 +1582,12 @@ buffer-local binding in buffer @var{buffer}, it returns the default value (@pxref{Default Value}) of @var{variable} instead. @end defun +@defun buffer-local-boundp variable buffer +This returns non-@code{nil} if there's either a buffer-local binding +of @var{variable} (a symbol) in buffer @var{buffer}, or @var{variable} +has a global binding. +@end defun + @defun buffer-local-variables &optional buffer This function returns a list describing the buffer-local variables in buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer @@ -1696,7 +1705,6 @@ buffer has a buffer-local binding. For example, you could use you are in a C or Lisp mode buffer that has a buffer-local value for this variable. -@c Emacs 19 feature The special forms @code{defvar} and @code{defconst} also set the default value (if they set the variable at all), rather than any buffer-local value. @@ -1708,7 +1716,6 @@ this variable. If @var{symbol} is not buffer-local, this is equivalent to @code{symbol-value} (@pxref{Accessing Variables}). @end defun -@c Emacs 19 feature @defun default-boundp symbol The function @code{default-boundp} tells you whether @var{symbol}'s default value is nonvoid. If @code{(default-boundp 'foo)} returns @@ -1884,6 +1891,14 @@ any form of file-local variable. For examples of why you might want to use this, @pxref{Auto Major Mode}. @end defvar +@defvar permanently-enabled-local-variables +Some local variable settings will, by default, be heeded even if +@code{enable-local-variables} is @code{nil}. By default, this is only +the case for the @code{lexical-binding} local variable setting, but +this can be controlled by using this variable, which is a list of +symbols. +@end defvar + @defun hack-local-variables &optional handle-mode This function parses, and binds or evaluates as appropriate, any local variables specified by the contents of the current buffer. The variable @@ -1980,6 +1995,20 @@ Doing so adds those variable/value pairs to file. @end defopt +@defopt ignored-local-variable-values +If there are some values of particular local variables that you always +want to ignore completely, you can use this variable. Its value has +the same form as @code{safe-local-variable-values}; a file-local +variable setting to the value that appears in the list will always be +ignored when processing the local variables specified by the file. As +with that variable, when Emacs queries the user about whether to obey +file-local variables, the user can choose to ignore their particular +values permanently, and that will alter this variable and save it to +the user's custom file. Variable-value pairs that appear in this +variable take precedence over the same pairs in +@code{safe-local-variable-values}. +@end defopt + @defun safe-local-variable-p sym val This function returns non-@code{nil} if it is safe to give @var{sym} the value @var{val}, based on the above criteria. diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index f305d1a8ee8..26f85df160e 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1318,6 +1318,33 @@ lieu of the usual action of @code{delete-window}. @xref{Window Parameters}. @end deffn +When @code{delete-window} deletes the selected window of its frame, it +has to make another window the new selected window of that frame. The +following option allows configuring which window is chosen. + +@defopt delete-window-choose-selected +This option allows specifying which window should become a frame's +selected window after @code{delete-window} has deleted the previously +selected one. Possible choices are + +@itemize +@item @code{mru} +(the default) choose the most recently used window on that frame. + +@item @code{pos} +choose the window comprising the frame coordinates of point of the +previously selected window on that frame. + +@item @code{nil} +choose the first window (the window returned by +@code{frame-first-window}) on that frame. +@end itemize + +A window with a non-@code{nil} @code{no-other-window} parameter is +chosen only if all other windows on that frame have that parameter set +to a non-@code{nil} value too. +@end defopt + @deffn Command delete-other-windows &optional window This function makes @var{window} fill its frame, deleting other windows as necessary. If @var{window} is omitted or @code{nil}, it @@ -1838,6 +1865,14 @@ with @var{window} as the selected window without needlessly running @code{buffer-list-update-hook}. @end defmac +@defmac with-selected-frame frame forms@dots{} +This macro executes @var{forms} with @var{frame} as the selected +frame. The value returned is the value of the last form in +@var{forms}. This macro saves and restores the selected frame, and +changes the order of neither the recently selected windows nor the +buffers in the buffer list. +@end defmac + @defun frame-selected-window &optional frame This function returns the window on @var{frame} that is selected within that frame. @var{frame} should be a live frame; if omitted or @@ -1999,7 +2034,7 @@ meaning as for @code{next-window}. criterion, without selecting it: @cindex least recently used window -@defun get-lru-window &optional all-frames dedicated not-selected +@defun get-lru-window &optional all-frames dedicated not-selected no-other This function returns a live window which is heuristically the least recently used. The optional argument @var{all-frames} has the same meaning as in @code{next-window}. @@ -2010,33 +2045,25 @@ window (@pxref{Dedicated Windows}) is never a candidate unless the optional argument @var{dedicated} is non-@code{nil}. The selected window is never returned, unless it is the only candidate. However, if the optional argument @var{not-selected} is non-@code{nil}, this -function returns @code{nil} in that case. +function returns @code{nil} in that case. The optional argument +@var{no-other}, if non-@code{nil}, means to never return a window whose +@code{no-other-window} parameter is non-@code{nil}. @end defun @cindex most recently used window -@defun get-mru-window &optional all-frames dedicated not-selected +@defun get-mru-window &optional all-frames dedicated not-selected no-other This function is like @code{get-lru-window}, but it returns the most recently used window instead. The meaning of the arguments is the -same as described for @code{get-lru-window}. +same as for @code{get-lru-window}. @end defun @cindex largest window -@defun get-largest-window &optional all-frames dedicated not-selected +@defun get-largest-window &optional all-frames dedicated not-selected no-other This function returns the window with the largest area (height times -width). The optional argument @var{all-frames} specifies the windows to -search, and has the same meaning as in @code{next-window}. - -A minibuffer window is never a candidate. A dedicated window -(@pxref{Dedicated Windows}) is never a candidate unless the optional -argument @var{dedicated} is non-@code{nil}. The selected window is not -a candidate if the optional argument @var{not-selected} is -non-@code{nil}. If the optional argument @var{not-selected} is -non-@code{nil} and the selected window is the only candidate, this -function returns @code{nil}. - -If there are two candidate windows of the same size, this function -prefers the one that comes first in the cyclic ordering of windows, -starting from the selected window. +width). If there are two candidate windows of the same size, it prefers +the one that comes first in the cyclic ordering of windows, starting +from the selected window. The meaning of the arguments is the same as +for @code{get-lru-window}. @end defun @cindex window that satisfies a predicate @@ -2164,12 +2191,13 @@ the name of an existing buffer; if omitted or @code{nil}, it defaults to the current buffer. The replacement buffer in each window is chosen via -@code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated -window displaying @var{buffer-or-name} is deleted if possible -(@pxref{Dedicated Windows}). If such a window is the only window on its -frame and there are other frames on the same terminal, the frame is -deleted as well. If the dedicated window is the only window on the only -frame on its terminal, the buffer is replaced anyway. +@code{switch-to-prev-buffer} (@pxref{Window History}). With the +exception of side windows (@pxref{Side Windows}), any dedicated window +displaying @var{buffer-or-name} is deleted if possible (@pxref{Dedicated +Windows}). If such a window is the only window on its frame and there +are other frames on the same terminal, the frame is deleted as well. +If the dedicated window is the only window on the only frame on its +terminal, the buffer is replaced anyway. @end deffn @@ -2557,7 +2585,7 @@ frame visible and, unless @var{alist} contains an This function tries to display @var{buffer} by finding a window that is displaying a buffer in a given mode. -If @var{alist} contains a @code{mode} entry, its value specifes a +If @var{alist} contains a @code{mode} entry, its value specifies a major mode (a symbol) or a list of major modes. If @var{alist} contains no @code{mode} entry, the current major mode of @var{buffer} is used instead. A window is a candidate if it displays a buffer @@ -2986,6 +3014,8 @@ If non-@code{nil}, such an entry tells @code{display-buffer} to mark any window it creates as dedicated to its buffer (@pxref{Dedicated Windows}). It does that by calling @code{set-window-dedicated-p} with the chosen window as first argument and the entry's value as second. +Side windows are by default dedicated with the value @code{side} +((@pxref{Side Window Options and Functions}). @vindex preserve-size@r{, a buffer display action alist entry} @item preserve-size @@ -4034,18 +4064,19 @@ slightly different, see below. Functions supposed to remove a buffer from a window or a window from a frame can behave specially when a window they operate on is dedicated. -We will distinguish three basic cases, namely where (1) the window is +We will distinguish four basic cases, namely where (1) the window is not the only window on its frame, (2) the window is the only window on -its frame but there are other frames on the same terminal left, and (3) -the window is the only window on the only frame on the same terminal. +its frame but there are other frames on the same terminal left, (3) +the window is the only window on the only frame on the same terminal, +and (4) the dedication's value is @code{side} +(@pxref{Displaying Buffers in Side Windows}). In particular, @code{delete-windows-on} (@pxref{Deleting Windows}) -handles case (2) by deleting the associated frame and case (3) by -showing another buffer in that frame's only window. The function +handles case (2) by deleting the associated frame and cases (3) and (4) +by showing another buffer in that frame's only window. The function @code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is called when a buffer gets killed, deletes the window in case (1) and behaves like @code{delete-windows-on} otherwise. -@c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)? When @code{bury-buffer} (@pxref{Buffer List}) operates on the selected window (which shows the buffer that shall be buried), it @@ -4308,6 +4339,25 @@ means to use a slot following (that is, below or on the right of) the middle slot. Hence, all windows on a specific side are ordered by their @code{slot} value. If unspecified, the window is located in the middle of the specified side. + +@item dedicated +The dedicated flag (@pxref{Dedicated Windows}) has a slightly different +meaning for side windows. When a side window is created, that flag is +set to the value @code{side} to prevent @code{display-buffer} to use the +window in other action functions. Its value persists across invocations +of @code{quit-window}, @code{kill-buffer}, @code{previous-buffer} and +@code{next-buffer}. + +In particular, these commands will refrain from showing, in a side +window, buffers that have not been displayed in that window before. +They will also refrain from having a normal, non-side window show a +buffer that has been already displayed in a side window. A notable +exception to the latter rule occurs when an application, after +displaying a buffer, resets that buffer’s local variables. To override +these rules and always delete a side window with @code{quit-window} or +@code{kill-buffer}, and eventually prevent the use of +@code{previous-buffer} and @code{next-buffer}, set this value to +@code{t} or specify a value via @code{display-buffer-mark-dedicated}. @end table If you specify the same slot on the same side for two or more different @@ -4328,16 +4378,6 @@ Functions}) unless it is explicitly specified as target of that action. Note also that @code{delete-other-windows} cannot make a side window the only window on its frame (@pxref{Deleting Windows}). - Once set up, side windows also change the behavior of the commands -@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} -(@pxref{Window History}). In particular, these commands will refrain -from showing, in a side window, buffers that have not been displayed in -that window before. They will also refrain from having a normal, -non-side window show a buffer that has been already displayed in a side -window. A notable exception to the latter rule occurs when an -application, after displaying a buffer, resets that buffer's local -variables. - @node Side Window Options and Functions @subsection Side Window Options and Functions @@ -5877,7 +5917,7 @@ which window parameters (if any) are saved by this function. @xref{Window Parameters}. @end defun -@defun set-window-configuration configuration &optional dont-set-frame +@defun set-window-configuration configuration &optional dont-set-frame dont-set-miniwindow This function restores the configuration of windows and buffers as specified by @var{configuration}, for the frame that @var{configuration} was created for, regardless of whether that frame @@ -5885,8 +5925,12 @@ is selected or not. The argument @var{configuration} must be a value that was previously returned by @code{current-window-configuration} for that frame. Normally the function also selects the frame which is recorded in the configuration, but if @var{dont-set-frame} is -non-@code{nil}, it leaves selected the frame which was current at the -start of the function. +non-@code{nil}, it leaves selected the frame which was already +selected at the start of the function. + +Normally the function restores the saved minibuffer (if any), but if +@var{dont-set-miniwindow} is non-@code{nil}, the minibuffer current +at the start of the function (if any) remains in the mini-window. If the frame from which @var{configuration} was saved is dead, all this function does is to restore the value of the variable |