From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: What's missing in ELisp that makes people want to use cl-lib? Date: Fri, 17 Nov 2023 08:56:14 +0200 Message-ID: <83cyw8q35d.fsf@gnu.org> References: <8734xetjkk.fsf@yahoo.com> <87cywhsrcf.fsf@yahoo.com> <87cywgx1z0.fsf@web.de> <83wmuowwp3.fsf@gnu.org> <8334xcwank.fsf@gnu.org> <320999cc-6c83-2315-0044-cc0403400af3@gutov.dev> <9ab5d2bd-a648-cae0-a4a7-ae86be10af0f@gutov.dev> <87r0kuqxbf.fsf@gmail.com> <54e115a2-fc36-3056-a030-0dbf32416ddb@gutov.dev> <43f290b0-4119-597b-c89a-0fb4c7db1665@gutov.dev> <87bkbtn79k.fsf@web.de> <87wmuhpxxv.fsf@gmail.com> <87v8a1lodp.fsf@web.de> <83msvdps4k.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="20833"; mail-complaints-to="usenet@ciao.gmane.io" Cc: michael_heerdegen@web.de, emacs-devel@gnu.org To: =?utf-8?B?Sm/Do28gVMOhdm9yYQ==?= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Nov 17 07:56:44 2023 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 1r3smS-0005CW-Hr for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Nov 2023 07:56:44 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r3sm5-0002n3-7h; Fri, 17 Nov 2023 01:56:21 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r3sm4-0002mt-BT for emacs-devel@gnu.org; Fri, 17 Nov 2023 01:56:20 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r3sm3-0001m3-Tj; Fri, 17 Nov 2023 01:56:19 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=xfkE0YQV67cvgnCj0kaDZUCS0C6lsHn1PDBPsurAF/0=; b=a7gVZNP49dH+QkX/wmrZ JsrC6Tpw4xNZzIunKsQd7h/Os3nXz7M59evVOfJnHhG/W/uXRNCMxtcH7HlNuFnL9qCUvpPiobiNN /6IYOebBii5u79Wz+AR+Ft+EFamdItCeY1Z5PvdVbxyokIo3vdVYQBcfeAOnGZYAC7xwC1vj7BtSX BnnWDxoYfAOoEnm9IvxrMpKaQA/CT/k6a6Fwo6G7Zegvkpq+8Kn2z7aagPk1lIBPtGTtjmg202on6 ANCC27u/tXLeriLmgLcWm2aJ4yJ1sj09b8Zgp2fH7vLFk+aLhud+VTcS7yr96llHp1/Mk0M7ci/vT pAtSiNmUDL+Aaw==; In-Reply-To: (message from =?utf-8?B?Sm/Do28gVMOhdm9yYQ==?= on Thu, 16 Nov 2023 21:58:51 +0000) 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-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:312851 Archived-At: > From: João Távora > Date: Thu, 16 Nov 2023 21:58:51 +0000 > Cc: Michael Heerdegen , emacs-devel > > On Thu, Nov 16, 2023 at 4:42 PM Eli Zaretskii wrote: > > > ?? There's a whole section in the ELisp manual called "Sequence > > Functions", which documents the seq-* functions. > > Yes, but from a custom sequence implementors perspective, > the "best" documentation is still that bit in the header, > which describes "you must implement these to get a working > custom sequence". > > So while the Elisp manual addresses custom sequences > (very briefly -- it just tells the user to look up generic > functions) it spends most time describing the generic > functions one by one, and while that's important, it's > just not enough. Feel free to suggest improvements and additions to what we have. Such improvements are always welcome here. I just answered your original question, viz.: > > seq.el's documentation is where? I don't see it. which seemed to imply that you didn't know at all that we have seq.el functions described in the manual. > It doesn't talk about the guarantees that the framework > offers with respect to when they are called, or if they > are called at all. For example, while I didn't read the > whole thing, I don't think it is stated that custom sequences > based on Lisp lists need many more gf implementations > than others, else they simply won't work (because of > list-specific shortcutting optimizations only found > when reading the seq.el code). Nor is it stated that, for > any representation, :around methods are probably a bad > idea. Nor is it stated that if you just implement the bare > minimum (which is described in seq.el's header) you will > likely get very poor performance. It says this: All functions defined in this library are free of side-effects; i.e., they do not modify any sequence (list, vector, or string) that you pass as an argument. Unless otherwise stated, the result is a sequence of the same type as the input. For those functions that take a predicate, this should be a function of one argument. The ‘seq.el’ library can be extended to work with additional types of sequential data-structures. For that purpose, all functions are defined using ‘cl-defgeneric’. *Note Generic Functions::, for more details about using ‘cl-defgeneric’ for adding extensions. If this is not enough, once again, please feel free to suggest improvements and extensions. > Such a manual is where one would find sentences like > "to make a working custom sequence that is accepted by > any seq-* call, the user must add implementations to > the following N generics. To get good performance > you must also add implementations to these other M > generics". Do you see something like that in other Lisp-related manuals we have? Does cl.info has this information regarding cl-lib? I think the answer is NO, because we generally don't say such things in our manuals, except in rare exceptional cases (which the seq.el one isn't, IMNSHO). Perhaps we should, but then we have a lot of work to do on our manuals, and that work is not only the necessary writeups, but also non-trivial research and analysis. Look how much effort was needed to perform a similar analysis on seq.el. Volunteers are welcome to do the same in other places, and suggest additions to the manuals for any significant findings.