lit - a modern literate programming tool
What is literate programming?
Literate programming is a way to write programs prioritized for understanding. All literate programs consist of prose and literate constructs. For example, this paragraph is a valid literate program.
Literate tools take a literate file and essentially generate two types of files. Primarily, they generate the source code that computers understand. Because literate programs are inherently legible, these tools often generate nice documentation.
Programs must be written for people to read, and only incidentally for machines to execute.
-H. Abelson and G. Sussman (SICP)
lit has several notable features:
- All prose can expressed in Markdown or plaintext
- Supports all programming languages
- Literate constructs defined by indentation
- Can watch files or directories for changes, recompiling automatically
Here is an example literate file
Here is an overview of a hello world Haskell program. We define * as the macro from which all other code or macros exist. << * >>= << a trivial comment >> << print a string >> Now we can define each of the above macros, beginning with an inconsequential comment! << a trivial comment >>= -- this is a hello world haskell program Lastly our program needs to print hello world << print a string >>= main = putStr "Hello, World!"
lit can process the literate file in several ways. To simply produce the code file run:
$ lit -c helloWorld.hs.lit
Which generates the file
-- this is a hello world haskell program main = putStr "Hello, World!"
lit only has two valid constructs:
A macro definition:
<< ... >>= and a macro reference:
<< ... >>
Any lines sharing or to the right of the initial indent, are included in the definition. A macro definition is where the actual source code is placed. It can also contain macro references.
It is also possible to extend a macro definition by creating a macro definition with the same name later in the literate file.
lit attempts to generate the source code from the literate file, it expands each
macro reference with the corresponding macro definition. By convention,
lit starts at the root macro
<< * >>=, which must be included to generate source code.
In order to use, install Haskell and run:
cabal install lit
Usage: lit OPTIONS... FILES... -h --html Generate html -m --markdown Generate markdown -c --code Generate code by file extension -n --number Add annotations to generated code noting the source lit file and line number --css=FILE Specify a css file for html generation --docs-dir=DIR Directory for generated docs --code-dir=DIR Directory for generated code -w --watch Watch for file changes, automatically run lit -v --version Print version --help Display help
In order to build from the latest snapshot run:
git clone https://github.com/cdosborn/lit.git; cd lit; cabal sandbox init; scripts/build.sh;
Submit an issue, with your input lit file, and failing output. If you're feeling motivated submit a pull request with both files added to test/.
Use the online docs to explore
the codebase. Make changes to
src/*.lit files, and then run
It's well documented and will handle rebuilding, running tests.