Merge pull request #2565 from BetterThanTomorrow/2556-proper-refresh-…

…commands

Make refresh commands return their promises and accept args

CHANGELOG.md

@@ -4,6 +4,8 @@ Changes to Calva.
 
 ## [Unreleased]
 
+[Extend "Refresh Changed Namespaces" to accept optional parameters exposed by cider-nrepl](https://github.com/BetterThanTomorrow/calva/issues/2556)
+
 ## [2.0.454] - 2024-06-03
 
 - Fix: [HTML->Hiccup fails on style attribute strings where the entries do not have whitespace](https://github.com/BetterThanTomorrow/calva/issues/2561)

docs/site/commands.md

@@ -0,0 +1,59 @@
+---
+title: Calva Commands
+description: A list of all (well, not by far yet) Calva commands. A part of Calva's API.
+---
+
+# Calva Commands
+
+!!! Note "This list is totally incomplete"
+    If you want to help the Calva project, one way to do so is to help making this list of commands complete.
+
+Calva's commands are part of the [Calva API](api.md). They often accept arguments of some type, which you can use from keybindings and from [Joyride](https://github.com/BetterThanTomorrow/joyride) (or another VS Code extension). Well behaved commands return a Promise, if it is async. You can utilize this with Joyride too, or with keybindings involving [`runCommands`](https://blog.agical.se/en/posts/vs-code-runcommands-for-multi-commands-keyboard-shortcuts/).
+
+## Example shortcut bindings
+
+To illustrate how to provide arguments to the Calva commands, here's a keyboard shortcut binding for `calva.refresh`:
+
+```json
+  {
+    "key": "ctrl+alt+c f1",
+    "command": "calva.refresh",
+    "args": {
+      "after": "component.repl/reset"
+    }
+  },
+```
+
+It sends along the `:after` argument for the `cider-nrepl/refresh` op. (The actual argument only makes sense with [Component](https://github.com/stuartsierra/component))
+
+Here's another way to achieve something similar.
+
+```json
+  {
+    "key": "ctrl+alt+c f1",
+    "command": "runCommands",
+    "args": {
+      "commands": [
+        "calva.refresh",
+        {
+          "command": "calva.runCustomREPLCommand",
+          "args": "(component.repl/reset)"
+        }
+      ]
+    }
+  }
+```
+
+## REPL commands
+
+Commands that establishes or needs a REPL connection.
+
+| Command | Title | Arguments | Notes |
+| :------ | :---- | :-------- | :---- |
+| `calva.refresh` | Refreshes changed namespaces | A JSON object with stuff from [cider-nrepl ops/refresh](https://github.com/clojure-emacs/cider-nrepl/blob/master/doc/modules/ROOT/pages/nrepl-api/ops.adoc#refresh) | Mostly meant for sending `:dirs`, `:after`, and `:before`. The print options may or may not work.
+| `calva.refreshAll` | Refreshes changed namespaces | A JSON object with stuff from [cider-nrepl ops/refresh-aa](https://github.com/clojure-emacs/cider-nrepl/blob/master/doc/modules/ROOT/pages/nrepl-api/ops.adoc#refresh-all) | Mostly meant for sending `:dirs`, `:after`, and `:before`. The print options may or may not work.
+
+
+## Wait, where are all the commands?
+
+Told you the list is incomplete... Please consider helping with making this a complete list! 🙏

mkdocs.yml

@@ -103,7 +103,9 @@ nav:
     - quirks.md
     - async-out.md
     - clj-java-decompiler.md
-  - api.md
+  - API:
+    - api.md
+    - commands.md
   - In Depth:
     - jack-in-guide.md
   - Guides:

src/extension.ts

@@ -17,7 +17,7 @@ import { CalvaSignatureHelpProvider } from './providers/signature';
 import testRunner from './testRunner';
 import annotations from './providers/annotations';
 import eval from './evaluate';
-import refresh from './refresh';
+import * as refresh from './refresh';
 import * as greetings from './greet';
 import Analytics from './analytics';
 import * as open from 'open';

src/nrepl/index.ts

@@ -763,7 +763,7 @@ export class NReplSession {
     });
   }
 
-  private _refresh(cmd, opts: { dirs?: string[]; before?: string[]; after?: string[] } = {}) {
+  private _refresh(cmd, opts = {}) {
     return new Promise<any>((resolve, reject) => {
       const id = this.client.nextId;
       const msg = {
@@ -793,6 +793,9 @@ export class NReplSession {
           if (msg.err) {
             err += msg.err;
           }
+          if (msg.out) {
+            output.appendOtherOut(msg.out);
+          }
           if (hasStatus(msg, 'done')) {
             const res = { reloaded, status } as any;
             if (error) {
@@ -816,11 +819,11 @@ export class NReplSession {
     });
   }
 
-  refresh(opts: { dirs?: string[]; before?: string[]; after?: string[] } = {}) {
+  refresh(opts = {}) {
     return this._refresh('refresh', opts);
   }
 
-  refreshAll(opts: { dirs?: string[]; before?: string[]; after?: string[] } = {}) {
+  refreshAll(opts = {}) {
     return this._refresh('refresh-all', opts);
   }
 

src/refresh.ts

@@ -19,37 +19,33 @@ function report(res) {
     }
     output.appendLineEvalOut(':error 😿');
   }
+  return res;
 }
 
-function refresh(document = {}) {
-  const doc = util.tryToGetDocument(document),
+export function refresh(opts?: Record<string, unknown>) {
+  const doc = util.tryToGetDocument({}),
     client: NReplSession = replSession.getSession(util.getFileType(doc));
 
   if (client != undefined) {
     output.appendLineEvalOut('Reloading...');
-    void client.refresh().then((res) => {
-      report(res);
+    return client.refresh(opts).then((res) => {
+      return report(res);
     });
   } else {
-    void vscode.window.showErrorMessage('Not connected to a REPL.');
+    return vscode.window.showErrorMessage('Not connected to a REPL.');
   }
 }
 
-function refreshAll(document = {}) {
-  const doc = util.tryToGetDocument(document),
+export function refreshAll(opts?: Record<string, unknown>) {
+  const doc = util.tryToGetDocument({}),
     client: NReplSession = replSession.getSession(util.getFileType(doc));
 
   if (client != undefined) {
     output.appendLineEvalOut('Reloading all the things...');
-    void client.refreshAll().then((res) => {
-      report(res);
+    return client.refreshAll(opts).then((res) => {
+      return report(res);
     });
   } else {
-    void vscode.window.showErrorMessage('Not connected to a REPL.');
+    return vscode.window.showErrorMessage('Not connected to a REPL.');
   }
 }
-
-export default {
-  refresh,
-  refreshAll,
-};