mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-26 07:11:34 -08:00
Code Issues Projects Releases Wiki Activity

Merge from origin/emacs-26

Browse source 
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
This commit is contained in:
Glenn Morris 2018-11-04 09:37:03 -08:00
commit 410e65e4ce
7 changed files with 1390 additions and 537 deletions
Download patch file Download diff file Expand all files Collapse all files

127
doc/emacs/windows.texi
View file

@ -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
@code{pop-up-frames} 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
@vindex same-window-buffer-names
@vindex 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
@code{same-window-buffer-names}, 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
@code{display-buffer-alist} (@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:
@example
@group
(customize-set-variable
'display-buffer-alist
'("\\*scratch\\*" (display-buffer-same-window)))
@end group
@end 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.
@vindex 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
@code{pop-up-frames} to a non-@code{nil} value. The special value
@code{graphic-only} 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:
@example
@group
(customize-set-variable
'display-buffer-base-action
'((display-buffer-reuse-window display-buffer-pop-up-frame)
(reusable-frames . 0)))
@end group
@end 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
@code{pop-up-frames} is non-@code{nil} 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
@code{display-buffer} is by using the option @code{display-buffer-alist}
mentioned in the next section.
@node Temporary Displays
@subsection Displaying non-editable buffers.
@cindex 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
@code{display-buffer} 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.
@code{display-buffer}, as described in the previous subsection. 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.
If you prefer Emacs to display a temporary buffer in a different
fashion, we recommend customizing the variable
@code{display-buffer-alist} (@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})
@code{temp-buffer-resize-mode} (@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

226
doc/lispref/control.texi
View file

@ -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
@cindex pattern matching
@cindex 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
@item 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}.
@item
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}.
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
@item The equality tests use @code{eql}.
@item The values must be known and written in advance.
@item
The equality tests use @code{eql}.
@item
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 non-@code{nil}, the pattern matches the value
(or sometimes ``the value matches the pattern'').
When the predicate, called on the value of the first arg, returns
non-@code{nil}, 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}.
@cindex 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 non-@code{nil}
when called on @var{expval}.
@var{function} 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: @w{@code{(= 42 @var{expval})}}.
@item (app @var{function} @var{pattern})
Matches if @var{function} called on @var{expval} returns a
value that matches @var{pattern}.
@var{function} 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.
@var{function} 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 non-@code{nil}.
@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
@var{pattern} 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 @var{pattern1}@dots{})
Attempts to match @var{pattern1}@dots{}, 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 @var{pattern1}@dots{}, 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} @var{pattern2}@dots{})
Attempts to match @var{pattern1}, @var{pattern2}, @dots{}, in order,
until one of them succeeds.
In that case, @code{or} likewise matches,
and the rest of the sub-patterns are not tested.
(Note that there must be at least two sub-patterns.
until one of them succeeds. In that case, @code{or} likewise matches,
and the rest of the sub-patterns are not tested. (Note that there
must be at least two sub-patterns.
Simply @w{@code{(or @var{pattern1})}} signals error.)
@c Issue: Is this correct and intended?
@c Are there exceptions, qualifications?
@ -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}.
@dfn{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}.
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
@node Destructuring patterns
@subsection Destructuring Patterns
@cindex destructuring patterns
@node Destructuring with pcase Patterns
@subsection Destructuring with @code{pcase} Patterns
@cindex 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,
@code{pcase} 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}.
@dfn{Destructuring} 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
@dfn{destructuring}. Using @code{pcase} patterns allows to perform
@dfn{destructuring 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
@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}.
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
@ref{seq-let}.
@defmac pcase-let bindings body@dots{}
Bind variables according to @var{bindings} and then eval @var{body}.
Perform destructuring binding of variables according to
@var{bindings}, and then evaluate @var{body}.
@var{bindings} is a list of bindings of the form @w{@code{(@var{pattern}
@var{exp})}}, where @var{exp} is an expression to evaluate and
@var{pattern} is a destructuring pattern.
@var{pattern} 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
@var{pattern} to the values of the corresponding elements of the
evaluated @var{exp}.
@end defmac
@defmac pcase-let* bindings body@dots{}
Bind variables according to @var{bindings} and then eval @var{body}.
Perform destructuring binding of variables according to
@var{bindings}, 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
@var{pattern} is a destructuring pattern.
@var{pattern} 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 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}.
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
@var{exp}s of the @var{bindings} that follow it, additionally to
being available in @var{body}.
@end defmac
@findex dolist
@defmac pcase-dolist (pattern list) body@dots{}
This construct executes @var{body} once for each element of
@var{list}, 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
@var{pattern} to the values of the corresponding subfields of the
element of @var{list}. The bindings are performed as if by
@code{pcase-let}. When @var{pattern} is a simple variable, this ends
up being equivalent to @code{dolist} (@pxref{Iteration}).
@end defmac

16
doc/lispref/elisp.texi
View file

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

10
doc/lispref/frames.texi
View file

@ -3261,11 +3261,11 @@ and should be preferred when specifying a non-@code{nil}
@code{drag-with-mode-line} parameter.
When a child frame is used for displaying a buffer via
@code{display-buffer-in-child-frame} (@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.
@code{display-buffer-in-child-frame} (@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}

20
doc/lispref/sequences.texi
View file

@ -1049,15 +1049,18 @@ that @var{sequence} can be a list, vector or string. This is
primarily useful for side-effects.
@end defmac
@defmac seq-let arguments sequence body@dots{}
@anchor{seq-let}
@defmac seq-let var-sequence val-sequence body@dots{}
@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
@var{var-sequence} 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
@code{sequence}.
The @var{var-sequence} sequence can also include the @code{&rest}
marker followed by a variable name to be bound to the rest of
@var{val-sequence}.
@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

1481
doc/lispref/windows.texi
View file

File diff suppressed because it is too large Load diff

43
lisp/emacs-lisp/pcase.el
View file

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