jq: Привязки LuaJIT FFI к jq

Установка

Если вы еще не настроили подписку на репозиторий RPM, подпишитесь. Затем вы можете продолжить с следующими шагами.

CentOS/RHEL 7 или Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-jq

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-jq

Чтобы использовать эту библиотеку Lua с NGINX, убедитесь, что nginx-module-lua установлен.

Этот документ описывает lua-resty-jq v0.2.0, выпущенный 6 июня 2025 года.

---

lua-resty-jq — это небольшая обертка LuaJIT FFI для jq

Hello World с lua-resty-jq

-- <example-input> из https://api.github.com/repos/stedolan/jq/commits?per_page=5
local jq = require "resty.jq".new()

jq:compile("[ .[] | {message: .commit.message, name: .commit.committer.name} ]")
local output = jq:filter(<example-input>)

print(output)

jq:teardown()

Запуск приведенного выше кода выведет (или что-то похожее):

[
  {
    "message": "Add some missing code quoting to the manual",
    "name": "William Langford"
  },
  {
    "message": "Reduce allocation on string multiplication",
    "name": "William Langford"
  },
  {
    "message": "Fix multiple string multiplication",
    "name": "William Langford"
  },
  {
    "message": "Fix error handling in strftime",
    "name": "William Langford"
  },
  {
    "message": "Makefile: prepend srcdir to jq.1.prebuilt to fix out of source compilation",
    "name": "William Langford"
  }
]

new

syntax: jq, err = require("resty.jq").new()

Выделяет контекст libjq.

teardown

syntax: jq:teardown()

Уничтожает контекст libjq, освобождая ресурсы.

compile

syntax: ok, err = jq:compile(program)

Возвращает true, если программа была скомпилирована, в противном случае nil и ошибка compilation failed.

Обратите внимание, что в настоящее время невозможно просмотреть детали ошибки компиляции. Если вы сомневаетесь, попробуйте вашу программу в CLI jq.

filter

syntax: res, err = jq:filter(data, options)

Фильтрует data, используя ранее скомпилированную программу. Таблица options может содержать флаги, которые изменяют поведение фильтра, аналогично подмножеству параметров CLI для jq:

• compact_output: Возвращает вывод в компактной форме без дополнительных пробелов и с каждым JSON-объектом на одной строке. По умолчанию true. Установите в false для "красивого" вывода.
• raw_output: Выводит как необработанные строки, а не JSON с кавычками. По умолчанию false.
• join_output: Как raw_output, но дополнительно не выводит разделители новой строки. По умолчанию false.
• ascii_output: jq обычно выводит не-ASCII символы Unicode как UTF-8, даже если входные данные указывают их как escape-последовательности (например, "\u03bc"). Используя эту опцию, вы можете заставить jq производить чистый ASCII-вывод, заменяя каждый не-ASCII символ эквивалентной escape-последовательностью. По умолчанию false.
• sort_keys: Выводит поля каждого объекта с ключами в отсортированном порядке. По умолчанию false.
• table_output: Возвращает последовательность, подобную таблице, закодированных результатов вместо конкатенации их в одну строку. По умолчанию false.

Кроме того, filter() принимает таблицу в качестве необязательного 3-го аргумента. Когда она предоставлена, эта таблица будет использоваться для хранения результатов вместо создания новой таблицы для каждого вызова filter():

local buf = {}
local res, err = jq:filter(data, nil, buf)
for _, elem in ipairs(buf) do
  -- ...
end

Это подразумевает, что options.table_output = true, поэтому эта опция должна быть явно установлена в false, чтобы получить строковый результат:

local buf = {}
local res, err = jq:filter(data, { table_output = false }, buf)
print(res)

ПРИМЕЧАНИЕ: filter() добавляет завершающий nil в таблицу, так что оператор длины (#buf) и ipairs(buf) возвращают точные результаты после выполнения, но он не очищает таблицу. Вызывающие функции должны очищать таблицу самостоятельно, если это необходимо.

См. также

• lua-jq

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-jq.