Bricoleur
The bricoleur tool is an unfinished personal tool designed for drafting blog posts that include source code.
The fundamental problem that bricoleur aims to solve is that it's easy for executable source code to get out of sync with a blog-post-in-progress. There's a temptation (for me, at least) to edit variable names or modify source layout of source code snippets as I write a blog post, and if I forget to update a variable name somewhere or make a typo, it's possible I've produced a blog post that includes invalid source code. I sometimes avoid this by always copy/pasting from working source examples, but that can be tedious.
With bricoleur, I start writing my post with placeholders, which are indicated with guillemets. The post can be in any format, but for my purposes here, let's assume it's in Markdown. I can write a post like this, say, in a file called post.md:
The hello world program in Python looks like this:
```python
«hello»
```
I can then write, say in main.py, the actual source code I wanted to include:
print("Hello, world!")
I can then tie them together with a "bricoleur" file, which is conventionally just named bricoleur:
(document
# this tells us that we're assembling "post.md"
"post.md"
# and then we define the fragments we care about
{
# this fragment's name is "hello"
name "hello"
# to test this fragment, we run "python main.py"
cmd [ "python main.py" ]
# and this fragment should be replaced by the contents
# the file "main.py"
expose (file "main.py")
}
)
Once I've done this, I can use the bricoleur tool in two ways: for one, I can run bricoleur test and it'll execute the relevant commands and tell me whether they succeeded, and for another, I can run bricoleur splice and it'll stitch the contents of the source file at the relevant place in the original, producing the output:
The hello world program in Python looks like this:
```python
print("Hello, world!")
```
I can do more than this: for example, instead of exposing the entirety of a file, I can indicate particular chunks of the file via special comments, and I can expose multiple files, or even have multiple "subprojects" that each get tested individually in different ways. The README file has some more examples.
I haven't properly released this tool yet, and thus make no guarantees about it, but if you're interested in trying it out, you can find the source code on my personal git server, or clone the repo with
$ git clone https://git.gdritter.com/bricoleur/
This will also require a copy of the adnot library.