Pandoc умеет фильтровать AST документа между парсингом и генерацией. Раньше для этого использовались внешние фильтры через JSON: программа читала AST из stdin, меняла и писала в stdout. Это удобно, но есть минусы: накладные расходы на сериализацию и зависимость от интерпретатора и библиотек в окружении пользователя.
Начиная с Pandoc 2.0, в сам исполнительный файл встроен интерпретатор Lua 5.4 и библиотека для работы с AST. Фильтры пишутся на Lua, обходятся без внешних зависимостей и работают напрямую — без JSON-прокладки. Пример: замена Strong на SmallCaps:
return {
Strong = function(elem)
return pandoc.SmallCaps(elem.content)
end,
}
Такой фильтр сохраняют в .lua файл и запускают через pandoc --lua-filter=smallcaps.lua. В тесте с преобразованием мануала Pandoc в HTML Lua-фильтр отработал за 1.03 с, почти как сам pandoc (1.01 с), тогда как JSON-фильтры на Haskell и Python заняли 1.36 и 1.40 с соответственно — разница из-за лишнего ввода-вывода.
Структура фильтра — это таблица, где ключи — имена элементов AST (Str, Para, Meta), а значения — функции, которые получают элемент и должны вернуть nil (оставить как есть), объект того же типа (заменить) или список объектов (вставить). Для последовательностей Inlines и Blocks есть специальные функции — они получают сразу весь список. Можно задать порядок обхода: по умолчанию 'typewise' (сначала все Inline, потом Inline-списки, потом Block и т.д.), но можно и 'topdown' — сверху вниз, с возможностью оборвать обход, вернув false вторым значением.
В глобальных переменных доступны FORMAT (текущий формат вывода), PANDOC_VERSION, PANDOC_API_VERSION, PANDOC_SCRIPT_FILE и другие. Модуль pandoc предоставляет конструкторы элементов (Str, Para, CodeBlock, Table и т.д.) и утилиты вроде walk для применения фильтра к поддереву, pipe для запуска внешних команд, mediabag для встраивания бинарных данных.
В статье приведено много примеров: замена макроса {{helloworld}} на выделенный текст, центрирование изображений в LaTeX и HTML, удаление пробелов перед авторскими цитатами, подсчёт слов в документе, создание таблицы из Lua, конвертация ABC-ноты в изображение через abcm2ps и ImageMagick, построение TikZ-рисунков с помощью pdflatex и pdf2svg.
Для отладки рекомендуют luacheck для статического анализа, модуль pandoc-lua-logging от Уильяма Луптона для pretty-print AST, а также отладчик mobdebug вместе с редактором ZeroBrane Studio — он позволяет ставить брейкпоинты и шагать по фильтру.