Voiture télécommandée

Les fonctions

Tu peux définir tes propres fonctions personnalisées en jq pour encapsuler la logique dont tu as besoin. Les fonctions se comportent exactement comme les fonctions natives : elles prennent une entrée et émettent zéro, une ou plusieurs sorties.

Définis une fonction

Tu peux définir une fonction jq avec la syntaxe suivante :

# no arguments
def funcname: expression;

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

• commence par le mot-clé def,
• un deux-points avant le corps de la fonction,
• le corps est constitué d'une seule expression,
• se termine par un point-virgule,
• comme dans le reste de la syntaxe jq, tu peux utiliser des espaces arbitraires pour la lisibilité.

Où placer les fonctions

Les fonctions doivent être définies avant d'être utilisées : ceci provoque une erreur :

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

Cela implique que tu dois placer les fonctions en haut de ton code jq, avant l'expression « principale ».

Fonctions imbriquées

Les fonctions peuvent être imbriquées :

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

Ici, la fonction B n'est visible que dans le corps de A.

Portée

Une fonction introduit une nouvelle portée pour les variables et les fonctions imbriquées.

Arguments

Les arguments d'une fonction sont séparés par des points-virgules, et non par des virgules. Par exemple, une fonction qui prend un nombre, puis ajoute un nombre et multiplie par un nombre :

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

Les arguments sont des expressions

Les arguments d'une fonction sont des filtres, pas des valeurs. En ce sens, ils se comportent comme ce que d'autres langages appellent des callbacks :

Prenons la fonction add_mul comme exemple :

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

Que se passe-t-il ici ?

• l'argument adder reçoit l'expression . + 5
  • quand la fonction fait . + adder, cela devient . + . + 5
  • ce qui vaut 25 puisque . == 10
• de même, l'argument multiplier est l'expression . - 2
  • ce qui vaut 8
  • le résultat est alors 25 * 8 == 200

Les arguments en tant que valeurs

Parfois, tu voudras « matérialiser » un argument dans une variable :

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

Il existe une notation abrégée pour cela :

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

Note bien qu'il s'agit simplement de « sucre syntaxique » : le nom arg sans $ reste dans la portée de la fonction.

Arité

Les fonctions ont une arité, c'est-à-dire le nombre d'arguments qu'elles prennent.

Des fonctions peuvent porter le même nom avec des arités différentes. La fonction native range le montre : range/1, range/2 et range/3 coexistent toutes les trois.

Cela peut être utile pour définir des fonctions récursives qui transportent un état via leurs arguments. Par exemple, map pourrait être implémentée comme ceci :

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]

Récursivité

jq effectue une optimisation des appels terminaux, mais uniquement pour les fonctions d'arité 0.

Modules

Un module jq est un fichier qui ne contient que des fonctions. Les modules sont inclus dans un programme jq avec les commandes include ou import.