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

[npostavs@users.sourceforge.net]

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.