Show HN: jnv: `jq` を使ったインタラクティブな JSON フィルタ

 (github.com/ynqa)
3 ポイント 投稿者 GN⁺ 2024-03-20 | 1件のコメント | WhatsAppで共有
  • jnv は JSON を探索するために作られたツールで、インタラクティブな JSON ビューアと jq フィルタエディタをあわせて提供する
  • フィルタ適用には jaq を使うため、ユーザーが別途 jq を用意する必要はない
  • 入力はファイルと stdin をサポートし、単一の JSON だけでなく、StreamDeserializer でデシリアライズできる JSON Lines のような複数の JSON 構造も扱える
  • TOML 設定でヒント表示、UI の応答性、エディタの動作、JSON ビューアのスタイル、自動補完の表示と動作、キー バインディング を調整できる
  • 自動補完は jq 機能のうち Identity、Object Identifier-Index、Array Index のみをサポートし、v0.7.0 で TOML 設定構文が変わったが、移行ツールは提供されていない

jnv が提供する機能

  • jnv は JSON を探索するためのインタラクティブツールで、JSON ビューアと jq フィルタエディタを提供する
  • JSON には シンタックスハイライト を適用できる
  • jq フィルタの適用には jaq を使う
    • ユーザーが自分で jq を用意する必要はない
  • jid と jiq から着想を得ている

入力形式とフィルタ編集

  • 入力は ファイル または stdin から受け取れる
  • データは単一の JSON または複数の JSON 構造を受け取れる
    • 複数の JSON 構造は StreamDeserializer でデシリアライズできる形式である必要がある
    • 例として JSON Lines が含まれる
  • フィルタの自動補完は限定的にサポートされる
  • フィルタ評価を支援する ヒントメッセージ を表示できる

インストール方法

  • Homebrew でインストール可能
    • brew install jnv
    • または brew install ynqa/tap/jnv
  • MacPorts でインストール可能
    • sudo port install jnv
  • Nix / NixOS で利用できる
    • nix-shell -p jnv
  • conda-forge 経由でインストールまたは実行できる
    • pixi global install jnv
    • cat data.json | pixi exec jnv
    • conda install jnv
  • Docker では、直接イメージをビルドして実行する例が提供されている
    • イメージは近い将来、どこかのレジストリで提供される予定だと案内されている
  • Cargo でインストール可能
    • cargo install jnv

使用例と CLI オプション

  • ファイルまたは標準入力で実行できる
    • cat data.json | jnv
    • jnv data.json
  • UNIX 環境では、終了時に現在の結果を stdout に書き出せる
    • cat data.json | jnv --write-to-stdout | some-command
    • cat data.json | jnv -- --write-to-stdout > result.json
  • 基本的な使用形式は jnv [OPTIONS] [INPUT]
  • [INPUT] は省略可能な JSON ファイルパス
    • 指定しないか - を指定すると標準入力から読み込む
  • 主なオプションは以下の通り
    • -c, --config <CONFIG_FILE>: 設定ファイルのパスを指定
    • --default-filter <DEFAULT_FILTER>: 入力データに適用するデフォルトの jq フィルタを指定
    • --write-to-stdout: 終了時に現在の JSON 結果を stdout に出力
    • -h, --help: ヘルプを表示
    • -V, --version: バージョンを表示

キー操作

  • 共通のキー バインディングは、エディタと JSON ビューア全体の基本動作を提供する
    • Ctrl + C: 終了
    • Ctrl + Q: jq フィルタをクリップボードにコピー
    • Ctrl + O: JSON をクリップボードにコピー
    • Shift + ↑, Shift + ↓: 別のモードに切り替え
  • Editor mode はデフォルトモード
    • Tab: 候補を入力
    • ←, →: カーソルを左右に移動
    • Ctrl + A, Ctrl + E: 行頭と行末に移動
    • Backspace: カーソル前の文字を削除
    • Ctrl + U: 行全体を削除
    • Alt + B, Alt + F: ., |, (, ), [, ] のうち最も近い文字を基準に前または次の位置へ移動
    • Ctrl + W, Alt + D: 同じ文字集合を基準に前または次の位置まで削除
  • 自動補完候補の表示中は、Tab または ↓ で次の候補を選び、↑ で前の候補を選ぶ
  • JSON viewer mode は JSON の探索と折りたたみ操作を提供する
    • ↑, Ctrl + K: 上へ移動
    • ↓, Ctrl + J: 下へ移動
    • Ctrl + H: 最後の項目へ移動
    • Ctrl + L: 最初の項目へ移動
    • Enter: 折りたたみを切り替え
    • Ctrl + P: すべて展開
    • Ctrl + N: すべて折りたたむ

