[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#32803: 26.1.50; cl-do: Add more literature in docstring
From: |
Tino Calancha |
Subject: |
bug#32803: 26.1.50; cl-do: Add more literature in docstring |
Date: |
Sat, 29 Sep 2018 05:13:57 +0900 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) |
Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>> I am OK to rephrase it to make it more obvious if you have something
>> in mind.
>
> I don't have a serious objection! It just seems to me that the key
> question about any test-and-loop construct is: does it test first, or
> loop first? As Eli points out, the rest of the docstring makes it clear
> that it tests first. It just seems to me that nothing is lost (and
> something gained) by replacing "in" with "before".
Thank you Eric.
I agree with you that such info is crucial. Indeed, in my first
version of the patch I included the line:
"On each iteration, check END-TEST before run BODY."
I think is worth to remark that.
Following patch applies on top of the previous one:
--8<-----------------------------cut here---------------start------------->8---
commit c057715eff519114e38d82d39b16d8f2a01c3c4d
Author: Tino Calancha <tino.calancha@gmail.com>
Date: Sat Sep 29 05:05:59 2018 +0900
Clarify that ENDTEST belongs to the iteration
diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index 10bc611325..b02a917ac0 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -1747,10 +1747,9 @@ cl--loop-build-ands
(defmacro cl-do (steps endtest &rest body)
"Bind variables and run BODY forms until END-TEST returns non-nil.
First, each VAR is bound to the associated INIT value as if by a `let' form.
-Then, in each iteration of the loop, the END-TEST is evaluated; if true,
-the loop is finished. Otherwise, the BODY forms are evaluated, then each
-VAR is set to the associated STEP expression (as if by a `cl-psetq'
-form) and the next iteration begins.
+Then, the END-TEST is evaluated; if true, the loop is finished. Otherwise,
+the BODY forms are evaluated, then each VAR is set to the associated
+STEP expression (as if by a `cl-psetq' form) and the next iteration begins.
Once the END-TEST becomes true, the RESULT forms are evaluated (with
the VARs still bound to their values) to produce the result
@@ -1759,6 +1758,10 @@ cl-do
Note that the entire loop is enclosed in an implicit `nil' block, so
that you can use `cl-return' to exit at any time.
+Also note that the ENDTEST belongs to the iteration; it's always checked
+before evaluate BODY. In particular, if ENDTEST evaluates initially non-nil,
+the `cl-do' will end without running BODY.
+
For more details, see `cl-do' description in Info node `(cl) Iteration'.
\(fn ((VAR INIT [STEP])...) (END-TEST [RESULT...]) BODY...)"
@@ -1785,6 +1788,10 @@ cl-do*
Note that the entire loop is enclosed in an implicit `nil' block, so
that you can use `cl-return' to exit at any time.
+Also note that the ENDTEST belongs to the iteration; it's always checked
+before evaluate BODY. In particular, if ENDTEST evaluates initially non-nil,
+the `cl-do*' will end without running BODY.
+
This is to `cl-do' what `let*' is to `let'.
For more details, see `cl-do*' description in Info node `(cl) Iteration'.
--8<-----------------------------cut here---------------end--------------->8---
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Tino Calancha, 2018/09/22
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Eli Zaretskii, 2018/09/24
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Tino Calancha, 2018/09/24
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Eric Abrahamsen, 2018/09/24
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Eli Zaretskii, 2018/09/24
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Eric Abrahamsen, 2018/09/24
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Tino Calancha, 2018/09/24
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Eric Abrahamsen, 2018/09/27
- bug#32803: 26.1.50; cl-do: Add more literature in docstring,
Tino Calancha <=
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Eric Abrahamsen, 2018/09/28
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Tino Calancha, 2018/09/29