Auto de control remoto

Funciones

Puedes definir tus propias funciones personalizadas en jq para encapsular la lógica que necesites. Las funciones se comportan igual que las integradas: reciben una entrada y emiten cero, una o más salidas.

Definir una función

Puedes definir una función de jq con la siguiente sintaxis:

# no arguments
def funcname: expression;

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

• empieza con la palabra clave def,
• dos puntos antes del cuerpo de la función,
• el cuerpo consiste en una sola expresión,
• termina con un punto y coma,
• como en el resto de la sintaxis de jq, puedes usar espacios en blanco arbitrarios para que se lea mejor.

Dónde colocar las funciones

Las funciones deben definirse antes de usarse: esto es un error:

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

Esto implica que debes colocar las funciones al inicio de tu código de jq, antes de la expresión «principal».

Funciones anidadas

Las funciones se pueden anidar:

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

Aquí, la función B solo es visible en el cuerpo de A.

Ámbito

Una función introduce un nuevo ámbito para las variables y las funciones anidadas.

Argumentos

Los argumentos de una función se separan con punto y coma, no con comas. Por ejemplo, una función que recibe un número y luego suma un número y multiplica por un 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

Los argumentos son expresiones

Los argumentos de una función son filtros, no valores. En este sentido, actúan como lo que otros lenguajes describen como callbacks:

Usando la función add_mul como ejemplo:

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

¿Qué está pasando aquí?

• el argumento adder recibe la expresión . + 5
  • cuando la función hace . + adder, eso se convierte en . + . + 5
  • eso se evalúa como 25, ya que . == 10
• de manera similar, el argumento multiplier es la expresión . - 2
  • eso se evalúa como 8
  • entonces el resultado es 25 * 8 == 200

Argumentos como valores

A veces vas a querer «materializar» un argumento en una variable:

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

Hay una forma abreviada de hacer esto:

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

Ten en cuenta que esto es solo «azúcar sintáctico»: el nombre arg sin $ sigue estando en el ámbito de la función.

Aridad

Las funciones tienen una aridad: la cantidad de argumentos que reciben.

Las funciones pueden usar el mismo nombre con distintas aridades. La función integrada range lo demuestra: range/1, range/2 y range/3 coexisten.

Esto puede ser útil para definir funciones recursivas que llevan estado a través de los argumentos. Por ejemplo, map podría implementarse así:

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]

Recursión

jq realiza optimización de llamadas de cola, pero solo para funciones de aridad 0.

Módulos

Un módulo de jq es un archivo que contiene solo funciones. Los módulos se incluyen en un programa de jq con los comandos include o import.