Some time ago, I read this journal entry by Aristotle. I liked it and suspected it could be easily implemented in XS. It turned out to be the most elegant piece of XS I've ever written.
void
induce(block, var)
SV* block;
SV* var;
PROTOTYPE: &$
PPCODE:
SAVESPTR(DEFSV);
DEFSV = sv_mortalcopy(var);
while (SvOK(DEFSV)) {
PUSHMARK(SP);
call_sv(block, G_ARRAY);
SPAGAIN;
}
I assume most readers don't know much C, let alone the perl API or XS, so I'll explain it piece by piece.
void
induce(block, var)
SV* block;
SV* var;
PROTOTYPE: &$
This declares the xsub. It has two parameters, both scalar values. The function has the prototype &$. So far little surprises.
PPCODE:
This declares that a piece of code follows. Unlike CODE blocks, PPCODE blocks pop the arguments off the stack at the start. This turns out to be important later on.
SAVESPTR(DEFSV);
DEFSV = sv_mortalcopy(var);
These lines localizes $_ and initializes it to var.
while (SvOK(DEFSV)) {
This line is equivalent to while (defined($_)).
Now comes the interesting part:
PUSHMARK(SP);
call_sv(block, G_ARRAY);
SPAGAIN;
To understand what this block does, you have to know how perl works inside.
If you've read perlxs, you may notice this function does not push any values on the stack. Are careless reader might be mistaken and think this function doesn't return anything: they couldn't be more wrong!
If you've read perlcall, you would notice a lot more is missing. For starters, the function calls SPAGAIN (pretty much equivalent to saying I accept the values you return to me), but it doesn't do anything with them.
Also, you may notive that both ENTER/LEAVE(needed to delocalize $_) and SAVETMPS/FREETMPS (needed to get rid of temporary values) are missing. The function that calls the xsub automatically surrounds it by an ENTER/LEAVE pair, so that one isn't necessary. The lack of SAVETMPS/FREETMP however is not only deliberate but also essential.
The loop calls the block without arguments (PUSHMARK & call_sv). The xsub accept the return values on the stack and leaves them there. This sequence repeated. This way it assembles the induces values on the stack. PPCODE removing the arguments at the start prevents it from returning those as first two return values. It also adds a trailer that causes all elements that have been pushed on the stack to be recognized as return values of this function. That's why a SAVETMPS/FREETMPS pair would break this code: the values must live after the code returns.
That's the elegance of this function. It doesn't even touch it's return values, it delegates everyting to the block. All the things that are missing make that it does exactly what it should do.