[[Vorlage(Getestet, jammy)]]

{{{#!vorlage Wissen
[:Pakete installieren: Installation von Programmen]
[:Terminal: Ein Terminal öffnen]
}}}

[[Inhaltsverzeichnis(1)]]

[[Bild(jq.png, 48, align=left)]]
[https://stedolan.github.io/jq/ jq] {en} ist ein Kommandozeilen-Programm, mit dem auf einen Stream von [wikipedia:JavaScript Object Notation:JSON]-Daten verschiedene Filter angewandt werden können. Auf diese Weise können gewünschte Daten aus dem JSON-Stream extrahiert werden. Es können verschiedene Filter über Pipes miteinander verbunden werden. 

= Installation =
jq kann direkt aus den Quellen installiert werden [1]. 

{{{#!vorlage Paketinstallation
jq, universe
}}}

Das Programm kann dann sofort gestartet werden.

= Benutzung =
Die allgemeine Syntax von jq lautet:

{{{#!vorlage Befehl
jq [OPTIONEN] <JQ FILTER> [DATEIEN]
}}}

Wird kein `DATEI` angegeben, liest das Programm von der Standardeingabe.

== Optionen ==
Das Programm kennt unter anderem die folgenden Optionen:

{{{#!vorlage Tabelle
<-2 rowclass="titel">Auswahl von Optionen
+++
<rowclass="kopf">Option
Beschreibung
+++
`-c`
kompakte (einzeilige) Ausgabe
+++
<rowclass="highlight">`-n`
Eingabewert 'nul', nützlich um JSON-Dateien zu generieren. 
+++
`-s`
Liest den Eingabestream in einen Array. 
+++
<rowclass="highlight">`-r`
''"raw"'' Ausgabe (keine Anführungszeichen um strings) 
+++
`-R`
''"raw"'' Eingabe (jede Zeile wird als string übergeben)
}}}

Weitere Optionen kann man in der [:man:Manpage] nachlesen. 

== Filter ==
=== Beispiel ===

Im Folgenden wird angenommen, dass die Datei ''"simpsons.json"'' folgenden Inhalt hat: 
{{{#!code json
[
  {
      "Name": "Homer Simpson",
    "Alter": 39,
    "Kinder": ["Bart","Lisa","Maggie"],
    "Jobs": ["techinscher Überwacher im KKW","Astronaut","Fett-Verkäufer"],
    "Hobbies": ["Bowling","Angeln"],
    "Freunde": ["Carl", "Lenny", "Moe"]
  },
  {
      "Name": "Marge Simpson",
    "Alter": 34,
    "Kinder": ["Bart","Lisa","Maggie"],
    "Jobs": ["Hausfrau","KKW Angestellte","Polizistin","Telefonseelsorgerin"],
    "Hobbies": ["Malen","Zeichnen"]
  }
]
}}}

===Einfache Filter===

Der einfachste Filter ist die Identität ''"."'', bei welcher Input und Output identisch sind (abgesehen von der Formatierung).

{{{#!vorlage Befehl
jq "." simpsons.json
}}}

gibt den Inhalt der Datei formatiert aus. 

Bei der Beispiel-Datei handelt es sich um einen Array von Daten, auf Arrays kann mit dem ''"[]"'' Operator zugegriffen werden, so gibt 

{{{#!vorlage Befehl
jq ".[0]" simpsons.json
}}}

{{{#!code json
{
  "Name": "Homer Simpson",
  "Alter": 39,
  "Kinder": [
    "Bart",
    "Lisa",
    "Maggie"
  ],
  "Jobs": [
    "techinscher Überwacher im KKW",
    "Astronaut",
    "Fett-Verkäufer"
  ],
  "Hobbies": [
    "Bowling",
    "Angeln"
  ],
  "Freunde": [
    "Carl",
    "Lenny", 
    "Moe",
  ]
}

}}}

das Objekt mit ''"Name"'' ''"Homer Simpsons"'' zurück. 

Der Filter ''".[]"'' gibt alle Objekte des Arrays zurück. Werden diese weiter gefiltert 

{{{#!vorlage Befehl
jq ".[].Name" simpsons.json 
}}}

erhält man beispielsweise alle Namen der Objekte der Liste:

{{{
"Homer Simpson"
"Marge Simpson"
}}}

Will man diese zu einer neuen Liste verknüpfen, geht dies mit ''"[.[].Name]"'': 

{{{#!vorlage Befehl
jq "[.[].Name]" simpsons.json 
}}}

{{{#!code json
[
  "Homer Simpson",
  "Marge Simpson"
]
}}}

Mit dem Pipe-Operator ''"|"'' können verschiedene Filter verknüpft werde, der vorherige Filter kann auch als ''"[.[]|.Name]"'' geschrieben werden. 

===Komplexere Filter====

Der Additionsoperator ''"+"'' kann auf Zahlen (normale Addition), Strings (werden aneinander gehangen) , Arrays und Objekte angewendet werden. Beispielsweise liefert 

{{{#!vorlage Befehl
jq ".[0]+.[1]" simpsons.json
}}}


{{{#!code json
{
  "Name": "Marge Simpson",
  "Alter": 34,
  "Kinder": [
    "Bart",
    "Lisa",
    "Maggie"
  ],
  "Jobs": [
    "Hausfrau",
    "KKW Angestellte",
    "Polizistin",
    "Telefonseelsorgerin"
  ],
  "Hobbies": [
    "Malen",
    "Zeichnen"
  ],
  "Freunde": [
    "Carl",
    "Lenny", 
    "Moe"
  ]
}
}}}

ein Objekt, mit den Werten von Marge und den Freunden von Homer (weil bei gleichen Werten der rechts vom Plus-Zeichen genommen wird). 

{{{#!vorlage Befehl
jq ".[0].Jobs+.[1].Jobs" simpsons.json 
}}}


{{{#!code json
[
  "techinscher Überwacher im KKW",
  "Astronaut",
  "Fett-Verkäufer",
  "Hausfrau",
  "KKW Angestellte",
  "Polizistin",
  "Telefonseelsorgerin"
]
}}}

liefert eine Liste mit den Jobs von Homer und Marge. 


Der select-Filter ''"select(foo)"'' reicht seinen Input für die Fälle durch, in denen ''"foo"'' wahr ist, zum Beispiel gibt

{{{#!vorlage Befehl
jq ".[]|select(.Name==\"Marge Simpson\")" simpsons.json 
}}}

{{{#!code json
{
  "Name": "Marge Simpson",
  "Alter": 34,
  "Kinder": [
    "Bart",
    "Lisa",
    "Maggie"
  ],
  "Jobs": [
    "Hausfrau",
    "KKW Angestellte",
    "Polizistin",
    "Telefonseelsorgerin"
  ],
  "Hobbies": [
    "Malen",
    "Zeichnen"
  ]
}

}}}

das Objekt von ''"Marge Simpson"'' zurück, ohne dass der Index angegeben werden muss.  Die Kombination mit dem ''"contains()"''-Filter ist ebenso nützlich 


{{{#!vorlage Befehl
jq ".[].Jobs|.[]|select(contains(\"KKW\"))" simpsons.json
}}}

{{{
"techinscher Überwacher im KKW"
"KKW Angestellte"
}}}

Dieser Filter gibt alle Jobs zurück, die den String ''"KKW"'' enthalten. 

Mit dem ''"match()"'' filter können reguläre Ausdrücke gesucht werden, beispielsweise liefert 

{{{#!vorlage Befehl
jq ".[].Kinder|.[]|match(\"^....$\")" simpsons.json
}}}

{{{#!code json
{
  "offset": 0,
  "length": 4,
  "string": "Bart",
  "captures": []
}
{
  "offset": 0,
  "length": 4,
  "string": "Lisa",
  "captures": []
}
{
  "offset": 0,
  "length": 4,
  "string": "Bart",
  "captures": []
}
{
  "offset": 0,
  "length": 4,
  "string": "Lisa",
  "captures": []
}
}}}

alle Kinder mit einer Namenslänge von vier Buchstaben, sowie zusätzliche Informationen. 

jq ist mit sehr vielen weiteren Filtern ausgestattet, über die man sich auf der [https://stedolan.github.io/jq/manual/ manual-page] {en} des Projektes informieren kann. 

= Links =
 * [https://stedolan.github.io/jq/manual/ jq-manual] {en}
 * [https://jqplay.org/ jq online live testen] {en}

#tag: Shell, Programmierung, JSON