generator documentation improvement

generator documentation improvement

[Paul Pogonyshev]

[-- Attachment #1: Type: text/plain, Size: 639 bytes --]

I suggest the following short improvement to documentation of
generator functions.  It took me very long to understand what's wrong
with my code.

Problem can be illustrated with this:

(require 'generator)
(defvar xxx 0)
(iter-defun my-iter ()
  (print "A")
  (let ((xxx nil))
    (print "B")
    (iter-yield 0)
    (print "C"))
  (print "D"))
(iter-do (x (my-iter))
  (print x))

If you evaluate the last form, you'll see "B" and "C" printed twice
because `let' for dynamic variable is internally implemented with
something similar to `unwind-protect'. However, when documentation
doesn't mention it, that's very hard to pinpoint.

Paul

[-- Attachment #2: generator-doc.diff --]
[-- Type: text/plain, Size: 506 bytes --]

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 401a999cf2..e279be8557 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -730,7 +730,8 @@ result as its condition data.
 
 Any kind of Lisp code is valid inside @var{body}, but
 @code{iter-yield} and @code{iter-yield-from} cannot appear inside
-@code{unwind-protect} forms.
+@code{unwind-protect} forms or any dynamic @code{let} bindings,
+i.e. bindings for variables defined with @code{defvar}.
 
 @end defmac
 

Re: generator documentation improvement

[Noam Postavsky]

On Wed, Mar 8, 2017 at 3:47 PM, Paul Pogonyshev <pogonyshev@gmail.com> wrote:
>
> If you evaluate the last form, you'll see "B" and "C" printed twice
> because `let' for dynamic variable is internally implemented with
> something similar to `unwind-protect'. However, when documentation
> doesn't mention it, that's very hard to pinpoint.

Is this Bug#25965 "iter-lambda may evaluate certain forms twice"?

https://debbugs.gnu.org/cgi/bugreport.cgi?bug=25965

Re: generator documentation improvement

[Andreas Politz]

Noam Postavsky <npostavs@users.sourceforge.net> writes:

> Is this Bug#25965 "iter-lambda may evaluate certain forms twice"?
>
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=25965

Yes, it is.

Are sure that "iter-yield [...] cannot appear inside [...] dynamic let
bindings" is the intended behavior ? There is special code in
generator.el handling these dynamic bindings, which I think is just
incorrect.

-ap

Re: generator documentation improvement

[Paul Pogonyshev]

> Are sure that "iter-yield [...] cannot appear inside [...] dynamic let
> bindings" is the intended behavior ?

No, I just assumed it was related.  I noticed weird behaviour in
real code and managed to pinpoint it to let-binding global variables.
Local (lexical scope) bindings are not a problem. I guessed that
global variable binding are in some sense similar to `unwind-protect',
since no matter how you exit body of `let' (normally or with an error),
previous value must be restored.

If it is not intended and can be fixed, then of course the
documentation patch is not needed.

Paul

On 8 March 2017 at 22:28, Andreas Politz <politza@hochschule-trier.de> wrote:
> Noam Postavsky <npostavs@users.sourceforge.net> writes:
>
>> Is this Bug#25965 "iter-lambda may evaluate certain forms twice"?
>>
>> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=25965
>
> Yes, it is.
>
> Are sure that "iter-yield [...] cannot appear inside [...] dynamic let
> bindings" is the intended behavior ? There is special code in
> generator.el handling these dynamic bindings, which I think is just
> incorrect.
>
> -ap