From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Phil Hagelberg Newsgroups: gmane.emacs.devel Subject: Changes to completing-read Date: Sat, 18 Oct 2008 21:31:21 -0700 Message-ID: <87myh1dx46.fsf@hagelb.org> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1224390699 9745 80.91.229.12 (19 Oct 2008 04:31:39 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 19 Oct 2008 04:31:39 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Oct 19 06:32:43 2008 connect(): Connection refused Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1KrPy5-00036i-S6 for ged-emacs-devel@m.gmane.org; Sun, 19 Oct 2008 06:32:42 +0200 Original-Received: from localhost ([127.0.0.1]:46003 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1KrPx0-0008IS-9o for ged-emacs-devel@m.gmane.org; Sun, 19 Oct 2008 00:31:34 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1KrPwv-0008IL-KB for emacs-devel@gnu.org; Sun, 19 Oct 2008 00:31:29 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1KrPwt-0008I9-90 for emacs-devel@gnu.org; Sun, 19 Oct 2008 00:31:28 -0400 Original-Received: from [199.232.76.173] (port=34258 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1KrPwt-0008I6-2J for emacs-devel@gnu.org; Sun, 19 Oct 2008 00:31:27 -0400 Original-Received: from sd-green-bigip-66.dreamhost.com ([208.97.132.66]:47482 helo=spunkymail-a17.g.dreamhost.com) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1KrPws-0000IR-IU for emacs-devel@gnu.org; Sun, 19 Oct 2008 00:31:26 -0400 Original-Received: from dynabook (96-26-232-193.sea.clearwire-dns.net [96.26.232.193]) by spunkymail-a17.g.dreamhost.com (Postfix) with ESMTP id 34C29734B0 for ; Sat, 18 Oct 2008 21:31:21 -0700 (PDT) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.0.60 (gnu/linux) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:104624 Archived-At: I've been building a couple tools that use the completing-read function for more advanced completions, and I've got some questions about how it behaves when a function is passed as the "collection" argument. >From the completing-read docstring: > collection can also be a function to do the completion itself. > predicate limits completion to a subset of collection. > See `try-completion' and `all-completions' for more details > on completion, collection, and predicate. It looks like the function gets called four times when the user presses TAB, and the only difference between the four calls is the last argument. t, nil, 'lambda, and the cons (boundaries . "") are passed. According to the docstrings of try-completion and all-completions, t and nil should be passed to the collection function when those two functions get called as part of the completion process somehow. But I have no idea where 'lambda or (boundaries . "") are coming from. >From the try-completion docstring: > Return common substring of all completions of string in collection. > Test each possible completion specified by collection > to see if it begins with string. >From the all-completions docstring: > Search for partial matches to string in collection. > Test each of the possible completions specified by collection > to see if it begins with string. It's rather unclear from the docstrings, but from what I can piece together, the "collection" function should act totally differently based on the value of the third argument. So it seems there are really three problems: * The description overall behaviour of the "collection" function is spread out over three separate docstrings and is even then not very clear. * One function (collection) is supposed to perform four distinct tasks based on the value of one of its arguments. (Though this is probably justified for backwards-compatibility reasons; seems fairly understandable.) * Only two of the four tasks that the function is supposed to perform are documented at all. Is this accurate? Could someone explain the meaning of the mystery arguments? I would like to submit a documentation patch, but I feel that my understanding of the subject is very sketchy, and the implementation is in C, so I can't just dive in and understand it. thanks, Phil