bug#23550: 25.0.93; cl.texi (for var on list by func): Fix documentation

bug#23550: 25.0.93; cl.texi (for var on list by func): Fix documentation

[Tino Calancha]

* doc/misc/cl.texi (for var on list by func): Fix documentation

'cl-loop for var on list by func' behaves as in CL: 'on' expression
need to be a list.

The following tests run in the *scratch* buffer return
same values as in SBCL: 
;; CL cl-loop -> loop

emacs -Q:

(require 'cl-lib)
(setq preys '("grass" "lion" "rabbit"))

(defun next-prey (x)
   "Return the name of the prey of animal X."
   (cl-loop while (not (atom x))
            do (setq x (car x)))
   (cond ((member x preys) ; elisp
   ;; (cond ((member x preys :test #'string=) ; CL
          (cond ((string= x "lion") "rabbit")
                ((string= x "rabbit") "grass")
                (t nil)))
         (t
          nil)))
(defun next-prey-list (x)
   "Return a list with the name of the prey of animal X."
   (let ((res (next-prey x)))
     (if res
         (list res)
       nil)))

[A] (mapcar 'next-prey '("grass" "lion" "rabbit"))
[B] (mapcar 'next-prey-list '("grass" "lion" "rabbit"))

[A] (nil "rabbit" "grass")
[B] (nil ("rabbit") ("grass"))

[I]   (cl-loop for y on preys collect y)
[II]  (cl-loop for y on preys by #'next-prey collect y)
[III] (cl-loop for y on (car preys) by #'next-prey collect y)
[IV]  (cl-loop for y on (car preys) by #'next-prey-list collect y)
[V]   (cl-loop for y on preys by #'next-prey-list collect y)

[I]   (("grass" "lion" "rabbit") ("lion" "rabbit") ("rabbit"))
[II]  (("grass" "lion" "rabbit"))
[III] nil
[IV]  nil
[V]   (("grass" "lion" "rabbit"))


In GNU Emacs 25.0.93.3 (x86_64-pc-linux-gnu, GTK+ Version 2.24.30)
Repository revision: 6de0715f5467d4b925e2dfe082174529ace3b174


From 3e1756fb4d76e34b74b96782d4509582e9ce0cd3 Mon Sep 17 00:00:00 2001
From: Tino Calancha <f92capac@gmail.com>
Date: Tue, 17 May 2016 00:04:56 +0900
Subject: [PATCH] ; * cl.texi (clause 'for' with 'on'): Fix documentation

---
  doc/misc/cl.texi | 12 ------------
  1 file changed, 12 deletions(-)

diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 4137a95..319592c 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -1956,18 +1956,6 @@ For Clauses
          @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
  @end example

-With @code{by}, there is no real reason that the @code{on} expression
-must be a list.  For example:
-
-@example
-(cl-loop for x on first-animal by 'next-animal collect x)
-@end example
-
-@noindent
-where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
-the next in the (assumed) sequence of animals, or @code{nil} if
-@var{x} was the last animal in the sequence.
-
  @item for @var{var} in-ref @var{list} by @var{function}
  This is like a regular @code{in} clause, but @var{var} becomes
  a @code{setf}-able ``reference'' onto the elements of the list
-- 
2.8.1

bug#23550: 25.0.93; cl.texi (for var on list by func): Fix documentation

[npostavs]

Tino Calancha <f92capac@gmail.com> writes:

> * doc/misc/cl.texi (for var on list by func): Fix documentation
>
> 'cl-loop for var on list by func' behaves as in CL: 'on' expression
> need to be a list.

Well, it only needs to be a cons, because that's what the loop checks
for.

>
> emacs -Q:
>
> (require 'cl-lib)
> (setq preys '("grass" "lion" "rabbit"))
>
> (defun next-prey (x)
>   "Return the name of the prey of animal X."
>   (cl-loop while (not (atom x))
>            do (setq x (car x)))
>   (cond ((member x preys) ; elisp
>   ;; (cond ((member x preys :test #'string=) ; CL
>          (cond ((string= x "lion") "rabbit")
>                ((string= x "rabbit") "grass")
>                (t nil)))
>         (t
>          nil)))
> (defun next-prey-list (x)
>   "Return a list with the name of the prey of animal X."
>   (let ((res (next-prey x)))
>     (if res
>         (list res)
>       nil)))

I guess the idea behind that statement is that the rest of the list can
be implied by the stepping function, e.g.

    (cl-loop for y on (list "lion") by #'next-prey-list collect (car y))
      ;=> ("lion" "rabbit" "grass")

Works with the "in" clause too:

    (cl-loop for y in (list "lion") by #'next-prey-list collect y)
      ;=> ("lion" "rabbit" "grass")

I guess it could be useful in combination with streams?  Not sure if
it's worth having this in the manual.

bug#23550: 25.0.93; cl.texi (for var on list by func): Fix documentation

[Tino Calancha]

npostavs@users.sourceforge.net writes:

>>
>> emacs -Q:
>>
>> (require 'cl-lib)
>> (setq preys '("grass" "lion" "rabbit"))
>>
>> (defun next-prey (x)
>>   "Return the name of the prey of animal X."
>>   (cl-loop while (not (atom x))
>>            do (setq x (car x)))
>>   (cond ((member x preys) ; elisp
>>   ;; (cond ((member x preys :test #'string=) ; CL
>>          (cond ((string= x "lion") "rabbit")
>>                ((string= x "rabbit") "grass")
>>                (t nil)))
>>         (t
>>          nil)))
>> (defun next-prey-list (x)
>>   "Return a list with the name of the prey of animal X."
>>   (let ((res (next-prey x)))
>>     (if res
>>         (list res)
>>       nil)))
>
> I guess the idea behind that statement is that the rest of the list can
> be implied by the stepping function, e.g.
>
>     (cl-loop for y on (list "lion") by #'next-prey-list collect (car y))
>       ;=> ("lion" "rabbit" "grass")
>
> Works with the "in" clause too:
>
>     (cl-loop for y in (list "lion") by #'next-prey-list collect y)
>       ;=> ("lion" "rabbit" "grass")
>
> I guess it could be useful in combination with streams?  Not sure if
> it's worth having this in the manual.
In the way is written makes me expect that:
(cl-loop for y on "lion" by #'next-prey-list collect (car y))

will be evaluated to: ("lion" "rabbit" "grass").

Becase i read in the example first-animal, instead of (list first-animal), 
and they also write:
'With @code{by}, there is no real reason that the @code{on} expression
must be a list.'

It might be useful rewrite that part to make it more clear, but i don't
have a clear proposal.

bug#23550: 25.0.93; cl.texi (for var on list by func): Fix documentation

[npostavs]

Tino Calancha <tino.calancha@gmail.com> writes:

> It might be useful rewrite that part to make it more clear, but i don't
> have a clear proposal.

Actually, looking at this some more, I think you should just apply your
patch that removes this stuff completely.  It's much clearer to write
that sort of example as

    (cl-loop for y = "lion" then (next-prey y)
             while y collect y)

And looking down the page, `for VAR = EXPR1 then EXPR2' is already
explained well enough (as well as the equivalence to the `for VAR on
LIST by FUNCTION' form).

bug#23550: 25.0.93; cl.texi (for var on list by func): Fix documentation

[Tino Calancha]

npostavs@users.sourceforge.net writes:

> Tino Calancha <tino.calancha@gmail.com> writes:
>
>> It might be useful rewrite that part to make it more clear, but i don't
>> have a clear proposal.
>
> Actually, looking at this some more, I think you should just apply your
> patch that removes this stuff completely.  It's much clearer to write
> that sort of example as
>
>     (cl-loop for y = "lion" then (next-prey y)
>              while y collect y)
>
> And looking down the page, `for VAR = EXPR1 then EXPR2' is already
> explained well enough (as well as the equivalence to the `for VAR on
> LIST by FUNCTION' form).
Thank you.
Pushed fix into emacs-25 branch with commit:
3f0d047d2eb1fb59be2ff962c01392d8c808a654