bricoleur

The collage tool is a tool for writing documents that rely on code samples while keeping the code samples up-to-date.

Including an Entire Source File

To create a collage project, create a directory that contains a file called collage as well as one or more subdirectories that contain the code that you want to expose, and a document in whatever plain text format you want. For example, say that we have a piece of Python source we'd like to write about: let's create a project directory as well as the subdirectory for the Python program, and initialize it with a trivial Python program:

$ mkdir my-post
$ mkdir my-post/python-example
$ echo "print 'Hello, world!'" >my-post/python-example/main.py

Now, let's write a document: save the following to my-document.md:

Here is a document describing a snippet of Python source. A 'Hello
World' program in Python looks like this:

~~~python
«hello»
~~~

Isn't that easy?

Notice that the code block there contains a string in guillemets («hello») instead of the actual source code. Now, finally, we write a collage file that ties these together:

(document
  # first, we tell it which document we care about
  "my-document.md"

  # then, we define a "source": this is a project we're drawing
  # from to get source code. We called it «hello» up above, so
  # we're going to give it the name "hello", and we've put it
  # in the directory "python-example". Our test build will be
  # simply running it, and finally, we'll point to the file
  # "main.py" as the file whose source code we care about
  {
    name "hello"
    dir "python-example"
    cmd [ "python main.py" ]
    expose (file "main.py")
  }
)

In our directory, we can now run collage test and we'll get output that looks like the following:

$ collage test
testing my-document.md
- building source hello
  - running "python main.py" in my-post/python-example
Hello, world

we can also run collage splice to stitch the source code in question into our document:

$ collage splice
Here is a document describing a snippet of Python source. A 'Hello
World' program in Python looks like this:

~~~python
print 'Hello, world'
~~~

Isn't that easy?

Including Multiple Source Files Per Project

In addition to exposing a single source file, we can expose more than one. Replace the (file "my-file") expression with a map from names to files, and then use forward slashes to refer to names within this mapping. For example, if I added a helper.py file, and I wanted to use both, my Markdown file could reference «hello/main» and «hello/helper», and my collage file could be updated to include

# ...
  expose {
    main (file "main.py")
    helper (file "helper.py")
  }
# ...

Including Only Some Part of a Source File

If we have only some parts of a source file we want to draw attention to, we can expose using the the sections expression instead. Let's say we expand main.py above to look like this:

import sys

# «main»
def main():
    sys.stdout.write("Hello, world!\n")
# «end»

if __name__ == '__main__':
    main()

The two comment lines around the main function demarcate a section of the file: collage will look for those substrings and then select only the lines of the file in between those two. We can refer to that section identifier just like we refer to multiple files above, as «helper/main». We can then update our collage file to read:

# ...
  {
    name "hello"
    dir "python-example"
    cmd [ "python main.py" ]
    expose (sections "main.py")
  }
# ...