Worgle

What is this?

Worgle is the Web ORg TanGLEr. At the very least, it aims to be able to tangler for literate programs written in a subset of org markup that is compatible with org-babel. This includes noweb style code expansion, a crucial aspect to literate programming (which often seems to be ignored in other non-emacs org-mode tanglers).

There is also a quick and dirty HTML renderer called sorg, useful for a fast and portable solution to rendering documents written in Worgle.

Moviations

The initial motivation for building Worgle is performance. The tangling done by org-babel is embarassingly slow to the point of being useless for any projects larger than a script. Worgle aims to make org-tangle usable for actual software projects.

The larger goal is to build a spirtual successor to CWEB, a program I use on a daily basis to write literate programs in C. It is perhaps one of the best literate programming tools out there. Now over 3 decades old, CWEB is definitely showing signs of old age.

Features

Right now, Worgle has just enough features to be useful.

Written in portable ANSI C
Named code block declarations (NAME, BEGIN_SRC and END_SRC)
Noweb-style code block expansion (can be referenced before being declared)
Implicit code block appending
Tangling of multiple files in one org-document
Line declarations C/C++ code (for easy debugging in GDB, Valgrind, etc)
Public Domain License

Anti-features

Pretty much any of the advanced features of org-mode won’t be implemented. Emacs is plenty good at handling that if you really need it.

Compilation

To compile, run make.

To install, run sudo make install.

Sample code

As it turns out, this README is the sample code. Cool, right?

A code block for a simple hello world program in C looks like this:

#include <stdio.h>

int main(int argc, char *argv[])
{
    <<say_the_worgle_greeting>>
    return 0;
}

The code mentioned above has a code block called say_the_worgle_greeting.

This gets expanded to this code block below:

printf("Orgle Worgle Borgle!\n");

To tangle, run:

./worgle README.org
gcc hello.c -o hello
./hello

Performance

A very casual performance test indicates that Worgle is able to tangle itself faster than Emacs by a several orders of magnitude! This has less to do with Worgle being well designed, and more to do with org-tangle being terribly designed (especially for noweb expansion).

The sorg parser has a speed-up boost of about 625x times on average. This one is a little less fair, because the emacs version produces a table of contents and does syntax highlighting.

The test is done using the shell script measure_performance.sh.

The results printed below are from a mid-2015 MacBook pro running Mojave:

Org-babel-tangle (via Emacs): 0m36.806s
Worgle: 0m0.002s
Org-export-to-html (via Emacs): 1m21.955s
Sorg: 0m0.006s

Amalgamation

A portable version of worglite can be made by generating an amalgamation.

An amalgamation can be dynamically generated with mkamalg.sh, which generates the file amalg.c

./mkamalg.sh

It can then be compiled with;

gcc amalg.c -o worglite

License

This project is placed under the public domain. Happy hacking, humans.

PaulBatchelor/worgle