[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 410e65e 5/6: Merge from origin/emacs-26
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] master 410e65e 5/6: Merge from origin/emacs-26 |
|
Date: |
Sun, 4 Nov 2018 12:46:13 -0500 (EST) |
branch: master
commit 410e65e4ce6f871fd1b8a2ef4b227cbeeb17c1dd
Merge: 4fbdcce 6937c35
Author: Glenn Morris <address@hidden>
Commit: Glenn Morris <address@hidden>
Merge from origin/emacs-26
6937c35 (origin/emacs-26) Improve recent changes in documentation of ...
c04b48c Rewrite documentation of buffer display
7cadb32 ; * doc/lispref/control.texi (pcase Macro): Fix another typo.
963f1d9 ; * doc/lispref/control.texi (pcase Macro): Fix a typo.
e824c91 Improve documentation of destructuring-binding macros
---
doc/emacs/windows.texi | 127 ++--
doc/lispref/control.texi | 228 +++----
doc/lispref/elisp.texi | 16 +-
doc/lispref/frames.texi | 10 +-
doc/lispref/sequences.texi | 20 +-
doc/lispref/windows.texi | 1459 ++++++++++++++++++++++++++++++++++----------
lisp/emacs-lisp/pcase.el | 43 +-
7 files changed, 1378 insertions(+), 525 deletions(-)
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 17ce4ad..8cc5144 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -48,8 +48,8 @@ other windows at all. However, there are other commands such
as
@kbd{C-x 4 b} that select a different window and switch buffers in it.
Also, all commands that display information in a window, including
(for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
-(@code{list-buffers}), work by switching buffers in a nonselected
-window without affecting the selected window.
+(@code{list-buffers}), usually work by displaying buffers in a
+nonselected window without affecting the selected window.
When multiple windows show the same buffer, they can have different
regions, because they can have different values of point. However,
@@ -347,11 +347,9 @@ heights of all the windows in the selected frame.
in response to a user command. There are several different ways in
which commands do this.
- Many commands, like @kbd{C-x C-f} (@code{find-file}), display the
-buffer by ``taking over'' the selected window, expecting that the
-user's attention will be diverted to that buffer. These commands
-usually work by calling @code{switch-to-buffer} internally
-(@pxref{Select Buffer}).
+ Many commands, like @kbd{C-x C-f} (@code{find-file}), by default
+display the buffer by ``taking over'' the selected window, expecting
+that the user's attention will be diverted to that buffer.
Some commands try to display intelligently, trying not to take
over the selected window, e.g., by splitting off a new window and
@@ -374,10 +372,9 @@ key (@pxref{Pop Up Window}).
Commands with names ending in @code{-other-frame} behave like
@code{display-buffer}, except that they (i) never display in the
-selected window and (ii) prefer to create a new frame to display the
-desired buffer instead of splitting a window---as though the variable
address@hidden is set to @code{t} (@pxref{Window Choice}).
-Several of these commands are bound in the @kbd{C-x 5} prefix key.
+selected window and (ii) prefer to either create a new frame or use a
+window on some other frame to display the desired buffer. Several of
+these commands are bound in the @kbd{C-x 5} prefix key.
@menu
* Window Choice:: How @code{display-buffer} works.
@@ -390,33 +387,61 @@ Several of these commands are bound in the @kbd{C-x 5}
prefix key.
The @code{display-buffer} command (as well as commands that call it
internally) chooses a window to display by following the steps given
-below. @xref{Choosing Window,,Choosing a Window for Display, elisp,
-The Emacs Lisp Reference Manual}, for details about how to alter this
-sequence of steps.
+below. @xref{Choosing Window,,Choosing a Window for Displaying a
+Buffer, elisp, The Emacs Lisp Reference Manual}, for details about how
+to alter this sequence of steps.
@itemize
address@hidden same-window-buffer-names
address@hidden same-window-regexps
@item
-First, check if the buffer should be displayed in the selected window
-regardless of other considerations. You can tell Emacs to do this by
-adding the desired buffer's name to the list
address@hidden, or adding a matching regular
-expression to the list @code{same-window-regexps}. By default, these
-variables are @code{nil}, so this step is skipped.
+If the buffer should be displayed in the selected window regardless of
+other considerations, reuse the selected window. By default, this
+step is skipped, but you can tell Emacs not to skip it by adding a
+regular expression matching the buffer's name together with a
+reference to the @code{display-buffer-same-window} action function
+(@pxref{Buffer Display Action Functions,,Action Functions for Buffer
+Display, elisp, The Emacs Lisp Reference Manual}) to the option
address@hidden (@pxref{Choosing Window,,Choosing a Window
+for Displaying a Buffer, elisp, The Emacs Lisp Reference Manual}).
+For example, to display the buffer @file{*scratch*} preferably in the
+selected window write:
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-alist
+ '("\\*scratch\\*" (display-buffer-same-window)))
address@hidden group
address@hidden example
+
+By default, @code{display-buffer-alist} is @code{nil}.
@item
Otherwise, if the buffer is already displayed in an existing window,
-reuse that window. Normally, only windows on the selected frame
-are considered, but windows on other frames are also reusable if you
-change @code{pop-up-frames} (see below) to @code{t}.
+reuse that window. Normally, only windows on the selected frame are
+considered, but windows on other frames are also reusable if you use
+the corresponding @code{reusable-frames} action alist entry
+(@pxref{Buffer Display Action Alists,,Action Alists for Buffer
+Display, elisp, The Emacs Lisp Reference Manual}). See the
+next step for an example of how to do that.
address@hidden pop-up-frames
@item
Otherwise, optionally create a new frame and display the buffer there.
-By default, this step is skipped. To enable it, change the variable
address@hidden to a address@hidden value. The special value
address@hidden means to do this only on graphical displays.
+By default, this step is skipped. To enable it, change the value of
+the option @code{display-buffer-base-action} (@pxref{Choosing
+Window,,Choosing a Window for Displaying a Buffer, elisp, The Emacs
+Lisp Reference Manual}) as follows:
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-base-action
+ '((display-buffer-reuse-window display-buffer-pop-up-frame)
+ (reusable-frames . 0)))
address@hidden group
address@hidden example
+
+This customization will also try to make the preceding step search for
+a reusable window on all visible or iconified frames.
@item
Otherwise, try to create a new window by splitting a window on the
@@ -436,9 +461,9 @@ window was not split before (to avoid excessive splitting).
@item
Otherwise, display the buffer in a window previously showing it.
-Normally, only windows on the selected frame are considered, but if
address@hidden is address@hidden the window may be also on another
-frame.
+Normally, only windows on the selected frame are considered, but with
+a suitable @code{reusable-frames} action alist entry (see above) the
+window may be also on another frame.
@item
Otherwise, display the buffer in an existing window on the selected
@@ -449,41 +474,35 @@ If all the above methods fail for whatever reason, create
a new frame
and display the buffer there.
@end itemize
-A more advanced and flexible way to customize the behavior of
address@hidden is by using the option @code{display-buffer-alist}
-mentioned in the next section.
-
@node Temporary Displays
@subsection Displaying non-editable buffers.
address@hidden pop-up windows
@cindex temporary windows
Some buffers are shown in windows for perusal rather than for editing.
Help commands (@pxref{Help}) typically use a buffer called @file{*Help*}
for that purpose, minibuffer completion (@pxref{Completion}) uses a
-buffer called @file{*Completions*} instead. Such buffers are usually
+buffer called @file{*Completions*}, etc. Such buffers are usually
displayed only for a short period of time.
Normally, Emacs chooses the window for such temporary displays via
address@hidden as described above. The @file{*Completions*}
-buffer, on the other hand, is normally displayed in a window at the
-bottom of the selected frame, regardless of the number of windows
-already shown on that frame.
address@hidden, as described in the previous subsection. The
address@hidden buffer, on the other hand, is normally displayed
+in a window at the bottom of the selected frame, regardless of the
+number of windows already shown on that frame.
If you prefer Emacs to display a temporary buffer in a different
-fashion, we recommend customizing the variable
address@hidden (@pxref{Choosing Window,,Choosing a Window
-for Display, elisp, The Emacs Lisp Reference Manual}). For example,
-to display @file{*Completions*} by splitting a window as described in
-the previous section, use the following form in your initialization
-file (@pxref{Init File}):
+fashion, customize the variable @code{display-buffer-alist}
+(@pxref{Choosing Window,,Choosing a Window for Displaying a Buffer,
+elisp, The Emacs Lisp Reference Manual}) appropriately. For example,
+to display @file{*Completions*} always below the selected window, use
+the following form in your initialization file (@pxref{Init File}):
@example
@group
(customize-set-variable
'display-buffer-alist
- '(("\\*Completions\\*" display-buffer-pop-up-window)))
+ '(("\\*Completions\\*" display-buffer-below-selected)))
@end group
@end example
@@ -491,10 +510,10 @@ file (@pxref{Init File}):
The @file{*Completions*} buffer is also special in the sense that
Emacs usually tries to make its window just as large as necessary to
display all of its contents. To resize windows showing other
-temporary displays like, for example, the @file{*Help*} buffer
-accordingly, turn on the minor mode (@pxref{Minor Modes})
address@hidden (@pxref{Temporary Displays,,Temporary
-Displays, elisp, The Emacs Lisp Reference Manual}).
+temporary displays, like, for example, the @file{*Help*} buffer, turn
+on the minor mode (@pxref{Minor Modes}) @code{temp-buffer-resize-mode}
+(@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp
+Reference Manual}).
@vindex temp-buffer-max-height
@vindex temp-buffer-max-width
@@ -502,7 +521,7 @@ Displays, elisp, The Emacs Lisp Reference Manual}).
can be controlled by customizing the options
@code{temp-buffer-max-height} and @code{temp-buffer-max-width}
(@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp
-Reference Manual}) and cannot exceed the size of the containing frame.
+Reference Manual}), and cannot exceed the size of the containing frame.
@node Window Convenience
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index e5041ee..5cc43c4 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -419,65 +419,68 @@ This is not completely equivalent because it can evaluate
@var{arg1} or
@node Pattern-Matching Conditional
@section Pattern-Matching Conditional
@cindex pcase
address@hidden pattern matching
address@hidden pattern matching, programming style
Aside from the four basic conditional forms, Emacs Lisp also
has a pattern-matching conditional form, the @code{pcase} macro,
a hybrid of @code{cond} and @code{cl-case}
(@pxref{Conditionals,,,cl,Common Lisp Extensions})
that overcomes their limitations and introduces
-the @dfn{pattern matching} programming style.
-First, the limitations:
+the @dfn{pattern matching programming style}.
+The limitations that @code{pcase} overcomes are:
@itemize
address@hidden The @code{cond} form chooses among alternatives
-by evaluating the predicate @var{condition} of each
-of its clauses (@pxref{Conditionals}).
-The primary limitation is that variables let-bound in @var{condition}
-are not available to the clause's @var{body-forms}.
address@hidden
+The @code{cond} form chooses among alternatives by evaluating the
+predicate @var{condition} of each of its clauses
+(@pxref{Conditionals}). The primary limitation is that variables
+let-bound in @var{condition} are not available to the clause's
address@hidden
Another annoyance (more an inconvenience than a limitation)
is that when a series of @var{condition} predicates implement
-equality tests, there is a lot of repeated code.
-For that, why not use @code{cl-case}?
+equality tests, there is a lot of repeated code. (@code{cl-case}
+solves this inconvenience.)
@item
The @code{cl-case} macro chooses among alternatives by evaluating
the equality of its first argument against a set of specific
values.
-The limitations are two-fold:
+
+Its limitations are two-fold:
@enumerate
address@hidden The equality tests use @code{eql}.
address@hidden The values must be known and written in advance.
address@hidden
+The equality tests use @code{eql}.
address@hidden
+The values must be known and written in advance.
@end enumerate
@noindent
These render @code{cl-case} unsuitable for strings or compound
-data structures (e.g., lists or vectors).
-For that, why not use @code{cond}?
-(And here we end up in a circle.)
+data structures (e.g., lists or vectors). (@code{cond} doesn't have
+these limitations, but it has others, see above.)
@end itemize
@noindent
Conceptually, the @code{pcase} macro borrows the first-arg focus
of @code{cl-case} and the clause-processing flow of @code{cond},
replacing @var{condition} with a generalization of
-the equality test called @dfn{matching},
+the equality test which is a variant of @dfn{pattern matching},
and adding facilities so that you can concisely express a
clause's predicate, and arrange to share let-bindings between
a clause's predicate and @var{body-forms}.
The concise expression of a predicate is known as a @dfn{pattern}.
-When the predicate, called on the value of the first arg,
-returns address@hidden, the pattern matches the value
-(or sometimes ``the value matches the pattern'').
+When the predicate, called on the value of the first arg, returns
address@hidden, we say that ``the pattern matches the value'' (or
+sometimes ``the value matches the pattern'').
@menu
-* The @code{pcase} macro: pcase Macro. Plus examples and caveats.
+* The @code{pcase} macro: pcase Macro. Includes examples and caveats.
* Extending @code{pcase}: Extending pcase. Define new kinds of patterns.
-* Backquote-Style Patterns: Backquote Patterns. Structural matching.
-* Destructuring patterns:: Using pcase patterns to extract subfields.
+* Backquote-Style Patterns: Backquote Patterns. Structural patterns matching.
+* Destructuring with pcase Patterns:: Using pcase patterns to extract
subfields.
@end menu
@node pcase Macro
@@ -498,30 +501,30 @@ of the last of @var{body-forms} in the successful clause.
Otherwise, @code{pcase} evaluates to @code{nil}.
@end defmac
-Each @var{pattern} has to be a @dfn{pcase pattern}, which can either
-use one of the core patterns defined below, or use one of the patterns
-defined via @code{pcase-defmacro}.
address@hidden pcase pattern
+Each @var{pattern} has to be a @dfn{pcase pattern}, which can use
+either one of the core patterns defined below, or one of the patterns
+defined via @code{pcase-defmacro} (@pxref{Extending pcase}).
-The rest of this subsection
-describes different forms of core patterns,
-presents some examples,
-and concludes with important caveats on using the
-let-binding facility provided by some pattern forms.
-A core pattern can have the following forms:
+The rest of this subsection describes different forms of core
+patterns, presents some examples, and concludes with important caveats
+on using the let-binding facility provided by some pattern forms. A
+core pattern can have the following forms:
@table @code
@item _
Matches any @var{expval}.
-This is known as @dfn{don't care} or @dfn{wildcard}.
+This is also known as @dfn{don't care} or @dfn{wildcard}.
@item '@var{val}
-Matches if @var{expval} is @code{equal} to @var{val}.
+Matches if @var{expval} equals @var{val}. The comparison is done as
+if by @code{equal} (@pxref{Equality Predicates}).
@item @var{keyword}
@itemx @var{integer}
@itemx @var{string}
-Matches if @var{expval} is @code{equal} to the literal object.
+Matches if @var{expval} equals the literal object.
This is a special case of @code{'@var{val}}, above,
possible because literal objects of these types are self-quoting.
@@ -533,17 +536,17 @@ Matches any @var{expval}, and additionally let-binds
@var{symbol} to
If @var{symbol} is part of a sequencing pattern @var{seqpat}
(e.g., by using @code{and}, below), the binding is also available to
the portion of @var{seqpat} following the appearance of @var{symbol}.
-This usage has some caveats (@pxref{pcase-symbol-caveats,,caveats}).
+This usage has some caveats, see @ref{pcase-symbol-caveats,,caveats}.
Two symbols to avoid are @code{t}, which behaves like @code{_}
-(above) and is deprecated, and @code{nil}, which signals error.
+(above) and is deprecated, and @code{nil}, which signals an error.
Likewise, it makes no sense to bind keyword symbols
(@pxref{Constant Variables}).
@item (pred @var{function})
Matches if the predicate @var{function} returns address@hidden
when called on @var{expval}.
address@hidden can have one of the possible forms:
+the predicate @var{function} can have one of the following forms:
@table @asis
@item function name (a symbol)
@@ -570,20 +573,17 @@ the actual function call becomes: @address@hidden(= 42
@var{expval})}}.
@item (app @var{function} @var{pattern})
Matches if @var{function} called on @var{expval} returns a
value that matches @var{pattern}.
address@hidden can take one of the
-forms described for @code{pred}, above.
-Unlike @code{pred}, however,
address@hidden tests the result against @var{pattern},
-rather than against a boolean truth value.
address@hidden can take one of the forms described for @code{pred},
+above. Unlike @code{pred}, however, @code{app} tests the result
+against @var{pattern}, rather than against a boolean truth value.
@item (guard @var{boolean-expression})
Matches if @var{boolean-expression} evaluates to address@hidden
@item (let @var{pattern} @var{expr})
-Evaluates @var{expr} to get @var{exprval}
-and matches if @var{exprval} matches @var{pattern}.
-(It is called @code{let} because
address@hidden can bind symbols to values using @var{symbol}.)
+Evaluates @var{expr} to get @var{exprval} and matches if @var{exprval}
+matches @var{pattern}. (It is called @code{let} because @var{pattern}
+can bind symbols to values using @var{symbol}.)
@end table
@cindex sequencing pattern
@@ -596,18 +596,16 @@ but instead of processing values, they process
sub-patterns.
@table @code
@item (and @address@hidden)
-Attempts to match @address@hidden, in order,
-until one of them fails to match.
-In that case, @code{and} likewise fails to match,
-and the rest of the sub-patterns are not tested.
-If all sub-patterns match, @code{and} matches.
+Attempts to match @address@hidden, in order, until one of them
+fails to match. In that case, @code{and} likewise fails to match, and
+the rest of the sub-patterns are not tested. If all sub-patterns
+match, @code{and} matches.
@item (or @var{pattern1} @address@hidden)
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.
+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 @address@hidden(or @var{pattern1})}} signals error.)
@c Issue: Is this correct and intended?
@c Are there exceptions, qualifications?
@@ -1042,12 +1040,11 @@ Both use a single backquote construct
(@pxref{Backquote}).
This subsection describes @dfn{backquote-style patterns},
a set of builtin patterns that eases structural matching.
-For background, @xref{Pattern-Matching Conditional}.
+For background, @pxref{Pattern-Matching Conditional}.
address@hidden patterns} are a powerful set of
address@hidden pattern extensions (created using @code{pcase-defmacro})
-that make it easy to match @var{expval} against
-specifications of its @emph{structure}.
+Backquote-style patterns are a powerful set of @code{pcase} pattern
+extensions (created using @code{pcase-defmacro}) that make it easy to
+match @var{expval} against specifications of its @emph{structure}.
For example, to match @var{expval} that must be a list of two
elements whose first element is a specific string and the second
@@ -1171,87 +1168,102 @@ evaluation results:
(evaluate '(sub 1 2) nil) @result{} error
@end example
address@hidden Destructuring patterns
address@hidden Destructuring Patterns
address@hidden destructuring patterns
address@hidden Destructuring with pcase Patterns
address@hidden Destructuring with @code{pcase} Patterns
address@hidden destructuring with pcase patterns
Pcase patterns not only express a condition on the form of the objects
-they can match but they can also extract sub-fields of those objects.
-Say we have a list and want to extract 2 elements from it with the
-following code:
+they can match, but they can also extract sub-fields of those objects.
+For example we can extract 2 elements from a list that is the value of
+the variable @code{my-list} with the following code:
@example
- (pcase l
+ (pcase my-list
(`(add ,x ,y) (message "Contains %S and %S" x y)))
@end example
This will not only extract @code{x} and @code{y} but will additionally
-test that @code{l} is a list containing exactly 3 elements and whose
-first element is the symbol @code{add}. If any of those tests fail,
address@hidden will directly return @code{nil} without calling
+test that @code{my-list} is a list containing exactly 3 elements and
+whose first element is the symbol @code{add}. If any of those tests
+fail, @code{pcase} will immediately return @code{nil} without calling
@code{message}.
address@hidden of an object is an operation that extracts
-multiple values stored in the object, e.g., the 2nd and the 3rd
-element of a list or a vector. @dfn{Destructuring binding} is
-similar to a local binding (@pxref{Local Variables}), but it gives
-values to multiple elements of a variable by extracting those values
-from an object of compatible structure.
+Extraction of multiple values stored in an object is known as
address@hidden Using @code{pcase} patterns allows to perform
address@hidden binding}, which is similar to a local binding
+(@pxref{Local Variables}), but gives values to multiple elements of
+a variable by extracting those values from an object of compatible
+structure.
-The macros described in this section use @dfn{destructuring
-patterns}, which are normal Pcase patterns used in a context where we
-presume that the object does match the pattern, and we only want
-to extract some subfields. For example:
+The macros described in this section use @code{pcase} patterns to
+perform destructuring binding. The condition of the object to be of
+compatible structure means that the object must match the pattern,
+because only then the object's subfields can be extracted. For
+example:
@example
- (pcase-let ((`(add ,x ,y) l))
+ (pcase-let ((`(add ,x ,y) my-list))
(message "Contains %S and %S" x y))
@end example
@noindent
does the same as the previous example, except that it directly tries
-to extract @code{x} and @code{y} from @code{l} without first verifying
-if @code{l} is a list which has the right number of elements and has
address@hidden as its first element.
-The precise behavior when the object does not actually match the
-pattern is undefined, although the body will not be silently skipped:
-either an error is signaled or the body is run with some of the
-variables potentially bound to arbitrary values like @code{nil}.
+to extract @code{x} and @code{y} from @code{my-list} without first
+verifying if @code{my-list} is a list which has the right number of
+elements and has @code{add} as its first element. The precise
+behavior when the object does not actually match the pattern is
+undefined, although the body will not be silently skipped: either an
+error is signaled or the body is run with some of the variables
+potentially bound to arbitrary values like @code{nil}.
+
+The pcase patterns that are useful for destructuring bindings are
+generally those described in @ref{Backquote Patterns}, since they
+express a specification of the structure of objects that will match.
+
+For an alternative facility for destructuring binding, see
address@hidden
@defmac pcase-let bindings address@hidden
-Bind variables according to @var{bindings} and then eval @var{body}.
+Perform destructuring binding of variables according to
address@hidden, and then evaluate @var{body}.
@var{bindings} is a list of bindings of the form @address@hidden(@var{pattern}
@var{exp})}}, where @var{exp} is an expression to evaluate and
address@hidden is a destructuring pattern.
address@hidden is a @code{pcase} pattern.
-All @var{exp}s are evaluated first after which they are matched
+All @var{exp}s are evaluated first, after which they are matched
against their respective @var{pattern}, introducing new variable
-bindings which can then be used inside @var{body}.
+bindings that can then be used inside @var{body}. The variable
+bindings are produced by destructuring binding of elements of
address@hidden to the values of the corresponding elements of the
+evaluated @var{exp}.
@end defmac
@defmac pcase-let* bindings address@hidden
-Bind variables according to @var{bindings} and then eval @var{body}.
+Perform destructuring binding of variables according to
address@hidden, and then evaluate @var{body}.
@var{bindings} is a list of bindings of the form @code{(@var{pattern}
@var{exp})}, where @var{exp} is an expression to evaluate and
address@hidden is a destructuring pattern.
-
-Unlike @code{pcase-let}, but like @code{let*}, each @var{exp} is
-matched against its corresponding @var{pattern} before passing to the
-next element of @var{bindings}, so the variables introduced in each
-binding are available in the @var{exp}s that follow it, additionally
-to being available in @var{body}.
address@hidden is a @code{pcase} pattern. The variable bindings are
+produced by destructuring binding of elements of @var{pattern} to the
+values of the corresponding elements of the evaluated @var{exp}.
+
+Unlike @code{pcase-let}, but similarly to @code{let*}, each @var{exp}
+is matched against its corresponding @var{pattern} before processing
+the next element of @var{bindings}, so the variable bindings
+introduced in each one of the @var{bindings} are available in the
address@hidden of the @var{bindings} that follow it, additionally to
+being available in @var{body}.
@end defmac
address@hidden dolist
@defmac pcase-dolist (pattern list) address@hidden
-This construct executes @var{body} once for each element of
address@hidden, in a context where the variables appearing in the the
-destructuring pattern @var{pattern} are bound to the corresponding
-values found in the element.
-When @var{pattern} is a simple variable, this ends up being equivalent
-to @code{dolist}.
+Execute @var{body} once for each element of @var{list}, on each
+iteration performing a destructuring binding of variables in
address@hidden to the values of the corresponding subfields of the
+element of @var{list}. The bindings are performed as if by
address@hidden When @var{pattern} is a simple variable, this ends
+up being equivalent to @code{dolist} (@pxref{Iteration}).
@end defmac
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 0b84629..08414e6 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1045,9 +1045,7 @@ Windows
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
* Switching Buffers:: Higher-level functions for switching to a buffer.
-* Choosing Window:: How to choose a window for displaying a buffer.
-* Display Action Functions:: Subroutines for @code{display-buffer}.
-* Choosing Window Options:: Extra options affecting how buffers are displayed.
+* Displaying Buffers:: Displaying a buffer in a suitable window.
* Window History:: Each window remembers the buffers displayed in it.
* Dedicated Windows:: How to avoid displaying another buffer in
a specific window.
@@ -1069,6 +1067,18 @@ Windows
redisplay going past a certain point,
or window configuration changes.
+Displaying Buffers
+
+* Choosing Window:: How to choose a window for displaying a buffer.
+* Buffer Display Action Functions:: Support functions for buffer display.
+* Buffer Display Action Alists:: Alists for fine-tuning buffer display
+ action functions.
+* Choosing Window Options:: Extra options affecting how buffers are displayed.
+* Precedence of Action Functions:: A tutorial explaining the precedence of
+ buffer display action functions.
+* The Zen of Buffer Display:: How to avoid that buffers get lost in between
+ windows.
+
Side Windows
* Displaying Buffers in Side Windows:: An action function for displaying
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index ba4b931..ad5d0fc 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -3261,11 +3261,11 @@ and should be preferred when specifying a address@hidden
@code{drag-with-mode-line} parameter.
When a child frame is used for displaying a buffer via
address@hidden (@pxref{Display Action Functions}),
-the frame's @code{auto-hide-function} parameter (@pxref{Frame
-Interaction Parameters}) can be set to a function, in order to
-appropriately deal with the frame when the window displaying the buffer
-shall be quit.
address@hidden (@pxref{Buffer Display Action
+Functions}), the frame's @code{auto-hide-function} parameter
+(@pxref{Frame Interaction Parameters}) can be set to a function, in
+order to appropriately deal with the frame when the window displaying
+the buffer shall be quit.
When a child frame is used during minibuffer interaction, for example,
to display completions in a separate window, the @code{minibuffer-exit}
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 6a6f4d5..5547160 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -1049,15 +1049,18 @@ that @var{sequence} can be a list, vector or string.
This is
primarily useful for side-effects.
@end defmac
address@hidden seq-let arguments sequence address@hidden
address@hidden
address@hidden seq-let var-sequence val-sequence address@hidden
@cindex sequence destructuring
- This macro binds the variables defined in @var{arguments} to the
-elements of @var{sequence}. @var{arguments} can themselves include
-sequences, allowing for nested destructuring.
+ This macro binds the variables defined in @var{var-sequence} to the
+values that are the corresponding elements of @var{val-sequence}.
+This is known as @dfn{destructuring binding}. The elements of
address@hidden can themselves include sequences, allowing for
+nested destructuring.
-The @var{arguments} sequence can also include the @code{&rest} marker
-followed by a variable name to be bound to the rest of
address@hidden
+The @var{var-sequence} sequence can also include the @code{&rest}
+marker followed by a variable name to be bound to the rest of
address@hidden
@example
@group
@@ -1081,6 +1084,9 @@ followed by a variable name to be bound to the rest of
@end group
@result{} [3 4]
@end example
+
+The @code{pcase} patterns provide an alternative facility for
+destructuring binding, see @ref{Destructuring with pcase Patterns}.
@end defmac
@defun seq-random-elt sequence
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 52bfbde..772bcdf 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -25,9 +25,7 @@ is displayed in windows.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
* Switching Buffers:: Higher-level functions for switching to a buffer.
-* Choosing Window:: How to choose a window for displaying a buffer.
-* Display Action Functions:: Subroutines for @code{display-buffer}.
-* Choosing Window Options:: Extra options affecting how buffers are displayed.
+* Displaying Buffers:: Displaying a buffer in a suitable window.
* Window History:: Each window remembers the buffers displayed in it.
* Dedicated Windows:: How to avoid displaying another buffer in
a specific window.
@@ -1542,11 +1540,11 @@ direction as the existing window combination
(otherwise, a new internal
window is created anyway).
@item window-size
-This means that @code{display-buffer} makes a new parent window when it
-splits a window and is passed a @code{window-height} or
address@hidden entry in the @var{alist} argument (@pxref{Display
-Action Functions}). Otherwise, window splitting behaves as for a value
-of @code{nil}.
+This means that @code{display-buffer} makes a new parent window when
+it splits a window and is passed a @code{window-height} or
address@hidden entry in the @var{alist} argument (@pxref{Buffer
+Display Action Functions}). Otherwise, window splitting behaves as
+for a value of @code{nil}.
@item temp-buffer-resize
In this case @code{with-temp-buffer-window} makes a new parent window
@@ -1879,7 +1877,7 @@ most recently used one (@pxref{Cyclic Window Ordering}).
@cindex ordering of windows, cyclic
@cindex window ordering, cyclic
- When you use the command @kbd{C-x o} (@code{other-window}) to select
+ When you use the command @address@hidden o}} (@code{other-window}) to select
some other window, it moves through live windows in a specific order.
For any given configuration of windows, this order never varies. It
is called the @dfn{cyclic ordering of windows}.
@@ -1899,7 +1897,7 @@ if omitted or @code{nil}, it defaults to the selected
window.
The optional argument @var{minibuf} specifies whether minibuffer windows
should be included in the cyclic ordering. Normally, when @var{minibuf}
is @code{nil}, a minibuffer window is included only if it is currently
-active; this matches the behavior of @kbd{C-x o}. (Note that a
+active; this matches the behavior of @address@hidden o}}. (Note that a
minibuffer window is active as long as its minibuffer is in use; see
@ref{Minibuffers}).
@@ -2083,7 +2081,8 @@ variables in the specified buffer. However, if the
optional argument
@var{keep-margins} is address@hidden, it leaves @var{window}'s display
margins, fringes and scroll bar settings alone.
-When writing an application, you should normally use the higher-level
+When writing an application, you should normally use
address@hidden (@pxref{Choosing Window}) or the higher-level
functions described in @ref{Switching Buffers}, instead of calling
@code{set-window-buffer} directly.
@@ -2168,7 +2167,6 @@ frame on its terminal, the buffer is replaced anyway.
@node Switching Buffers
@section Switching to a Buffer in a Window
@cindex switching to a buffer
address@hidden displaying a buffer
This section describes high-level functions for switching to a specified
buffer in some window. In general, ``switching to a buffer'' means to
@@ -2327,32 +2325,70 @@ unless @var{norecord} is address@hidden
@end deffn
address@hidden Displaying Buffers
address@hidden Displaying a Buffer in a Suitable Window
address@hidden buffer display
address@hidden displaying a buffer
+
+This section describes lower-level functions Emacs uses to find or
+create a window for displaying a specified buffer. The common
+workhorse of these functions is @code{display-buffer} which eventually
+handles all incoming requests for buffer display (@pxref{Choosing
+Window}).
+
+ @code{display-buffer} delegates the task of finding a suitable
+window to so-called action functions (@pxref{Buffer Display Action
+Functions}). First, @code{display-buffer} compiles a so-called action
+alist---a special association list that action functions can use to
+fine-tune their behavior. Then it passes that alist on to each action
+function it calls (@pxref{Buffer Display Action Alists}).
+
+ The behavior of @code{display-buffer} is highly customizable. To
+understand how customizations are used in practice, you may wish to
+study examples illustrating the order of precedence which
address@hidden uses to call action functions (@pxref{Precedence
+of Action Functions}). To avoid conflicts between Lisp programs
+calling @code{display-buffer} and user customizations of its behavior,
+it may make sense to follow a number of guidelines which are sketched
+in the final part of this section (@pxref{The Zen of Buffer Display}).
+
address@hidden
+* Choosing Window:: How to choose a window for displaying a buffer.
+* Buffer Display Action Functions:: Support functions for buffer display.
+* Buffer Display Action Alists:: Alists for fine-tuning buffer display.
+* Choosing Window Options:: Extra options affecting how buffers are displayed.
+* Precedence of Action Functions:: Examples to explain the precedence of
+ action functions.
+* The Zen of Buffer Display:: How to avoid that buffers get lost in between
+ windows.
address@hidden menu
+
+
@node Choosing Window
address@hidden Choosing a Window for Display
address@hidden Choosing a Window for Displaying a Buffer
- The command @code{display-buffer} flexibly chooses a window for
+The command @code{display-buffer} flexibly chooses a window for
display, and displays a specified buffer in that window. It can be
called interactively, via the key binding @kbd{C-x 4 C-o}. It is also
used as a subroutine by many functions and commands, including
@code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
Buffers}).
address@hidden buffer display display action
@cindex display action
address@hidden action function, for @code{display-buffer}
address@hidden action alist, for @code{display-buffer}
This command performs several complex steps to find a window to
display in. These steps are described by means of @dfn{display
-actions}, which have the form @code{(@var{function} . @var{alist})}.
-Here, @var{function} is either a function or a list of functions,
-which we refer to as @dfn{action functions}; @var{alist} is an
-association list, which we refer to as an @dfn{action alist}.
+actions}, which have the form @code{(@var{functions} . @var{alist})}.
+Here, @var{functions} is either a single function or a list of
+functions, referred to as ``action functions'' (@pxref{Buffer Display
+Action Functions}); and @var{alist} is an association list, referred
+to as ``action alist'' (@pxref{Buffer Display Action Alists}).
address@hidden Zen of Buffer Display}, for samples of display actions.
An action function accepts two arguments: the buffer to display and
an action alist. It attempts to display the buffer in some window,
picking or creating a window according to its own criteria. If
successful, it returns the window; otherwise, it returns @code{nil}.
address@hidden Action Functions}, for a list of predefined action
-functions.
@code{display-buffer} works by combining display actions from
several sources, and calling the action functions in turn, until one
@@ -2363,12 +2399,14 @@ value.
This command makes @var{buffer-or-name} appear in some window, without
selecting the window or making the buffer current. The argument
@var{buffer-or-name} must be a buffer or the name of an existing
-buffer. The return value is the window chosen to display the buffer.
+buffer. The return value is the window chosen to display the buffer,
+or @code{nil} if no suitable window was found.
The optional argument @var{action}, if address@hidden, should normally
be a display action (described above). @code{display-buffer} builds a
list of action functions and an action alist, by consolidating display
-actions from the following sources (in order):
+actions from the following sources (in order of their precedence,
+from highest to lowest):
@itemize
@item
@@ -2388,40 +2426,65 @@ The constant @code{display-buffer-fallback-action}.
@end itemize
@noindent
-Each action function is called in turn, passing the buffer as the
-first argument and the combined action alist as the second argument,
-until one of the functions returns address@hidden The caller can
-pass @code{(allow-no-window . t)} as an element of the action alist to
-indicate its readiness to handle the case of not displaying the
-buffer in a window.
+In practice this means that @code{display-buffer} builds a list of all
+action functions specified by these display actions. The first
+element of this list is the first action function specified by
address@hidden, if any. Its last element is
address@hidden last action function
+specified by @code{display-buffer-fallback-action}. Duplicates are
+not removed from this list---hence one and the same action function
+may be called multiple times during one call of @code{display-buffer}.
+
address@hidden calls the action functions specified by this
+list in turn, passing the buffer as the first argument and the
+combined action alist as the second argument, until one of the
+functions returns address@hidden @xref{Precedence of Action
+Functions}, for examples how display actions specified by different
+sources are processed by @code{display-buffer}.
+
+Note that the second argument is always the list of @emph{all} action
+alist entries specified by the sources named above. Hence, the first
+element of that list is the first action alist entry specified by
address@hidden, if any. Its last element is
+the last alist entry of @code{display-buffer-base-action}, if any (the
+action alist of @code{display-buffer-fallback-action} is empty).
+
+Note also, that the combined action alist may contain duplicate
+entries and entries for the same key with different values. As a
+rule, action functions always use the first association of a key they
+find. Hence, the association an action function uses is not
+necessarily the association provided by the display action that
+specified that action function,
The argument @var{action} can also have a address@hidden, non-list
value. This has the special meaning that the buffer should be
displayed in a window other than the selected one, even if the
selected window is already displaying it. If called interactively
-with a prefix argument, @var{action} is @code{t}.
+with a prefix argument, @var{action} is @code{t}. Lisp programs
+should always supply a list value.
The optional argument @var{frame}, if address@hidden, specifies which
frames to check when deciding whether the buffer is already displayed.
-It is equivalent to adding an element @code{(reusable-frames
-. @var{frame})} to the action alist of @var{action}. @xref{Display
-Action Functions}.
+It is equivalent to adding an element @address@hidden(reusable-frames
+. @var{frame})}} to the action alist of @var{action} (@pxref{Buffer
+Display Action Alists}). The @var{frame} argument is provided for
+compatibility reasons, Lisp programs should not use it.
@end deffn
@defvar display-buffer-overriding-action
The value of this variable should be a display action, which is
treated with the highest priority by @code{display-buffer}. The
-default value is empty, i.e., @code{(nil . nil)}.
+default value is an empty display action, i.e., @address@hidden(nil . nil)}}.
@end defvar
@defopt display-buffer-alist
The value of this option is an alist mapping conditions to display
actions. Each condition may be either a regular expression matching a
buffer name or a function that takes two arguments: a buffer name and
-the @var{action} argument passed to @code{display-buffer}. If the name
-of the buffer passed to @code{display-buffer} either matches a regular
-expression in this alist or the function specified by a condition
-returns address@hidden, then @code{display-buffer} uses the
+the @var{action} argument passed to @code{display-buffer}. If either
+the name of the buffer passed to @code{display-buffer} matches a
+regular expression in this alist, or the function specified by a
+condition returns address@hidden, then @code{display-buffer} uses the
corresponding display action to display the buffer.
@end defopt
@@ -2437,13 +2500,19 @@ This display action specifies the fallback behavior for
@end defvr
address@hidden Display Action Functions
address@hidden Action Functions for @code{display-buffer}
address@hidden Buffer Display Action Functions
address@hidden Action Functions for Buffer Display
address@hidden buffer display action function
address@hidden action function, for buffer display
+
+An @dfn{action function} is a function @code{display-buffer} calls for
+choosing a window to display a buffer. Action functions take two
+arguments: @var{buffer}, the buffer to display, and @var{alist}, an
+action alist (@pxref{Buffer Display Action Alists}). They are
+supposed to return a window displaying @var{buffer} if they succeed
+and @code{nil} if they fail.
-The following basic action functions are defined in Emacs. Each of
-these functions takes two arguments: @var{buffer}, the buffer to
-display, and @var{alist}, an action alist. Each action function
-returns the window if it succeeds, and @code{nil} if it fails.
+ The following basic action functions are defined in Emacs.
@defun display-buffer-same-window buffer alist
This function tries to display @var{buffer} in the selected window.
@@ -2453,57 +2522,99 @@ to another buffer (@pxref{Dedicated Windows}). It also
fails if
@end defun
@defun display-buffer-reuse-window buffer alist
-This function tries to display @var{buffer} by finding a window
-that is already displaying it.
+This function tries to display @var{buffer} by finding a window that
+is already displaying it.
If @var{alist} has a address@hidden @code{inhibit-same-window} entry,
-the selected window is not eligible for reuse. If @var{alist}
-contains a @code{reusable-frames} entry, its value determines which
-frames to search for a reusable window:
-
address@hidden @bullet
address@hidden
address@hidden means consider windows on the selected frame.
-(Actually, the last non-minibuffer frame.)
address@hidden
address@hidden means consider windows on all frames.
address@hidden
address@hidden means consider windows on all visible frames.
address@hidden
-0 means consider windows on all visible or iconified frames.
address@hidden
-A frame means consider windows on that frame only.
address@hidden itemize
-
-Note that these meanings differ slightly from those of the
address@hidden argument to @code{next-window} (@pxref{Cyclic Window
-Ordering}).
-
-If @var{alist} contains no @code{reusable-frames} entry, this function
-normally searches just the selected frame; however, if the variable
address@hidden is address@hidden, it searches all frames on the
-current terminal. @xref{Choosing Window Options}.
-
-If this function chooses a window on another frame, it makes that frame
-visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
-entry (@pxref{Choosing Window Options}), raises that frame if necessary.
+the selected window is not eligible for reuse. The set of frames to
+search for a window already displaying @var{buffer} can be specified
+with the help of the @code{reusable-frames} action alist entry. If
address@hidden contains no @code{reusable-frames} entry, this function
+searches just the selected frame.
+
+If this function chooses a window on another frame, it makes that
+frame visible and, unless @var{alist} contains an
address@hidden entry, raises that frame if necessary.
@end defun
@defun display-buffer-reuse-mode-window buffer alist
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 is a major mode
-(a symbol) or a list of major modes. If @var{alist} contains no
address@hidden entry, the current major mode of @var{buffer} is used. A
-window is a candidate if it displays a buffer that derives from one of
-the given modes.
+If @var{alist} contains a @code{mode} entry, its value specifes 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
+whose mode derives from one of the modes specified thusly.
-The behavior is also controlled by entries for
+The behavior is also controlled by @var{alist} entries for
@code{inhibit-same-window}, @code{reusable-frames} and
address@hidden as is done in the function
address@hidden
address@hidden, like @code{display-buffer-reuse-window}
+does.
address@hidden defun
+
address@hidden display-buffer-pop-up-window buffer alist
+This function tries to display @var{buffer} by splitting the largest
+or least recently-used window (usually located on the selected frame).
+It actually performs the split by calling the function specified by
address@hidden (@pxref{Choosing Window
+Options}).
+
+The size of the new window can be adjusted by supplying
address@hidden and @code{window-width} entries in @var{alist}.
+If @var{alist} contains a @code{preserve-size} entry, Emacs will also
+try to preserve the size of the new window during future resize
+operations (@pxref{Preserving Window Sizes}).
+
+This function fails if no window can be split. More often than not,
+this happens because no window is large enough to allow splitting.
+Setting @code{split-height-threshold} or @code{split-width-threshold}
+to lower values may help in this regard. Spliting also fails when the
+selected frame has an @code{unsplittable} frame parameter;
address@hidden Parameters}.
address@hidden defun
+
address@hidden display-buffer-in-previous-window buffer alist
+This function tries to display @var{buffer} in a window where it was
+previously displayed. If @var{alist} has a address@hidden
address@hidden entry, the selected window is not eligible
+for reuse. If @var{alist} contains a @code{reusable-frames} entry,
+its value determines which frames to search for a suitable window.
+If @var{alist} has a @code{previous-window} entry and the window
+specified by that entry is live and not dedicated to another buffer,
+that window will be preferred, even if it never showed @var{buffer}
+before.
address@hidden defun
+
address@hidden display-buffer-use-some-window buffer alist
+This function tries to display @var{buffer} by choosing an existing
+window and displaying the buffer in that window. It can fail if all
+windows are dedicated to other buffers (@pxref{Dedicated Windows}).
address@hidden defun
+
address@hidden display-buffer-below-selected buffer alist
+This function tries to display @var{buffer} in a window below the
+selected window. If there is a window below the selected one and that
+window already displays @var{buffer}, it reuses that window.
+
+If there is no such window, this function tries to create a new window
+by splitting the selected one, and displays @var{buffer} there. It will
+also try to adjust that window's size provided @var{alist} contains a
+suitable @code{window-height} or @code{window-width} entry, see above.
+
+If splitting the selected window fails and there is a non-dedicated
+window below the selected one showing some other buffer, this function
+tries to use that window for showing @var{buffer}.
address@hidden defun
+
address@hidden display-buffer-at-bottom buffer alist
+This function tries to display @var{buffer} in a window at the bottom
+of the selected frame.
+
+This either tries to split the window at the bottom of the frame or
+the frame's root window, or to reuse an existing window at the bottom
+of the selected frame.
@end defun
@defun display-buffer-pop-up-frame buffer alist
@@ -2511,37 +2622,37 @@ This function creates a new frame, and displays the
buffer in that
frame's window. It actually performs the frame creation by calling
the function specified in @code{pop-up-frame-function}
(@pxref{Choosing Window Options}). If @var{alist} contains a
address@hidden entry, the associated value
-is added to the newly created frame's parameters.
address@hidden entry, the associated value is added to
+the newly created frame's parameters.
@end defun
@defun display-buffer-in-child-frame buffer alist
This function tries to display @var{buffer} in a child frame
-(@pxref{Child Frames}) of the selected frame, either reusing an existing
-child frame or by making a new one. If @var{alist} has a address@hidden
address@hidden entry, the corresponding value is an alist
-of frame parameters to give the new frame. A @code{parent-frame}
-parameter specifying the selected frame is provided by default. If the
-child frame should be or become the child of another frame, a
-corresponding entry must be added to @var{alist}.
+(@pxref{Child Frames}) of the selected frame, either reusing an
+existing child frame or by making a new one. If @var{alist} has a
address@hidden @code{child-frame-parameters} entry, the corresponding
+value is an alist of frame parameters to give the new frame. A
address@hidden parameter specifying the selected frame is
+provided by default. If the child frame should become the child of
+another frame, a corresponding entry must be added to @var{alist}.
The appearance of child frames is largely dependent on the parameters
provided via @var{alist}. It is advisable to use at least ratios to
specify the size (@pxref{Size Parameters}) and the position
-(@pxref{Position Parameters}) of the child frame and to add the
address@hidden in order to make sure that the child frame remains
-visible. For other parameters that should be considered see @ref{Child
-Frames}.
+(@pxref{Position Parameters}) of the child frame, and to add a
address@hidden parameter (@pxref{Frame Interaction Parameters}), in
+order to make sure that the child frame remains visible. For other
+parameters that should be considered see @ref{Child Frames}.
@end defun
@defun display-buffer-use-some-frame buffer alist
-This function tries to display @var{buffer} by trying to find a
-frame that meets a predicate (by default any frame other than the
-current frame).
+This function tries to display @var{buffer} by finding a frame that
+meets a predicate (by default any frame other than the selected
+frame).
-If this function chooses a window on another frame, it makes that frame
-visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
-entry (@pxref{Choosing Window Options}), raises that frame if necessary.
+If this function chooses a window on another frame, it makes that
+frame visible and, unless @var{alist} contains an
address@hidden entry, raises that frame if necessary.
If @var{alist} has a address@hidden @code{frame-predicate} entry, its
value is a function taking one argument (a frame), returning
@@ -2549,237 +2660,281 @@ address@hidden if the frame is a candidate; this
function replaces the
default predicate.
If @var{alist} has a address@hidden @code{inhibit-same-window} entry,
-the selected window is used; thus if the selected frame has a single
-window, it is not used.
+the selected window is not used; thus if the selected frame has a
+single window, it is not used.
@end defun
address@hidden display-buffer-pop-up-window buffer alist
-This function tries to display @var{buffer} by splitting the largest
-or least recently-used window (typically one on the selected frame).
-It actually performs the split by calling the function specified in
address@hidden (@pxref{Choosing Window
-Options}).
address@hidden display-buffer-no-window buffer alist
+If @var{alist} has a address@hidden @code{allow-no-window} entry, then
+this function does not display @var{buffer} and returns the symbol
address@hidden This constitutes the only exception to the convention
+that an action function returns either @code{nil} or a window showing
address@hidden If @var{alist} has no such @code{allow-no-window}
+entry, this function returns @code{nil}.
+
+If this function returns @code{fail}, @code{display-buffer} will skip
+the execution of any further display actions and return @code{nil}
+immediately. If this function returns @code{nil},
address@hidden will continue with the next display action, if
+any.
-The size of the new window can be adjusted by supplying
address@hidden and @code{window-width} entries in @var{alist}. To
-adjust the window's height, use an entry whose @sc{car} is
address@hidden and whose @sc{cdr} is one of:
+It is assumed that when a caller of @code{display-buffer} specifies a
address@hidden @code{allow-no-window} entry, it is also able to handle
+a @code{nil} return value.
address@hidden defun
+
+Two other action functions are described in their proper
address@hidden (@pxref{Displaying
+Buffers in Side Windows}) and @code{display-buffer-in-atom-window}
+(@pxref{Atomic Windows}).
+
+
address@hidden Buffer Display Action Alists
address@hidden Action Alists for Buffer Display
address@hidden buffer display action alist
address@hidden action alist for buffer display
+
+An @dfn{action alist} is an association list mapping predefined
+symbols recognized by action functions to values these functions are
+supposed to interpret accordingly. In each call,
address@hidden constructs a new, possibly empty action alist
+and passes that entire list on to any action function it calls.
+
+ By design, action functions are free in their interpretation of
+action alist entries. In fact, some entries like
address@hidden or @code{previous-window} have a meaning only
+for one or a few action functions, and are ignored by the rest. Other
+entries, like @code{inhibit-same-window} or @code{window-parameters},
+are supposed to be respected by most action functions, including those
+provided by application programs and external packages.
+
+ In the previous subsection we have described in detail how
+individual action functions interpret the action alist entries they
+care about. Here we give a reference list of all known action alist
+entries according to their symbols, together with their values and
+action functions (@pxref{Buffer Display Action Functions}) that
+recognize them. Throughout this list, the terms ``buffer'' will refer
+to the buffer @code{display-buffer} is supposed to display, and
+``value'' refers to the entry's value.
+
address@hidden @code
address@hidden address@hidden, a buffer display action alist entry}
address@hidden inhibit-same-window
+If the value is address@hidden, this signals that the selected window
+must not be used for displaying the buffer. All action functions that
+(re-)use an existing window should respect this entry.
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden previous-window
+The value must specify a window that may have displayed the buffer
+previously. @code{display-buffer-in-previous-window} will give
+preference to such a window provided it is still live and not
+dedicated to another buffer.
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden mode
+The value is either a major mode or a list of major modes.
address@hidden may reuse a window whenever
+the value specified by this entry matches the major mode of that
+window's buffer. Other action functions ignore such entries.
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden frame-predicate
+The value must be a function taking one argument (a frame), supposed
+to return address@hidden if that frame is a candidate for displaying
+the buffer. This entry is used by
address@hidden
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden reusable-frames
+The value specifies the frame(s) to search for a window that can be
+reused because it already displays the buffer. It can be set as
+follows:
@itemize @bullet
@item
address@hidden means to leave the height of the new window alone.
address@hidden means consider only windows on the selected frame.
+(Actually, the last frame used that is not a minibuffer-only frame.)
address@hidden
address@hidden means consider windows on all frames.
address@hidden
address@hidden means consider windows on all visible frames.
address@hidden
+0 means consider windows on all visible or iconified frames.
address@hidden
+A frame means consider windows on that frame only.
address@hidden itemize
+
+Note that the meaning of @code{nil} differs slightly from that of the
address@hidden argument to @code{next-window} (@pxref{Cyclic Window
+Ordering}).
+
+A major client of this is @code{display-buffer-reuse-window}, but all
+other action functions that try to reuse a window are affected as
+well.
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden inhibit-switch-frame
+A address@hidden value prevents another frame from being raised or
+selected, if the window chosen by @code{display-buffer} is displayed
+there. Primarily affected by this are
address@hidden and
address@hidden
address@hidden should be affected as well, but
+there is no guarantee that the window manager will comply.
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden window-parameters
+The value specifies an alist of window parameters to give the chosen
+window. All action functions that choose a window should process this
+entry.
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden window-height
+The value specifies whether and how to adjust the height of the chosen
+window, and can have the following values:
+
address@hidden @bullet
address@hidden
address@hidden means to leave the height of the chosen window alone.
@item
-A number specifies the desired height of the new window. An integer
-specifies the number of lines of the window. A floating-point
+A number specifies the desired height of the chosen window. An
+integer specifies the number of lines of the window. A floating-point
number gives the fraction of the window's height with respect to the
height of the frame's root window.
@item
-If the @sc{cdr} specifies a function, that function is called with one
-argument: the new window. The function is supposed to adjust the
+If the value specifies a function, that function is called with one
+argument---the chosen window. The function is supposed to adjust the
height of the window; its return value is ignored. Suitable functions
are @code{shrink-window-if-larger-than-buffer} and
@code{fit-window-to-buffer}, see @ref{Resizing Windows}.
@end itemize
-To adjust the window's width, use an entry whose @sc{car} is
address@hidden and whose @sc{cdr} is one of:
+All action functions that choose a window should process this entry.
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden window-width
+This entry is similar to the @code{window-height} entry described
+before, but used to adjust the chosen window's width instead. The
+value can be one of the following:
@itemize @bullet
@item
address@hidden means to leave the width of the new window alone.
address@hidden means to leave the width of the chosen window alone.
@item
-A number specifies the desired width of the new window. An integer
+A number specifies the desired width of the chosen window. An integer
specifies the number of columns of the window. A floating-point
number gives the fraction of the window's width with respect to the
width of the frame's root window.
@item
-If the @sc{cdr} specifies a function, that function is called with one
-argument: the new window. The function is supposed to adjust the width
-of the window; its return value is ignored.
+If the value specifies a function, that function is called with one
+argument---the chosen window. The function is supposed to adjust the
+width of the window; its return value is ignored.
@end itemize
-If @var{alist} contains a @code{preserve-size} entry, Emacs will try to
-preserve the size of the new window during future resize operations
-(@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a
-cons cell whose @sc{car}, if address@hidden, means to preserve the width
-of the window and whose @sc{cdr}, if address@hidden, means to preserve
-the height of the window.
-
-This function can fail if no window splitting can be performed for some
-reason (e.g., if the selected frame has an @code{unsplittable} frame
-parameter; @pxref{Buffer Parameters}).
address@hidden defun
-
address@hidden display-buffer-below-selected buffer alist
-This function tries to display @var{buffer} in a window below the
-selected window. If there is a window below the selected one and that
-window already displays @var{buffer}, it reuses that window.
-
-If there is no such window, this function tries to create a new window
-by splitting the selected one and display @var{buffer} there. It will
-also adjust that window's size provided @var{alist} contains a suitable
address@hidden or @code{window-width} entry, see above.
-
-If splitting the selected window fails and there is a non-dedicated
-window below the selected one showing some other buffer, it uses that
-window for showing @var{buffer}.
address@hidden defun
-
address@hidden display-buffer-in-previous-window buffer alist
-This function tries to display @var{buffer} in a window previously
-showing it. If @var{alist} has a address@hidden
address@hidden entry, the selected window is not eligible
-for reuse. If @var{alist} contains a @code{reusable-frames} entry, its
-value determines which frames to search for a suitable window as with
address@hidden
-
-If @var{alist} has a @code{previous-window} entry, the window
-specified by that entry will override any other window found by the
-methods above, even if that window never showed @var{buffer} before.
address@hidden defun
-
address@hidden display-buffer-at-bottom buffer alist
-This function tries to display @var{buffer} in a window at the bottom
-of the selected frame.
-
-This either splits the window at the bottom of the frame or the
-frame's root window, or reuses an existing window at the bottom of the
-selected frame.
address@hidden defun
-
address@hidden display-buffer-use-some-window buffer alist
-This function tries to display @var{buffer} by choosing an existing
-window and displaying the buffer in that window. It can fail if all
-windows are dedicated to another buffer (@pxref{Dedicated Windows}).
address@hidden defun
-
address@hidden display-buffer-no-window buffer alist
-If @var{alist} has a address@hidden @code{allow-no-window} entry, then
-this function does not display @code{buffer}. This allows you to
-override the default action and avoid displaying the buffer. It is
-assumed that when the caller specifies a address@hidden
address@hidden value it can handle a @code{nil} value returned
-from @code{display-buffer} in this case.
address@hidden defun
-
-If the @var{alist} argument of any of these functions contains a
address@hidden entry, @code{display-buffer} assigns the
-elements of the associated value as window parameters of the chosen
-window.
-
- To illustrate the use of action functions, consider the following
-example.
-
address@hidden
address@hidden
-(display-buffer
- (get-buffer-create "*foo*")
- '((display-buffer-reuse-window
- display-buffer-pop-up-window
- display-buffer-pop-up-frame)
- (reusable-frames . 0)
- (window-height . 10) (window-width . 40)))
address@hidden group
address@hidden example
-
address@hidden
-Evaluating the form above will cause @code{display-buffer} to proceed as
-follows: If a buffer called *foo* already appears on a visible or
-iconified frame, it will reuse its window. Otherwise, it will try to
-pop up a new window or, if that is impossible, a new frame and show the
-buffer there. If all these steps fail, it will proceed using whatever
address@hidden and
address@hidden prescribe.
-
- Furthermore, @code{display-buffer} will try to adjust a reused window
-(provided *foo* was put by @code{display-buffer} there before) or a
-popped-up window as follows: If the window is part of a vertical
-combination, it will set its height to ten lines. Note that if, instead
-of the number 10, we specified the function
address@hidden, @code{display-buffer} would come up with a
-one-line window to fit the empty buffer. If the window is part of a
-horizontal combination, it sets its width to 40 columns. Whether a new
-window is vertically or horizontally combined depends on the shape of
-the window split and the values of
address@hidden, @code{split-height-threshold}
-and @code{split-width-threshold} (@pxref{Choosing Window Options}).
-
- Now suppose we combine this call with a preexisting setup for
address@hidden as follows.
-
address@hidden
address@hidden
-(let ((display-buffer-alist
- (cons
- '("\\*foo\\*"
- (display-buffer-reuse-window display-buffer-below-selected)
- (reusable-frames)
- (window-height . 5))
- display-buffer-alist)))
- (display-buffer
- (get-buffer-create "*foo*")
- '((display-buffer-reuse-window
- display-buffer-pop-up-window
- display-buffer-pop-up-frame)
- (reusable-frames . 0)
- (window-height . 10) (window-width . 40))))
address@hidden group
address@hidden example
+All action functions that choose a window should process this entry.
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden preserve-size
+If address@hidden such an entry tells Emacs to preserve the size of
+the window chosen (@pxref{Preserving Window Sizes}). The value should
+be either @code{(t . nil)} to preserve the width of the window,
address@hidden(nil . t)} to preserve its height or @code{(t . t)} to preserve
+both its width and its height. All action functions that choose a
+window should process this entry.
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden pop-up-frame-parameters
+The value specifies an alist of frame parameters to give a new frame,
+if one is created. @code{display-buffer-pop-up-frame} is its one and
+only addressee.
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden parent-frame
+The value specifies the parent frame to be used when the buffer is
+displayed on a child frame. This entry is used only by
address@hidden
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden child-frame-parameters
+The value specifies an alist of frame parameters to use when the buffer
+is displayed on a child frame. This entry is used only by
address@hidden
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden side
+The value denotes the side of the frame or window where a new window
+displaying the buffer shall be created. This entry is used by
address@hidden to indicate the side of the frame
+where a new side window shall be placed (@pxref{Displaying Buffers in
+Side Windows}). It is also used by
address@hidden to indicate the side of an
+existing window where the new window shall be located (@pxref{Atomic
+Windows}).
address@hidden
-This form will have @code{display-buffer} first try reusing a window
-that shows *foo* on the selected frame. If there's no such window, it
-will try to split the selected window or, if that is impossible, use the
-window below the selected window.
address@hidden address@hidden, a buffer display action alist entry}
address@hidden slot
+If address@hidden, the value specifies the slot of the side window
+supposed to display the buffer. This entry is used only by
address@hidden
- If there's no window below the selected one, or the window below the
-selected one is dedicated to its buffer, @code{display-buffer} will
-proceed as described in the previous example. Note, however, that when
-it tries to adjust the height of any reused or popped-up window, it will
-in any case try to set its number of lines to 5 since that value
-overrides the corresponding specification in the @var{action} argument
-of @code{display-buffer}.
address@hidden address@hidden, a buffer display action alist entry}
address@hidden window
+The value specifies a window that is in some way related to the window
+chosen by @code{display-buffer}. This entry is currently used by
address@hidden to indicate the window on whose
+side the new window shall be created.
+
address@hidden address@hidden, a buffer display action alist entry}
address@hidden allow-no-window
+If the value is address@hidden, @code{display-buffer} does not
+necessarily have to display the buffer and the caller is prepared to
+accept that. This entry is not intended for user customizations,
+since there is no guarantee that an arbitrary caller of
address@hidden will be able to handle the case that no window
+will display the buffer. @code{display-buffer-no-window} is the only
+action function that cares about this entry.
address@hidden table
@node Choosing Window Options
address@hidden Additional Options for Displaying Buffers
address@hidden Additional Options for Displaying Buffers
-The behavior of the standard display actions of @code{display-buffer}
-(@pxref{Choosing Window}) can be modified by a variety of user
-options.
+The behavior of buffer display actions (@pxref{Choosing Window}) can
+be further modified by the following user options.
@defopt pop-up-windows
If the value of this variable is address@hidden, @code{display-buffer}
is allowed to split an existing window to make a new window for
displaying in. This is the default.
-This variable is provided mainly for backward compatibility. It is
+This variable is provided for backward compatibility only. It is
obeyed by @code{display-buffer} via a special mechanism in
address@hidden, which only calls the action
-function @code{display-buffer-pop-up-window} (@pxref{Display Action
-Functions}) when the value is @code{nil}. It is not consulted by
address@hidden itself, which the user may specify
-directly in @code{display-buffer-alist} etc.
address@hidden, which calls the action function
address@hidden (@pxref{Buffer Display Action
+Functions}) when the value of this option is address@hidden It is
+not consulted by @code{display-buffer-pop-up-window} itself, which the
+user may specify directly in @code{display-buffer-alist} etc.
@end defopt
@defopt split-window-preferred-function
This variable specifies a function for splitting a window, in order to
make a new window for displaying a buffer. It is used by the
@code{display-buffer-pop-up-window} action function to actually split
-the window (@pxref{Display Action Functions}).
+the window.
-The default value is @code{split-window-sensibly}, which is documented
-below. The value must be a function that takes one argument, a window,
-and return either a new window (which will be used to display the
-desired buffer) or @code{nil} (which means the splitting failed).
+The value must be a function that takes one argument, a window, and
+returns either a new window (which will be used to display the desired
+buffer) or @code{nil} (which means the splitting failed). The default
+value is @code{split-window-sensibly}, which is documented next.
@end defopt
@defun split-window-sensibly &optional window
-This function tries to split @var{window}, and return the newly created
+This function tries to split @var{window} and return the newly created
window. If @var{window} cannot be split, it returns @code{nil}. If
@var{window} is omitted or @code{nil}, it defaults to the selected
window.
@@ -2790,31 +2945,31 @@ placing the new window below, subject to the
restriction imposed by
@code{split-height-threshold} (see below), in addition to any other
restrictions. If that fails, it tries to split by placing the new
window to the right, subject to @code{split-width-threshold} (see
-below). If that fails, and the window is the only window on its
+below). If that also fails, and the window is the only window on its
frame, this function again tries to split and place the new window
below, disregarding @code{split-height-threshold}. If this fails as
well, this function gives up and returns @code{nil}.
@end defun
@defopt split-height-threshold
-This variable, used by @code{split-window-sensibly}, specifies whether
-to split the window placing the new window below. If it is an
+This variable specifies whether @code{split-window-sensibly} is
+allowed to split the window placing the new window below. If it is an
integer, that means to split only if the original window has at least
that many lines. If it is @code{nil}, that means not to split this
way.
@end defopt
@defopt split-width-threshold
-This variable, used by @code{split-window-sensibly}, specifies whether
-to split the window placing the new window to the right. If the value
-is an integer, that means to split only if the original window has at
-least that many columns. If the value is @code{nil}, that means not
-to split this way.
+This variable specifies whether @code{split-window-sensibly} is
+allowed to split the window placing the new window to the right. If
+the value is an integer, that means to split only if the original
+window has at least that many columns. If the value is @code{nil},
+that means not to split this way.
@end defopt
@defopt even-window-sizes
This variable, if address@hidden, causes @code{display-buffer} to even
-window sizes whenever it reuses an existing window and that window is
+window sizes whenever it reuses an existing window, and that window is
adjacent to the selected one.
If its value is @code{width-only}, sizes are evened only if the reused
@@ -2839,9 +2994,9 @@ search any visible or iconified frame, not just the
selected frame.
This variable is provided mainly for backward compatibility. It is
obeyed by @code{display-buffer} via a special mechanism in
@code{display-buffer-fallback-action}, which calls the action function
address@hidden (@pxref{Display Action Functions})
-if the value is address@hidden (This is done before attempting to
-split a window.) This variable is not consulted by
address@hidden (@pxref{Buffer Display Action
+Functions}) if the value is address@hidden (This is done before
+attempting to split a window.) This variable is not consulted by
@code{display-buffer-pop-up-frame} itself, which the user may specify
directly in @code{display-buffer-alist} etc.
@end defopt
@@ -2849,8 +3004,7 @@ directly in @code{display-buffer-alist} etc.
@defopt pop-up-frame-function
This variable specifies a function for creating a new frame, in order
to make a new window for displaying a buffer. It is used by the
address@hidden action function (@pxref{Display
-Action Functions}).
address@hidden action function.
The value should be a function that takes no arguments and returns a
frame, or @code{nil} if no frame could be created. The default value
@@ -2860,30 +3014,670 @@ is a function that creates a frame using the
parameters specified by
@defopt pop-up-frame-alist
This variable holds an alist of frame parameters (@pxref{Frame
-Parameters}), which is used by the default function in
+Parameters}), which is used by the function specified by
@code{pop-up-frame-function} to make a new frame. The default is
@code{nil}.
address@hidden defopt
address@hidden same-window-buffer-names
-A list of buffer names for buffers that should be displayed in the
-selected window. If a buffer's name is in this list,
address@hidden handles the buffer by showing it in the selected
-window.
+This option is provided for backward compatibility only. Note, that
+when @code{display-buffer-pop-up-frame} calls the function specified
+by @code{pop-up-frame-function}, it prepends the value of all
address@hidden action alist entries to
address@hidden so that the values specified by the action
+alist entry effectively override any corresponding values of
address@hidden
+
+Hence, users should set up a @code{pop-up-frame-parameters} action
+alist entry in @code{display-buffer-alist} instead of customizing
address@hidden Only this will guarantee that the value of
+a parameter specified by the user overrides the value of that
+parameter specified by the caller of @code{display-buffer}.
@end defopt
address@hidden same-window-regexps
-A list of regular expressions that specify buffers that should be
-displayed in the selected window. If the buffer's name matches any of
-the regular expressions in this list, @code{display-buffer} handles the
-buffer by showing it in the selected window.
address@hidden defopt
+ Many efforts in the design of @code{display-buffer} have been given
+to maintain compatibility with code that uses older options like
address@hidden, @code{pop-up-frames},
address@hidden, @code{same-window-buffer-names} and
address@hidden Lisp Programs and users should refrain
+from using these options. Above we already warned against customizing
address@hidden Here we describe how to convert the
+remaining options to use display actions instead.
+
address@hidden @code
address@hidden pop-up-windows
address@hidden address@hidden, replacement for}
+This variable is @code{t} by default. Instead of customizing it to
address@hidden and thus telling @code{display-buffer} what not to do, it's
+much better to list in @code{display-buffer-base-action} the action
+functions it should try instead as, for example:
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-base-action
+ '((display-buffer-reuse-window display-buffer-same-window
+ display-buffer-in-previous-window
+ display-buffer-use-some-window)))
address@hidden group
address@hidden example
+
address@hidden pop-up-frames
address@hidden address@hidden, replacement for}
+Instead of customizing this variable to @code{t}, customize
address@hidden, for example, as follows:
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-base-action
+ '((display-buffer-reuse-window display-buffer-pop-up-frame)
+ (reusable-frames . 0)))
address@hidden group
address@hidden example
+
address@hidden same-window-buffer-names
address@hidden same-window-regexps
address@hidden address@hidden, replacement for}
address@hidden address@hidden, replacement for}
+Instead of adding a buffer name or a regular expression to one of
+these options use a @code{display-buffer-alist} entry for that buffer
+specifying the action function @code{display-buffer-same-window}.
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-alist
+ (cons '("\\*foo\\*" (display-buffer-same-window))
+ display-buffer-alist))
address@hidden group
address@hidden example
address@hidden table
+
+
address@hidden Precedence of Action Functions
address@hidden Precedence of Action Functions
address@hidden precedence of buffer display action functions
address@hidden execution order of buffer display action functions
address@hidden buffer display action functions, precedence
+
+From the past subsections we already know that @code{display-buffer}
+must be supplied with a number of display actions (@pxref{Choosing
+Window}) in order to display a buffer. In a completely uncustomized
+Emacs, these actions are specified by
address@hidden in the following order of
+precedence: Reuse a window, pop up a new window on the same frame, use
+a window previously showing the buffer, use some window and pop up a
+new frame. (Note that the remaining actions named by
address@hidden are void in an uncustomized
+Emacs).
+
+Consider the following form:
+
address@hidden
+(display-buffer (get-buffer-create "*foo*"))
address@hidden example
+
address@hidden
+Evaluating this form in the buffer @file{*scratch*} of an uncustomized
+Emacs session will usually fail to reuse a window that shows
address@hidden already, but succeed in popping up a new window.
+Evaluating the same form again will now not cause any visible
address@hidden reused the window already showing
address@hidden because that action was applicable and had the highest
+precedence among all applicable actions.
+
+ Popping up a new window will fail if there is not enough space on
+the selected frame. In an uncustomized Emacs it typically fails when
+there are already two windows on a frame. For example, if you now
+type @address@hidden 1}} followed by @address@hidden 2}} and evaluate the form
+once more, @file{*foo*} should show up in the lower
address@hidden just used ``some'' window. If, before
+typing @address@hidden 2}} you had typed @address@hidden o}}, @file{*foo*}
+would have been shown in the upper window because ``some'' window
+stands for the ``least recently used'' window and the selected window
+has been least recently used if and only if it is alone on its frame.
+
+ Let's assume you did not type @address@hidden o}} and @file{*foo*} is
+shown in the lower window. Type @address@hidden o}} to get there followed
+by @address@hidden left}} and evaluate the form again. This should
+display @file{*foo*} in the same, lower window because that window had
+already shown @file{*foo*} previously and was therefore chosen instead
+of some other window.
+
+ So far we have only observed the default behavior in an uncustomized
+Emacs session. To see how this behavior can be customized, let's
+consider the option @code{display-buffer-base-action}. It provides a
+very coarse customization which conceptually affects the display of
address@hidden buffer. It can be used to supplement the actions supplied
+by @code{display-buffer-fallback-action} by reordering them or by
+adding actions that are not present there but fit more closely the
+user's editing practice. However, it can also be used to change the
+default behavior in a more profound way.
+
+ Let's consider a user who, as a rule, prefers to display buffers on
+another frame. Such a user might provide the following customization:
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-base-action
+ '((display-buffer-reuse-window display-buffer-pop-up-frame)
+ (reusable-frames . 0)))
address@hidden group
address@hidden example
+
address@hidden
+This setting will cause @code{display-buffer} to first try to find a
+window showing the buffer on a visible or iconified frame and, if no
+such frame exists, pop up a new frame. You can observe this behavior
+on a graphical system by typing @address@hidden 1}} in the window showing
address@hidden and evaluating our canonical @code{display-buffer}
+form. This will usually create (and give focus to) a new frame whose
+root window shows @file{*foo*}. Iconify that frame and evaluate the
+canonical form again: @code{display-buffer} will reuse the window on
+the new frame (usually raising the frame and giving it focus too).
+
+ Only if creating a new frame fails, @code{display-buffer} will
+apply the actions supplied by @code{display-buffer-fallback-action}
+which means to again try reusing a window, popping up a new window and
+so on. A trivial way to make frame creation fail is supplied by the
+following form:
+
address@hidden
address@hidden
+(let ((pop-up-frame-function 'ignore))
+ (display-buffer (get-buffer-create "*foo*")))
address@hidden group
address@hidden example
+
address@hidden
+We will forget about that form immediately after observing that it
+fails to create a new frame and uses a fallback action instead.
+
+ Note that @code{display-buffer-reuse-window} appears redundant in
+the customization of @code{display-buffer-base-action} because it is
+already part of @code{display-buffer-fallback-action} and should be
+tried there anyway. However, that would fail because due to the
+precedence of @code{display-buffer-base-action} over
address@hidden, at that time
address@hidden would have already won the race.
+In fact, this:
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-base-action
+ '(display-buffer-pop-up-frame (reusable-frames . 0)))
address@hidden group
address@hidden example
+
address@hidden
+would cause @code{display-buffer} to @emph{always} pop up a new frame
+which is probably not what our user wants.
+
+ So far, we have only shown how @emph{users} can customize the
+default behavior of @code{display-buffer}. Let us now see how
address@hidden can change the course of @code{display-buffer}.
+The canonical way to do that is to use the @var{action} argument of
address@hidden or a function that calls it, like, for example,
address@hidden (@pxref{Switching Buffers}).
+
+ Suppose an application wants to display @file{*foo*} preferably
+below the selected window (to immediately attract the attention of the
+user to the new window) or, if that fails, in a window at the bottom
+of the frame. It could do that with a call like this:
+
address@hidden
address@hidden
+(display-buffer
+ (get-buffer-create "*foo*")
+ '((display-buffer-below-selected display-buffer-at-bottom)))
address@hidden group
address@hidden example
+
address@hidden
+In order to see how this new, modified form works, delete any frame
+showing @file{*foo*}, type @address@hidden 1}} followed by @address@hidden 2}}
in the
+window showing @file{*scratch*}, and subsequently evaluate that form.
address@hidden should split the upper window, and show
address@hidden in the new window. Alternatively, if after @address@hidden 2}}
+you had typed @address@hidden o}}, @code{display-buffer} would have split the
+window at the bottom instead.
+
+ Suppose now that, before evaluating the new form, you have made the
+selected window as small as possible, for example, by evaluating the
+form @code{(fit-window-to-buffer)} in that window. In that case,
address@hidden would have failed to split the selected window
+and would have split the frame's root window instead, effectively
+displaying @file{*foo*} at the bottom of the frame.
+
+ In either case, evaluating the new form a second time should reuse
+the window already showing @file{*foo*} since both functions supplied
+by the @var{action} argument try to reuse such a window first.
+
+ By setting the @var{action} argument, an application effectively
+overrules any customization of @code{display-buffer-base-action}. Our
+user can now either accept the choice of the application, or redouble
+by customizing the option @code{display-buffer-alist} as follows:
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-alist
+ '(("\\*foo\\*"
+ (display-buffer-reuse-window display-buffer-pop-up-frame))))
address@hidden group
address@hidden example
+
address@hidden
+Trying this with the new, modified form above in a configuration that
+does not show @file{*foo*} anywhere, will display @file{*foo*} on a
+separate frame, completely ignoring the @var{action} argument of
address@hidden
+
+ Note that we didn't care to specify a @code{reusable-frames} action
+alist entry in our specification of @code{display-buffer-alist}.
address@hidden always takes the first one it finds---in our
+case the one specified by @code{display-buffer-base-action}. If we
+wanted to use a different specification, for example, to exclude
+iconified frames showing @file{*foo*} from the list of reusable ones,
+we would have to specify that separately, however:
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-alist
+ '(("\\*foo\\*"
+ (display-buffer-reuse-window display-buffer-pop-up-frame)
+ (reusable-frames . visible))))
address@hidden group
address@hidden example
+
address@hidden
+If you try this, you will notice that repeated attempts to display
address@hidden will succeed to reuse a frame only if that frame is
+visible.
+
+ The above example would allow the conclusion that users customize
address@hidden for the sole purpose to overrule the
address@hidden argument chosen by applications. Such a conclusion would
+be incorrect. @code{display-buffer-alist} is the standard option for
+users to direct the course of display of specific buffers in a
+preferred way regardless of whether the display is also guided by an
address@hidden argument.
+
+ We can, however, reasonably conclude that customizing
address@hidden differs from customizing
address@hidden in two major aspects: it is stronger
+because it overrides the @var{action} argument of
address@hidden, and it allows to explicitly specify the
+affected buffers. In fact, displaying other buffers is not affected
+in any way by a customization for @file{*foo*}. For example,
+
address@hidden
+(display-buffer (get-buffer-create "*bar*"))
address@hidden example
+
address@hidden
+continues being governed by the settings of
address@hidden and
address@hidden only.
+
+ We could stop with our examples here but Lisp programs still have
+an ace up their sleeves which they can use to overrule any
+customization of @code{display-buffer-alist}. It's the variable
address@hidden which they can bind around
address@hidden calls as follows:
+
address@hidden
address@hidden
+(let ((display-buffer-overriding-action
+ '((display-buffer-same-window))))
+ (display-buffer
+ (get-buffer-create "*foo*")
+ '((display-buffer-below-selected display-buffer-at-bottom))))
address@hidden group
address@hidden example
+
address@hidden
+Evaluating this form will usually display @file{*foo*} in the selected
+window regardless of the @var{action} argument and any user
+customizations. (Usually, an application will not bother to also
+provide an @var{action} argument. Here it just serves to illustrate
+the fact that it gets overridden.)
+
+It might be illustrative to look at the list of action functions
address@hidden would have tried to display @file{*foo*} with
+the customizations we provided here. The list (including comments
+explaining who added this and the subsequent elements) is:
+
address@hidden
address@hidden
+(display-buffer-same-window ;; `display-buffer-overriding-action'
+ display-buffer-reuse-window ;; `display-buffer-alist'
+ display-buffer-pop-up-frame
+ display-buffer-below-selected ;; ACTION argument
+ display-buffer-at-bottom
+ display-buffer-reuse-window ;; `display-buffer-base-action'
+ display-buffer-pop-up-frame
+ display-buffer--maybe-same-window ;; `display-buffer-fallback-action'
+ display-buffer-reuse-window
+ display-buffer--maybe-pop-up-frame-or-window
+ display-buffer-in-previous-window
+ display-buffer-use-some-window
+ display-buffer-pop-up-frame)
address@hidden group
address@hidden example
+
address@hidden
+Note that among the internal functions listed here,
address@hidden is effectively ignored while
address@hidden actually runs
address@hidden
+
+The action alist passed in each function call is:
+
address@hidden
address@hidden
+((reusable-frames . visible)
+ (reusable-frames . 0))
address@hidden group
address@hidden example
+
address@hidden
+which shows that we have used the second specification of
address@hidden above, overriding the specification
+supplied by @code{display-buffer-base-action}. Suppose our user had
+written that as
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-alist
+ '(("\\*foo\\*"
+ (display-buffer-reuse-window display-buffer-pop-up-frame)
+ (inhibit-same-window . t)
+ (reusable-frames . visible))))
address@hidden group
address@hidden example
+
address@hidden
+In this case the @code{inhibit-same-window} alist entry will
+successfully invalidate the @code{display-buffer-same-window}
+specification from @code{display-buffer-overriding-action} and
address@hidden will show @file{*foo*} on another frame. To
+make @code{display-buffer-overriding-action} more robust in this
+regard, the application would have to specify an appropriate
address@hidden entry too, for example, as follows:
+
address@hidden
address@hidden
+(let ((display-buffer-overriding-action
+ '(display-buffer-same-window (inhibit-same-window . nil))))
+ (display-buffer (get-buffer-create "*foo*")))
address@hidden group
address@hidden example
+
address@hidden
+This last example shows that while the precedence order of action
+functions is fixed, as described in @ref{Choosing Window}, an action
+alist entry specified by a display action ranked lower in that order
+can affect the execution of a higher ranked display action.
+
+
address@hidden The Zen of Buffer Display
address@hidden The Zen of Buffer Display
address@hidden guidelines for buffer display
address@hidden writing buffer display actions
address@hidden buffer display conventions
+
+In its most simplistic form, a frame accommodates always one single
+window that can be used for displaying a buffer. As a consequence, it
+is always the latest call of @code{display-buffer} that will have
+succeeded in placing its buffer there.
+
+ Since working with such a frame is not very practical, Emacs by
+default allows for more complex frame layouts controlled by the
+default values of the frame size and the @code{split-height-threshold}
+and @code{split-width-threshold} options. Displaying a buffer not yet
+shown on a frame then either splits the single window on that frame or
+(re-)uses one of its two windows.
+
+ The default behavior is abandoned as soon as the user customizes
+one of these thresholds or manually changes the frame's layout. The
+default behavior is also abandoned when calling @code{display-buffer}
+with a address@hidden @var{action} argument or the user customizes one
+of the options mentioned in the previous subsections. Mastering
address@hidden soon may become a frustrating experience due to
+the plethora of applicable display actions and the resulting frame
+layouts.
+
+ However, refraining from using buffer display functions and falling
+back on a split & delete windows metaphor is not a good idea either.
+Buffer display functions give Lisp programs and users a framework to
+reconcile their different needs; no comparable framework exists for
+splitting and deleting windows. Buffer display functions also allow
+to at least partially restore the layout of a frame when removing a
+buffer from it later (@pxref{Quitting Windows}).
+
+ Below we will give a number of guidelines to redeem the frustration
+mentioned above and thus to avoid literally losing buffers in-between
+the windows of a frame.
+
address@hidden @asis
address@hidden Write display actions without stress
+Writing display actions can be a pain because one has to lump together
+action functions and action alists in one huge list. (Historical
+reasons prevented us from having @code{display-buffer} support
+separate arguments for these.) It might help to memorize some basic
+forms like the ones listed below:
+
address@hidden
+'(nil (inhibit-same-window . t))
address@hidden example
+
address@hidden
+specifies an action alist entry only and no action function. Its sole
+purpose is to inhibit a @code{display-buffer-same-window} function
+specified elsewhere from showing the buffer in the same window, see
+also the last example of the preceding subsection.
+
address@hidden
+'(display-buffer-below-selected)
address@hidden example
+
address@hidden
+on the other hand, specifies one action function and an empty action
+alist. To combine the effects of the above two specifications one
+would write the form
+
address@hidden
+'(display-buffer-below-selected (inhibit-same-window . t))
address@hidden example
+
address@hidden
+to add another action function one would write
+
address@hidden
address@hidden
+'((display-buffer-below-selected display-buffer-at-bottom)
+ (inhibit-same-window . t))
address@hidden group
address@hidden example
+
address@hidden
+and to add another alist entry one would write
+
address@hidden
address@hidden
+'((display-buffer-below-selected display-buffer-at-bottom)
+ (inhibit-same-window . t)
+ (window-height . fit-window-to-buffer))
address@hidden group
address@hidden example
+
address@hidden
+That last form can be used as @var{action} argument of
address@hidden in the following way:
+
address@hidden
address@hidden
+(display-buffer
+ (get-buffer-create "*foo*")
+ '((display-buffer-below-selected display-buffer-at-bottom)
+ (inhibit-same-window . t)
+ (window-height . fit-window-to-buffer)))
address@hidden group
address@hidden example
+
address@hidden
+In a customization of @code{display-buffer-alist} it would be used as
+follows:
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-alist
+ '(("\\*foo\\*"
+ (display-buffer-below-selected display-buffer-at-bottom)
+ (inhibit-same-window . t)
+ (window-height . fit-window-to-buffer))))
address@hidden group
address@hidden example
+
address@hidden
+To add a customization for a second buffer one would then write:
+
address@hidden
address@hidden
+(customize-set-variable
+ 'display-buffer-alist
+ '(("\\*foo\\*"
+ (display-buffer-below-selected display-buffer-at-bottom)
+ (inhibit-same-window . t)
+ (window-height . fit-window-to-buffer))
+ ("\\*bar\\*"
+ (display-buffer-reuse-window display-buffer-pop-up-frame)
+ (reusable-frames . visible))))
address@hidden group
address@hidden example
+
address@hidden Treat each other with respect
address@hidden and @code{display-buffer-base-action} are
+user options---Lisp programs must never set or rebind them.
address@hidden, on the other hand, is
+reserved for applications---who seldom use that option and if they use
+it, then with utmost care.
+
+ Older implementations of @code{display-buffer} frequently caused
+users and applications to fight over the settings of user options like
address@hidden and @code{pop-up-windows} (@pxref{Choosing Window
+Options}). This was one major reason for redesigning
address@hidden provide a clear framework specifying what
+users and applications should be allowed to do.
+
+ Lisp programs must be prepared that user customizations may
+cause buffers to get displayed in an unexpected way. They should
+never assume in their subsequent behavior, that the buffer has been
+shown precisely the way they asked for in the @var{action} argument of
address@hidden
+
+ Users should not pose too many and too severe restrictions on how
+arbitrary buffers get displayed. Otherwise, they will risk to lose
+the characteristics of showing a buffer for a certain purpose.
+Suppose a Lisp program has been written to compare different versions
+of a buffer in two windows side-by-side. If the customization of
address@hidden prescribes that any such buffer should be
+always shown in or below the selected window, the program will have a
+hard time to set up the desired window configuration via
address@hidden
+
+ To specify a preference for showing an arbitrary buffer, users
+should customize @code{display-buffer-base-action}. An example of how
+users who prefer working with multiple frames would do that was given
+in the previous subsection. @code{display-buffer-alist} should be
+reserved for displaying specific buffers in a specific way.
+
address@hidden Consider reusing a window that already shows the buffer
+Generally, it's always a good idea for users and Lisp
+programmers to be prepared for the case that a window already shows
+the buffer in question and to reuse that window. In the preceding
+subsection we have shown that failing to do so properly may cause
address@hidden to continuously pop up a new frame although a
+frame showing that buffer existed already. In a few cases only, it
+might be undesirable to reuse a window, for example, when a different
+portion of the buffer should be shown in that window.
+
+ Hence, @code{display-buffer-reuse-window} is one action function
+that should be used as often as possible, both in @var{action}
+arguments and customizations. An @code{inhibit-same-window} entry in
+the @var{action} argument usually takes care of the most common case
+where reusing a window showing the buffer should be avoided---that
+where the window in question is the selected one.
+
address@hidden Attract focus to the window chosen
+This is a no-brainer for people working with multiple frames---the
+frame showing the buffer will automatically raise and get focus unless
+an @code{inhibit-switch-frame} entry forbids it. For single frame
+users this task can be considerably more difficult. In particular,
address@hidden and
address@hidden can become obtrusive in this
+regard. They split or use a seemingly arbitrary (often the largest or
+least recently used) window, distracting the user's attention.
+
+Some Lisp programs therefore try to choose a window at the bottom of
+the frame, for example, in order to display the buffer in vicinity of
+the minibuffer window where the user is expected to answer a question
+related to the new window. For non-input related actions
address@hidden might be preferable because the
+selected window usually already has the user's attention.
+
address@hidden Handle subsequent invocations of @code{display-buffer}
address@hidden is not overly well suited for displaying several
+buffers in sequence and making sure that all these buffers are shown
+orderly in the resulting window configuration. Again, the standard
+action functions @code{display-buffer-pop-up-window} and
address@hidden are not very suited for this
+purpose due to their somewhat chaotic nature in more complex
+configurations.
+
+ To produce a window configuration displaying multiple buffers (or
+different views of one and the same buffer) in one and the same
+display cycle, Lisp programmers will unavoidably have to write
+their own action functions. A few tricks listed below might help in
+this regard.
+
address@hidden @bullet
address@hidden
+Making windows atomic (@pxref{Atomic Windows}) avoids breaking an
+existing window composition when popping up a new window.
+The new window will pop up outside the composition instead.
+
address@hidden
+Temporarily dedicating windows to their buffers (@pxref{Dedicated
+Windows}) avoids using a window for displaying a different
+buffer. A non-dedicated window will be used instead.
+
address@hidden
+Calling @code{window-preserve-size} (@pxref{Preserving Window Sizes})
+will try to keep the size of the argument window unchanged when
+popping up a new window. You have to make sure that another window in
+the same combination can be shrunk instead, though.
+
address@hidden
+Side windows (@pxref{Side Windows}) can be used for displaying
+specific buffers always in a window at the same position of a frame.
+This permits grouping buffers that do not compete for being shown at
+the same time on a frame and showing any such buffer in the same window
+without disrupting the display of other buffers.
+
address@hidden
+Child frames (@pxref{Child Frames}) can be used to display a buffer
+within the screen estate of the selected frame without disrupting that
+frame's window configuration and without the overhead associated with
+full-fledged frames as inflicted by @code{display-buffer-pop-up-frame}.
address@hidden itemize
address@hidden table
address@hidden same-window-p buffer-name
-This function returns @code{t} if displaying a buffer
-named @var{buffer-name} with @code{display-buffer} would
-put it in the selected window.
address@hidden defun
@node Window History
@section Window History
@@ -3202,12 +3996,13 @@ main window is either a ``normal'' live window or
specifies the area
containing all the normal windows.
In their most simple form of use, side windows allow to display
-specific buffers always in the same area of a frame. Hence they can be
-regarded as a generalization of the concept provided by
address@hidden (@pxref{Display Action Functions}) to
-the remaining sides of a frame. With suitable customizations, however,
-side windows can be also used to provide frame layouts similar to those
-found in so-called integrated development environments (IDEs).
+specific buffers always in the same area of a frame. Hence they can
+be regarded as a generalization of the concept provided by
address@hidden (@pxref{Buffer Display Action
+Functions}) to the remaining sides of a frame. With suitable
+customizations, however, side windows can be also used to provide
+frame layouts similar to those found in so-called integrated
+development environments (IDEs).
@menu
* Displaying Buffers in Side Windows:: An action function for displaying
@@ -3221,9 +4016,9 @@ found in so-called integrated development environments
(IDEs).
@node Displaying Buffers in Side Windows
@subsection Displaying Buffers in Side Windows
-The following action function for @code{display-buffer} (@pxref{Display
-Action Functions}) creates or reuses a side window for displaying the
-specified buffer.
+The following action function for @code{display-buffer} (@pxref{Buffer
+Display Action Functions}) creates or reuses a side window for
+displaying the specified buffer.
@defun display-buffer-in-side-window buffer alist
This function displays @var{buffer} in a side window of the selected
@@ -3263,11 +4058,11 @@ explicitly provided via a @code{window-parameters}
entry in @var{alist}.
@end defun
By default, side windows cannot be split via @code{split-window}
-(@pxref{Splitting Windows}). Also, a side window is not reused or split
-by any buffer display action (@pxref{Display Action Functions}) unless
-it is explicitly specified as target of that action. Note also that
address@hidden cannot make a side window the only window on
-its frame (@pxref{Deleting Windows}).
+(@pxref{Splitting Windows}). Also, a side window is not reused or
+split by any buffer display action (@pxref{Buffer Display Action
+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}
@@ -3453,9 +4248,9 @@ retain their respective sizes when maximizing the frame,
the variable
@xref{Resizing Windows}.
The last form also makes sure that none of the created side windows
-are accessible via @kbd{C-x o} by installing the @code{no-other-window}
+are accessible via @address@hidden o}} by installing the @code{no-other-window}
parameter for each of these windows. In addition, it makes sure that
-side windows are not deleted via @kbd{C-x 1} by installing the
+side windows are not deleted via @address@hidden 1}} by installing the
@code{no-delete-other-windows} parameter for each of these windows.
Since @code{dired} buffers have no fixed names, we use a special
@@ -3547,7 +4342,7 @@ does is to set the @code{window-atom} parameter of each
descendant of
To create a new atomic window from an existing live window or to add a
new window to an existing atomic window, the following buffer display
-action function (@pxref{Display Action Functions}) can be used:
+action function (@pxref{Buffer Display Action Functions}) can be used:
@defun display-buffer-in-atom-window buffer alist
This function tries to display @var{buffer} in a new window that will be
diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el
index 2746738..a2143bf 100644
--- a/lisp/emacs-lisp/pcase.el
+++ b/lisp/emacs-lisp/pcase.el
@@ -264,10 +264,14 @@ variable name being but a special case of it)."
;;;###autoload
(defmacro pcase-let* (bindings &rest body)
- "Like `let*' but where you can use `pcase' patterns for bindings.
-BODY should be an expression, and BINDINGS should be a list of bindings
-of the form (PATTERN EXP).
-See `pcase-let' for discussion of how PATTERN is matched."
+ "Like `let*', but supports destructuring BINDINGS using `pcase' patterns.
+As with `pcase-let', BINDINGS are of the form (PATTERN EXP), but the
+EXP in each binding in BINDINGS can use the results of the destructuring
+bindings that precede it in BINDINGS' order.
+
+Each EXP should match (i.e. be of compatible structure) to its
+respective PATTERN; a mismatch may signal an error or may go
+undetected, binding variables to arbitrary values, such as nil."
(declare (indent 1)
(debug ((&rest (pcase-PAT &optional form)) body)))
(let ((cached (gethash bindings pcase--memoize)))
@@ -280,13 +284,16 @@ See `pcase-let' for discussion of how PATTERN is matched."
;;;###autoload
(defmacro pcase-let (bindings &rest body)
- "Like `let' but where you can use `pcase' patterns for bindings.
-BODY should be a list of expressions, and BINDINGS should be a list of bindings
-of the form (PATTERN EXP).
-The PATTERNs are only used to extract data, so the code does not test
-whether the data does match the corresponding patterns: a mismatch
-may signal an error or may go undetected, binding variables to arbitrary
-values, such as nil."
+ "Like `let', but supports destructuring BINDINGS using `pcase' patterns.
+BODY should be a list of expressions, and BINDINGS should be a list of
+bindings of the form (PATTERN EXP).
+All EXPs are evaluated first, and then used to perform destructuring
+bindings by matching each EXP against its respective PATTERN. Then
+BODY is evaluated with those bindings in effect.
+
+Each EXP should match (i.e. be of compatible structure) to its
+respective PATTERN; a mismatch may signal an error or may go
+undetected, binding variables to arbitrary values, such as nil."
(declare (indent 1) (debug pcase-let*))
(if (null (cdr bindings))
`(pcase-let* ,bindings ,@body)
@@ -304,11 +311,15 @@ values, such as nil."
;;;###autoload
(defmacro pcase-dolist (spec &rest body)
- "Superset of `dolist' where the VAR binding can be a `pcase' PATTERN.
-More specifically, this is just a shorthand for the following combination
-of `dolist' and `pcase-let':
-
- (dolist (x LIST) (pcase-let ((PATTERN x)) BODY...))
+ "Eval BODY once for each set of bindings defined by PATTERN and LIST
elements.
+PATTERN should be a `pcase' pattern describing the structure of
+LIST elements, and LIST is a list of objects that match PATTERN,
+i.e. have a structure that is compatible with PATTERN.
+For each element of LIST, this macro binds the variables in
+PATTERN to the corresponding subfields of the LIST element, and
+then evaluates BODY with these bindings in effect. The
+destructuring bindings of variables in PATTERN to the subfields
+of the elements of LIST is performed as if by `pcase-let'.
\n(fn (PATTERN LIST) BODY...)"
(declare (indent 1) (debug ((pcase-PAT form) body)))
(if (pcase--trivial-upat-p (car spec))
- [Emacs-diffs] master updated (19d2ba0 -> 294a524), Glenn Morris, 2018/11/04
- [Emacs-diffs] master 4fbdcce 4/6: ; Merge from origin/emacs-26, Glenn Morris, 2018/11/04
- [Emacs-diffs] master 5ad0d80 2/6: ; Merge from origin/emacs-26, Glenn Morris, 2018/11/04
- [Emacs-diffs] master a914009 3/6: Merge from origin/emacs-26, Glenn Morris, 2018/11/04
- [Emacs-diffs] master 9b90f1b 1/6: Merge from origin/emacs-26, Glenn Morris, 2018/11/04
- [Emacs-diffs] master 294a524 6/6: * src/xfaces.c (face_at_buffer_position): Adapt lookup_basic_face call., Glenn Morris, 2018/11/04
- [Emacs-diffs] master 410e65e 5/6: Merge from origin/emacs-26,
Glenn Morris <=