procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Further improve buffer-match-p related documentation

Browse source 
* doc/lispref/buffers.texi (Buffer List): Add entries for
* buffer-match-p and match-buffers
* etc/NEWS: Give examples for buffer-match-p conditions
* lisp/window.el (display-buffer-assq-regexp): Mention what happens
when no entry in the alist satisfies a condition.
This commit is contained in:
Philip Kaludercic 2022-04-17 01:11:06 +02:00
parent 5be9a9cacf
commit b5f70c239e
2 changed files with 52 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
doc/lispref/buffers.texi
View file

@ -953,15 +953,59 @@ with a @code{nil} @var{norecord} argument since this may lead to
infinite recursion.
@end defvar
@defun buffer-match-p condition buffer-or-name &optional arg
This function checks if a buffer designated by @code{buffer-or-name}
satisfies a @code{condition}. Optional third argument @var{arg} is
passed to the predicate function in @var{condition}. A condition can
be one of the following:
@itemize @bullet{}
@item
A string, interpreted as a regular expression. The buffer
satisfies the condition if the regular expression matches the buffer
name.
@item
A predicate function, which should return non-@code{nil} if the buffer
matches. If the function expects one argument, it is called with
@var{buffer-or-name} as the argument; if it expects 2 arguments, the
first argument is @var{buffer-or-name} and the second is @var{arg}
(or @code{nil} if @var{arg} is omitted).
@item
A cons-cell @code{(@var{oper} . @var{expr})} where @var{oper} is one
of
@table @code
@item not
Satisfied if @var{expr} doesn't satisfy @code{buffer-match-p} with
the same buffer and @code{arg}.
@item or
Satisfied if @var{oper} is a list and @emph{any} condition if
@var{expr} satisfies @code{buffer-match-p}, with the same buffer and
@code{arg}.
@item and
Satisfied if @var{oper} is a list and @emph{all} condition if
@var{expr} satisfies @code{buffer-match-p}, with the same buffer and
@code{arg}.
@end table
@end itemize
@end defun
@defun match-buffers condition &optional buffer-list arg
This function returns a list of all buffers that satisfy a
@code{condition}, as defined for @code{buffer-match-p}. By default
all buffers are considered, but this can be restricted via the second
optional @code{buffer-list} argument. Optional third argument
@var{arg} will be used by @var{condition} in the same way as
@code{buffer-match-p} does.
@end defun
@node Creating Buffers
@section Creating Buffers
@cindex creating buffers
@cindex buffers, creating
This section describes the two primitives for creating buffers.
@code{get-buffer-create} creates a buffer if it finds no existing buffer
with the specified name; @code{generate-new-buffer} always creates a new
buffer and gives it a unique name.
@code{get-buffer-create} creates a buffer if it finds no existing
buffer with the specified name; @code{generate-new-buffer} always
creates a new buffer and gives it a unique name.
Both functions accept an optional argument @var{inhibit-buffer-hooks}.
If it is non-@code{nil}, the buffer they create does not run the hooks

6
etc/NEWS
View file

@ -1548,7 +1548,11 @@ This hook is run before 'x-popup-menu' is about to display a
deck-of-cards menu on screen.
** New function 'buffer-match-p'
Check if a buffer matches a condition, specified using a DSL.
Check if a buffer satisfies some condition. Some examples for
conditions can be regular expressions that match a buffer name, a
cons-cell like (major-mode . shell-mode) that matches any buffer where
major-mode is shell-mode or a combined with a condition like (and
"\\`\\*.+\\*\\'" (major-mode . special-mode)).
** New function 'match-buffers'
Use 'buffer-match-p' to gather a list of buffers that match a