(break) out of loop with multiple bindings

[thegeez]

Using (break) within a loop with multiple bindings gives surprising (to me) behavior. The documentation for (break) as a special form does specify that it only breaks from the innermost while loop. And a loop with multiple nesting expands into nested while expressions.
So to break out of the whole loop the usage of (prompt :label ... (loop [...] (return :label res) ...)) or something similar is needed.

For writing user code this requires some attention, but it is not insurmountable. But I believe for some Janet API code that uses (break) within a loop with multiple bindings it is wrong:

The :modifier :while expands to use (break) within nested while expressions causing the following behavior:

(loop [i :in [1 2 3 4]
       :before (printf "before i: %p" i)
       j :in [100 200 400]
       :while (not= (* i j) 600)]
  (printf "i: %p j: %p *: %p" i j (* i j)))
  
#=> output
before i: 1
i: 1 j: 100 *: 100
i: 1 j: 200 *: 200
i: 1 j: 400 *: 400
before i: 2
i: 2 j: 100 *: 200
i: 2 j: 200 *: 400
i: 2 j: 400 *: 800
before i: 3
i: 3 j: 100 *: 300
before i: 4            # superfluous iterations
i: 4 j: 100 *: 400     #  "
i: 4 j: 200 *: 800     #  "
i: 4 j: 400 *: 1600    #  "

Would it be an option to add (breakloop) or something similar for fixing the :while modifier and to make it available as "easier"/"lower cost" option to break out of a loop with multiple bindings?

[pyrmont]

I'm not sure I agree this is 'wrong'.

If you write

(loop [i :in [1 2 3 4]
       :while (< i 3)
       :before (printf "before i: %p" i)
       j :in [100 200 400]
       :while (not= (* i j) 600)]
  (printf "i: %p j: %p *: %p" i j (* i j)))

the output is

#=> 
before i: 1
i: 1 j: 100 *: 100
i: 1 j: 200 *: 200
i: 1 j: 400 *: 400
before i: 2
i: 2 j: 100 *: 200
i: 2 j: 200 *: 400
i: 2 j: 400 *: 800
before i: 3
i: 3 j: 100 *: 300

So the :while modifier applies to the loop created most immediately above the modifier (which is what I'd expect). This is consistent with the way other modifiers (e.g. :before in your example) work, too.

[thegeez]

I should have elaborated that I mean 'wrong' with how I read the documentation for a while clause:
":while expression - breaks from the loop if expression is falsey"

I wrote a few bugs before it dawned on me that the 'loop' in that description also only means the last binding before it, rather than leaving the entire (loop ....

There are cases where a :while using multiple bindings can't be expressed with a :while after each binding. For such cartesian products with a cut-off clause a (breakloop) would be useful.

[pyrmont]

Causing :while to break out of all nested loops would be a breaking change since there could be code out there that relies on the existing behaviour to only break out of a nested loop. I think the appropriate change here is to the documentation. I've filed PR #893 to try to make the behaviour clearer.