Libx jq ドキュメント

    このページの内容

    モジュール

    jqにはライブラリ／モジュールの仕組みがあります。モジュールは、ファイル名が .jq で終わるファイルです。

    プログラムがインポートするモジュールは、既定の検索パスで探します。以下を参照してください。import と include の指示では、インポートする側がこのパスを変更できます。

    検索パス内のパスには、さまざまな置換を適用します。

    ~/ で始まるパスでは、~ をユーザーのホームディレクトリで置き換えます。

    $ORIGIN/ で始まるパスでは、$ORIGIN をjq実行ファイルがあるディレクトリで置き換えます。

    ./ で始まるパス、または . というパスでは、. を、そのファイルを取り込む側のファイルのパスで置き換えます。コマンドラインで指定した最上位のプログラムの場合は、現在のディレクトリを使います。

    インポートの指示では、検索パスを任意で指定できます。その後ろに既定の検索パスを追加します。

    既定の検索パスは、コマンドラインオプション -L に指定した検索パスです。それがなければ、["~/.jq", "$ORIGIN/../lib/jq", "$ORIGIN/../lib"] です。

    nullまたは空文字列のパス要素は、検索パスの処理を終了させます。

    相対パス foo/bar の依存モジュールは、指定した検索パス内の foo/bar.jq と foo/bar/bar.jq で探します。これは、モジュールをバージョン管理ファイルやREADMEファイルなどと一緒にディレクトリへ置けるようにしつつ、単一ファイルのモジュールも使えるようにするためです。

    曖昧さを避けるため、同じ名前のパス要素を連続させることは認められていません。たとえば、foo/foo です。

    例として、-L$HOME/.jq を指定すると、モジュール foo は、$HOME/.jq/foo.jq と $HOME/.jq/foo/foo.jq に見つかります。

    ユーザーのホームディレクトリに .jq があり、ディレクトリではなくファイルである場合、メインプログラムへ自動的に読み込まれます。

    import RelativePathString as NAME [<metadata>];

    検索パス内のディレクトリからの相対パスとして、指定したパスで見つかったモジュールをインポートします。相対パス文字列には .jq 接尾辞を追加します。モジュールの記号には、NAME:: という接頭辞が付きます。

    任意のメタデータは、定数のjq式でなければなりません。homepage などのキーを持つオブジェクトにするべきです。現時点で、jqが使うのは、メタデータの search のキーと値だけです。メタデータは、組込み関数 modulemeta によって利用者にも提供されます。

    メタデータに search キーがある場合、その値は文字列か、文字列の配列であるべきです。これは、最上位の検索パスの先頭に追加する検索パスです。

    include RelativePathString [<metadata>];

    検索パス内のディレクトリからの相対パスとして、指定したパスで見つかったモジュールを、その場所へ取り込むかのようにインポートします。相対パス文字列には .jq 接尾辞を追加します。モジュールの記号は、モジュールの内容を直接取り込んだかのように、呼出し側の名前空間へインポートされます。

    任意のメタデータは、定数のjq式でなければなりません。homepage などのキーを持つオブジェクトにするべきです。現時点で、jqが使うのは、メタデータの search のキーと値だけです。メタデータは、組込み関数 modulemeta によって利用者にも提供されます。

    import RelativePathString as $NAME [<metadata>];

    検索パス内のディレクトリからの相対パスとして、指定したパスで見つかったJSONファイルをインポートします。相対パス文字列には .json 接尾辞を追加します。ファイルのデータは、$NAME::NAME として使えます。

    任意のメタデータは、定数のjq式でなければなりません。homepage などのキーを持つオブジェクトにするべきです。現時点で、jqが使うのは、メタデータの search のキーと値だけです。メタデータは、組込み関数 modulemeta によって利用者にも提供されます。

    メタデータに search キーがある場合、その値は文字列か、文字列の配列であるべきです。これは、最上位の検索パスの先頭に追加する検索パスです。

    module <metadata>;

    この指示は完全に任意です。正しく動作するためには必要ありません。組込み関数 modulemeta で読み取れるメタデータを提供することだけが目的です。

    メタデータは、定数のjq式でなければなりません。homepage のようなキーを持つオブジェクトにするべきです。現時点で、jqはこのメタデータを使いませんが、組込み関数 modulemeta によって利用者に提供されます。

    modulemeta

    モジュール名を入力として受け取り、モジュールのメタデータをオブジェクトとして出力します。モジュールがインポートするものは、メタデータも含めて deps キーの配列の値になり、モジュールが定義する関数は defs キーの配列の値になります。

    プログラムは、この関数でモジュールのメタデータを問い合わせ、たとえば、不足している依存モジュールの検索、ダウンロード、インストールに使えます。