Merge pull request #2584 from BetterThanTomorrow/2583-auto-jack-in

Add configuration for auto jack-in on project open

CHANGELOG.md

@@ -4,6 +4,8 @@ Changes to Calva.
 
 ## [Unreleased]
 
+- [Add configuration for automatically starting and connecting the project REPL](https://github.com/BetterThanTomorrow/calva/issues/2583)
+
 ## [2.0.459] - 2024-06-23
 
 - [Do not open auto open the jack-in terminal by default](https://github.com/BetterThanTomorrow/calva/issues/2578)

bundled/minimal/.vscode/settings.json

@@ -1,12 +1,10 @@
+// Configurration of the mini-project for use with Calva
+// It will autostart the repl and connect it to the editor (Jack-in)
 {
-  "calva.autoOpenInspector": true,
-  "calva.autoOpenREPLWindow": false,
-  "calva.enableInspectorRainbow": true,
-  "calva.outputDestinations": {
-    "evalResults": "terminal",
-    "evalOutput": "terminal",
-    "otherOutput": "terminal"
-  },
+  // It will autostart the repl and connect it to the editor (Jack-in)
+  // https://calva.io/customizing-jack-in-and-connect/#customizing-jack-in
+  "calva.autoStartRepl": true,
+  // https://calva.io/connect-sequences/
   "calva.replConnectSequences": [
     {
       "name": "The Minimal Clojure Project",
@@ -19,5 +17,30 @@
         "cljAliases": ["test"]
       }
     }
-  ]
+  ],
+
+  // The below settings are more suitible for user settings.
+  // They are included here to make it easier to write guides
+  // about using Calva to create the mini project.
+  // You can also regard them as a suggestion for a nice repl
+  // workflow setup.
+  // Remove them from here to keep using your custom user settings.
+
+  // It will use the Output “terminal” for evaluation results
+  // and side effect output.
+  // https://calva.io/output/
+  "calva.outputDestinations": {
+    "evalResults": "terminal",
+    "evalOutput": "terminal",
+    "otherOutput": "terminal"
+  },
+  // It reveals the Calva Inspector when the repl connects.
+  //   (All evaluation results are available in the inspector.)
+  "calva.autoOpenInspector": true,
+  "calva.enableInspectorRainbow": true,
+  // It won't open the REPL prompt window automatically
+  // We recommend using regular editor files instead.
+  // (There's a command for opening the REPL window.)
+  "calva.autoOpenREPLWindow": false
+  // See also: https://calva.io/fiddle-files/
 }

bundled/minimal/src/mini/playground.clj

@@ -0,0 +1,8 @@
+(ns mini.playground)
+
+; This project has custom configuration.
+; See .vscode/settings.json
+
+; If you are new to Calva, you may want to use the command:
+; Calva: Create a “Getting Started” REPL project
+; which creates a project with a an interactive Calva (and Clojure) guide.

docs/site/getting-started.md

@@ -39,21 +39,8 @@ If you are new to Calva, a good place to start is using the command **Calva: Cre
 
 ![Command Palette Getting Started REPL](/images/getting-started-with-clojure/vscode-command-palette-calva-getting-started.png "Create a ”Getting Started” REPL")
 
-It will create a new project, open up a three files, and start and connect a REPL. The files are:
-
-- `hello_repl.clj` – The basics of how to evaluate code in Calva
-- `hello_paredit.clj` - A super brief intro to Calva structural editing
-- `welcome_to_clojure.clj` - The very basics of the Clojure language
-
-![Hello REPL](images/howto/hello-repl.png "hello-repl.clj")
-
-The only prerequisite here is that you have Java installed.
-
 See the [Getting Started with Clojure](get-started-with-clojure.md) guide for a bit more about this feature.
 
