From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#34794: 26.1; doc of `read-buffer' Date: Sat, 9 Mar 2019 14:32:22 -0800 (PST) Message-ID: References: <<>> <<<831s3g7zv1.fsf@gnu.org>>> <> <<83r2bf7w21.fsf@gnu.org>> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="40364"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 34794@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Mar 09 23:33:10 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1h2kWk-000AMK-Ga for geb-bug-gnu-emacs@m.gmane.org; Sat, 09 Mar 2019 23:33:10 +0100 Original-Received: from localhost ([127.0.0.1]:36327 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h2kWj-0003iq-GG for geb-bug-gnu-emacs@m.gmane.org; Sat, 09 Mar 2019 17:33:09 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:57521) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h2kWd-0003gt-93 for bug-gnu-emacs@gnu.org; Sat, 09 Mar 2019 17:33:04 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h2kWc-0000b3-8M for bug-gnu-emacs@gnu.org; Sat, 09 Mar 2019 17:33:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:52180) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h2kWc-0000aw-3q for bug-gnu-emacs@gnu.org; Sat, 09 Mar 2019 17:33:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1h2kWc-00058V-0D for bug-gnu-emacs@gnu.org; Sat, 09 Mar 2019 17:33:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 09 Mar 2019 22:33:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 34794 X-GNU-PR-Package: emacs Original-Received: via spool by 34794-submit@debbugs.gnu.org id=B34794.155217075419703 (code B ref 34794); Sat, 09 Mar 2019 22:33:01 +0000 Original-Received: (at 34794) by debbugs.gnu.org; 9 Mar 2019 22:32:34 +0000 Original-Received: from localhost ([127.0.0.1]:37489 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h2kWA-00057j-6r for submit@debbugs.gnu.org; Sat, 09 Mar 2019 17:32:34 -0500 Original-Received: from userp2120.oracle.com ([156.151.31.85]:39738) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h2kW7-00057V-RL for 34794@debbugs.gnu.org; Sat, 09 Mar 2019 17:32:33 -0500 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x29MTvlA137367; Sat, 9 Mar 2019 22:32:25 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=jm4ioGczLAAN1hWb1TuDVZAIDyGHevzVRP1/jGPi9iQ=; b=HqQrOiZFNWrTq4B4n9sPvqt+2r7CejV4sQgj2o/qSv7gM+tIYx4kruhyi4Itw5eI9ZpP nLCEKMUXTeoEJHDdM3HJpyZpeuZBGqJzA0TSvX/5OZgcwPTNQlgUR9p1O6sPBdkvHnsY eSeS5ibGVkxkENoXPpT66QlSyswtPHuZlnKJnZ/iSz5SOOiRUJ24x9A+m9xMmNin8GUR baCAmecjOXwxh7tpf4l6sn0nJ+my4yLQg71yigBUQrlaxHhQ89n2R1ymlP81aPlZV+AC Kqhep6qcqSys+wN/57RycbMPN62SvMJk1nJ8DDjXzQaBMTycpdlYugCxtMAnwZ7kcjjl aw== Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp2120.oracle.com with ESMTP id 2r464r1hww-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sat, 09 Mar 2019 22:32:25 +0000 Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id x29MWO9n018906 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sat, 9 Mar 2019 22:32:24 GMT Original-Received: from abhmp0014.oracle.com (abhmp0014.oracle.com [141.146.116.20]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id x29MWNh2029669; Sat, 9 Mar 2019 22:32:23 GMT In-Reply-To: <<83r2bf7w21.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4810.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=9190 signatures=668685 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1903090171 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:156205 Archived-At: > > > > AFAICT neither the doc string nor the Elisp manual states what the > > > > default value is if argument DEF is nil. IOW, what is the default > > > > buffer name if no explicit default is provided? It seems (without > > > > thorough testing) to be the value of `(buffer-name (current-buffer)= )'. > > > > > > No, it's an empty string, and I think the doc string already conveys > > > that. > > > > I cannot tell from the doc string that the default value, > > i.e., the value returned when DEF is nil, is the empty > > string. >=20 > Optional second arg DEF is value to return if user enters an empty line= . >=20 > Doesn't this say that when DEF is omitted the function will return > that empty line? No, it doesn't. If DEF is omitted it is nil. Is nil the "value to return if user enters an empty line?" I don't think so.=20 `RET' with empty input can result in anything one likes as default value. And other input-reading functions do so. There is nothing here that says that empty input results in the empty string being returned. > > > (Note that if read-buffer-function is non-nil, what happens > > > then is entirely up to that function, which doesn't make it easy to > > > say exactly how DEF is handled.) > > > > It's not hard to state what the default DEF behavior > > is, and then later say that if `read-buffer-function' > > is non-nil then the use of the other args is up to it, > > i.e., not necessarily as described above. This is > > not unusual for a function that optionally accepts a > > function arg as one possibility. >=20 > Please suggest such a text, because I definitely don't see an easy way > of saying that, without triggering more bug reports like this one. 1. OK. How about this? Read the name of a buffer with completion and return it as a string. If option `read-buffer-function' is non-nil then it is a function that accepts all of the `read-buffer' arguments, in order, and returns a buffer name. That buffer name is returned by `read-buffer'. Otherwise, prompt with first arg PROMPT, a string that should end with a colon followed by a space char (`: '). Other args control the read behavior, as follows. Optional arg DEFAULT determines the return value if user input is empty (just `RET' with no minibuffer input): * If a non-nil list then return its first element. * If absent or nil then return the empty string, \"\". * If anything else then return it (DEFAULT). Non-nil optional arg REQUIRE-MATCH means allow only names of existing buffers as input. It is the same as for 'completing-read'. The names of all existing (live) buffers are completion candidates. Non-nil optional arg PREDICATE should be a function that accepts a buffer or buffer name as its first argument. It filters the list of candidate buffers, excluding any buffers for which it returns nil. Non-nil option `read-buffer-completion-ignore-case' means that buffer-name completion ignores case while reading the buffer name. [If you prefer, the description of the use of `read-buffer-function' could be moved to the end. I think it is probably better where it is. It definitely should not be put in the middle of descriptions of the arguments, IMO.] 2. I guessed wrt REQUIRE-MATCH, regarding which buffer names are completion candidates. 3. I also had to guess wrt PREDICATE, as the current doc does not say what is acceptable as an argument (buffer? buffer name?), and it doesn't say which way the predicate works as a filter: keeping things that satisfy it or excluding them. I guessed that it works with either a buffer or its name, and I guessed that it keeps things that satisfy it.=20 4. There appears to be a fairly large bug in the behavior, BTW. The function is supposed to return a buffer name, which is presumably a string. But try this, hitting `RET' with empty minibuffer input: (read-buffer "b: " (selected-window) t) That returns a window! And this returns a number, not a numeric string: (read-buffer "b: " 42 t) It apparently can return anything at all. This is in spite of the fact that the REQUIRE-MATCH arg is `t', and according to the doc that should mean that you cannot exit the minibuffer unless the input corresponds to an existing buffer. Is that the behavior we want? That's the behavior I documented, above. Do you prefer a separate bug report for this bug, or can you fix it based on this report? 5. Other doc-string bugs (fixed in my suggestion): * Doesn't say that it reads with completion. (You can guess that, when you read some of the argument descriptions - it mentions completion only in passing.) * Doesn't say in what way REQUIRE-MATCH "determines whether non-existing buffer names are allowed". It refers to `completing-read', but that says nothing about existing buffers - that says only that WHATEVER the set of candidates, you cannot exit the minibuffer without matching one of them. * Arguments are described out of order. * Arg PREDICATE is described after the statement about `read-buffer-function'. =20