Repository files navigation

This repository contains a Lua parser fordjot, a light markup syntax.

Despite being written in an interpreted language, thisimplementation is very fast (converting a 260K test document in141 ms on an M1 mac using the standardlua interpreter). Itcan produce an AST, rendered HTML, or a stream of match tokensthat identify elements by source position, which could be usedfor syntax highlighting or a linting tool.

We also provide a custom pandoc writer for djot (djot-writer.lua),so that documents in other formats can be converted to djotformat, and a custom pandoc reader (djot-reader.lua), so thatdjot documents can be converted to any format pandoc supports.To use these, just put them in your working directory and usepandoc -f djot-reader.lua to convert from djot, andpandoc -t djot-writer.lua to convert to djot. You'll need pandoc version2.18 or higher, and you'll need the djot library to be installedin yourLUA_PATH; seeInstalling, below. Ifyou're using the dev version of djot or don't want to worryabout the djot library being installed, you can createself-contained versions of the custom reader and writerusing theamalg tool:

luarocks install amalgmake djot-reader.amalg.luamake djot-writer.amalg.lua

These can be moved anywhere and do not require any Lua librariesto be installed.

To install djot usingluarocks, just

luarocks install djot

This will install both the library and the executabledjot.

If you just want to parse some input and produce HTML:

localdjot=require("djot")localinput="This is *djot*"localdoc=djot.parse(input)localhtml=djot.render_html(doc)

The AST is available as a Lua table,doc.ast.

To render the AST:

localrendered=djot.render_ast_pretty(doc)

Or as JSON:

localrendered=djot.render_ast_json(doc)

To alter the AST with a filter:

localsrc="return { str = function(e) e.text = e.text:upper() end }"localfilter=djot.filter.load_filter(src)djot.filter.apply_filter(doc,filter)

For a streaming parser:

forstartpos,endpos,annotationindjot.parse_events("*hello there*")doprint(startpos,endpos,annotation)end

(This will print start and end byte offsets into the inputfor annotated tokens.)

The code for djot (excluding the test suite) is standard Lua,compatible with lua 5.1--5.4 and luajit. Djot has no externaldependencies. You can run it without installing it using./run.sh.

make install will build the rockspec and install thelibrary and executable using luarocks. Once installed,the library can be used by Lua programs, and the executable canbe run usingdjot.djot -h will give help output.

If you can't assume that lua or luajit will be installed onthe target machine, you can usemake djot in theclibdirectory to create a portable binary that bakes in a luainterpreter and the necessary scripts.

make test will run the tests, andmake testall will alsorun some tests of pathological cases.

The code and documentation are released under the MIT license.