Merge pull request #2240 from BetterThanTomorrow/2199-fiddle

Fixes #2199
BetterThanTomorrow · Jul 11, 2023 · 0ca008c · 0ca008c
2 parents 9cac006 + fe16676
commit 0ca008c
Show file tree

Hide file tree

Showing 29 changed files with 1,519 additions and 152 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -155,6 +155,7 @@
     "prepending",
     "Prettiful",
     "prewatch",
+    "prio",
     "Pseudoterminal",
     "randr",
     "REBL",
@@ -223,7 +224,7 @@
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
   "[json]": {
-    "editor.defaultFormatter": "vscode.json-language-features"
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
   "[jsonc]": {
     "editor.defaultFormatter": "vscode.json-language-features"

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,8 @@ Changes to Calva.
 
 ## [Unreleased]
 
+- [Add “Fiddle” files Support](https://github.com/BetterThanTomorrow/calva/issues/2199)
+
 ## [2.0.375] - 2023-07-11
 
 - [If calva.fmt.configPath not set, look in default config locations](https://github.com/BetterThanTomorrow/calva/issues/2243)

diff --git a/docs/site/fiddle-files.md b/docs/site/fiddle-files.md
@@ -0,0 +1,152 @@
+---
+title: Fiddle Files Support
+description: Power up you Interactive Programming with Fiddle Files. Rich Comments in files of their own with some extra Calva treatment to go with them.
+search:
+  boost: 5
+---
+
+# Fiddle Files support
+
+In the podcast **Functional Design in Clojure**, [Episode 014: Fiddle with the REPL](https://clojuredesign.club/episode/014-fiddle-with-the-repl/), they discuss a workflow where you keep some of your exploratory code in separate files, which they call **Fiddle Files**. It's like [Rich Comments](rich-comments.md), and the files often consist of such comments. The **Fiddle** files are typically not on the classpath, and are only loaded in the REPL by you when you are developing on your project. Some developers keep personal fiddle files, in some project they are meant to be shared, and in other projects its a combination.
+
+Calva has some extra support for the fiddle file workflow, beyond what VS Code offers in terms of navigating between files. The support comes in the form of three commands supported by some little configuration.
+
+## The three Fiddle File commands
+
+The commands let you quickly navigate between your implementation code (called **Source** here) and your **Fiddle** fle, and to evaluate the **Fiddle** file without leaving the **Source** file.
+
+| Command | Action | Shortcut | Active |
+|---------|--------|----------|--------|
+| **Calva: Open Fiddle File for Current File** | Opens the **Fiddle** file corresponding to the current Clojure **Source** file. | <div style="white-space: nowrap; overflow-x: auto;"><kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>c</kbd><br><kbd>f</kbd></div> | When the currently active file is _not_ a **Fiddle** file. |
+| **Calva: Open Source File for Current Fiddle File** | Opens the **Source** file corresponding to the current **Fiddle** file. | <div style="white-space: nowrap; overflow-x: auto;"><kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>c</kbd><br><kbd>f</kbd></div> | When the currently active file _is_ a **Fiddle** file + there is an existing, and corresponding, source file. |
+| **Calva: Evaluate Fiddle File for Current File** | Evaluates the **Fiddle** file corresponding to the current Clojure **Source** file. | <div style="white-space: nowrap; overflow-x: auto;"><kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>c</kbd><br><kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>f</kbd></div> | When the currently active file is _not_ a **Fiddle** file. |
+
+The commands for opening and evaluating corresponding **Fiddle** files will offer to Create the **Fiddle** file if it does not already exist. But the **Calva: Open Source File for Current Fiddle File** will _not_ offer to create the target file.
+
+What does **corresponding** mean here? Without any configuration Calva will look for “sibling” files, where files with Clojure file extensions (E.g. `.clj`, `.cljs`, `.bb`) will be treated as **Source** files, and files with the `.fiddle` extension will be treated as **Fiddle** files. Sibling file here means residing side by side in the file system. If this default behaviour is not your cup of tea, there is some flexibility added by configuration.
+
+## The Fiddle File configuration
+
+To know how to map between **Fiddle** <-> **Source** files, Calva has three different modes of operation:
+
+1. The sibling files, as described above. This is the default. Example:
+    * **`src`**`/a/b/c.cljc` corresponding to:
+    * **`src`**`/a/b/c.fiddle`
+1. Parallel directory structures. Mapping a **Source** directory tree to a **Fiddle** directory tree. Example:
+    * **`src`**`/a/b/c.cljc` corresponding to:
+    * **`env/dev/fiddles`**`/a/b/c.cljc`
+1. A dedicated **Fiddle** file for a **Source** directory tree. E.g. both:
+    * **`src`**`/a/b/c.cljc` and:
+    * **`src`**`/d/e/f.cljc` corresponding to:
+    * **`env/dev/fiddles`**`/x.cljc`
+
+The setting is named `calva.fiddleFilePaths` and is an array of `source` and `fiddle` root paths, _relative to the project root_.
+
+!!! Note "The Project Root"
+    It is important to note that the **project root** depends on wether you are connected to a REPL or not, and to which project you are connected, in case the workspace contains several projects.
+
+    **Without** a REPL connection (disregarding that fiddle files are not very interesting then) the project root is the same as the first Workspace root. And if you have a regular VS Code window open, it is the root of the folder you have opened in that window.
+
+    **With** a REPL connection, the project root will be the root of the project, i.e. where the project file (`deps.edn`, `project.clj`, `shadow-cljs.edn`) is.
+
+### Example configurations
+
+#### Single parallel directory structure
+
+```json
+"calva.fiddleFilePaths": [
+  {
+    "source": ["src"],
+    "fiddle": ["env", "dev", "fiddles"]
+  }
+]
+```
+
+This will make any file in the `src` directory tree correspond to a matching file with the same relative path. E.g.:
+
+* `src/a/b/c.clj` -> `env/dev/fiddles/a/b/c.clj`, for both the **open** and **evaluate** commands
+* `env/dev/fiddles/a/b/c.clj` -> `src/a/b/c.clj`
+
+#### Single dedicated Fiddle file
+
+If you generally work with one **Fiddle** file at a time, you can configure a mapping to a **Dedicated Fiddle** file. E.g.:
+
+
+```json
+"calva.fiddleFilePaths": [
+  {
+    "source": ["src"],
+    "fiddle": ["env", "dev", "fiddle.clj"]
+  },
+]
+```
+
+This will make any file in the `src` directory tree correspond to the same **Fiddle** file. E.g.:
+
+* `src/a/b/c.clj` -> `env/dev/fiddle.clj`, for both the **open** and **evaluate** commands
+* `src/d/e/f.clj` -> `env/dev/fiddle.clj`, ditto
+* `env/dev/fiddle.clj` -> Won't correspond to a **Source** file in this case
+
+!!! Note "Jumping from a dedicated fiddle to a source file"
+    Calva's command for opening the corresponding source file won't work in this case because it is one->many situation. If you want to open the last file you worked with before using doing **Open Fiddle File for Current File**, consider using the VS Code command: **Go Previous**.
+
+#### Multiple mappings
+
+The configuration is an array so that you can configure different mappings for different **Source** directories. Given several mappings with overlapping **Source**, the longest mapping will win. Given several mappings with the _same_ **Source**, the first one will win, _unless_ one of them is a _Dedicated_ **Fiddle**, in which case that one will win.
+
+```json
+"calva.fiddleFilePaths": [
+  {
+    "source": ["src"],
+    "fiddle": ["env", "dev", "fiddles"]
+  },
+  {
+    "source": ["src"],
+    "fiddle": ["env", "dev", "fiddle.clj"]
+  },
+  {
+    "source": ["src"],
+    "fiddle": ["env", "dev", "fiddle.cljs"]
+  },
+  {
+    "source": ["src"],
+    "fiddle": ["env", "dev", "fiddle.bb"]
+  },
+  {
+    "source": ["src", "b"],
+    "fiddle": ["env", "dev", "b-fiddles"]
+  },
+]
+```
+
+With this configuration we would get a behaviour like so:
+
+* `src/a/b/c.clj` -> `env/dev/fiddle.clj`, because all four first `["src"]` mappings match, but the second one is a dedicated fiddle file, and matches the `.clj` extension.
+* `src/a/b/c/d.bb` -> `env/dev/fiddle.bb`, because all four first `["src"]` mappings match, but the second one is a dedicated fiddle file, and matches the `.bb` extension.
+* `src/a/b/c/d.cljc` -> `env/dev/fiddle.clj`, because all four first `["src"]` mappings match, but the second one is a dedicated fiddle file, without a matching  file extension, (so the first dedicated fiddle file is picked).
+* `src/b/c/d.clj` -> `env/dev/b-fiddles/c/d.clj`, because the `["src", "b"]` mapping is longer than the also matching `["src"]` mappings.
+
+## Tips
+
+It can be tempting to put your **Fiddle** files directory on the classpath for the `dev` alias/profile, but it is most often a mistake (will depend on your particular use of fiddle files, but generally). Instead load/evaluate fiddle files when you need them (e.g. by using the command for it mentioned above). The REPL does not need something to be on the classpath in order to evaluate it.
+
+When you want your fiddle code to be evaluated in the same workspace as its corresponding **Source** file, you can use the same namespace declaration for both files. The linter might complain, but the REPL will be happily comply.
+
+If you primarily evaluate the fiddle file using the provided command for it, from the **Source** files, you can omit the namespace declaration, and Calva will evaluate it in the namespace of the **Source** file.
+
+!!! Note "The linter and fiddle files"
+    For some fiddle files you will get a lot of linter warnings, because clj-kondo doesn't know about fiddle files, and they are often not on the classpath, making. You might find yourself wanting to silence some linters for some fiddle files. E.g. like this:
+
+    ``` clojure
+    (ns main.core
+      {:clj-kondo/config
+       '{:linters {:unresolved-symbol {:level :off}}}})
+    ```
+
+     See [clj-kondo Configuration](https://github.com/clj-kondo/clj-kondo/blob/master/doc/config.md) for more on what options you have for this.
+
+## See also
+
+* [Rich Comments](rich-comments.md)
+* **Functional Design in Clojure** [Episode 014: Fiddle with the REPL](https://clojuredesign.club/episode/014-fiddle-with-the-repl/)
+* The Polylith [Development](https://polylith.gitbook.io/poly/architecture/development) page mentions good practice for where to put your fiddle files (not called fiddle files there, but it is the same concept).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -52,21 +52,22 @@ nav:
   - Features:
     - commands-top10.md
     - evaluation.md
+    - formatting.md
+    - syntax-highlighting.md
+    - paredit.md
+    - linting.md
     - rich-comments.md
+    - fiddle-files.md
+    - refactoring.md
+    - custom-commands.md
+    - connect-sequences.md
+    - notebooks.md
     - clojuredocs.md
     - output.md
-    - formatting.md
-    - paredit.md
     - debugger.md
     - pprint.md
-    - refactoring.md
     - test-runner.md
-    - syntax-highlighting.md
-    - connect-sequences.md
-    - custom-commands.md
-    - linting.md
     - namespace-form-auto-creation.md
-    - notebooks.md
     - hiccup.md
   - Customizing Calva:
     - customizing.md

diff --git a/netlfiy.toml b/netlfiy.toml
@@ -0,0 +1,8 @@
+[build]
+publish = "docs/site"
+command = """
+restore_home_cache ".cache" "pip cache" &&
+restore_cwd_cache '.venv' 'python virtualenv' &&
+pip install -r requirements.txt &&
+mkdocs build -d docs/site
+"""
diff --git a/package.json b/package.json
@@ -111,7 +111,8 @@
           ".joke",
           ".boot",
           ".bb",
-          ".calva-repl"
+          ".calva-repl",
+          ".fiddle"
         ],
         "configuration": "./language-configuration.json"
       }
@@ -162,6 +163,34 @@
         "type": "object",
         "title": "Calva",
         "properties": {
+          "calva.fiddleFilePaths": {
+            "type": "array",
+            "markdownDescription": "An array of `source` and `fiddle` root paths, relative to the project root. This is used by the commands **Calva: Open Fiddle File for Current File**, and **Calva: Evaluate Fiddle File for Current File**. Example:\n\n```json\n\"calva.fiddleFilePaths\": [\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddles\"]\n  }\n]\n```\n\nThe default is `null`, which will make Calva associate files with a `.fiddle` file extension as the fiddle file for a Clojure file. E.g. a file `src/foo/bar/baz_main.cljc`, will have an associated fiddle file named `src/foo/bar/baz_main.fiddle`. See [calva.io/fiddle](https://calva.io/fiddle-files/) for more info.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "source": {
+                  "markDownDescription": "The source files root path. An array of strings, used as path segments. E.g. `[\"src\"]`",
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "fiddle": {
+                  "markDownDescription": "The fiddle files root path. An array of strings, used as path segments. E.g. `[\"env\", \"dev\", \"fiddles\"]`",
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "required": [
+                "source",
+                "fiddle"
+              ]
+            },
+            "default": null
+          },
           "calva.useLiveShare": {
             "type": "boolean",
             "markdownDescription": "Enable support for LiveShare. Currently defaults to false, because of [ive-share/issues/4551](https://github.com/MicrosoftDocs/live-share/issues/4551). This issue makes Calva fail to connect to a REPL for some users.",
@@ -1788,6 +1817,24 @@
         "category": "Calva Format",
         "enablement": "editorLangId == clojure"
       },
+      {
+        "category": "Calva",
+        "command": "calva.openFiddleForSourceFile",
+        "title": "Open Fiddle File for Current File",
+        "enablement": "!calva:activeEditorIsFiddle"
+      },
+      {
+        "category": "Calva",
+        "command": "calva.evaluateFiddleForSourceFile",
+        "title": "Evaluate Fiddle File for Current File",
+        "enablement": "!calva:activeEditorIsFiddle"
+      },
+      {
+        "category": "Calva",
+        "command": "calva.openSourceFileForFiddle",
+        "title": "Open Source File for Current Fiddle File",
+        "enablement": "calva:activeEditorIsFiddle"
+      },
       {
         "category": "Calva",
         "command": "calva.showOutputWindow",
@@ -2478,6 +2525,21 @@
         "key": "shift+tab",
         "when": "calva:keybindingsEnabled && editorLangId == clojure && editorTextFocus && !editorReadOnly && !suggestWidgetVisible && !hasOtherSuggestions"
       },
+      {
+        "command": "calva.openFiddleForSourceFile",
+        "key": "ctrl+alt+c f",
+        "when": "calva:keybindingsEnabled && !calva:activeEditorIsFiddle"
+      },
+      {
+        "command": "calva.evaluateFiddleForSourceFile",
+        "key": "ctrl+alt+c ctrl+alt+f",
+        "when": "calva:keybindingsEnabled && calva:connected && !calva:activeEditorIsFiddle"
+      },
+      {
+        "command": "calva.openSourceFileForFiddle",
+        "key": "ctrl+alt+c f",
+        "when": "calva:keybindingsEnabled && calva:activeEditorIsFiddle"
+      },
       {
         "command": "calva.showOutputWindow",
         "key": "ctrl+alt+o o",
@@ -2855,6 +2917,21 @@
           "enablement": "editorLangId == clojure && calva:connected",
           "command": "calva.setOutputWindowNamespace",
           "group": "calva/b-eval"
+        },
+        {
+          "enablement": "editorLangId == clojure && !calva:activeEditorIsFiddle",
+          "command": "calva.openFiddleForSourceFile",
+          "group": "calva/a-fiddle"
+        },
+        {
+          "enablement": "calva:connected && editorLangId == clojure && !calva:activeEditorIsFiddle",
+          "command": "calva.evaluateFiddleForSourceFile",
+          "group": "calva/a-fiddle"
+        },
+        {
+          "enablement": "editorLangId == clojure && calva:activeEditorIsFiddle",
+          "command": "calva.openSourceFileForFiddle",
+          "group": "calva/a-fiddle"
         }
       ],
       "editor/context": [
@@ -2873,7 +2950,7 @@
         {
           "when": "editorLangId == clojure",
           "command": "calva.selectCurrentForm",
-          "group": "calva/a-eval"
+          "group": "calva/a-structural-editing"
         },
         {
           "when": "editorLangId == clojure",