From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Matt Armstrong Newsgroups: gmane.emacs.bugs Subject: bug#52202: [PATCH] try-completion, all-completions support for a list of strings COLLECTION is not documented in their docstrings Date: Tue, 30 Nov 2021 11:18:05 -0800 Message-ID: <871r2xjvv6.fsf@rfc20.org> References: <875ys9k2a7.fsf@rfc20.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="37950"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) To: bug#52202 <52202@debbugs.gnu.org> Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Nov 30 20:19:10 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1ms8ej-0009dd-Th for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 30 Nov 2021 20:19:10 +0100 Original-Received: from localhost ([::1]:42272 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ms8eh-00048e-VB for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 30 Nov 2021 14:19:07 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:43710) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ms8ec-00048O-6K for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2021 14:19:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:59229) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ms8eb-0004L2-UK for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2021 14:19:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ms8eb-0001p8-Jq for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2021 14:19:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Matt Armstrong Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 30 Nov 2021 19:19:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52202 X-GNU-PR-Package: emacs Original-Received: via spool by 52202-submit@debbugs.gnu.org id=B52202.16382998986942 (code B ref 52202); Tue, 30 Nov 2021 19:19:01 +0000 Original-Received: (at 52202) by debbugs.gnu.org; 30 Nov 2021 19:18:18 +0000 Original-Received: from localhost ([127.0.0.1]:42542 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ms8dt-0001nu-DM for submit@debbugs.gnu.org; Tue, 30 Nov 2021 14:18:17 -0500 Original-Received: from relay11.mail.gandi.net ([217.70.178.231]:45825) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ms8dr-0001nf-0N for 52202@debbugs.gnu.org; Tue, 30 Nov 2021 14:18:16 -0500 Original-Received: (Authenticated sender: matt@rfc20.org) by relay11.mail.gandi.net (Postfix) with ESMTPSA id 417FE10000A for <52202@debbugs.gnu.org>; Tue, 30 Nov 2021 19:18:07 +0000 (UTC) Original-Received: from matt by naz with local (Exim 4.95) (envelope-from ) id 1ms8dh-000HOV-1W for 52202@debbugs.gnu.org; Tue, 30 Nov 2021 11:18:05 -0800 In-Reply-To: bug's message of "Tue, 30 Nov 2021 19:06:51 +0000" X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:221165 Archived-At: --=-=-= Content-Type: text/plain Attached is a docstring patch against the emacs-28 branch for this issue. Note/question: I wonder if the `all-completions' docstring should refer to `try-completion' rather than copy much of the text. The same approach works well in the lisp ref manual, I think. --=-=-= Content-Type: text/x-diff; charset=utf-8 Content-Disposition: inline; filename=0001-Improve-the-try-completion-and-all-completions-docst.patch Content-Transfer-Encoding: quoted-printable >From 8bc1bee134f0626513efd00f4a283cf5a2d2a359 Mon Sep 17 00:00:00 2001 From: Matt Armstrong Date: Tue, 30 Nov 2021 10:54:17 -0800 Subject: [PATCH] Improve the `try-completion' and `all-completions' docstri= ngs * src/minibuf.c (Ftry_completion): (Fall_completions): Use language from the Emacs lisp manual when talking about the COLLECTION and PREDICATE arguments. Most notably, the way completion tables may be passed is now more clear. The prior docstring did not mention lists of strings/symbols at all. Bug#52202 --- src/minibuf.c | 124 +++++++++++++++++++++++++++++++------------------- 1 file changed, 77 insertions(+), 47 deletions(-) diff --git a/src/minibuf.c b/src/minibuf.c index 6c0cd358c5..f1ee7b2453 100644 --- a/src/minibuf.c +++ b/src/minibuf.c @@ -1569,34 +1569,49 @@ match_regexps (Lisp_Object string, Lisp_Object rege= xps, DEFUN ("try-completion", Ftry_completion, Stry_completion, 2, 3, 0, doc: /* Return common substring of all completions of STRING in COL= LECTION. Test each possible completion specified by COLLECTION -to see if it begins with STRING. The possible completions may be -strings or symbols. Symbols are converted to strings before testing, -see `symbol-name'. -All that match STRING are compared together; the longest initial sequence -common to all these matches is the return value. -If there is no match at all, the return value is nil. -For a unique match which is exact, the return value is t. - -If COLLECTION is an alist, the keys (cars of elements) are the -possible completions. If an element is not a cons cell, then the -element itself is the possible completion. -If COLLECTION is a hash-table, all the keys that are strings or symbols -are the possible completions. -If COLLECTION is an obarray, the names of all symbols in the obarray -are the possible completions. +to see if it begins with STRING. =20 -COLLECTION can also be a function to do the completion itself. -It receives three arguments: the values STRING, PREDICATE and nil. +All completions that match STRING are compared together; the longest +initial sequence common to all these matches is the return value. If +there is no match at all, the return value is nil. For a unique match +which is exact, the return value is t. + +COLLECTION is called the "completion table." Its value must be a +list, a hash table, an obarray, or a completion function. + +If COLLECTION is a list, the possible completions are specified by the +elements of the list, each of which should be either a string, a +symbol, or a cons cell whose CAR is either a string or a symbol. If +the list contains elements of any other type, those are ignored. + +If COLLECTION is a hash-table, all the keys that are strings or +symbols are the possible completions. + +If COLLECTION is an obarray, all the symbols in the obarray are the +possible completions. + +The possible completions from COLLECTION that are symbols are +converted to strings before testing, see `symbol-name'. + +COLLECTION can also be a function to do the completion itself. It +receives three arguments: the values STRING, PREDICATE and nil (the +third argument is so that the same function can be used in +=E2=80=98all-completions=E2=80=99 and do the appropriate thing in either c= ase). Whatever it returns becomes the value of `try-completion'. =20 -If optional third argument PREDICATE is non-nil, -it is used to test each possible match. -The match is a candidate only if PREDICATE returns non-nil. -The argument given to PREDICATE is the alist element -or the symbol from the obarray. If COLLECTION is a hash-table, -predicate is called with two arguments: the key and the value. -Additionally to this predicate, `completion-regexp-list' -is used to further constrain the set of candidates. */) +If optional third argument PREDICATE is non-nil, it is used to test +each possible match. The match is a candidate only if PREDICATE +returns non-nil. The argument given to PREDICATE is an element from +COLLECTION. If COLLECTION is a list it is a list element (either a +symbol, string, or cons cell whose CAR is a symbol or string). If +COLLECTION is an obarray, a symbol from it. If COLLECTION is a +hash-table, predicate is called with two arguments: a key and the +value. + +In addition, to be acceptable, a completion must also match all the +regular expressions in =E2=80=98completion-regexp-list=E2=80=99. (Unless = COLLECTION +is a function, in which case that function has to handle +=E2=80=98completion-regexp-list=E2=80=99 itself.) */) (Lisp_Object string, Lisp_Object collection, Lisp_Object predicate) { =20 @@ -1808,31 +1823,46 @@ DEFUN ("try-completion", Ftry_completion, Stry_comp= letion, 2, 3, 0, DEFUN ("all-completions", Fall_completions, Sall_completions, 2, 4, 0, doc: /* Search for partial matches to STRING in COLLECTION. Test each of the possible completions specified by COLLECTION -to see if it begins with STRING. The possible completions may be -strings or symbols. Symbols are converted to strings before testing, -see `symbol-name'. -The value is a list of all the possible completions that match STRING. - -If COLLECTION is an alist, the keys (cars of elements) are the -possible completions. If an element is not a cons cell, then the -element itself is the possible completion. -If COLLECTION is a hash-table, all the keys that are strings or symbols -are the possible completions. -If COLLECTION is an obarray, the names of all symbols in the obarray -are the possible completions. +to see if it begins with STRING. +The value is a list of strings for all the possible completions that +match STRING. =20 -COLLECTION can also be a function to do the completion itself. -It receives three arguments: the values STRING, PREDICATE and t. +COLLECTION is called the "completion table." Its value must be a +list, a hash table, an obarray, or a completion function. + +If COLLECTION is a list, the permissible completions are specified by +the elements of the list, each of which should be either a string, a +symbol, or a cons cell whose CAR is either a string or a symbol. If +the list contains elements of any other type, those are ignored. + +If COLLECTION is a hash-table, all the keys that are strings or +symbols are the possible completions. + +If COLLECTION is an obarray, all the symbols in the obarray are the +possible completions. + +The possible completions from COLLECTION that are symbols are +converted to strings before testing, see `symbol-name'. + +COLLECTION can also be a function to do the completion itself. It +receives three arguments: the values STRING, PREDICATE and t (the +third argument is so that the same function can be used in +=E2=80=98try-completion=E2=80=99 and do the appropriate thing in either ca= se). Whatever it returns becomes the value of `all-completions'. =20 -If optional third argument PREDICATE is non-nil, -it is used to test each possible match. -The match is a candidate only if PREDICATE returns non-nil. -The argument given to PREDICATE is the alist element -or the symbol from the obarray. If COLLECTION is a hash-table, -predicate is called with two arguments: the key and the value. -Additionally to this predicate, `completion-regexp-list' -is used to further constrain the set of candidates. +If optional third argument PREDICATE is non-nil, it is used to test +each possible match. The match is a candidate only if PREDICATE +returns non-nil. The argument given to PREDICATE is an element from +COLLECTION. If COLLECTION is a list it is a list element (either a +symbol, string, or cons cell whose CAR is a symbol or string). If +COLLECTION is an obarray, a symbol from it. If COLLECTION is a +hash-table, predicate is called with two arguments: a key and the +value. + +In addition, to be acceptable, a completion must also match all the +regular expressions in =E2=80=98completion-regexp-list=E2=80=99. (Unless = COLLECTION +is a function, in which case that function has to handle +=E2=80=98completion-regexp-list=E2=80=99 itself.) =20 An obsolete optional fourth argument HIDE-SPACES is still accepted for backward compatibility. If non-nil, strings in COLLECTION that start --=20 2.33.0 --=-=-=--