Ferngesteuertes Auto

Funktionen

Du kannst in jq deine eigenen benutzerdefinierten Funktionen definieren, um die Logik zu kapseln, die du brauchst. Funktionen verhalten sich wie eingebaute Funktionen: Sie nehmen einen Eingabewert und geben null, eine oder mehrere Ausgaben aus.

Eine Funktion definieren

Du kannst eine jq-Funktion mit der folgenden Syntax definieren:

# no arguments
def funcname: expression;

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

• beginnt mit dem Schlüsselwort def,
• ein Doppelpunkt vor dem Funktionskörper,
• der Körper besteht aus einem einzigen Ausdruck,
• endet mit einem Semikolon,
• wie im restlichen jq-Syntax kannst du beliebige Leerzeichen zur besseren Lesbarkeit verwenden.

Wohin Funktionen gehören

Funktionen müssen definiert werden, bevor sie verwendet werden. Das hier ist ein Fehler:

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

Das bedeutet, du musst Funktionen oben in deinem jq-Code platzieren, vor dem „Haupt“-Ausdruck.

Verschachtelte Funktionen

Funktionen können verschachtelt werden:

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

Hier ist die B-Funktion nur im Körper von A sichtbar.

Gültigkeitsbereich

Eine Funktion führt einen neuen Gültigkeitsbereich für Variablen und verschachtelte Funktionen ein.

Argumente

Funktionsargumente werden durch Semikolons getrennt, nicht durch Kommas. Zum Beispiel eine Funktion, die eine Zahl entgegennimmt und dann eine Zahl addiert und mit einer Zahl multipliziert:

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

Argumente sind Ausdrücke

Funktionsargumente sind Filter, keine Werte. In diesem Sinn verhalten sie sich wie das, was andere Sprachen als Callbacks bezeichnen:

Am Beispiel der add_mul-Funktion:

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

Was passiert hier?

• das adder-Argument erhält den Ausdruck . + 5
  • wenn die Funktion . + adder ausführt, wird daraus . + . + 5
  • das ergibt 25, da . == 10
• ähnlich ist das multiplier-Argument der Ausdruck . - 2
  • das ergibt 8
  • dann ist das Ergebnis 25 * 8 == 200

Argumente als Werte

Manchmal möchtest du ein Argument in eine Variable „materialisieren“:

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

Dafür gibt es eine Kurzschreibweise:

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

Beachte, dass das nur „syntaktischer Zucker“ ist: Der Name arg ohne $ ist weiterhin im Gültigkeitsbereich der Funktion.

Stelligkeit

Funktionen haben eine Stelligkeit: die Anzahl der Argumente, die sie entgegennehmen.

Funktionen können denselben Namen mit unterschiedlichen Stelligkeiten verwenden. Die eingebaute Funktion range zeigt das: range/1, range/2 und range/3 existieren alle nebeneinander.

Das kann nützlich sein, um rekursive Funktionen zu definieren, die ihren Zustand über Argumente tragen. Zum Beispiel könnte map so implementiert werden:

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]

Rekursion

jq führt Tail-Call-Optimierung durch, aber nur für Funktionen mit Stelligkeit 0.

Module

Ein jq-Modul ist eine Datei, die nur Funktionen enthält. Module werden mit den Befehlen include oder import in ein jq-Programm eingebunden.