CoffeeScript v1.5.0 was released a few days ago. One of the new features touted in this release was the addition of "Literate CoffeeScript". This was an additional mode in the compiler that allows it to process files ending with .litcoffee that contain both Markdown and CoffeeScript together to form a literate program.

Literate programming, introduced by Donald Knuth, is a technique of writing programs in the natural order and style that you would use if you were to verbally describe the way a program works. Literate programming is designed to break the order of source code required by traditional compilers. It can be fun to build programs in this way by simply starting a document with a description and a list of headers for each feature.

I thought it was really cool to see this in CoffeeScript, but it made me wonder why exactly this needed to be a CoffeeScript extension and not another tool available for any language. So I wrote a small utility to do exactly that.

There are several utilities out there already for assisting with literate programming, however I have a crazy case of Not Invented Here so I decided it would be fun to write my own take on the idea.


From GitHub, litc is "A stupidly simple utility for compiling/interpreting literate style programs written in markdown.". Of course the tool itself is also written in a literate style, with a bootstrapped "compiler" written in Ruby.

You can grab the tool at litc .

Writing a literate program with Litc

To start off a new literate program, create a new file with an extension based on the source type (this is used by CodeRay to detect the language for syntax highlighting) but add a markdown extension to the end. For example, for a script in Scheme.

Now open this file in your favourite Markdown editor write up a nice description of your program followed by some headings for each main section of the program, or whatever feels natural as that is the point of literate programming after all!

In order for litc to understand how to run your script, the first code block in the file must be the command-line used to run the source. The filename will be appended automatically. After this you may mix as many code blocks as you like into the "literature". Once you're finished you should have something that looks like this:

# My fancy hello world in Chicken Scheme

This is a fancy schmancy hello world script written in Chicken Scheme.
It can be run with the following command-line:

    csi -script

## The Hello World

The first and only thing that this script does, is print the string "Hello, World!" to the user.

    (display "Hello, World!\n")

Now, to run this script, we simply invoke litc and pass the script filename. It will take care of the rest!

$ litc ./
Hello, World!

It will also leave an .html file in the same directory with the rendered Markdown, complete with syntax highlighting if the file extension was correctly guessed.

And that's all there is to it! Enjoy :)

(Maybe) Related posts: