Liste de courses

Les bases

On suppose que tu connais la syntaxe et les types de données JSON.

jq fonctionne en faisant passer les données JSON entrantes à travers une expression unique (écrite sous la forme d'un enchaînement de filtres) pour obtenir les données transformées souhaitées.

Filtres et tubes

Les filtres sont aussi appelés expressions.

Un filtre prend une entrée et produit une sortie. Comme dans un shell Unix, on peut relier des filtres avec un tube | pour connecter la sortie d'un filtre à l'entrée d'un autre.

Le filtre identité : .

C'est le filtre le plus simple. Il transmet simplement son entrée à sa sortie.

$ echo '[1, 2, 3]' | jq '.'
[
  1,
  2,
  3
]

Les tableaux

Voici une introduction rapide à la manipulation des tableaux. On verra ce sujet plus en détail plus loin.

On accède aux éléments d'un tableau avec des crochets, et l'indexation commence à zéro.

$ echo '[10, 20, 30]' | jq '.[1]'
20

Un filtre peut construire un tableau en entourant une expression de [ et ]

• avec une liste connue d'éléments :

  jq -n '[1, 2, 3]'
  

• pour rassembler un flux d'éléments : par exemple, range est une fonction qui produit un flux de nombres

  $ jq -n 'range(10; 70; 15)'
  10
  25
  40
  55
  

  L'utilisation de [] rassemble les résultats de l'expression dans un tableau

  $ jq -c -n '[range(10; 70; 15)]'
  [10,25,40,55]
  

La virgule est un opérateur

La virgule n'est pas seulement une syntaxe qui sépare les éléments d'un tableau. La virgule est un opérateur qui assemble des flux.

Par exemple, [1, 2, 3] est un filtre qui utilise le constructeur de tableau [] pour rassembler le résultat de l'assemblage des trois expressions 1, 2 et 3.

Tu as remarqué les points-virgules dans range(10; 70; 15) ci-dessus ? Comme les virgules ont un rôle spécifique dans le langage jq, les fonctions qui prennent plusieurs arguments utilisent des points-virgules pour séparer les arguments.

Les objets

Une introduction rapide aux objets.

Comme dans beaucoup de langages de programmation, on utilise des points pour accéder aux propriétés d'un objet

$ echo '{"foo": {"bar": "qux"}}' | jq '.foo.bar'
"qux"

$ echo '{"foo bar": "qux"}' | jq '.["foo bar"]'
"qux"

Tu peux construire un objet avec {} et des paires key: value. Les guillemets ne sont pas nécessaires autour des clés qui sont des strings « simples ».

jq -n '{question: (6 * 9), answer: 42}'

produit

{
  "question": 54,
  "answer": 42
}

Pour traiter la clé comme une expression, il faut l'entourer de parenthèses (l'exemple suivant produit lui aussi le même résultat que ci-dessus).

echo '[{"key":"question", "value":54}, {"key":"answer", "value":42}]' \
| jq '{(.[0].key): .[0].value, (.[1].key): .[1].value}'

Enchaînements de filtres

Par exemple, avec un fichier file.json contenant

{
  "key1": "value1",
  "key2": [5, 15, 25]
}

Calculons la longueur du tableau key2 :

$ jq '.key2 | length' file.json
3

On envoie la sortie de l'expression .key2 en entrée de length, qui, sans surprise, produit le nombre d'éléments du tableau.

Un filtre peut ignorer son entrée

Dans cet exemple, les données JSON d'entrée sont ignorées et n'ont aucun impact sur la sortie :

$ echo '{"answer": 42}' | jq '6 * 9'
54

Un filtre peut produire des flux de données

Un filtre peut produire plusieurs valeurs. Par exemple, le filtre .[] produit chaque élément d'un tableau comme une valeur distincte :

$ jq -n -c '[1, 2, 3]'
[1,2,3]

$ jq -n -c '[1, 2, 3] | .[]'
1
2
3

En enchaînant un tel filtre avec un autre, le deuxième filtre sera exécuté pour chaque valeur :

$ jq -n -c '[1, 2, 3] | .[] | . * 2'
2
4
6

C'est une sorte d'itération implicite. Une fois que tu as compris cette technique, tu réalises que des filtres jq très puissants peuvent être très concis.

Les parenthèses

Les parenthèses servent à regrouper des sous-expressions pour imposer l'ordre des opérations, comme dans d'autres langages. En jq, le besoin de parenthèses peut sembler un peu surprenant.

Par exemple, imaginons que l'on veuille construire un tableau à 2 éléments : la racine carrée de 9, et e élevé à la puissance 1. Les deux expressions individuelles sont 9 | sqrt et 1 | exp. On s'attend à ce que la sortie soit le tableau [3, 2.7...]

$ jq -n '[ 9|sqrt, 1|exp ]'
[
  20.085536923187668,
  2.718281828459045
]

Pourquoi n'a-t-on pas obtenu ce qu'on attendait ? jq interprète cela comme ceci :

[ ((9|sqrt), 1) | exp ]

jq construit un flux de deux éléments (3 et 1) qui sont chacun donnés à exp.

Il faut s'assurer que exp ne prend qu'un seul nombre en entrée. Autrement dit, il faut imposer que le tube soit évalué avant la virgule.

$ jq -n '[ 9|sqrt, (1|exp) ]'
[
  3,
  2.718281828459045
]

Fonctions et opérateurs

Sans entrer dans les détails (les fonctions feront l'objet d'un autre exercice), voici quelques fonctions intégrées utiles :

• length

  Étant donné un tableau en entrée, produit le nombre d'éléments du tableau.

  $ jq -n '[10, 20, 30, 40] | length'
  4
  

• +

  Cet opérateur fait des choses différentes selon le type de ses opérandes : il additionne des nombres, il concatène des strings, il ajoute des tableaux, il fusionne des objets.

  $ jq -c -n '
      3 + 4,
      "foo" + "bar",
      ["a", "b"] + ["c"],
      {"m": 10} + {"n": 20}
  '
  7
  "foobar"
  ["a","b","c"]
  {"m":10,"n":20}
  

  add est une fonction qui prend un tableau et renvoie un élément obtenu en additionnant tous les éléments selon les règles de +. [1, 2, 3] | add produit 6.

• map

  Étant donné un tableau en entrée et un filtre en argument, produit un tableau où le filtre est appliqué à chaque élément

  $ jq -c -n '[10, 20, 30, 40] | map(. / 5)'
  [2,4,6,8]
  

• select

  Étant donné une entrée et un filtre en argument :

  • si le filtre appliqué à l'argument donne une valeur vraie, produit l'entrée inchangée
  • sinon, ne produit rien (pas la valeur null, vraiment aucune sortie)

  Par exemple, étant donné quelques nombres, on sélectionne ceux qui sont divisibles par 3

  $ jq -n 'range(10) | select(. % 3 == 0)'
  0
  3
  6
  9
  

  Rappelle-toi que range produit un flux de nombres. select sera appelé une fois pour chaque nombre. Seuls les nombres qui « passent » l'expression sont produits.

  On a souvent besoin de sélectionner des éléments d'un tableau. Il y a plusieurs façons de procéder.

  Avec l'entrée ["Anne", "Bob", "Cathy", "Dave"], sélectionne les noms de longueur 4.

  • utilise map et select ensemble

    map(select(length == 4))
    

  • éclate le tableau en éléments, applique select sur ce flux, puis rassemble les résultats

    [ .[] | select(length == 4) ]
    

Les commentaires

Les commentaires commencent par le caractère # et se poursuivent jusqu'à la fin de la ligne.