入出力

現在のjqの入出力機能は最小限で、主に、いつ入力を読むかを制御する形で提供されています。このために、組込み関数 input と inputs があります。これらは、jq自体と同じ入力元（たとえば stdin や、コマンドラインで指定したファイル）から読み込みます。この2つの組込み関数と、jq自体の読込みは、互いに交互に実行できます。一般に、入力を1つ暗黙に読み込むのを防ぐため、null入力オプション -n と組み合わせて使います。

最小限の出力機能を提供する組込み関数は、debug と stderr です。jqプログラムの出力値は、常にJSONテキストとして stdout に出力されることを思い出してください。組込み関数 debug は、アプリケーション固有の動作を持つ場合があります。たとえば、libjqのC APIを使う、jq実行ファイル自体とは異なる実行ファイルの場合です。組込み関数 stderr は、入力をそのままの形式でstderrへ出力し、装飾は一切付けず、改行さえ付けません。

jqの組込み関数の多くは参照透過です。一定の入力に適用すると、一定で再現可能な値のストリームを生成します。入出力の組込み関数は、これに当てはまりません。

input

新しい入力を1つ出力します。

input を使う場合、通常はコマンドラインオプション -n を指定してjqを起動する必要があります。そうしないと、最初の入力が失われることに注意してください。

echo 1 2 3 4 | jq '[., input]' # [1,2] [3,4]

inputs

残っている入力を、1つずつすべて出力します。

これは、主にプログラムの入力全体に対して集約処理を行う際に便利です。inputs を使う場合、通常はコマンドラインオプション -n を指定してjqを起動する必要があります。そうしないと、最初の入力が失われることに注意してください。

echo 1 2 3 | jq -n 'reduce inputs as $i (0; . + $i)' # 6

debug, debug(msgs)

この2つのフィルターは . と同様ですが、副作用としてstderrに1つ以上のメッセージを生成します。

フィルター debug が生成するメッセージは、次の形式です。

["DEBUG:",<input-value>]

ここで、<input-value> は、入力値をコンパクトに表したものです。この形式は、将来変わる可能性があります。

フィルター debug(msgs) は、(msgs | debug | empty), . と定義されています。そのため、メッセージの内容を柔軟に指定でき、複数行のデバッグ文も作れます。

たとえば、次の式は、

1 as $x | 2 | debug("Entering function foo with $x == \($x)", .) | (.+1)

値3を生成しますが、次の2行をstderrへ書き出します。

["DEBUG:","Entering function foo with $x == 1"]
["DEBUG:",2]

stderr

入力をそのままのコンパクトな形式でstderrへ出力します。装飾は一切付けず、改行さえ付けません。

input_filename

現在フィルターで処理している入力のファイル名を返します。jqをUTF-8ロケールで実行していない場合、うまく動作しないことに注意してください。

input_line_number

現在フィルターで処理している入力の行番号を返します。