clojure-eval

Clojure REPL 評価

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• 編集した Clojure ファイルが正しくコンパイルされ、読み込まれることを確認する
• 関数の動作を対話的にテストする
• REPL の現在の状態を確認する
• 式を評価してコードをデバッグする
• テスト用に名前空間を require または読み込む
• コミットする前にコードの変更が機能することを検証する

仕組み

clj-nrepl-eval コマンドは、nREPL サーバーに接続して Clojure コードを評価します。セッションの状態は評価の間で保持されるため、ある評価で名前空間を require し、後続の呼び出しで使用できます。ホストとポートの組み合わせごとに、個別のセッションファイルが維持されます。

手順

0. nREPL サーバーを検出して選択する

まず、現在のディレクトリで実行中の nREPL サーバーを検出します。

clj-nrepl-eval --discover-ports

現在のプロジェクトディレクトリで実行中のすべての nREPL サーバー（Clojure、Babashka、shadow-cljs など）が表示されます。

次に、AskUserQuestion ツールを使用します。

• ポートが検出された場合： 使用する nREPL ポートをユーザーに選択してもらいます。

  • question：「どの nREPL ポートを使用しますか？」
  • header：「nREPL ポート」
  • options： 検出された各ポートを、次の内容を含む選択肢として表示します。
    • label： ポート番号
    • description： サーバーの種類と状態（例：「現在のディレクトリにある Clojure nREPL サーバー」）
  • 検出されたポートを最大 4 つまで選択肢に含めます。
  • ユーザーは「Other」を選択して、任意のポート番号を入力できます。

• ポートが検出されなかった場合： nREPL サーバーの起動方法をユーザーに選択してもらいます。

  • question：「nREPL サーバーが見つかりませんでした。どの方法で起動しますか？」
  • header：「nREPL を起動」
  • options：
    • label：「deps.edn alias」、description：「deps.edn で nREPL エイリアスを見つけて使用する」
    • label：「Leiningen」、description：「'lein repl' を使用して nREPL を起動する」
  • ユーザーは別の方法を選ぶ場合や、特定のポートで実行中のサーバーがすでにある場合、「Other」を選択できます。

重要：REPL を起動する場合はポートを指定しないでください。nREPL の起動を待ち、起動したポート番号を取得してください。

1. Clojure コードを評価する

評価時には、指定されたポートに自動的に接続します。

-p フラグでポートを指定し、Clojure コードを渡します。

推奨：シェルのエスケープ処理の問題を避けるため、標準入力からヒアドキュメントを使用します。 シングルクォートで囲んだ区切り文字（<<'EOF'）を使うと、すべての文字がそのまま渡されます。

clj-nrepl-eval -p <PORT> <<'EOF'
(+ 1 2 3)
EOF

複数の式を評価する場合：

clj-nrepl-eval -p <PORT> <<'EOF'
(def x 10)
(+ x 20)
EOF

2. nREPL セッションを表示する

現在のディレクトリにあるすべての nREPL サーバーを検出する：

clj-nrepl-eval --discover-ports

現在のプロジェクトディレクトリで実行中のすべての nREPL サーバーと、その種類（clj/bb/basilisp）、および現在の作業ディレクトリと一致するかどうかを表示します。

以前に接続したセッションを確認する：

clj-nrepl-eval --connected-ports

以前に接続したセッションのみを表示します（ポートで最初の評価を行った後に表示されます）。

3. よく使うパターン

名前空間を require する（変更を反映するため、必ず :reload を使用）：

clj-nrepl-eval -p <PORT> "(require '[my.namespace :as ns] :reload)"

require 後に関数をテストする：

clj-nrepl-eval -p <PORT> "(ns/my-function arg1 arg2)"

ファイルがコンパイルされるか確認する：

clj-nrepl-eval -p <PORT> "(require 'my.namespace :reload)"

複数の式：

clj-nrepl-eval -p <PORT> "(def x 10) (* x 2) (+ x 5)"

複雑な複数行のコード：

clj-nrepl-eval -p <PORT> <<'EOF'
(def x 10)
(* x 2)
(+ x 5)
EOF

タイムアウトを指定する（ミリ秒）：

clj-nrepl-eval -p <PORT> --timeout 5000 "(long-running-fn)"

セッションをリセットする（すべての状態をクリア）：

clj-nrepl-eval -p <PORT> --reset-session
clj-nrepl-eval -p <PORT> --reset-session "(def x 1)"

使用可能なオプション

• -p, --port PORT - nREPL ポート（必須）
• -H, --host HOST - nREPL ホスト（デフォルト：127.0.0.1）
• -t, --timeout MILLISECONDS - タイムアウト（デフォルト：120000 = 2 分）
• -r, --reset-session - 永続的な nREPL セッションをリセットする
• -c, --connected-ports - 以前に接続した nREPL セッションを一覧表示する
• -d, --discover-ports - 現在のディレクトリにある nREPL サーバーを検出する
• -h, --help - ヘルプメッセージを表示する

重要な注意事項

• stdin 経由でヒアドキュメントを優先してください： シェルのエスケープに関する問題を避けるため、clj-nrepl-eval -p <PORT> <<'EOF' ... EOF を使用します
• セッションは保持されます： 状態（変数、名前空間、読み込まれたライブラリ）は、nREPL サーバーが再起動するまで呼び出し間で保持されます。--reset-session は nREPL セッションのみをリセットし（*e、*1 などの動的変数をクリアします）、def で定義された変数や読み込み済みの名前空間はリセットしません
• 区切り文字は自動修復されます： ツールは不足している括弧や対応していない括弧を自動的に修復します
• 必ず :reload を使用してください： 名前空間を require する際は、最近の変更を反映するために :reload を使用します
• デフォルトのタイムアウト： 2 分（120000ms）です。長時間実行する処理では延長してください
• 入力の優先順位： コマンドライン引数は stdin より優先されます

一般的なワークフロー

1. nREPL サーバーを検出します：clj-nrepl-eval --discover-ports
2. AskUserQuestion ツールを使用して、ユーザーにポートを選択してもらいます
3. 名前空間を require します：

   clj-nrepl-eval -p <PORT> "(require '[my.ns :as ns] :reload)"
   

4. 関数をテストします：

   clj-nrepl-eval -p <PORT> "(ns/my-fn ...)"
   

5. 繰り返します：変更を加え、:reload を付けて再度 require し、もう一度テストします