Weaving Raku: semiliterate programming in a beautiful language
The other day (er, ok, month) Brian Wisti wrote an excellent blog post about tangling code using Raku.
Inverse inspiration
My first thought when reading that post was that I want exactly what it describes. My second thought, however, is that I don't – I actually want the exact inverse of what the post describes.
Brian wants to start by writing documentation and then to tangle code out of that file and into one or more executable programs. In his example, Brian starts by writing a Markdown file, and then processes it to produce multiple executable files in multiple programming languages.
On the other hand, I want to start by writing some code – specifically, some Raku code – and then to weave documentation out of that file. Like Brian, I want to write one file that both tells a story and produces machine-executable code; unlike Brian, I want to start a bit closer to the code, and generate the documentation.
Wait, isn't that just Pod6?
At first, this could sound like I'm just describing Pod6, Raku's excellent tool for writing and formatting documentation. Using Pod6, it's already easy to write clear, well-formatted documentation directly in-line with your code. And you can then render the documentation as Markdown, HTML, plain text, or any other output format you'd like. Isn't that exactly what I said I wanted?
Well, no, not exactly. A Raku file with Pod blocks is cleanly divided into documentation (everything inside Pod blocks) and code (everything outside Pod blocks). When you render output documentation, the code is ignored; when you run the code, the documentation is ignored.
This works great for many typical Pod use cases, but it doesn't really let us do the sort of thing Brian was talking about: we can't use Pod to write code and to display that code as part of our documentation. That's a little abstract, so maybe an example is in order.
