Carro telecomandado

Funções

Podes definir as tuas próprias funções personalizadas em jq para encapsular a lógica de que precisares. As funções funcionam exatamente como as funções nativas: recebem um valor de entrada e emitem zero, uma ou mais saídas.

Definir uma função

Podes definir uma função de jq com a seguinte sintaxe:

# no arguments
def funcname: expression;

# or with arguments
def funcname(args): expression;

• começa com a palavra-chave def,
• dois pontos antes do corpo da função,
• o corpo é constituído por uma única expressão,
• termina com um ponto e vírgula,
• tal como no resto da sintaxe do jq, podes usar espaços em branco à vontade para facilitar a leitura.

Onde colocar as funções

As funções têm de ser definidas antes de serem usadas: isto dá erro:

def A: B(10);
def B(n): n + 1;
A
# => error: B/1 is not defined

Isto implica que tens de colocar as funções no início do teu código jq, antes da expressão «principal».

Funções aninhadas

As funções podem ser aninhadas:

def A:
    def B(n): n + 1;
    B(10)
    ;
A
# => 11

Aqui, a função B só é visível no corpo de A.

Âmbito

Uma função introduz um novo âmbito para variáveis e funções aninhadas.

Argumentos

Os argumentos de uma função são separados por pontos e vírgulas, não por vírgulas. Por exemplo, uma função que recebe um número e depois soma um número e multiplica por um número:

def add_mul(adder; multiplier): (. + adder) * multiplier;

10 | add_mul(5; 4)    # => 60

10 | add_mul(5, 4)
# error: add_mul/1 is not defined

Os argumentos são expressões

Os argumentos de uma função são filtros, não valores. Neste sentido, comportam-se como aquilo a que outras linguagens chamam callbacks:

Usando a função add_mul como exemplo:

10 | add_mul(. + 5; . - 2)    # => 200

O que está aqui a acontecer?

• o argumento adder recebe a expressão . + 5
  • quando a função faz . + adder, isso passa a ser . + . + 5
  • isso dá 25, uma vez que . == 10
• de forma semelhante, o argumento multiplier é a expressão . - 2
  • isso dá 8
  • e o resultado é 25 * 8 == 200

Argumentos como valores

Às vezes vais querer «materializar» um argumento numa variável:

def my_func(arg):
    arg as $arg
    | other stuff ...
;

Há uma forma abreviada de fazer isto:

def my_func($arg):
    other stuff ...
;

Repara que isto é apenas «açúcar sintático»: o nome arg sem $ continua dentro do âmbito da função.

Aridade

As funções têm uma aridade: o número de argumentos que recebem.

As funções podem usar o mesmo nome com aridades diferentes. A função nativa range demonstra isto: range/1, range/2 e range/3 coexistem.

Isto pode ser útil para definir funções recursivas que transportam estado através dos argumentos. Por exemplo, map poderia ser implementado assim:

def my_map($accumulator; func):
    if length == 0
        then $accumulator
        else first as $elem | .[1:] | my_map($accumulator + [$elem | func]; func)
    end
    ;

def my_map(func):
    my_map([]; func)
    ;

[1, 2, 3, 4] | my_map(. * 10)   # => [10, 20, 30, 40]

Recursão

O jq faz otimização de chamadas em cauda, mas apenas para funções de aridade 0.

Módulos

Um módulo de jq é um ficheiro que contém apenas funções. Os módulos são incluídos num programa jq com os comandos include ou import.