Lualit

Lualit is literate programming for Lua. It lets you write your Lua code as a markdown file with a .lualit or .lua.md extension. Indented text is treated as Lua code. Everything else is treated as a comment. See an example: example.lua.md

Lualit files get pretty syntax highlighting on GitHub (via .lua.md) and can be compiled to pretty documentation with Docco.

Code is read more often than it is written. Lualit encourages self-documenting code by letting you write code for humans first. It's text-driven development!

Installing

To install with Luarocks:

luarocks install lualit

You can also just download the files and use them directly.

Using

Adding Lualit support is easy. Just require("lualit.register") and Lua will know how to load and run any Lualit file.

require("lualit.register")
local my_lualit_module = require("my_lualit_module")
print(my_lualit_module.some_function())

This will will register a loader that will look for and run .lualit and .lua.md files in your Lua path. The Lualit loader will be careful to retain the same line numbers for code, so so that errors will report correct line numbers.

Running a .lualit file directly is also easy:

lualit path/to/file.lualit

Compiling

You can also precompile Lualit to lua using the lit2lua command line utility. lit2lua takes Lualit via stdin and returns valid lua via stdout.

Here's how to use it to compile a Lualit file:

less -f "some_file.lua.md" | lit2lua > some_file.lua

Documentation with Docco

You can generate pretty documentation pages from your Lualit files using Docco. Just install docco:

npm install -g docco

And run it on your Lualit files:

docco path/to/file.lua.md

Editor Support

Syntax highlighting support:

Vim: gordonbrander/vim_lualit
SublimeText/TextMate
Emacs
Micro

To-do

.lualit to .lua
Dynamic loader
Docco compatibility
Precompile .lualit to luac binaries
Auto-compile .lualit to luac binaries at runtime (the way Python does with .pyc)
metalua .mlua.md to .lua
.moon.md to .lua

Maybe:

lualit format (wrap lines)
lit2lua --nice nicely formatted Lua (wraps lines, etc). This could be useful for distribution. But it wouldn't retain line numbers.
lua to lualit

Ideas:

How can we support writing tests inline, then removing them at compile time? Something similar to Python's doctest. Note this will make problems with line numbers if not careful.

Thanks

Inspired by Literate Coffeescript and Docco.

tilkinsc/lualit