From: Philip Kaludercic <philipk@posteo.net>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: master c3ab8f1: Improve buffer-match-p documentation
Date: Sat, 16 Apr 2022 23:11:59 +0000 [thread overview]
Message-ID: <87bkx0ipxc.fsf@posteo.net> (raw)
In-Reply-To: <837d7p1eer.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 16 Apr 2022 14:00:28 +0300")
[-- Attachment #1: Type: text/plain, Size: 2247 bytes --]
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: emacs-devel@gnu.org
>> Date: Sat, 16 Apr 2022 09:53:26 +0000
>>
>> Eli Zaretskii <eliz@gnu.org> writes:
>>
>> >> +** New function 'buffer-match-p'
>> >> +Check if a buffer matches a condition, specified using a DSL.
>> >
>> > A "DSL"? what's that? We don't have that acronym anywhere else in
>> > Emacs, AFAICS. Please make that entry more self-explanatory.
>>
>> It is supposed to mean "Domain Specific Language". I never noticed that
>> it wasn't used anywhere else, so sorry about that. Then again I wasn't
>> sure how else to put it. What about
>>
>> Can be used to check if buffers satisfy a possibly complex
>> condition, [giving a few examples]
>
> Just "satisfies some conditions" (with examples) should be fine, IMO.
>
>> > Since buffer-match-p is not documented in the manual, I think this
>> > change is for the worse, as it leaves CONDITIONS undocumented. Or am
>> > I missing something?
>>
>> No, I haven't written that yet. This should best be documented in
>> lispref/buffers.texi, right?
>
> Probably in "Buffer List", yes.
>
>> >> -(defun display-buffer-assq-regexp (buffer-name alist action)
>> >> +(defun display-buffer-assq-regexp (buffer-or-name alist action)
>> >> "Retrieve ALIST entry corresponding to BUFFER-NAME.
>> >> -This returns the cdr of the alist entry ALIST if either its key
>> >> -satisfied a BUFFER-NAME per `buffer-match'. ACTION should have
>> >> -the form of the action argument passed to `display-buffer'."
>> >> +This returns the cdr of the alist entry ALIST if key and
>> >> +buffer-or-name satisfy `buffer-match-p'. ACTION should have the
>> >> +form of the action argument passed to `display-buffer'."
>> >
>> > I fixed some minor issues with the modified doc string, but that still
>> > leaves one question unanswered: what does this function return if no
>> > alist entry satisfies buffer-match-p? That should be documented.
>>
>> ... If no entry is found, nil is returned?
>
> That's fine, but please avoid passive tense. Something like
>
> If no matching entry is found in ALIST, return nil.
Before I push something I should fix, I'll attach my proposed changes
here:
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Further-improve-buffer-match-p-related-documentation.patch --]
[-- Type: text/x-diff, Size: 4064 bytes --]
From 4aa5fecf89d0aae084eb12ba5b2651b6fd9dc991 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Sun, 17 Apr 2022 01:11:06 +0200
Subject: [PATCH] Further improve buffer-match-p related documentation
* 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.
---
doc/lispref/buffers.texi | 41 ++++++++++++++++++++++++++++++++++++++++
etc/NEWS | 6 +++++-
lisp/window.el | 3 ++-
3 files changed, 48 insertions(+), 2 deletions(-)
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 1fe5a60b35..0004f255fe 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -953,6 +953,47 @@ Buffer List
infinite recursion.
@end defvar
+@defun buffer-match-p condition buffer-or-name arg
+This function can be used to check if a buffer designated by
+@code{buffer-or-name} satisfies a @code{condition}. An optional third
+argument @code{arg} can be passed on to predicate functions. A
+predicate can be one of the following:
+@itemize @bullet{}
+@item
+A string containing a regular expression. The buffer satisfies the
+predicate if the regular expression matches the buffer name.
+@item
+A function that is passed the buffer, and is satisfied if the function
+returns a non-nil value. The first argument is always the buffer, and
+if the function accepts two arguments (as per @code{func-arity}), the
+third argument to @code{buffer-match-p} will be passed on to the
+predicate function.
+@item
+A cons-cell @code{(TYPE . DATA)} where @code{TYPE} is one of
+@table @code
+@item not
+Satisfied if @code{DATA} doesn't satisfy @code{buffer-match-p} with
+the same buffer and @code{arg}.
+@item or
+Satisfied if @code{DATA} is a list and @emph{any} condition if
+@code{DATA} satisfies @code{buffer-match-p}, with the same buffer and
+@code{arg}.
+@item and
+Satisfied if @code{DATA} is a list and @emph{all} condition if
+@code{DATA} satisfies @code{buffer-match-p}, with the same buffer and
+@code{arg}.
+@end table
+@end itemize
+@end defun
+
+@defun match-buffers condition 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. Optionally, a third argument
+@code{arg} is passed on to @code{buffer-match-p}.
+@end defun
+
@node Creating Buffers
@section Creating Buffers
@cindex creating buffers
diff --git a/etc/NEWS b/etc/NEWS
index 14d970fe11..fb26ca64f8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1493,7 +1493,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
diff --git a/lisp/window.el b/lisp/window.el
index ea90995541..b7503ac999 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -7499,7 +7499,8 @@ display-buffer-assq-regexp
"Retrieve ALIST entry corresponding to BUFFER-NAME.
This returns the cdr of the alist entry ALIST if key and
buffer-or-name satisfy `buffer-match-p'. ACTION should have the
-form of the action argument passed to `display-buffer'."
+form of the action argument passed to `display-buffer'.
+If no matching entry is found in ALIST, return nil."
(catch 'match
(dolist (entry alist)
(when (buffer-match-p (car entry) buffer-or-name action)
--
2.30.2
[-- Attachment #3: Type: text/plain, Size: 24 bytes --]
--
Philip Kaludercic
next prev parent reply other threads:[~2022-04-16 23:11 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-04-16 8:26 master c3ab8f1: Improve buffer-match-p documentation Eli Zaretskii
2022-04-16 9:53 ` Philip Kaludercic
2022-04-16 11:00 ` Eli Zaretskii
2022-04-16 23:11 ` Philip Kaludercic [this message]
2022-04-17 6:42 ` Eli Zaretskii
2022-04-17 8:48 ` Philip Kaludercic
2022-04-17 11:30 ` Eli Zaretskii
2022-04-17 9:02 ` Philip Kaludercic
2022-04-17 11:31 ` Eli Zaretskii
2022-04-17 12:06 ` Philip Kaludercic
-- strict thread matches above, loose matches on Subject: below --
2022-04-16 8:34 Eli Zaretskii
2022-04-16 8:40 Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87bkx0ipxc.fsf@posteo.net \
--to=philipk@posteo.net \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.