From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.devel Subject: Re: master c3ab8f1: Improve buffer-match-p documentation Date: Sat, 16 Apr 2022 23:11:59 +0000 Message-ID: <87bkx0ipxc.fsf@posteo.net> References: <83fsmd1lje.fsf@gnu.org> <87sfqdicbt.fsf@posteo.net> <837d7p1eer.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="11797"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Apr 17 01:13:02 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nfrbC-0002tp-Dm for ged-emacs-devel@m.gmane-mx.org; Sun, 17 Apr 2022 01:13:02 +0200 Original-Received: from localhost ([::1]:36604 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nfrbB-0006dA-9c for ged-emacs-devel@m.gmane-mx.org; Sat, 16 Apr 2022 19:13:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:46784) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nfraJ-0005w9-Bi for emacs-devel@gnu.org; Sat, 16 Apr 2022 19:12:07 -0400 Original-Received: from mout01.posteo.de ([185.67.36.65]:33269) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nfraG-0002Qy-Gd for emacs-devel@gnu.org; Sat, 16 Apr 2022 19:12:07 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 6237A240027 for ; Sun, 17 Apr 2022 01:12:01 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1650150721; bh=HhkD2FFG21UlLXul0Y2G7gdEDeFVIaS6WLMIxEYKMks=; h=From:To:Cc:Subject:Autocrypt:Date:From; b=IxpYjSzFqmct14vRrVfXNwhW9+3LoLLDlqa4JlqZ6oSXLjBQxmYVkNG9mRP2dhGpn F5JjAOyM+NmBfMP9fsAK3V9SlBYIYZ7p29JmM3FLzykjXGGvRXkd5tNzPZJTVhVkKW 1KpEdxTIMp12Jwgzhj6PEUWMp+2pw/i4u8xg+XFQOOtX/ZSwITID17xmzbpc38sy5s yA5mog+e0cpMkGFYYNLZsQhsCzCSKwMQZmD1BWk+mqYUknMFwoGNfWaAgHyZLyIjfd 9FRNRhObeq8rXCMAwX6qn13M4X5RCv3DWjiMirqCxH7ZdqOfIaYcOAWW62k3JlOwqJ iRcDEG4+oUsEw== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4Kgpqh5TPCz9rxG; Sun, 17 Apr 2022 01:12:00 +0200 (CEST) Autocrypt: addr=philipk@posteo.net; prefer-encrypt=nopreference; keydata= mDMEYHHqUhYJKwYBBAHaRw8BAQdAp3GdmYJ6tm5McweY6dEvIYIiry+Oz9rU4MH6NHWK0Ee0QlBo aWxpcCBLYWx1ZGVyY2ljIChnZW5lcmF0ZWQgYnkgYXV0b2NyeXB0LmVsKSA8cGhpbGlwa0Bwb3N0 ZW8ubmV0PoiQBBMWCAA4FiEEDM2H44ZoPt9Ms0eHtVrAHPRh1FwFAmBx6lICGwMFCwkIBwIGFQoJ CAsCBBYCAwECHgECF4AACgkQtVrAHPRh1FyTkgEAjlbGPxFchvMbxzAES3r8QLuZgCxeAXunM9gh io0ePtUBALVhh9G6wIoZhl0gUCbQpoN/UJHI08Gm1qDob5zDxnIHuDgEYHHqUhIKKwYBBAGXVQEF AQEHQNcRB+MUimTMqoxxMMUERpOR+Q4b1KgncDZkhrO2ql1tAwEIB4h4BBgWCAAgFiEEDM2H44Zo Pt9Ms0eHtVrAHPRh1FwFAmBx6lICGwwACgkQtVrAHPRh1Fw1JwD/Qo7kvtib8jy7puyWrSv0MeTS g8qIxgoRWJE/KKdkCLEA/jb9b9/g8nnX+UcwHf/4VfKsjExlnND3FrBviXUW6NcB In-Reply-To: <837d7p1eer.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 16 Apr 2022 14:00:28 +0300") Received-SPF: pass client-ip=185.67.36.65; envelope-from=philipk@posteo.net; helo=mout01.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:288514 Archived-At: --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> From: Philip Kaludercic >> Cc: emacs-devel@gnu.org >> Date: Sat, 16 Apr 2022 09:53:26 +0000 >> >> Eli Zaretskii 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: --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=0001-Further-improve-buffer-match-p-related-documentation.patch >From 4aa5fecf89d0aae084eb12ba5b2651b6fd9dc991 Mon Sep 17 00:00:00 2001 From: Philip Kaludercic 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 --=-=-= Content-Type: text/plain -- Philip Kaludercic --=-=-=--