From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Robert Cochran Newsgroups: gmane.emacs.bugs Subject: bug#24459: 24.5; cl-flet and cl-labels are not properly documented Date: Mon, 19 Sep 2016 19:32:29 -0700 Message-ID: <87wpi7s3lu.fsf@cochranmail.com> References: NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1474338808 21976 195.159.176.226 (20 Sep 2016 02:33:28 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 20 Sep 2016 02:33:28 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux) Cc: 24459@debbugs.gnu.org To: Carlos =?UTF-8?Q?Garc=C3=ADa?= Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Sep 20 04:33:24 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bmAry-0004G7-Av for geb-bug-gnu-emacs@m.gmane.org; Tue, 20 Sep 2016 04:33:16 +0200 Original-Received: from localhost ([::1]:59643 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bmArw-0001bC-9F for geb-bug-gnu-emacs@m.gmane.org; Mon, 19 Sep 2016 22:33:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39416) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bmArp-0001b5-7E for bug-gnu-emacs@gnu.org; Mon, 19 Sep 2016 22:33:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bmArl-0002Q7-VW for bug-gnu-emacs@gnu.org; Mon, 19 Sep 2016 22:33:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:51514) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bmArl-0002Q2-PM for bug-gnu-emacs@gnu.org; Mon, 19 Sep 2016 22:33:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1bmArl-0006jK-IW for bug-gnu-emacs@gnu.org; Mon, 19 Sep 2016 22:33:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Robert Cochran Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 20 Sep 2016 02:33:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 24459 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 24459-submit@debbugs.gnu.org id=B24459.147433876025829 (code B ref 24459); Tue, 20 Sep 2016 02:33:01 +0000 Original-Received: (at 24459) by debbugs.gnu.org; 20 Sep 2016 02:32:40 +0000 Original-Received: from localhost ([127.0.0.1]:57704 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bmArP-0006iX-Pk for submit@debbugs.gnu.org; Mon, 19 Sep 2016 22:32:40 -0400 Original-Received: from mail.workgrouplinux.net ([207.195.177.82]:42865) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bmArO-0006iM-2A for 24459@debbugs.gnu.org; Mon, 19 Sep 2016 22:32:38 -0400 DKIM-Signature: v=1; a=rsa-sha1; c=simple; d=cochranmail.com; h=from:to :cc:subject:references:date:in-reply-to:message-id:mime-version :content-type:content-transfer-encoding; s=dkim1; bh=i/4CwpVWePO Ej9W1FYIN59cBu7o=; b=su4g9kJjZyUcseLeq4iU6uCnl8/3aUmCEyP3kF625Bz sjBxtGKnjni+86cOd5kFc90CbuiZqPM9ktGQ2S4UMZAR8+nEOAGQdiWmoUTUUTD8 DOyVzsnQu0z+QJfokXiFQKf9Vyjks3lN9JpDKMkld/FTBoNH7k0Qw8rpaKlkF5M/ PT1acfWkHpHN5itp92y6EtTrp15rewcfHJ10DIKSFdsk7B5qNq0ohaJAkCHy3s37 mOvlSGBz6zuuYQPXvsp+CDM0pI/4MaA1cyymuAyvW/jZyfmqR1es16i7Rws1JVUY g8vNzHCzAyOkVz7tpDXYe2kdXWhtBPbvHzFpkFQtnTQ== Original-Received: (qmail 30477 invoked by uid 0); 20 Sep 2016 02:32:34 -0000 Comment: DomainKeys? See http://antispam.yahoo.com/domainkeys DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=private; d=cochranmail.com; b=KAbtj6n9CHAhXHf8cZ6CXzoM4KiSx/osL9Dq/XQ+cQQhIItVutQYX6oENLYtHRzZON7bq4JgLV1NM/clx/1Q6Q==; Original-Received: from 131-191-86-130.as.clicknet.org (HELO SoraLaptop) (robert@cochranmail.com@131.191.86.130) by mail.cochrantribe.org with ESMTPA; 20 Sep 2016 02:32:34 -0000 In-Reply-To: ("Carlos \=\?utf-8\?Q\?Garc\=C3\=ADa\=22's\?\= message of "Sun, 18 Sep 2016 15:27:45 +0200") 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: 208.118.235.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:123463 Archived-At: Carlos Garc=C3=ADa writes: > Dear Maintainer, > > I'd like to report a lack of documentation explaining the functions > cl-flet and cl-labels. The documentation does not specify how all > arguments are used and the exact purpose of the functions. > > Regards, > Carlos > Here is the docstring for `cl-flet` (from my fairly recent git version): cl-flet is an autoloaded Lisp macro in =E2=80=98cl-macs.el=E2=80=99. (cl-flet ((FUNC ARGLIST BODY...) ...) FORM...) Make local function definitions. Like =E2=80=98cl-labels=E2=80=99 but the definitions are not recursive. Each binding can take the form (FUNC EXP) where FUNC is the function name, and EXP is an expression that returns the function value to which it should be bound, or it can take the more common form (FUNC ARGLIST BODY...) which is a shorthand for (FUNC (lambda ARGLIST BODY)). I think that sounds pretty complete to me. I'll admit, I'm biased because I know what flet is supposed to do, but there's nothing noticably missing from that description. Here is the docstring for `cl-labels` (from this same version): cl-labels is an autoloaded Lisp macro in =E2=80=98cl-macs.el=E2=80=99. (cl-labels ((FUNC ARGLIST BODY...) ...) FORM...) Make temporary function bindings. The bindings can be recursive and the scoping is lexical, but capturing t= hem in closures will only work if =E2=80=98lexical-binding=E2=80=99 is in use. The only thing I've got to say about this is that it may be a good idea to point back to `cl-flet` from the `cl-labels` docstring, because the `cl-flet` docstring is more complete. I suppose you could also argue that `func` could be changed to ensure that it's clear it's supposed to be a name. Again, I know that is what it's supposed to be, but that may not be clear to readers that don't already know. As for use cases, well, I don't think that *any* docstring explicitly spells out the 'exact purpose' of the function, but I'll go ahead and give a couple examples for you: 1. Reducing global namespace polution from helper functions ; sum is supposed to take the single argument and sum all numbers below it ; ie 5 -> (+ 1 2 3 4 5) -> 15 (defun sum-1 (arg acc) (if (zerop arg) acc (sum-1 (1- arg) (+ acc arg)))) (defun sum (arg) (sum-1 arg 0)) vs (defun sum (arg) (cl-labels (sum-1 (arg acc) (if (zerop arg) acc (sum-1 (1- arg) (+ acc arg)))) (sum-1 arg 0))) Notice how this example uses `cl-labels` because it is a recursive definition. 2. Creating helper functions that use function-internal values (defun get-value (data-structure key) (cdr (assoc key data-structure))) (defun compute-foo () (let* ((data-structure (create-data-structure)) (bar-value (get-value data-structure 'bar))) ; blah blah blah )) vs (defun compute-foo () (let ((data-structure (create-data-structure))) (cl-flet (get-value (key) (assoc key data-structure)) (let ((bar-value (get-value 'bar))) ; blah blah blah )))) Notice how in the second version of `compute-foo`, `get-value` is able to directly use `data-structure` instead of having to pass that in as an argument. I used `cl-flet` because the function definition wasn't recursive, so I didn't need `cl-labels`. The one other big thing to use these functions for is when a lambda for a higher-order function gets long enough that its stylistically a bad idea to write it inline, but you don't want to declare it globally, like in the first example. Anyways, tl;dr: The docstrings are pretty good as they are IMO, but I am speaking as one who is familiar with what they are supposed to do. My only nit is that it is a probably a good idea to have the docstring of `cl-labels` point back to `cl-flet`, just as `cl-flet` points to `cl-labels`. HTH, --=20 ~Robert Cochran GPG Fingerprint - E778 2DD4 FEA6 6A68 6F26 AD2D E5C3 EB36 4886 8871