ラジコンカー

関数

jqでは、必要なロジックをまとめるために、自分だけのカスタム関数を定義できます。_関数_は組み込み関数とまったく同じように動作し、入力を受け取って、0個、1個、あるいはそれ以上の出力を出します。

関数を定義する

jqの_関数_は、次の構文で定義できます。

# no arguments
def funcname: expression;

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

• defキーワードで始まり、
• 関数の本体の前にコロンがあり、
• 本体は単一の式でできていて、
• セミコロンで終わり、
• jqの他の構文と同じように、読みやすさのために自由に空白を使えます。

関数をどこに書くか

_関数_は、使う前に定義しなければなりません。次のコードはエラーになります。

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

つまり、_関数_はjqコードの先頭、「メイン」の式より前に置く必要があります。

入れ子の関数

_関数_は入れ子にできます。

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

ここでは、Bの_関数_はAの本体の中でしか見えません。

スコープ

_関数_は、変数と入れ子の関数のために新しいスコープを導入します。

引数

_関数_の引数は、カンマではなく_セミコロン_で区切ります。 たとえば、数値を受け取り、それに数値を足して、さらに数値を掛ける_関数_は次のようになります。

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

引数は_式_です

関数の_引数_は値ではなく、フィルターです。 この意味で、これらは他の言語でコールバックと呼ばれるものと同じように動作します。

add_mul関数を例にしてみましょう。

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

ここで何が起きているのでしょうか？

• adder引数には_式_. + 5が入ります
  • 関数が. + adderを行うと、それは. + . + 5になります
  • . == 10なので、これは25と評価されます
• 同様に、multiplier引数は_式_. - 2です
  • これは8と評価されます
  • すると、結果は25 * 8 == 200になります

引数を値として扱う

_引数_を変数として「実体化」したいこともあるでしょう。

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

これには省略記法があります。

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

これは単なる「糖衣構文」にすぎないことに注意してください。$の付いていないargという名前も、_関数_のスコープ内に残っています。

アリティ

_関数_にはアリティがあります。つまり、受け取る_引数_の数です。

_関数_は、同じ名前を違う_アリティ_で使うことができます。組み込みのrange関数がその例で、range/1、range/2、range/3がすべて共存しています。

これは、引数を介して状態を引き継ぐ再帰関数を定義するのに便利です。たとえば、mapは次のように実装することも_できます_。

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]

再帰

jqは末尾呼び出し最適化を行いますが、それはアリティが0の関数だけです。

モジュール

jqのモジュールは、関数だけを含むファイルです。 モジュールは、includeまたはimportコマンドでjqのプログラムに取り込みます。