-!!! Note
-    On Windows the Oracle Java installer sets Java up in some funny way so that the Getting Started REPL fails to start. We are figuring about workarounds for this, but for now, if you are on Windows, you will need to make VS Code have some other Java in the `PATH` of its environment for this feature to work. See [this issue on the Calva repo](https://github.com/BetterThanTomorrow/calva/issues/1162) for more on this, including any progress.
-
 ### There are standalone ”ClojureScript Quick Start” REPLs
 
 Without creating a project structure or installing anything but Calva, you can start standalone ClojureScript REPLs both in a browser and for node:
@@ -80,9 +67,9 @@ If you are new to Clojure or ClojureScript altogether, please check out the guid
 
 There are also many great books on Clojure. [Clojure for the Brave and True](https://www.braveclojure.com/clojure-for-the-brave-and-true/) can be read for free online. It is a great resource for beginners.
 
-## Create a minimal Clojure project
+## Create a mini Clojure project
 
-When you are more familiar with Calva, and want a standalone REPL, there is a separate command: **Calva: Create a minimal Clojure project**. It will ask for folder to create the project in, and open this project for you, connecting the REPL. The project is _really_ minimal.
+When you are more familiar with Calva, and want a standalone REPL, there is a separate command: **Calva: Create a mini Clojure project**. It will ask for folder to create the project in, and open this project for you, connecting the REPL. This project only contains one source file and has no build tooling. For creating more “real” project starters, we recommend using [deps-new](https://github.com/seancorfield/deps-new), by sSean Corfield.
 
 ## Dram - Where the Guides Live
 

mkdocs.yml

@@ -57,27 +57,29 @@ nav:
     - formatting.md
     - syntax-highlighting.md
     - paredit.md
-    - linting.md
-    - repl-window.md
-    - output.md
-    - inspector.md
-    - fiddle-files.md
+    - REPL:
+      - repl-window.md
+      - output.md
+      - inspector.md
+      - fiddle-files.md
+      - connect-sequences.md
+      - custom-commands.md
     - refactoring.md
-    - custom-commands.md
-    - connect-sequences.md
     - notebooks.md
     - clojuredocs.md
     - debugger.md
     - pprint.md
     - test-runner.md
     - rich-comments.md
-    - namespace-form-auto-creation.md
     - hiccup.md
+  - Via clojure-lsp:
+    - clojure-lsp.md
+    - linting.md
+    - namespace-form-auto-creation.md
   - Customizing Calva:
     - customizing.md
     - customizing-jack-in-and-connect.md
     - when-clauses.md
-  - clojure-lsp.md
   - nrepl_and_cider-nrepl.md
   - Using Calva with ...:
     - shadow-cljs.md
@@ -106,10 +108,9 @@ nav:
   - API:
     - api.md
     - commands.md
-  - In Depth:
-    - jack-in-guide.md
   - Guides:
     - get-started-with-clojure.md
+    - jack-in-guide.md
   - tao.md
   - contribute.md
   - sponsors.md

package.json

@@ -460,6 +460,11 @@
             "default": false,
             "markdownDescription": "If true, Calva will auto-connect the REPL when a project is opened and there exists an nRepl port file."
           },
+          "calva.autoStartRepl": {
+            "type": "boolean",
+            "default": false,
+            "markdownDescription": "If true, Calva will auto-start and connect the REPL (a.k.a. Jack-in) when a Clojure project is opened. **NB:** To fully automate the jack-in process, you need to configure `calva.replConnectSequences` such that one sequence is marked with `autoSelectForJackIn`, has `projectRootPath` set, and has `menuSelections` configured."
+          },
           "calva.jackInDependencyVersions": {
             "type": "object",
             "description": "Versions of the dependencies injected by Calva Jack-in",
@@ -1320,7 +1325,7 @@
       },
       {
         "command": "calva.createMinimalProject",
-        "title": "Create a minimal Clojure project",
+        "title": "Create a mini Clojure project",
         "category": "Calva"
       },
       {
@@ -3314,6 +3319,7 @@
     "compile-test": "tsc -p ./",
     "postrelease": "",
     "package-vsix": "vsce package",
+    "package-vsix-prerelease": "vsce package",
     "vscode:prepublish": "npm run release",
     "bump-version": "npm set git-tag-version false && npm version patch",
     "calva-lib-test": "node ./out/cljs-lib/test/cljs-lib-tests.js",

src/config.ts

@@ -246,6 +246,7 @@ function getConfig() {
     depsCljPath: configOptions.get<string>('depsCljPath'),
     autoSelectNReplPortFromPortFile: configOptions.get<boolean>('autoSelectNReplPortFromPortFile'),
     autoConnectRepl: configOptions.get<boolean>('autoConnectRepl'),
+    autoStartRepl: configOptions.get<boolean>('autoStartRepl'),
     html2HiccupOptions: configOptions.get<converters.HiccupOptions>('html2HiccupOptions'),
     autoEvaluateCode: nreplUtil.mergeAutoEvaluateConfigs(
       [

src/extension.ts

@@ -550,12 +550,14 @@ async function activate(context: vscode.ExtensionContext) {
     );
   }
 
-  if (await connector.shouldAutoConnect()) {
+  fiddleFiles.activate(context);
+
+  if (config.getConfig().autoStartRepl) {
+    void vscode.commands.executeCommand('calva.jackIn');
+  } else if (await connector.shouldAutoConnect()) {
     void vscode.commands.executeCommand('calva.connect');
   }
 
-  fiddleFiles.activate(context);
-
   void dramRepl.maybeStartDramRepl();
 
   console.info('Calva activate END');

src/nrepl/dram-repl.ts

@@ -1,14 +1,10 @@
 import * as vscode from 'vscode';
 import * as path from 'path';
 import * as state from '../state';
-import eval from '../evaluate';
 import * as utilities from '../utilities';
 import * as sequence from './connectSequence';
-import * as jackIn from './jack-in';
-import { getConfig } from '../config';
 import * as cljsLib from '../../out/cljs-lib/cljs-lib';
 import { ReplConnectSequence } from './connectSequence';
-import * as output from '../results-output/output';
 import { ConnectType } from './connect-types';
 import * as replStart from './repl-start';
 
@@ -31,7 +27,7 @@ export const USER_TEMPLATE: DramTemplate = {
   config: {
     name: 'Standalone REPL',
     files: [
-      { path: 'src/minimal_clj/playground.clj', 'open?': true },
+      { path: 'src/mini/playground.clj', 'open?': true },
       { path: 'deps.edn', 'open?': false },
       { path: '.gitignore', 'open?': false },
       { path: '.vscode/settings.json', 'open?': false },
@@ -323,19 +319,10 @@ export async function startDramRepl() {
   const firstPos = mainEditor.document.positionAt(0);
   mainEditor.selections = [new vscode.Selection(firstPos, firstPos)];
   mainEditor.revealRange(new vscode.Range(firstPos, firstPos));
+
   await vscode.window.showTextDocument(mainDoc, {
     preview: false,
     viewColumn: vscode.ViewColumn.One,
     preserveFocus: false,
   });
-
-  return jackIn.jackIn(args.dramTemplate.connectSequence, false, async () => {
-    await vscode.window.showTextDocument(mainDoc, {
-      preview: false,
-      viewColumn: vscode.ViewColumn.One,
-      preserveFocus: false,
-    });
-    await eval.loadDocument({}, getConfig().prettyPrintingOptions);
-    output.replWindowAppendPrompt();
-  });
 }

src/nrepl/repl-start.ts

@@ -39,7 +39,7 @@ const OPEN_SOURCE_FOR_FIDDLE_OPTION = 'Open Source File for Current Fiddle';
 const OPEN_SOURCE_FOR_FIDDLE_COMMAND = 'calva.openSourceFileForFiddle';
 export const JACK_IN_OPTION = 'Start your project with a REPL and connect (a.k.a. Jack-in)';
 const JACK_IN_COMMAND = 'calva.jackIn';
-export const CREATE_PROJECT_OPTION = 'Create a minimal Clojure project';
+export const CREATE_PROJECT_OPTION = 'Create a mini Clojure project';
 const CREATE_PROJECT_COMMAND = 'calva.createMinimalProject';
 const START_JOYRIDE_REPL_OPTION = 'Start a Joyride REPL and Connect';
 const START_JOYRIDE_REPL_COMMAND = 'calva.startJoyrideReplAndConnect';