Literate programming for Lua
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
docs
fixtures
lualit
test
.gitignore
LICENSE
README.md
lualit-0.0.2-1.rockspec
lualit.lua
makefile

README.md

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:

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.