Document multi-shot generators

[Technologicat]

As of v0.15.0, there is a toy implementation of multi-shot generators (i.e. re-resumable generators) buried within the automated tests, see unpythonic.syntax.tests.test_conts_gen.

Playing around with the idea, multi-shot generators seem a much nicer API to use continuations with than the low-level call_cc[].

Thus, we could extract it into a proper mcpyrate macro, and add it to the public macro API.

We should caution in the docs that it'll only work inside a with continuations block, since doing things like this in Python requires a CPS conversion. Or maybe make this another, alternative multi-shot-continuations API, and internally compile into a with continuations.

This requires first fleshing out some details. Ideally, a multi-shot generator should look similar to a classical Python generator, with only the difference that a multi-shot generator can resume again from an earlier yield (arbitrarily many times).

[Technologicat]

Supporting all of the generator API is a large project, so maybe just implement the very basics, showing how it could be done.

With the new get_cc function in 0.15.1, and the multi-phase compiler in mcpyrate, we can write a lot cleaner demo than what was possible before.

So, let's include such a short demo in 0.15.2.

[Technologicat]

Example moved into unpythonic.syntax.tests.test_conts_multishot.

[Technologicat]

Now we just need to update the documentation, particularly the section on continuations in doc/macros.md.

• Document get_cc and the pattern k = call_cc[get_cc()]. Material exists in the docstring of get_cc.
• Document how to use this pattern to make multi-shot generators. Refer to unpythonic.syntax.tests.test_conts_multishot, which demonstrates this and packages it into a @multishot decorator macro, which can be used lexically inside a with continuations block.

[Technologicat]

Now the demo includes also a MultishotIterator that shows how to make a @multishot multi-shot generator conform to the most often used parts of Python's generator API.