In all functions that allow iterables as input arguments, a great number of steps are present to perform the iteration process. For example, in the Map constructor:
Let next be the result of IteratorNext(iter).
ReturnIfAbrupt(next).
Let done be IteratorComplete(next).
ReturnIfAbrupt(done).
If done is true, then return NormalCompletion(map).
Let nextItem be IteratorValue(next).
ReturnIfAbrupt(nextItem).
are all just setup for getting nextItem. Set has almost-the-same steps:
Let next be the result of IteratorNext(iter).
ReturnIfAbrupt(next).
Let done be IteratorComplete(next).
ReturnIfAbrupt(done).
If done is true, then return set.
Let nextValue be IteratorValue(next).
ReturnIfAbrupt(nextValue).
DOM promises [1] want this, but I chickened out of actually copying all those steps in to the spec and just said "For each value `nextValue` of `iterable."
It would be great if you abstracted the above steps into some reusable construct that could be used throughout the spec. I think the only modification would be that you'd say "If done is true, stop repeat." or similar instead of "If done is true, then return x." You'd then move the "return set" and "return NormalCompletion(map)" (why are they different?) after the repeat.
[1]: https://github.com/domenic/promises-unwrapping#promiseraceiterable
I've looked into this and I could replace most uses of IteratorNext+IteratorComplete in the spec. with a new abstract operations IteratorStep(iterator [, value]) which returns either true indicating "done" or an iteration result obj for the not done cases. The 7 line sequence could then be expressed in 5 lines like:
let next be the result of IteratorStep(iter).
ReturnIfAbrupt(next).
If next is true, then return NormalCompletion(map).
Let nextItem be IteratorValue(next).
ReturnIfAbrupt(nextItem).
But I think there is a tension between conciseness and clarity. This is a specification, not an actual implementation, and it primary goal is to clearly and precisely communicate the required semantics. Adding an additional layer of procedural abstraction that over-loads its result type won't necessarily make the spec. easier to understand. IteratorStep would make some algorithms slightly easier to write but will it make them harder to read/understand?
What do you think?
fixed in rev20 editor's draft
added IteratorStep
fixed in rev20 draft, Oct. 28, 2013