TOML 設定

  • jnv は TOML 設定ファイル でさまざまな機能をカスタマイズできる
  • 設定ファイルの読み込み優先順位は、コマンドラインで指定した -c または --config のパスが先で、その次がデフォルト設定ファイルのパス
  • デフォルト設定ファイルの場所はプラットフォームごとに異なる
    • Linux: ~/.config/jnv/config.toml
    • macOS: ~/Library/Application Support/jnv/config.toml
    • Windows: C:\Users\{Username}\AppData\Roaming\jnv\config.toml
  • 設定ファイルがない場合は、初回実行時に自動生成される
  • v0.7.0 で default.toml のような TOML 設定構文が変更されており、例は新しい形式を反映している
    • この変更に対する 移行ツール は提供されていない
    • ローカルの config.toml は新構文に合わせて手動で置き換えるか更新する必要がある
  • 端末の種類や環境によっては、文字やスタイルが正しく表示されないことがある
    • 一部のターミナルエミュレータでは、特定のキー バインディングや装飾文字が表示されなかったり動作しなかったりする可能性がある

調整可能な設定項目

  • ヒントメッセージを隠すかどうかを no_hint で設定できる
  • エディタ設定はフォーカス状態と非フォーカス状態を分けて調整できる
    • 入力モードには Insert と Overwrite を使う
    • 単語境界文字の一覧を指定して、カーソル移動や削除動作を決められる
    • 接頭表示文字、接頭スタイル、カーソル下の文字スタイル、残りの文字スタイルを指定できる
  • JSON 表示設定には、インデント、括弧スタイル、キーと値のスタイル、選択行の属性、幅超過時の処理方法が含まれる
    • ストリーム入力では、処理する JSON オブジェクトの最大数を max_streams で制限できる
    • この値は大きなデータストリームを扱う際のメモリ使用量を減らすための設定で、指定しなければ制限はない
  • 自動補完設定では、検索結果とバックグラウンド読み込みのチャンクサイズを調整する
    • 値が大きいほど結果表示や読み込み完了が速くなる可能性があるが、より多くのメモリを使う
  • キー バインディングは、終了、クエリのコピー、結果のコピー、モード切り替え、エディタ操作、JSON ビューア操作ごとに設定可能
  • UI の応答性設定では、入力処理の遅延、ウィンドウサイズ変更後の再描画遅延、スピナーアニメーションの間隔を調整する

関連記事

1件のコメント

 
GN⁺ 2024-03-20
Hacker News のコメント

  • すばらしい。小さな不満を挙げると、中規模の JSON（16MB）でも非常に遅いことと、フォントの色が暗すぎること（PR は送った）
    高性能な代替を探していて fx（https://fx.wtf）を見たが、jq の機能はないものの高速な JSON ビューアだった

    • 「16MB JSONでも非常に遅い」という話どおりなら、aqny が遊びでここに来て、やることを見つけたというわけだ。性能問題に取り組むのが一番楽しい
    • 会社で 50MB 超の JSON ファイルを扱う必要があるので、jnv がその程度を処理できるなら本当にありがたい

  • よさそう。jq でいつももどかしかったのは、実行するまでどんなデータを取り出すことになるのか見られない点だった

  • 本当に楽しみ。必ず試すつもり
    これまでは対話的なクエリに jq と up [0] を併用していたが、up のユーザー体験はあまり気に入っていなかった。特に長いクエリや 非 ASCII データでは不便なので、代替を探したい
    [0]: https://github.com/akavel/up

  • すごくいい。ノートPCを手に取り次第すぐインストールするつもり
    以前似たものを作ったことがあるので、この投稿にすぐ引き込まれた
    https://github.com/bigH/interactively.git
    このアイデアをさらに一般化して、CLI でより多くのコマンドに対話型インターフェースを付けられるのではないかと思う。ずっと前から、カーソル位置に応じて適切なドキュメントを呼び出し、コマンドラインを編集している間に表示する「コマンドビルダー」を想像してきた

  • とてもすばらしい。無理なお願いかもしれないが、jq 構文の代わりに JSONPath を使う OjG でも動くように適用できるか気になる。よければ喜んで手伝いたい

  • よさそう。jless（https://github.com/PaulJuliusMartinez/jless）にかなり近そう

    • jless は結果を jq クエリとしてコピーしてくれるわけではなさそう

  • 代替として fx もみんな知っておくとよさそう
    map、filter、reduce のようなこともずっと多くできるし、セマンティクスもすでに馴染みのあるものに近い。YAML もサポートしている
    https://fx.wtf/getting-started

  • JSONL ログファイルを動的にフィルタリングして見るためのツールを探していて、VisiData を使うようになった
    JSONL（JSON Lines）を扱うなら強くおすすめする

  • これは fzf だけでもできるのではないかと思った

  • Sublime Text を使っているなら、同じことができるプラグインもある [0]
    ちなみに、このプラグインは以前自分が作ったもの
    [0]: https://packagecontrol.io/packages/Jq