GNU bug report logs - #24459
24.5; cl-flet and cl-labels are not properly documented

Previous Next

Package: emacs;

Reported by: Carlos García <carloscg <at> gmail.com>

Date: Sun, 18 Sep 2016 17:47:02 UTC

Severity: minor

Tags: fixed

Found in version 24.5

Fixed in version 27.1

Done: Lars Ingebrigtsen <larsi <at> gnus.org>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 24459 in the body.
You can then email your comments to 24459 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#24459; Package emacs. (Sun, 18 Sep 2016 17:47:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Carlos García <carloscg <at> gmail.com>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Sun, 18 Sep 2016 17:47:02 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Carlos García <carloscg <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.5; cl-flet and cl-labels are not properly documented
Date: Sun, 18 Sep 2016 15:27:45 +0200
[Message part 1 (text/plain, inline)]
 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
[Message part 2 (text/html, inline)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#24459; Package emacs. (Tue, 20 Sep 2016 02:33:01 GMT) Full text and rfc822 format available.

Message #8 received at 24459 <at> debbugs.gnu.org (full text, mbox):

From: Robert Cochran <robert-emacs <at> cochranmail.com>
To: Carlos García <carloscg <at> gmail.com>
Cc: 24459 <at> debbugs.gnu.org
Subject: Re: bug#24459: 24.5; cl-flet and cl-labels are not properly documented
Date: Mon, 19 Sep 2016 19:32:29 -0700
Carlos García <carloscg <at> gmail.com> 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 ‘cl-macs.el’.

  (cl-flet ((FUNC ARGLIST BODY...) ...) FORM...)

  Make local function definitions.
  Like ‘cl-labels’ 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 ‘cl-macs.el’.

  (cl-labels ((FUNC ARGLIST BODY...) ...) FORM...)

  Make temporary function bindings.
  The bindings can be recursive and the scoping is lexical, but capturing them
  in closures will only work if ‘lexical-binding’ 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,
-- 
~Robert Cochran

GPG Fingerprint - E778 2DD4 FEA6 6A68 6F26  AD2D E5C3 EB36 4886 8871




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#24459; Package emacs. (Tue, 20 Sep 2016 02:43:01 GMT) Full text and rfc822 format available.

Message #11 received at 24459 <at> debbugs.gnu.org (full text, mbox):

From: npostavs <at> users.sourceforge.net
To: Robert Cochran <robert-emacs <at> cochranmail.com>
Cc: 24459 <at> debbugs.gnu.org, Carlos García <carloscg <at> gmail.com>
Subject: Re: bug#24459: 24.5; cl-flet and cl-labels are not properly documented
Date: Mon, 19 Sep 2016 22:42:47 -0400
Robert Cochran <robert-emacs <at> cochranmail.com> writes:

>
> As for use cases, well, I don't think that *any* docstring explicitly
> spells out the 'exact purpose' of the function

Docstrings indeed shouldn't be too verbose, but it may be worth linking
to the CL manual which has some more details on these macros.

(cl) Function Bindings,
https://www.gnu.org/software/emacs/manual/html_node/cl/Function-Bindings.html




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#24459; Package emacs. (Wed, 21 Sep 2016 12:12:02 GMT) Full text and rfc822 format available.

Message #14 received at 24459 <at> debbugs.gnu.org (full text, mbox):

From: Phil Sainty <psainty <at> orcon.net.nz>
To: npostavs <at> users.sourceforge.net,
 Robert Cochran <robert-emacs <at> cochranmail.com>
Cc: 24459 <at> debbugs.gnu.org, Carlos García <carloscg <at> gmail.com>
Subject: Re: bug#24459: 24.5; cl-flet and cl-labels are not properly documented
Date: Thu, 22 Sep 2016 00:11:29 +1200
On 20/09/16 14:42, npostavs <at> users.sourceforge.net wrote:
> Docstrings indeed shouldn't be too verbose, but it may be worth linking
> to the CL manual which has some more details on these macros.
>
> (cl) Function Bindings,
>
https://www.gnu.org/software/emacs/manual/html_node/cl/Function-Bindings.html

Strongly agreed; but that documentation should also include details
on using cl-letf for dynamic-scope function binding, and the link to
that info node should appear in the docstrings of all three macros.

I also think the summary text at the top of the node should include
something like "The practical difference between the following options
is the scope of the bindings, and therefore which one you use will be
determined by the scope you require."


-Phil




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#24459; Package emacs. (Sat, 12 Oct 2019 20:22:02 GMT) Full text and rfc822 format available.

Message #17 received at 24459 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: npostavs <at> users.sourceforge.net
Cc: Carlos García <carloscg <at> gmail.com>,
 Robert Cochran <robert-emacs <at> cochranmail.com>, 24459 <at> debbugs.gnu.org
Subject: Re: bug#24459: 24.5; cl-flet and cl-labels are not properly documented
Date: Sat, 12 Oct 2019 22:21:19 +0200
npostavs <at> users.sourceforge.net writes:

> Robert Cochran <robert-emacs <at> cochranmail.com> writes:
>
>> As for use cases, well, I don't think that *any* docstring explicitly
>> spells out the 'exact purpose' of the function
>
> Docstrings indeed shouldn't be too verbose, but it may be worth linking
> to the CL manual which has some more details on these macros.
>
> (cl) Function Bindings,
> https://www.gnu.org/software/emacs/manual/html_node/cl/Function-Bindings.html

I've now added one from the macro that didn't have one, and I don't
think there more to be done here, so I'm closing the bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no




Added tag(s) fixed. Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Sat, 12 Oct 2019 20:22:02 GMT) Full text and rfc822 format available.

bug marked as fixed in version 27.1, send any further explanations to 24459 <at> debbugs.gnu.org and Carlos García <carloscg <at> gmail.com> Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Sat, 12 Oct 2019 20:22:02 GMT) Full text and rfc822 format available.

bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Sun, 10 Nov 2019 12:24:13 GMT) Full text and rfc822 format available.

This bug report was last modified 4 years and 140 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.