Pular para conteúdo

jq: Vinculações FFI do LuaJIT para jq

Instalação

Se você ainda não configurou a assinatura do repositório RPM, inscreva-se. Em seguida, você pode prosseguir com os seguintes passos.

CentOS/RHEL 7 ou 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

Para usar esta biblioteca Lua com NGINX, certifique-se de que o nginx-module-lua esteja instalado.

Este documento descreve lua-resty-jq v0.2.0 lançado em 06 de junho de 2025.

lua-resty-jq é um pequeno wrapper FFI do LuaJIT para jq

Olá Mundo com lua-resty-jq

-- <example-input> de 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()

Executar o código acima irá produzir (ou algo semelhante):

[
  {
    "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()

Aloca um contexto libjq.

teardown

syntax: jq:teardown()

Destrói o contexto libjq, liberando recursos.

compile

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

Retorna true se o programa foi compilado, caso contrário, retorna nil e o erro compilation failed.

Observe que atualmente não é possível inspecionar detalhes do erro de compilação. Se tiver dúvidas, experimente seu programa na CLI jq.

filter

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

Filtra data usando o programa previamente compilado. A tabela options pode conter flags que alteram o comportamento do filtro, semelhante a um subconjunto das opções da CLI para jq:

  • compact_output: Retorna a saída em uma forma compacta sem espaçamento adicional, e com cada objeto JSON em uma única linha. O padrão é true. Defina como false para uma saída "bonita".
  • raw_output: Saídas como strings brutas, não JSON entre aspas. O padrão é false.
  • join_output: Como raw_output, mas além disso não produz separadores de nova linha. O padrão é false.
  • ascii_output: jq geralmente produz pontos de código Unicode não-ASCII como UTF-8, mesmo que a entrada os especifique como sequências de escape (como "\u03bc"). Usando esta opção, você pode forçar jq a produzir saída puramente ASCII com cada caractere não-ASCII substituído pela sequência de escape equivalente. O padrão é false.
  • sort_keys: Saída dos campos de cada objeto com as chaves em ordem classificada. O padrão é false.
  • table_output: Retorna uma tabela semelhante a uma sequência de resultados codificados em vez de concatená-los em uma única string. O padrão é false.

Além disso, filter() aceita uma tabela como um terceiro argumento opcional. Quando fornecida, esta tabela será usada para armazenar resultados em vez de criar uma nova tabela para cada chamada a filter():

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

Fazer isso implica options.table_output = true, então esta opção deve ser explicitamente definida como false para receber um resultado em string:

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

NOTA: filter() adiciona um nil ao final da tabela de modo que o operador de comprimento (#buf) e ipairs(buf) retornem resultados precisos após a execução, mas não limpa a tabela. Os chamadores devem limpar a tabela por conta própria, se desejado.

Veja Também

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-jq.