Worgle and Friends (Woven Programs)

Overview

This document aims to provide a summary for the woven output program Worgle and the components.

Worgle is a fast and portable tangler for literate programs written in noweb-styled org. It aims to parse a small subset of org markup, and also adds a few unique features as well.

Worgle outperforms the native org-tangle found in emacs by several orders of magnitude. A simple benchmark test is provided in the project that provides the following results from a mid-2015 MacBook pro (no, it's not a typo):

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

(Note: Worgle's great performance as a tangler has less to do with it being well designed, and more to do with org-tangle being terribly designed.)

Main Program

The main program contains most of the program. In fact, this document can be compiled by itself if the WORGLITE C flag is defined, which creates a simplified version of worgle called worglite. Worglite has most of the functionality of Worgle, with a few exceptions (most notably, database export is disabled).

Worglite is used as part of the bootstrapping process; it can be tangled into C code using orgle, a 700-line org tangler written directly in ANSI C rather than a literate program. Worglite is then used to tangle and build the rest of components that make up Worgle.

SQLite Database Export

One thing that Worgle can do that org-mode cannot do is export itself to a SQLite database, where it can be further parsed in analyzed, in particular by worgmap.

Sorg

Sorg is a very simple org to HTML converter that can be used to weave small worgle programs in a pinch. It isn't really maintained anymore. Using worgmap's weewiki export feature is a more robust option and ideal for larger programs.

Worgmap

Worgmap is a collection of small utilities designed to analyze and do stuff with databases generated by Worgle. The most useful interfaces by far are the weewiki export (used to generated this loom) and get programs (useful for getting insights about a program).

Worgmap itself is broken into smaller components, described below.

CLI

The Worgmap CLI is a the main entry paint, and in charge of making calls to all other programs.

Core

The core provides an API for common operations to do on a Worgle database. This is basically a thin abstraction on top of the SQLite3 C API.

Get

The get utility is a command-line interface useful for doing some basic querying. It was mainly written as a way to initially test the core API.

WeeWiki

The weewiki utility is used to dynamically export a worgle database to a weewiki database. This leverages the org parser in weewiki to generate HTML rather than duplicating the parsing task there.

This utility is what is used to construct the Loom.

Dot

The dot utility constructs a dot graph out of a worgle program. This hasn't been used in a while, and may need some updates.