diff --git a/customizing-jack-in-and-connect/index.html b/customizing-jack-in-and-connect/index.html
index 956b73d10..632df6596 100644
--- a/customizing-jack-in-and-connect/index.html
+++ b/customizing-jack-in-and-connect/index.html
@@ -1069,6 +1069,15 @@
     <nav class="md-nav" aria-label="Customizing Jack-in">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#jack-in-dependency-versions" class="md-nav__link">
+    <span class="md-ellipsis">
+      Jack-in Dependency Versions
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#options-for-the-jack-in-command" class="md-nav__link">
     <span class="md-ellipsis">
@@ -2025,6 +2034,15 @@
     <nav class="md-nav" aria-label="Customizing Jack-in">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#jack-in-dependency-versions" class="md-nav__link">
+    <span class="md-ellipsis">
+      Jack-in Dependency Versions
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#options-for-the-jack-in-command" class="md-nav__link">
     <span class="md-ellipsis">
@@ -2121,7 +2139,7 @@ <h2 id="auto-evaluate-code-on-connect">Auto-evaluate Code on Connect<a class="he
 <p>If you configure this both in User/global settings and in a Workspace, the workspace configured code will be concatenated on the user level code. Meaning both code snippets will be evaluated, first the User level code, then the Workspace level code. Also <code>null</code> disables the feature:</p>
 <ul>
 <li>If you use <code>null</code> in the User level code, you will disable the onConnect code evaluation for all workspaces that do not configure code for this.</li>
-<li>If you configure code on the User level it will be evaluated in all workspaces, except those that disable the feature by configuring <code>null</code>. </li>
+<li>If you configure code on the User level it will be evaluated in all workspaces, except those that disable the feature by configuring <code>null</code>.</li>
 </ul>
 </div>
 <h2 id="auto-evaluate-code-at-filenamespace-loadevaluation">Auto-evaluate Code at file/namespace load/evaluation<a class="headerlink" href="#auto-evaluate-code-at-filenamespace-loadevaluation" title="Permanent link">#</a></h2>
@@ -2165,11 +2183,30 @@ <h2 id="customizing-jack-in">Customizing Jack-in<a class="headerlink" href="#cus
 <li><code>calva.myLeinProfiles</code>: An array of Leiningen profiles not found in <code>project.clj</code>. Use this to tell Calva Jack-in to launch your REPL using your user defined profiles.</li>
 <li><code>calva.openBrowserWhenFigwheelStarted</code>: <em>For Legacy Figwheel only.</em> A boolean controlling if Calva should automatically launch your ClojureScript app, once it is compiled by Figwheel. Defaults to <code>true</code>.</li>
 <li><code>calva.depsEdnJackInExecutable</code>: A string which should either be <code>clojure</code> or <code>deps.clj</code>, or <code>clojure or deps.clj</code> (default). It determines which executable Calva Jack-in should use for starting a <code>deps.edn</code> project. With this setting at its default, <code>clojure or deps.clj</code>, Calva will test if the <code>clojure</code> executable works, and use it if it does, otherwise <code>deps.clj</code> will be used, which is bundled with Calva.</li>
+<li><code>calva.jackInDependencyVersions</code>: See <a href="#jack-in-dependency-versions">below</a></li>
 </ul>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>When processing the <code>calva.jackInEnv</code> setting you can refer to existing ENV variables with <code>${env:VARIABLE}</code>.</p>
 </div>
+<h3 id="jack-in-dependency-versions">Jack-in Dependency Versions<a class="headerlink" href="#jack-in-dependency-versions" title="Permanent link">#</a></h3>
+<p><a href="../jack-in-guide/">Calva Jack-in</a> injects the following dependencies in order for the REPL session to support IDE features</p>
+<ul>
+<li><a href="https://github.com/nrepl/nrepl">nrepl</a>: nREPL is the wonderful piece of software that gives Calva a structured and extensible connection to the REPL in your Clojure and ClojureScript projects.</li>
+<li><a href="https://github.com/clojure-emacs/cider-nrepl">cider-nrepl</a>: cider-nrepl is middleware that extends the nREPL connection with all sorts of nice stuff that Calva uses to give you a delightful IDE experience.</li>
+<li><a href="https://github.com/nrepl/piggieback">cider/piggieback</a>: Piggieback is used to create nREPL sessions in ClojureScript projects. (Not with <a href="http://shadow-cljs.org">shadow-cljs</a> projects though, which provides its own middleware for this.)</li>
+</ul>
+<p>The versions used are configurable via the VS Code settings <code>calva.jackInDependencyVersions</code>.</p>
+<div class="admonition note">
+<p class="admonition-title">Java 1.8 compatible versions</p>
+<p>The default dependency versions are not compatible with Java 1.8. If your project needs that version of Java you can use these settings in your Workspace <code>.vscode/settings.json</code>:</p>
+<div class="highlight"><pre><span></span><code><span class="nt">&quot;calva.jackInDependencyVersions&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
+<span class="w">  </span><span class="nt">&quot;nrepl&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;1.0.0&quot;</span><span class="p">,</span>
+<span class="w">  </span><span class="nt">&quot;cider-nrepl&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;0.28.5&quot;</span><span class="p">,</span>
+<span class="w">  </span><span class="nt">&quot;cider/piggieback&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;0.5.3&quot;</span>
+<span class="p">}</span>
+</code></pre></div>
+</div>
 <h3 id="options-for-the-jack-in-command">Options for the Jack-in Command<a class="headerlink" href="#options-for-the-jack-in-command" title="Permanent link">#</a></h3>
 <p>The <code>calva.jackIn</code> command takes an optional options argument defined like so:</p>
 <div class="highlight"><pre><span></span><code><span class="w">  </span><span class="nx">options</span><span class="o">?:</span><span class="w"> </span><span class="p">{</span>
@@ -2192,13 +2229,13 @@ <h3 id="options-for-the-jack-in-command">Options for the Jack-in Command<a class
 <span class="w"> </span><span class="p">(</span><span class="nf">clj-&gt;js</span><span class="w"> </span><span class="p">{</span><span class="ss">:connectSequence</span><span class="w"> </span><span class="p">{</span><span class="ss">:projectType</span><span class="w"> </span><span class="s">&quot;deps.edn&quot;</span>
 <span class="w">                             </span><span class="ss">:projectRootPath</span><span class="w"> </span><span class="p">[</span><span class="s">&quot;.&quot;</span><span class="p">]}}))</span>
 </code></pre></div>
-<p>It will prompt for any aliases it finds in the <code>deps.edn</code> file.    </p>
+<p>It will prompt for any aliases it finds in the <code>deps.edn</code> file.</p>
 <h2 id="starting-the-repl-from-application-code">Starting the REPL from application code?<a class="headerlink" href="#starting-the-repl-from-application-code" title="Permanent link">#</a></h2>
 <p>If your project is setup so that the REPL server is started by the application code, you will need to get the cider-nrepl middleware in place. See the cider-nrepl docs about <a href="https://docs.cider.mx/cider-nrepl/usage.html#via-embedding-nrepl-in-your-application">embedding nREPL in your application</a>.</p>
 <h2 id="auto-select-project-type-and-project-root">Auto-select Project Type and Project Root<a class="headerlink" href="#auto-select-project-type-and-project-root" title="Permanent link">#</a></h2>
 <p>You can make both Jack-in and Connect stop prompting you for project type and project root path in projects where you always want to use the same. See <a href="../connect-sequences/">Connect Sequences</a>.</p>
 <h2 id="project-roots-search-globing">Project roots search globing<a class="headerlink" href="#project-roots-search-globing" title="Permanent link">#</a></h2>
-<p>When searching for project roots in your workspace, Calva will glob for all files matching <code>project.clj</code>, <code>deps.edn</code>, or <code>shadow-cljs.edn</code>. This is done using VS Code's workspace search engine, and is very efficient. However, in a large monorepo, it is still a substantial task. In order to not waste resources Calva will exclude any directories in the setting <code>calva.projectRootsSearchExclude</code>. </p>
+<p>When searching for project roots in your workspace, Calva will glob for all files matching <code>project.clj</code>, <code>deps.edn</code>, or <code>shadow-cljs.edn</code>. This is done using VS Code's workspace search engine, and is very efficient. However, in a large monorepo, it is still a substantial task. In order to not waste resources Calva will exclude any directories in the setting <code>calva.projectRootsSearchExclude</code>.</p>
 <p><img alt="calva.projectRootsSearchExclude setting" src="../images/calva-project-roots-search-exclude.png" /></p>
 <div class="admonition note">
 <p class="admonition-title">Exclude entry globs</p>
diff --git a/customizing/index.html b/customizing/index.html
index 94c561bcc..db9c247ac 100644
--- a/customizing/index.html
+++ b/customizing/index.html
@@ -1057,15 +1057,6 @@
     </span>
   </a>
   
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#jack-in-dependency-versions" class="md-nav__link">
-    <span class="md-ellipsis">
-      Jack-in Dependency Versions
-    </span>
-  </a>
-  
 </li>
       
         <li class="md-nav__item">
@@ -2055,15 +2046,6 @@
     </span>
   </a>
   
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#jack-in-dependency-versions" class="md-nav__link">
-    <span class="md-ellipsis">
-      Jack-in Dependency Versions
-    </span>
-  </a>
-  
 </li>
       
         <li class="md-nav__item">
@@ -2183,14 +2165,7 @@ <h2 id="code-formatting">Code Formatting<a class="headerlink" href="#code-format
 <p>See <a href="../formatting/">Formatting</a> for information on how to configure this.</p>
 <h2 id="jack-in-and-connect">Jack-in and Connect<a class="headerlink" href="#jack-in-and-connect" title="Permanent link">#</a></h2>
 <p>Jack-in and Connect are very customizable through <a href="../connect-sequences/">Custom Connect Sequences</a>.</p>
-<h2 id="jack-in-dependency-versions">Jack-in Dependency Versions<a class="headerlink" href="#jack-in-dependency-versions" title="Permanent link">#</a></h2>
-<p><a href="../jack-in-guide/">Calva Jack-in</a> injects the following dependencies in order for the REPL session to support IDE features</p>
-<ul>
-<li><a href="https://github.com/nrepl/nrepl">nrepl</a>: nREPL is the wonderful piece of software that gives Calva a structured and extensible connection to the REPL in your Clojure and ClojureScript projects.</li>
-<li><a href="https://github.com/clojure-emacs/cider-nrepl">cider-nrepl</a>: cider-nrepl is middleware that extends the nREPL connection with all sorts of nice stuff that Calva uses to give you a delightful IDE experience.</li>
-<li><a href="https://github.com/nrepl/piggieback">cider/piggieback</a>: Piggieback is used to create nREPL sessions in ClojureScript projects. (Not with <a href="http://shadow-cljs.org">shadow-cljs</a> projects though, which provides its own middleware for this.)</li>
-</ul>
-<p>The versions used are configurable via the VS Code settings <code>calva.jackInDependencyVersions</code>.</p>
+<p>See also <a href="../customizing-jack-in-and-connect/">Customizing Jack-in and Connect</a></p>
 <h2 id="key-bindings">Key bindings<a class="headerlink" href="#key-bindings" title="Permanent link">#</a></h2>
 <p>Most of Calva's commands have default keybindings. They are only defaults, though, and you can change keybindings as you wish. To facilitate precision in binding keys Calva keeps some <a href="https://code.visualstudio.com/api/references/when-clause-contexts">when clause contexts</a> updated.</p>
 <h3 id="when-clause-contexts">When Clause Contexts<a class="headerlink" href="#when-clause-contexts" title="Permanent link">#</a></h3>
diff --git a/search/search_index.json b/search/search_index.json
index c83ee7546..dc3d07cf4 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-\\._]","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome!","text":"<p>Calva is an integrated, REPL powered, development environment for enjoyable and productive Clojure and ClojureScript programming in Visual Studio Code. It is feature rich and turnkey. A lot of effort has been put into making Calva a good choice if you are new to Clojure. Calva is open source and free to use.</p>"},{"location":"#getting-started","title":"Getting Started","text":"<p>Let's start a REPL!. \ud83d\ude80 Also see Get Started with Clojure</p>"},{"location":"#how-to-contribute-to-calva","title":"How to Contribute to Calva?","text":"<p>I'm glad you asked! Please see How to Contribute and The Tao of Calva</p>"},{"location":"#calva-patrons","title":"Calva Patrons","text":"The right kind of different"},{"location":"#calva-gold-sponsors","title":"Calva Gold Sponsors \u2665\ufe0f","text":"Scale your growth on mobile MAKE. DO. SHIP. <p>Please see this statement from Cognitect about the importance of supporting open source developers.</p> <p>See Sponsors for information about sponsoring Calva.</p> <p>If your Company benefits from Calva's existence and you see it as an important in the Clojure and ClojureScript ecosystem. please consider sponsoring!</p>"},{"location":"#features","title":"Features","text":"<p>Calva includes inline code evaluation, structural editing, code formatting, code navigation, a debugger, linting, syntax highlighting, Clojure aware rainbow brackets, a test runner, refactoring support, and more. </p>"},{"location":"#have-questions-and-feedback-need-help","title":"Have Questions and Feedback? Need Help?","text":"<p>Easiest way is to chat with us and other Calva users. Please join the #calva channel on the Clojurians Slack. If you haven't joined that slack workspace, you can get an invite here.</p> <p>If you're a beginner to Clojure(Script), the #beginners channel of the Clojurians Slack is very active and helpful.</p>"},{"location":"#please-star-the-calva-repo","title":"Please star the Calva repo!","text":"<p>Happy coding!</p>"},{"location":"api/","title":"The Calva Extension API","text":"<p>Calva exposes an API for use from other VS Code extensions (such as Joyride). The API is in an experimental state, while we are figuring out what is a good shape for this API. It is also rather small, and will grow to expose more of Calva's functionality.</p>","boost":7},{"location":"api/#accessing","title":"Accessing","text":"<p>To access the API the Calva extension needs to be activated. The API is exposed under the <code>v1</code> key on the extension's <code>exports</code>, and split up into submodules, like <code>repl</code>, and <code>ranges</code>.</p> <p>When using Joyride you can use its unique <code>require</code> API, for which one of the benefits is better lookup IDE support. When using the API from regular ClojureScript, you'll pick it up from the Calva extension instance. (Which you can do from Joyride as well, but why would you?). Here is how you access the API, with an example of usage as a bonus:</p> JoyrideClojureScriptJavaScript <pre><code>(ns ... (:require [\"ext://betterthantomorrow.calva$v1\" :as calva]))\n;; OR\n(require '[\"ext://betterthantomorrow.calva$v1\" :as calva])\n\n(calva/repl.currentSessionKey) =&gt; \"cljs\" ; or \"clj\", depending\n</code></pre> <pre><code>(def calvaExt (vscode/extensions.getExtension \"betterthantomorrow.calva\"))\n\n(def calva (-&gt; calvaExt\n             .-exports\n             .-v1\n             (js-&gt;clj :keywordize-keys true)))\n\n((get-in calva [:repl :currentSessionKey])) =&gt; \"cljs\" ; or \"clj\", depending\n</code></pre> <pre><code>const calvaExt = vscode.extensions.getExtension(\"betterthantomorrow.calva\");\n\nconst calva = calvaExt.exports.v1;\n\nconst sessionKey = calva.repl.currentSessionKey()\n</code></pre>","boost":7},{"location":"api/#repl","title":"<code>repl</code>","text":"<p>The <code>repl</code> module provides access to Calva's REPL connection.</p>","boost":7},{"location":"api/#replcurrentsessionkey","title":"<code>repl.currentSessionKey()</code>","text":"<p>Use <code>repl.currentSessionKey()</code> find out which REPL/session Calva's REPL is currently connected to (depends on the active file). Returns either <code>\"clj\"</code>, or <code>\"cljs\"</code>, or <code>nil</code> if no REPL is connected.</p> JoyrideClojureScriptJavaScript <pre><code>(def session-key (calva/repl.currentSessionKey))\n</code></pre> <pre><code>(def session-key ((get-in [:repl :currentSessionKey] calvaApi)))\n</code></pre> <pre><code>const sessionKey = calva.repl.currentSessionKey()\n</code></pre>","boost":7},{"location":"api/#replevaluatecode","title":"<code>repl.evaluateCode()</code>","text":"<p>This function lets you evaluate Clojure code through Calva's nREPL connection. Calling it returns a promise that resolves to a <code>Result</code> object. It's signature looks like so (TypeScript):</p> <pre><code>export async function evaluateCode(\n  sessionKey: 'clj' | 'cljs' | 'cljc' | undefined,\n  code: string,\n  ns = 'user',\n  output?: {\n    stdout: (m: string) =&gt; void;\n    stderr: (m: string) =&gt; void;\n  },\n  opts = {}\n): Promise&lt;Result&gt;;\n</code></pre> <p>Where <code>Result</code> is:</p> <pre><code>type Result = {\n  result: string;\n  ns: string;\n  output: string;\n  errorOutput: string;\n};\n</code></pre> <p>As you can see, the required arguments to the function are <code>sessionKey</code> and <code>code</code>. <code>sessionKey</code> should be <code>\"clj\"</code>, <code>\"cljs\"</code>, <code>\"cljc\"</code>, or <code>undefined</code> depending on which of Calva's REPL sessions/connections that should be used. It will depend on your project, and how you connect to it, which session keys are valid. Use <code>cljc</code> to request whatever REPL session <code>\"cljc\"</code> files are connected to. Use <code>undefined</code> to use the current REPL connection Calva would use (depends on which file is active).</p> <p>An example:</p> JoyrideClojureScriptJavaScript <pre><code>(-&gt; (p/let [evaluation (calva/repl.evaluateCode \"clj\" \"(+ 2 40)\")]\n      (println (.-result evaluation)))\n    (p/catch (fn [e]\n               (println \"Evaluation error:\" e))))\n</code></pre> <pre><code>(def evaluate (get-in [:repl :evaluateCode] calvaApi))\n(-&gt; (p/let [evaluation (evaluate \"clj\" \"(+ 2 40)\")]\n      (println (.-result evaluation)))\n    (p/catch (fn [e]\n               (println \"Evaluation error:\" e))))\n</code></pre> <pre><code>try {\n  const evaluation = await calvaApi.repl.evaluateCode(\"clj\", \"(+ 2 40)\");\n  console.log(evaluation.result);\n} catch (e) {\n  console.error(\"Evaluation error:\", e);\n}\n</code></pre>","boost":7},{"location":"api/#handling-output","title":"Handling Output","text":"<p>The <code>output</code> member on the <code>Result</code> object will have any output produced during evaluation. (The <code>errorOutput</code> member should contain error output produced, but currently some Calva bug makes this not work.) By default the stdout and stderr output is not printed anywhere.</p> <p>If you want to do something with either regular output or error output during, or after, evaluation, you'll need to provide the <code>output</code> argument to <code>evaluateCode()</code>. (The <code>stderr</code> callback function works, so this is the only way to get at any error output, until the above mentioned Calva bug is fixed.)</p> <p>An example:</p> JoyrideClojureScriptJavaScript <pre><code>(def oc (joyride.core/output-channel)) ;; Assuming Joyride is used\n(def evaluate (fn [code]\n                (calva/repl.evaluateCode\n                 \"clj\"\n                 code\n                 \"user\"\n                 #js {:stdout #(.append oc %)\n                      :stderr #(.append oc (str \"Error: \" %))})))\n\n(-&gt; (p/let [evaluation (evaluate \"(println :foo) (+ 2 40)\")]\n      (.appendLine oc (str \"=&gt; \" (.-result evaluation))))\n    (p/catch (fn [e]\n               (.appendLine oc (str \"Evaluation error: \" e)))))\n</code></pre> <pre><code>(def oc (joyride.core/output-channel)) ;; Assuming Joyride is used\n(def evaluate (fn [code]\n                ((get-in [:repl :evaluateCode] calvaApi)\n                 \"clj\"\n                 code\n                 \"user\"\n                 #js {:stdout #(.append oc %)\n                      :stderr #(.append oc (str \"Error: \" %))})))\n\n(-&gt; (p/let [evaluation (evaluate \"(println :foo) (+ 2 40)\")]\n      (.appendLine oc (str \"=&gt; \" (.-result evaluation))))\n    (p/catch (fn [e]\n               (.appendLine oc (str \"Evaluation error: \" e)))))\n</code></pre> <pre><code>const evaluate = (code) =&gt;\n  calvaApi.repl.evaluateCode(\"clj\", code, \"user\", {\n    stdout: (s) =&gt; {\n      console.log(s);\n    },\n    stderr: (s) =&gt; {\n      console.error(s);\n    },\n  });\n\ntry {\n  const evaluation = await evaluate(\"(println :foo) (+ 2 40)\");\n  console.log(\"=&gt;\", evaluation.result);\n} catch (e) {\n  console.error(\"Evaluation error:\", e);\n}\n</code></pre>","boost":7},{"location":"api/#ranges","title":"<code>ranges</code>","text":"<p>The <code>ranges</code> module contains functions for retreiving vscode.Ranges and text for pieces of interest in a Clojure document.</p> <p>All functions in this module have the following TypeScript signature:</p> <pre><code>(editor = vscode.window.activeTextEditor, position = editor?.selection?.active) =&gt; [vscode.Range, string];\n</code></pre> <p>I.e. they expect a vscode.TextEditor \u2013 defaulting to the currently active editor \u2013 and a vscode.Position \u2013 defaulting to the current active position in the editor (or the first active position if multiple selections/positions exist, and will return a tuple with the range, and the text for the piece of interest requested.</p> <p>Custom REPL Commands</p> <p>The <code>ranges</code> function have corresponding REPL Snippets/Commands substitution variables. It is the same implementation functions used in both cases.</p> <p>The functions available are:</p>","boost":7},{"location":"api/#rangescurrentform","title":"<code>ranges.currentForm()</code>","text":"<p>Retrieves information about the current form, as determined from the editor and position.</p> <p>Corresponding REPL Snippet variable: <code>$current-form</code>.</p> <p>See also about Calva's Current Form on YouTube.</p>","boost":7},{"location":"api/#rangescurrentenclosingform","title":"<code>ranges.currentEnclosingForm()</code>","text":"<p>The list/vector/etcetera form comtaining the current form.</p> <p>Corresponding REPL Snippet variable: <code>$enclosing-form</code>.</p>","boost":7},{"location":"api/#rangescurrenttoplevelform","title":"<code>ranges.currentTopLevelForm()</code>","text":"<p>The current top level form. Outside <code>(comment ...)</code> (Rich comments) forms this is most often (<code>(def ...), (defgn ...)</code>, etcetera. Inside Rich comments it will be the current immediate child to the <code>(comment ...)</code> form.</p> <p>Corresponding REPL Snippet variable: <code>$top-level-form</code>.</p>","boost":7},{"location":"api/#rangescurrentfunction","title":"<code>ranges.currentFunction()</code>","text":"<p>The current function, i.e. the form in \u201dcall position\u201d of the closest enclosing list.</p> <p>Corresponding REPL Snippet variable: <code>$current-fn</code>.</p>","boost":7},{"location":"api/#rangescurrenttopleveldef","title":"<code>ranges.currentTopLevelDef()</code>","text":"<p>The symbol being defined by the current top level form. NB: Will stupidly assume it is the second form. I.e. it does not check that it is an actual definition, and will often return nonsense if used in Rich comments.</p> <p>Corresponding REPL Snippet variable: <code>$top-level-defined-symbol</code>.</p>","boost":7},{"location":"api/#example-rangescurrenttoplevelform","title":"Example: <code>ranges.currentTopLevelForm()</code>","text":"JoyrideClojureScriptJavaScript <pre><code>(let [[range text] (calva/ranges.currentTopLevelForm)]\n  ...)\n</code></pre> <pre><code>(let [[range text] ((get-in [:ranges :currentTopLevelForm]))]\n  ...)\n</code></pre> <pre><code>const [range, text] = ranges.currentTopLevelForm();\n</code></pre>","boost":7},{"location":"api/#editor","title":"<code>editor</code>","text":"<p>The <code>editor</code> module has facilites (well, a facility, so far) for editing Clojure documents.</p>","boost":7},{"location":"api/#editorreplace","title":"<code>editor.replace()</code>","text":"<p>With <code>editor.replace()</code> you can replace a range in a Clojure editor with new text. The arguments are:</p> <ul> <li><code>editor</code>, a <code>vscode.TextEditor</code></li> <li><code>range</code>, a <code>vscode.Range</code></li> <li><code>newText</code>, a string</li> </ul> JoyrideJavaScript <pre><code>(-&gt; (p/let [top-level-form-range (first (calva/ranges.currentTopLevelForm))\n            _ (calva/editor.replace vscode/window.activeTextEditor top-level-form-range \"Some new text\")]\n      (println \"Text replaced!\"))\n    (p/catch (fn [e]\n               (println \"Error replacing text:\" e))))\n</code></pre> <pre><code>const topLevelRange = calvaApi.ranges.currentTopLevelForm();\ncalva.editor.replace(topLevelRange, \"Some new text\")\n  .then((_) =&gt; console.log(\"Text replaced!\"))\n  .catch((e) =&gt; console.log(\"Error replacing text:\", e));\n</code></pre>","boost":7},{"location":"api/#document","title":"<code>document</code>","text":"<p>The <code>document</code> module provides access to the Clojure/Calva aspects of VS Code <code>TextDocument</code>s.</p>","boost":7},{"location":"api/#documentgetnamespacedocument-vscodetextdocument-string","title":"<code>document.getNamespace(document?: vscode.TextDocument): string</code>","text":"<p><code>document.getNamespace()</code> returns the namespace of a document.</p> <ul> <li><code>document</code>, a <code>vscode.TextDocument</code> (defaults to the current active document)</li> </ul> <p>Example usage. To evaluate some code in the namespace of the current document:</p> JoyrideJavaScript <pre><code>(calva/repl.evaluateCode \"clj\" \"(+ 1 2 39)\" (calva/document.getNamespace))\n</code></pre> <pre><code>calva.repl.evaluateCode(\"clj\",  \"(+ 1 2 39)\", calva.document.getNamespace());\n</code></pre>","boost":7},{"location":"api/#documentgetnamespaceandnsformdocument-vscodetextdocument-ns-string-nsform-string","title":"<code>document.getNamespaceAndNsForm(document?: vscode.TextDocument): [ns: string, nsForm: string]</code>","text":"<p><code>document.getNamespaceAndNsForm()</code> returns the namespace and the <code>ns</code> form of a document as a tuple.</p> <ul> <li><code>document</code>, a <code>vscode.TextDocument</code> (defaults to the current active document)</li> </ul> <p>Example usage. To evaluate the <code>ns</code> form of the current document:</p> JoyrideJavaScript <pre><code>(calva/repl.evaluateCode \"clj\" (second (calva/document.getNamespaceAndNsForm)))\n</code></pre> <pre><code>calva.repl.evaluateCode(\"clj\", calva.document.getNamespaceAndNsForm()[1]);\n</code></pre>","boost":7},{"location":"api/#pprint","title":"<code>pprint</code>","text":"<p>The <code>pprint</code> module lets you pretty print Clojure code/data using Calva's pretty printing engine (which in turn uses zprint).</p>","boost":7},{"location":"api/#pprintprettyprint","title":"<code>pprint.prettyPrint()</code>","text":"<p>Use <code>pprint.prettyPrint()</code> to pretty print some Clojure data using your Calva pretty printing options. It accepts these arguments:</p> <ul> <li><code>text</code>, a <code>string</code> with the text to pretty print</li> <li><code>options</code>, a JavaScript object with pretty printing options, this is optional and will default to the current settings.</li> </ul> <p>The function is synchronous and returns the prettified text.</p> JoyrideJavaScript <pre><code>(println (calva/pprint.prettyPrint \"Some text\")))\n</code></pre> <pre><code>console.log(calvaApi.pprint.prettyPrint();\n</code></pre>","boost":7},{"location":"api/#pprintprettyprintingoptions","title":"<code>pprint.prettyPrintingOptions()</code>","text":"<p>Use to get the current pretty printint options:</p>","boost":7},{"location":"api/#vscode","title":"<code>vscode</code>","text":"<p>In the its <code>vscode</code> submodule, Calva exposes access to things from its own <code>vscode</code> module instance. It gets important in some situations.</p>","boost":7},{"location":"api/#vscoderegisterdocumentsymbolprovider","title":"<code>vscode.registerDocumentSymbolProvider()</code>","text":"<p>This is the <code>[vscode.languages](https://code.visualstudio.com/api/references/vscode-api#languages).registerDocumentSymbolProvider()</code> function from the Calva extension. Use it if you want to provide symbols for Clojure files together with the ones that Calva provides. (If you use the <code>vscode.languages.registerDocumentSymbolProvider()</code> function from your extension (or Joyride) you will provide a separate group.)</p> JoyrideClojureScriptJavaScript <pre><code>(-&gt; (joyride/extension-context)\n  .-subscriptions\n  (.push (calva/vscode.registerDocumentSymbolProvider ...)))\n</code></pre> <pre><code>(-&gt; yourExtensionContext\n  .-subscriptions\n  (.push ((get-in calva [:vscode :registerDocumentSymbolProvider]) ...)))\n</code></pre> <pre><code>yourExtensionContext.subscriptions.push(calva.vscode.registerDocumentSymbolProvider(...));\n</code></pre> <p>Deprecation candidate</p> <p>VS Code is still creating a separate group, just with the same name as Calva's, so this API is not good for anything, and we will probably remove it.</p>","boost":7},{"location":"api/#feedback-welcome","title":"Feedback Welcome","text":"<p>Please let us know how you fare using this API. Either in the #calva or #joyride channels on Slack or via the issues/discussions sections on the repositories. (Whichever seems to apply best.)</p>","boost":7},{"location":"async-out/","title":"Viewing Async Output While Working On Node Projects with <code>shadow-cljs</code>","text":"<p>When working on NodeJS projects with <code>shadow-cljs</code> and Calva, async output does not always appear in the Calva output window. To work around this problem, follow these steps:</p> <ol> <li>Run the command \"Calva: Copy Jack-in Command Line to Clipboard\", then paste the command in a terminal and run it.</li> <li>Wait for the message <code>shadow-cljs - nREPL server started on port &lt;some-port&gt;</code></li> <li>Issue the command Calva: Connect to a running REPL server in your project, <code>ctrl+alt+c ctrl+alt+c</code>. For project type select <code>shadow-cljs</code>, accept the proposed <code>localhost:&lt;some-port&gt;</code>, and for <code>build</code> select <code>node-repl</code>.</li> <li>Load a file from your project with the command <code>ctrl+alt+c Enter.</code> Evaluating forms in Calva will show results in the output window. Synchronous <code>stdout</code> output will be printed in both the output window and in the terminal where you started the repl. Some asynchronous output may show up in the output window, but all will appear in the terminal.</li> </ol> <p>If you use an integrated VSCode terminal to start shadow-cljs, all <code>stdout</code> will appear in the Calva window with your code. Alternatively, you can use an external terminal, which is especially nice when using a second monitor.</p> <p>For a discussion of this problem and other connection options, see issue #1468.</p>"},{"location":"babashka/","title":"Using Calva with Babashka","text":"<p>Since Babashka can be started such that it is an nREPL server, Calva can connect to it and a lot of the features will work.</p> <p>Calva can also start Babashka and connect its REPL for you, using the Jack-in command.</p> <p>Don't expect complete support</p> <p>Babashka's nREPL server is still a bit limited compared to a full cider-nrepl enhanced \"regular\" Clojure nREPL server. Things like function signatures, and more do not work.</p> <p>This might of course improve in the future, especially if you provide some PRs towards the Babashka nREPL.</p>","boost":5},{"location":"clj-java-decompiler/","title":"Decompiling and disassembly made easy","text":"<p>If you need some piece of Clojure code to execute as fast as possible you will often benefit from examining the code generated by the Clojure compiler from your code. There is a really easy to use tool for that: clj-java-decompiler. You can make the use of this tool super convenient with Calva custom command snippets.</p>"},{"location":"clj-java-decompiler/#prerequisites","title":"Prerequisites","text":"<p>Add <code>com.clojure-goes-fast/clj-java-decompiler</code> as a dependency to the project.</p>"},{"location":"clj-java-decompiler/#the-custom-snippets","title":"The custom snippets","text":"<p>You can add some Calva custom commands configuration to be able to decompile or disassemble any Clojure code in your editor with a keyboard shortcut. Here's an example configuration:</p> <pre><code>    \"calva.customREPLCommandSnippets\": [\n        {\n            \"name\": \"Decompile current top level form\",\n            \"key\": \"d\",\n            \"snippet\": \"(require '[clj-java-decompiler.core :refer [decompile]]) (spit \\\"decompiled-$top-level-defined-symbol.java\\\" (with-out-str (decompile $top-level-form)))\"\n        },\n        {\n            \"name\": \"Decompile current form\",\n            \"snippet\": \"(require '[clj-java-decompiler.core :refer [decompile]]) (spit \\\"decompiled.java\\\" (with-out-str (decompile $current-form)))\"\n        },\n        {\n            \"name\": \"Disassemble current top level form\",\n            \"key\": \"b\",\n            \"snippet\": \"(require '[clj-java-decompiler.core :refer [disassemble]]) (spit \\\"bytecode-$top-level-defined-symbol.class\\\" (with-out-str (disassemble $top-level-form)))\"\n        },\n        {\n            \"name\": \"Disassemble current current form\",\n            \"snippet\": \"(require '[clj-java-decompiler.core :refer [disassemble]]) (spit \\\"bytecode.class\\\" (with-out-str (disassemble $current-form)))\"\n        }\n    ],\n</code></pre> <p>Now, with the cursor anywhere in a top level defined function, you can spit out a file with the Java code generated for that function by pressing <code>ctrl+alt+space d</code>. For the byte code, press <code>ctrl+alt+space b</code>. The files will be generated in the same folder as the Clojure file and be named <code>decompiled-&lt;function name&gt;.java</code> and <code>bytecode-&lt;function name&gt;.class</code>, respectively. </p> <p>To decompile or disassemble the current form (or selection) press <code>ctrl+alt+space space</code> and pick the desired command from the quick pick menu that pops up. You can add <code>key</code> to these too if you want even quicker access, of course. The filenames for the results will here be named without any function name suffix, because there is often no function name that can be used.</p> <p>See this video for a demo.</p>"},{"location":"clojure-lsp/","title":"Clojure-lsp","text":"<p>Calva uses a mix of static and dynamic analysis to power the experience. A lot of the static abilities come from clojure-lsp. This enables you to check something up in a project, with a lot of navigational and contextual support, without starting a REPL for it. (And once you do start a REPL you'll get even more capabilities, enabled by the dynamic analysis.)</p> <p>Which clojure-lsp does Calva use?</p> <p>Calva defaults to using the <code>latest</code> clojure-lsp released. To use a different version of clojure-lsp, see the configuration section. Calva does not use the clojure-lsp installed on your system, unless you set the path for clojure-lsp to the installed binary in your settings. You can see what version is being used by running the <code>Clojure-lsp Server Info</code> command, which will also show the version of clj-kondo that's being used as well as other info.</p>"},{"location":"clojure-lsp/#the-lsp-server-lifecycle","title":"The LSP server lifecycle","text":"<p>By default you won't need to install/setup anything as Calva handles that for you by automatically downloading the latest clojure-lsp binary. It can take a while for clojure-lsp to start, especially the first time opening a new project, as clojure-lsp (via <code>clj-kondo</code>) indexes the project files.</p> <p>Calva is able to automatically start the clojure-lsp server for you and can be configured to start the server under various different conditions. These behaviours can be configured through the <code>calva.enableClojureLspOnStart</code> setting, which takes the following options:</p> <ul> <li>\"always-use-first-workspace-root\"</li> <li>\"when-workspace-opened-use-workspace-root\"</li> <li>\"when-file-opened-use-furthest-project\"</li> <li>\"never\"</li> </ul>"},{"location":"clojure-lsp/#always-use-first-workspace-root-default","title":"\"always-use-first-workspace-root\" [default]","text":"<p>When set to <code>\"always-use-first-workspace-root\"</code> Calva will attempt to start the clojure-lsp in the root of the first workspace folder if it is a valid clojure project. If it is not a valid clojure project it will fall back to starting the fallback server.</p> <p>This is the default auto-start behaviour.</p>"},{"location":"clojure-lsp/#when-workspace-opened-use-workspace-root","title":"\"when-workspace-opened-use-workspace-root\"","text":"<p>When set to <code>\"when-workspace-opened-use-workspace-root\"</code> Calva will start the clojure-lsp in the root of all opened vscode workspaces. All Clojure files in a workspace will be serviced by the clojure-lsp server running in that workspace. This behavior requires that you are opening workspaces with a valid Clojure project in the root (the directory must contain a <code>deps.edn</code>, <code>project.clj</code> or <code>shadow-cljs.edn</code> file).</p>"},{"location":"clojure-lsp/#when-file-opened-use-furthest-project","title":"\"when-file-opened-use-furthest-project\"","text":"<p>When set to <code>\"when-file-opened-use-furthest-project\"</code> Calva will attempt to start the clojure-lsp server whenever a Clojure file is opened. The LSP server will be started in the outermost valid Clojure project or will fall back to starting in the workspace root if no valid Clojure project can be found. A directory is considered a Clojure project if it contains typical Clojure project files such as a <code>deps.edn</code>, <code>project.clj</code>, or <code>shadow-cljs.edn</code> file. When working in a mono-repo style project or in a multi-workspace VS Code configuration you may have multiple LSP servers running, one for each independent Clojure project opened.</p> <p>Opening files that do not belong to a workspace folder</p> <p>When opening files that do not belong to any of the workspace folders currently open then Calva will fallback to starting the fallback clojure-lsp server</p>"},{"location":"clojure-lsp/#never","title":"\"never\"","text":"<p>When set to <code>\"never\"</code> Calva will never attempt to automatically start the clojure-lsp server. In this case you are responsible for manually starting the server. More advanced users might want to do this in order to have more control over which projects have a clojure-lsp server running for them. To manually start the clojure-lsp server you can run the <code>calva.clojureLsp.start</code> or the <code>calva.clojureLsp.manage</code> command and pick the project root. You can also click the <code>clojure-lsp</code> status bar icon to open the Management Menu.</p> <p>Additionally Calva has commands for:</p> <ul> <li>Inspecting the clojure-lsp server information</li> <li>Read the clojure-lsp server log</li> <li>Stopping any running clojure-lsp processes</li> <li>Starting clojure-lsp</li> <li>Restarting any running clojure-lsp processes</li> <li>Downloading the configured clojure-lsp version</li> </ul> <p>Note that the download command will download the configured clojure-lsp version regardless if it is already installed or not. This can be useful when some earlier download has failed resulting in that clojure-lsp can't be started. NB: It will not download anything if <code>calva.clojureLspPath</code> is set to something non-blank.</p>"},{"location":"clojure-lsp/#fallback-server","title":"Fallback Server","text":"<p>As a fallback behaviour Calva may start a clojure-lsp server in a temporary directory and use this to service lsp requests for clojure files that do not belong to a valid clojure project. This will show up in the management menu looking something like:</p> <p></p> <p>Any files that are handled by this server will have limited classpath analysis and lsp features. It is therefore recommended to setup your project as a clojure project (by creating a <code>deps.edn</code> file in the root, for example).</p>"},{"location":"clojure-lsp/#status-bar","title":"Status bar","text":"<p>In the status bar Calva will show an indicator with the clojure-lsp status. This status will track the currently open project, showing the status (<code>stopped</code>, <code>starting</code> or <code>active</code>) for the relevant clojure-lsp server.</p> <p>You can click on the status-bar item to open the clojure-lsp management menu which will look as follows:</p> <p></p> <p>The menu shows which clojure-lsp servers are active and which are stopped. Selecting a project will allow you to start/stop/restart the server for that project.</p>"},{"location":"clojure-lsp/#ignoring-lsp-cache-files","title":"Ignoring LSP cache files","text":"<p>Clojure-lsp stores its project analysis information in your project. Git users can add these lines to their project root directory <code>.gitignore</code>:</p> <pre><code>.lsp/.cache/\n.lsp/sqlite.*.db\n</code></pre>"},{"location":"clojure-lsp/#configuration","title":"Configuration","text":"<p>For information about how to configure clojure-lsp, see the settings page of the clojure-lsp docs.</p>"},{"location":"clojure-lsp/#changing-the-version-of-clojure-lsp-used-by-calva","title":"Changing the Version of Clojure-lsp Used by Calva","text":"<p>By default, Calva will use the latest released clojure-lsp. You can change the version of clojure-lsp used by Calva by setting the <code>calva.clojureLspVersion</code> property to a version of clojure-lsp found in its GitHub releases. This can be helpful if you're debugging an issue with clojure-lsp or you want to try out a feature of a new release that Calva does not yet use. However, you must remember to reset this setting in order for Calva to automatically use newer versions of clojure-lsp that are released with new versions of Calva.</p> <p>Example:</p> <pre><code>\"calva.clojureLspVersion\": \"2021.04.07-16.34.10\"\n</code></pre> <p>Special \u201dversion\u201d values</p> <p>Apart from the actual versions you can use two special values for this setting:</p> <ul> <li><code>latest</code>: Will download and use the latest stable build of clojure-lsp, when one becomes available. This is the default</li> <li><code>nightly</code>: Will always download and use the latest nightly build, whether there is a new version available or not.</li> </ul>"},{"location":"clojure-lsp/#using-a-custom-clojure-lsp","title":"Using a Custom Clojure-lsp","text":"<p>You can set a path to a custom clojure-lsp to be used by Calva by configuring the <code>calva.clojureLspPath</code> setting. This should be an absolute path to a native binary or JAR file.</p> <p>Example:</p> <pre><code>\"calva.clojureLspPath\": \"/usr/local/bin/clojure-lsp\"\n</code></pre> <p>Will override any <code>calva.clojureLspVersion</code> setting</p> <p>When <code>calva.clojureLspPath</code> is set, the binary at the path will be used uncoditionally, and the <code>calva.clojureLspVersion</code> setting will be ignored.</p>"},{"location":"clojure-lsp/#extra-commands","title":"Extra commands","text":"<p>clojure-lsp provides many useful [commands], and Calva has configuration for most of them. The clojure-lsp team works fast and sometimes Calva might miss some command. And Calva's configuration only really work for clojure-lsp commands that take no argument, or where it makes sense to prompt for the argument. Therefore Calva provides a generic command id, <code>clojure-lsp.command</code> which can be used with keyboard shortcuts and that allow for providing arguments that way. (The command can be used from Joyride too, of course.)</p> <p>When using the command, provide the args as an tuple of <code>[command-name, arguments]</code>, where <code>arguments</code> is an array of any arguments after <code>file-uri, row, col</code> which are common for all clojure-lsp extra commands and are provided automatically by Calva, based on active text editor and where the cursor is. It can look like so when binding a shortcut for <code>extract-function</code>:</p> <pre><code>    {\n        \"key\": \"ctrl+alt+r f\",\n        \"command\": \"clojure-lsp.command\",\n        \"args\": [\"extract-function\", [\"new-function\"]]\n    },\n</code></pre> <p>Note that even though <code>extract-function</code> takes only one argument, you should still provide it via an array.</p>"},{"location":"clojure-lsp/#troubleshooting","title":"Troubleshooting","text":""},{"location":"clojure-lsp/#viewing-the-logs-between-the-client-and-server","title":"Viewing the Logs Between the Client and Server","text":"<p>If something doesn't seem to be working correctly, and you suspect the issue is related to clojure-lsp, a good place to start investigating is the request and response logs between the LSP client and server. In your settings, set <code>clojure.trace.server</code> to <code>verbose</code>, then in the VS Code output tab, select the <code>Clojure Language Client</code> output channel.</p> <p></p> <p>It may be helpful to clear the output channel, then perform the action with which you're experiencing a problem, then read through the log for clues or paste the logs into a related issue in the Calva repo.</p>"},{"location":"clojure-lsp/#server-info-command","title":"Server Info Command","text":"<p>You can run the <code>Clojure-lsp Server Info</code> command to get information about the running clojure-lsp server, such as the version the server being used, the version of clj-kondo it's using, and more. This info is printed to the \"Calva says\" output channel.</p>"},{"location":"clojure-lsp/#opening-the-server-log-file","title":"Opening the Server Log File","text":"<p>You can open the clojure-lsp log file by running the command <code>Calva Diagnostics: Open Clojure-lsp Log File</code>. The log file will only be opened with this command if the clojure-lsp server is running and has finished initializing. If you need to open the file when the server is failing to run or initialize, see the clojure-lsp docs for information on the file location.</p>"},{"location":"clojure-lsp/#server-initialization-failed","title":"Server initialization failed","text":"<p>If clojure-lsp fails to start with \u201cServer initialization failed\u201d messages, it could be because the path to your project contains non-ASCII characters, or that the system PATH variable has been corrupted. (Or something else, of course.)</p> <p>See this issue for some findings about it: Issue #2251: Server initialization failed error</p>"},{"location":"clojure-lsp/#related","title":"Related","text":"<p>See also:</p> <ul> <li>Connecting the REPL</li> <li>Refactoring</li> </ul>"},{"location":"clojuredart/","title":"Using Calva with ClojureDart","text":"<p>Since ClojureDart is Clojure, Calva just works with it. Calva is also automatically configured to make VS COde treat <code>.cljd</code> files as a Clojure code.</p>","boost":4},{"location":"clojuredart/#dart-clojure-conversion","title":"Dart-&gt;Clojure Conversion","text":"<p>Similar to when using ClojureScript you will often find examples for Dart and Flutter written in, you guessed it, Dart. And then you will often wish there was a converter, because manually transpiling can be a bit tedious and error prone. Luckily you are in the Clojure community, and such a converter is provided: </p> <ul> <li>DartClojure</li> </ul> <p>There are several ways you can leverage this converter, and since you are using Calva, a very convenient way is available. There is a command Calva: Convert Dart code to Clojure/ClojureDart. This command takes whatever text is selected and uses DartClojure to convert it. Lacking a selection, the command will use the whole file.</p> <p>The workflow demoed in the video is something like so:</p> <ol> <li>Open a new untitled file/tab</li> <li>Paste your Dart/Flutter code in this file (VS Code will probably automatically figure out that it is Dart code, even if that doesn't matter for the converter.)</li> <li>Run Calva: Convert Dart code to Clojure/ClojureDart</li> <li>An, untitled, Clojure tab will open with the converted code in it.</li> </ol> <p>NB: The conversion will not always work. DartCLojure is work in progress. See the project repo for limitations and scope. Often when conversion, the error message will give you a clue to what is problematic. Try adjust your code selection and you will probably be able to get at least some help from the converter.</p> <p>Speaking of WIP...</p>","boost":4},{"location":"clojuredart/#work-in-progress","title":"Work in Progress","text":"<p>ClojureDart is very new and being super actively developed. Some feature are still missing. Like a REPL. Once that is added we will also add ClojureDart jack-in and connect support to Calva.</p>","boost":4},{"location":"clojuredart/#happy-clojuredart-hacking","title":"Happy ClojureDart Hacking!","text":"<p>Please feel welcome to the #clojuredart and #calva channel at the Clojurians Slack for questions, suggestions and support.</p>","boost":4},{"location":"clojuredocs/","title":"ClojureDocs integration","text":"<p>clojuredocs.org is the goto place #1 for finding out more about Clojure core(-ish) functions, macros, etcetera. It contains the doc strings from the functions and adds crowd sourced examples of usage and see alsos. You can surf for quite long on that site without getting bored. \ud83d\ude04</p> You can surf ClojureDocs in Calva <p>Calva integrates this information in two ways:</p> <ol> <li>Commands for requesting the ClojureDocs information for a symbol under the cursor:<ul> <li>Print clojuredocs.org examples to Rich Comment, default keybinding: <code>ctrl+alt+r d</code></li> <li>Print clojuredocs.org examples to OutputWindow, <code>ctrl+alt+o d</code></li> </ul> </li> <li>ClojureDocs information is included in the symbol lookup hovers, where each example has two buttons:<ul> <li>To Rich Comment</li> <li>To Output Window </li> </ul> </li> </ol> <p>That means that if you just want to glance at the examples, you look in the hover. And when you want to bring the examples to the REPL to play with them, you can do so very easily.</p> <p>ClojureScript support</p> <p>ClojureDocs information is available both for Clojure and ClojureScript files. However, clojuredocs.org only keeps info for Clojure. Thus: All information Calva shows about a symbol will be about the Clojure respresentation of that symbol. (The symbol might not even exist in ClojureScript.)</p>","boost":4},{"location":"clojuredocs/#clojuredocs-repl-surfing","title":"ClojureDocs REPL Surfing","text":"<p>Since the ClojureDocs information includes see-alsos, you can go for super interactive ClojureDocs surfing right in the file you are editing. Say you have this function:</p> <pre><code>(defn trim-text\n  \"Returns text without surrounding whitespace if not empty, otherwise nil\"\n  [text]\n  (let [trimmed-text (clojure.string/trim text)]\n    (when-not (empty? trimmed-text)\n      trimmed-text)))\n</code></pre> <p>Then you hover on <code>when-not</code> and scroll down a bit in the hover:</p> <p></p> <p>That first example would be interesting to play with, right? Click To Rich Comment and you will get:</p> <pre><code>(defn trim-text\n  \"Returns text without surrounding whitespace if not empty, otherwise nil\"\n  [text]\n  (let [trimmed-text (clojure.string/trim text)]\n    (when-not (empty? trimmed-text)\n      trimmed-text)))\n\n(comment\n  ;; = when-not - Example 1 = \n\n  ;; build tuples over sets with the same cardinality \n  (map\n   #(when-not (= %2 %3) [%1 %2 %3])\n   (iterate inc 0)   ; a lazy list of indices\n   [:a :b :c]\n   [:a :a :a])\n  ;;=&gt; (nil [1 :b :a] [2 :c :a])\n\n  ;; See also:\n  when\n  when-let\n  if\n  )\n</code></pre> <p>There you can evaluate the <code>(map ...)</code> form using <code>alt+enter</code>, modify it and evaluate again. You can also hover over <code>map</code>, <code>iterate</code>, or any of the \u201dSee also:\u201d symbols to find more fun examples to play with. And so on and so forth.</p> <p>See these two tweets for some videos of early versions of this functionality:</p> <ul> <li>Rich Comments surfing ClojureDocs Examples</li> <li>Clojuredocs in #Calva WIP 2: Hover examples -&gt; RFC</li> </ul> <p>Please retweet!</p>","boost":4},{"location":"clojuredocs/#quirks","title":"Quirks","text":"<p>Some of the ClojureDocs entries have text that is not really Clojure code, and sometimes even structural errors. This can break the structural integrity of your Clojure file. If you run into trouble trying to heal things, you can always use Undo until the Rich Comment is gone.</p>","boost":4},{"location":"commands-top10/","title":"The Top 10 Calva Commands","text":"<p>There are not all that many Calva commands. You can learn them all if you like, but here are the most important ones to know about for effective Clojure/ClojureScript coding:</p> <ul> <li>Grow/expand selection: <code>ctrl+w</code> (<code>shift+alt+right</code> on Windows and Linux)</li> <li>Load/Evaluate Current File and its Requires/Dependencies: <code>alt+ctrl+c enter</code>, evaluates the namespace code in the active editor tab. This also loads any required namespaces, and generally gives Calva what it needs to work.</li> <li>Evaluate current form:  <code>ctrl+enter</code> finds the form from the cursor position, evaluates it and displays the result inline. Hit <code>esc</code> to dismiss the results display.</li> <li>Evaluate current top-level form: <code>alt+enter</code>: inline evaluate the current top-level form. This also works inside <code>(comment)</code> forms. Use it to (re)define vars and then inside comment forms you can verify that they do what you want them to do.</li> <li>Dismiss the display of results: <code>escape</code>: (VIM Extension users should read Using Calva with the VIM Extension).</li> </ul> <p>There are also two commands for bringing over the current form and the current top level form over to the repl window:</p> <ul> <li><code>ctrl+alt+c ctrl+alt+e</code> (<code>ctrl+alt+c ctrl+alt+v</code> on Windows): to paste the current form in the REPL window.</li> <li><code>ctrl+alt+c ctrl+alt+space</code>: to paste the current top-level form in this window</li> </ul> <p>You can also switch the name space of the output/repl window to that of the current file: <code>alt+ctrl+c alt+n</code></p> <ul> <li>Toggle pretty printing of results on and off: <code>ctrl+alt+c p</code>. It's on by default. There is a status bar button showing the status and that also can be used to toggle the setting.</li> </ul>"},{"location":"commands-top10/#some-more-commands-to-try","title":"Some More Commands to Try","text":"<ul> <li>Code evaluation<ul> <li>Evaluate code and add as comment: <code>ctrl+alt+c c</code> (current form), <code>ctrl+alt+c ctrl+space</code> (current top level form)</li> <li>Evaluate code and replace it in the editor, inline: <code>ctrl+alt+c r</code></li> </ul> </li> <li>Integrated REPLs<ul> <li>Send current editor form to the REPL window: <code>ctrl+alt+c ctrl+alt+e</code> (<code>ctrl+alt+c ctrl+alt+v</code> on Windows)</li> <li>Send current editor top level form to the REPL window: <code>ctrl+alt+c ctrl+alt+space</code></li> </ul> </li> <li>Run tests and mark failures and errors in the Problems pane<ul> <li>Run namespace tests: <code>ctrl+alt+c t</code></li> <li>Run all tests: <code>ctrl+alt+c shift+t</code></li> <li>Run current test: <code>ctrl+alt+c ctrl+alt+t</code></li> <li>Rerun previously failing tests: <code>ctrl+alt+c ctrl+t</code></li> <li>Caveat: Right now the tests are reported only when all are run, making it painful to run all tests in larger projects. I'll fix it. Promise!</li> </ul> </li> <li>Select current form: <code>ctrl+alt+c s</code>.</li> <li>Run custom commands, i.e. code snippets, at will: <code>ctrl+alt+c .</code></li> </ul> <p>See also:</p> <ul> <li>Code Evaluation Tips</li> <li>Finding Calva Commands and Shortcuts</li> </ul>"},{"location":"connect-sequences/","title":"REPL Jack-in and Connect Sequences","text":"<p>Many projects grow out of the template phase and call for custom developer workflows involving application start commands, customized REPLs, and what have you. Even some templates add this kind of complexity. To make Jack-in usable for a broader set of projects, Calva has a setting keyed <code>calva.replConnectSequences</code> which lets you configure one ore more connect sequences.</p> <p>NB: Connect sequence configuration affects Calva's Jack-in menu in the following ways:</p> <ol> <li>With no sequence configured, Calva will prompt for the built-in sequences it has that seems to match your project.</li> <li>When any number of connection sequences are configured, Calva will prompt for your custom sequences, as well as the built-in sequences. Whether built-in or custom, only sequences relevant to your project will be included in the prompt.</li> </ol>","boost":6},{"location":"connect-sequences/#settings-for-adding-custom-sequences","title":"Settings for adding Custom Sequences","text":"<p>A connect sequence configures the following:</p> <ul> <li><code>name</code>: (required) This will show up in the Jack-in quick-pick menu when you start Jack-in (see above).</li> <li><code>projectType</code>: (required) This is either \"Leiningen\u201d, \"deps.edn\", \"shadow-cljs\", \"lein-shadow\", \"Gradle\", \u201dgeneric\u201d, or  \"custom\".</li> <li><code>autoSelectForJackIn</code>: A boolean. If true, this sequence will be automatically selected at Jack-in, suppressing the Project Type. Use together with <code>projectRootPath</code> to also suppress the Project Root menu. Add usage of <code>menuSelections</code> to go for a prompt-less REPL Jack-in. If you have more than one sequence with <code>autoSelectForJackIn</code> set to true, the first one will be used.</li> <li><code>autoSelectForConnect</code>: A boolean. If true, this sequence will be automatically selected at Connect, suppressing the Project Type menu. Use together with <code>projectRootPath</code> to also suppress the Project Root menu. If you have more than one sequence with <code>autoSelectForConnect</code> set to true, the first one will be used.</li> <li><code>projectRootPath</code>: An array of path segments leading to the root of the project to which this connect sequence corresponds. Use together with <code>autoSelectForJackIn</code>/<code>autoSelectForConnect</code> to suppress the Project Root menu. The path can be absolute or relative to the workspace root. If there are several Workspace Folders, the workspace root is the path of the first folder, so relative paths will only work for this first folder.</li> <li><code>nReplPortFile</code>: An array of path segments with the project root-relative path to the nREPL port file for this connect sequence. E.g. For shadow-cljs this would be <code>[\".shadow-cljs\", \"nrepl.port\"]</code>.</li> <li><code>afterCLJReplJackInCode</code>: Code to evaluate in the CLJ REPL once it has been created. You can use either a string or an array of strings. If you use an array, the strings will be joined with a newline character to form the resulting code.</li> <li><code>customJackInCommandLine</code>: A string with a command line that should be used to launch the REPL. See Custom Command Line, below.</li> <li><code>cljsType</code>: This can be either \"Figwheel Main\", \"shadow-cljs\", \"ClojureScript built-in for browser\", \"ClojureScript built-in for node\", \"lein-figwheel\", \"none\", or a dictionary configuring a custom type. If set to \"none\", Calva will skip connecting a ClojureScript repl. A custom type has the following fields:<ul> <li><code>dependsOn</code>: (required) Calva will use this to determine which dependencies it will add when starting the project (Jacking in). This can be either \"Figwheel Main\", \"shadow-cljs\", \"ClojureScript built-in for browser\", \"ClojureScript built-in for node\", \"lein-figwheel\", or \u201dUser provided\u201d. If it is \"User provided\", then you need to provide the dependencies in the project or launch with an alias (deps.edn), profile (Leiningen), or build (shadow-cljs) that provides the dependencies needed.</li> <li><code>isStarted</code>: Boolean. For CLJS REPLs that Calva does not need to start, set this to true. (If you base your custom cljs repl on a shadow-cljs workflow, for instance.)</li> <li><code>startCode</code>: Clojure code to be evaluated to create and/or start your custom CLJS REPL.</li> <li><code>isReadyToStartRegExp</code>: A regular expression which, when matched in the stdout from the startCode evaluation, will make Calva continue with connecting the REPL, and to prompt the user to start the application. If omitted and there is startCode Calva will continue when that code is evaluated.</li> <li><code>openUrlRegExp</code>: A regular expression, matched against the stdout of cljsType evaluations, for extracting the URL with which the app can be started. The expression should have a capturing group named <code>url</code>. E.g. \"Open URL: (?\\&lt;url&gt;S+)\"</li> <li><code>shouldOpenUrl</code>: Choose if Calva should automatically open the URL for you or not.</li> <li><code>connectCode</code>: (required) Clojure code to be evaluated to convert the REPL to a CLJS REPL that Calva can use to connect to the application. (For some setups this could also conditionally start the CLJS REPL. If so: <code>startCode</code> should be omitted.)</li> <li><code>isConnectedRegExp</code>: (required) A regular expression which, when matched in the <code>stdout</code> from the <code>connectCode</code> evaluation, will tell Calva that the application is connected. The default is <code>To quit, type: :cljs/quit</code> and you should leave it at that unless you know it won't work.</li> <li><code>printThisLineRegExp</code>: regular expression which, when matched in the <code>stdout</code> from any code evaluations in the <code>cljsType</code>, will make the matched text be printed to the Output window.</li> <li><code>buildsRequired</code>: Boolean. If the repl type requires that builds are started in order to connect to them, set this to true.</li> </ul> </li> <li><code>menuSelections</code>: a dictionary with pre-filled-in selections for the Jack-in and Connect prompts, making Calva not prompt for that particular selection:<ul> <li><code>leinProfiles</code>: At Jack-in to a Leiningen project, use these profiles to launch the repl.</li> <li><code>leinAlias</code>: At Jack-in to a Leiningen project, launch with this alias. Set to <code>null</code> to launch with Calva's default task (a headless repl), w/o prompting.</li> <li><code>cljAliases</code>: At Jack-in to a deps.edn project, use these aliases to launch the repl.</li> <li><code>cljsLaunchBuilds</code>: The cljs builds to start/watch at Jack-in/connect.</li> <li><code>cljsDefaultBuild</code>: Which cljs build to attach to at the initial connect.</li> </ul> </li> <li><code>jackInEnv</code>: An object with environment variables that will be merged with the global <code>calva.jackInEnv</code> and then applied to the Jack-in process. The merge is very similar to how Clojure's <code>merge</code> works. So for any common keys between the global setting and this one, the ones from this setting will win.</li> </ul> <p>The Calva built-in sequences also use this format, check them out to get a clearer picture of how these settings work.</p> <p>Force the project type menu to show</p> <p>The convenience of <code>autoSelectForJackIn/Connect</code> can be an inconvenience when you want to use another project type/sequence for a project. For this reason, the <code>calva.connect</code> and <code>calva.jackIn</code> can be provided with an option <code>disableAutoSelect</code>, which forces the project root and project type menus to show. See Options for the Connect Command and Options for the Jack-in Command for more on this.</p> <p>Path segments</p> <p><code>projectRootPath</code> and <code>nReplPortFile</code> both take an array of path segments. This is to make the paths work cross-platform. If you can't be bothered splitting up the path in segments, put the whole path in the first segment, though please note that if you use Windows path separators, these will not work for users with Linux or macOS.</p>","boost":6},{"location":"connect-sequences/#custom-command-line","title":"Custom Command Line","text":"<p>Custom command lines are there to bridge the gap to those situations where standard Jack-in command lines don't reach. Like:</p> <ol> <li>You want to provide command line options to a supported tool, which Jack-in does not provide</li> <li>Your project has some script through which it is started</li> <li>The REPL is provided by some tool that Calva does not know of</li> <li>Any other reason...</li> </ol> <p>A custom command line is executed from same directory as the REPL project root (See <code>projectRootPath</code>, above), and can be as simple as <code>my-repl-jack-in-command</code>. You  can use a relative or absolute path to your command line.</p> <p>If your custom command line starts a REPL of a project type that is not \u201dknown\u201d/built-in to Calva, use <code>custom</code> as the <code>projectType</code> for the connect sequence.</p>","boost":6},{"location":"connect-sequences/#custom-command-line-substitutionsplaceholdersenvironment-variables","title":"Custom Command Line Substitutions/Placeholders/Environment variables","text":"<p>You can use placeholders in your command line, and Calva will substitute them before executing the command. All these placeholders will also be provided to your script via environment variables with the same names (except dashes will be underscores in the env variable names):</p> <p>nREPL dependency versions:</p> <ul> <li><code>JACK-IN-NREPL-VERSION</code></li> <li><code>JACK-IN-CIDER-NREPL-VERSION</code></li> <li><code>JACK-IN-CIDER-PIGGIEBACK-VERSION</code></li> </ul> <p>Paths:</p> <ul> <li><code>JACK-IN-PROJECT-ROOT-PATH</code>: (See <code>projectRootPath</code>, above)</li> <li><code>JACK-IN-NREPL-PORT-FILE</code>: The path of the nREPL port file (see <code>nReplPortFile</code> above)</li> </ul> <p>Depending on the project type Calva will also look for these placeholders:</p> <ul> <li><code>JACK-IN-CLJ-MIDDLEWARE</code>: The nREPL middleware to be used for the Clojure REPL</li> <li><code>JACK-IN-CLJS-MIDDLEWARE</code>: The nREPL middleware to be used for the ClojureScript REPL</li> <li><code>JACK-IN-LEIN-PROFILES</code>: For Leiningen projects, the profiles selected by the user</li> <li><code>JACK-IN-LEIN-LAUNCH-ALIAS</code>: For Leiningen projects, the launch alias selected by the user</li> <li><code>JACK-IN-CLI-ALIASES</code>: For deps.edn projects, the aliases selected by the user</li> <li><code>JACK-IN-CLJS-LAUNCH-BUILDS</code>: For ClojureScript REPLs that configures builds, the builds selected by the user</li> <li><code>JACK-IN-NREPL-PORT</code>: For some project types (currently <code>nbb</code> and <code>Babashka</code>) Calva provided the TCP port they should use.</li> </ul>","boost":6},{"location":"connect-sequences/#example-custom-jack-in-command-lines","title":"Example Custom Jack-in Command lines","text":"","boost":6},{"location":"connect-sequences/#start-a-babashka-repl-via-wsl","title":"Start a Babashka REPL via WSL","text":"<p>Calva has a built-in jack-in sequence for starting a Babashka REPL and connect to it. It works as long as the <code>bb</code> process is on the same host as VS Code/Calva is running. So if you want it to run in WSL, but VS Code is running on your computer you need to start <code>bb</code> slightly differently. These settings in your VS Code settings file will give you a jack-in option that works for this:</p> <pre><code>  \"calva.replConnectSequences\": [\n    {\n        \"name\": \"Bashbabka (WSL)\",\n        \"projectType\": \"custom\",\n        \"customJackInCommandLine\": \"bash -c 'bb --nrepl-server JACK-IN-NREPL-PORT'\",\n    },\n  ],\n</code></pre> <p>If you place it in your user settings you will have access to it from any workspace.</p>","boost":6},{"location":"connect-sequences/#an-exampleskeleton-script","title":"An example/skeleton script","text":"<p>This script doesn't actually start a REPL, it's provided more for giving you an idea about what it could look like, and as a starting point for your real scripts:</p> <pre><code>#!/usr/bin/env bb\n\n(require '[clojure.string :as str])\n\n(defn parse-args [args]\n  (loop [args args\n         parsed {}]\n    (if (empty? args)\n      parsed\n      (let [[flag value &amp; rest-args] args]\n        (case flag\n          \"--aliases\" (recur rest-args (assoc parsed :aliases value))\n          \"--cider-nrepl-version\" (recur rest-args (assoc parsed :cider-nrepl-version value))\n          (do (println \"Unknown parameter:\" flag) (System/exit 1)))))))\n\n(defn process-args [args]\n  (let [aliases (str/split (:aliases args) #\",\")\n        cider-nrepl-version (:cider-nrepl-version args)\n        project-root-path (System/getenv \"JACK_IN_PROJECT_ROOT_PATH\")]\n    (println \"Aliases:\")\n    (doseq [alias aliases]\n      (println alias))\n    (println \"CIDER nREPL version:\" cider-nrepl-version)\n    (println \"JACK_IN_PROJECT_ROOT_PATH:\" project-root-path)))\n\n(def parsed-args (parse-args *command-line-args*))\n\n(when (= *file* (System/getProperty \"babashka.file\"))\n  (process-args parsed-args))\n</code></pre> <p>It's written in Babashka to encourage you to write your shell scripts in a civilized language. \ud83d\ude00 See the article Changing my mind: Converting a script from bash to Babashka for a small success-story about this mindset. See also bash2bb.</p> <p>The script reads <code>JACK-IN-CLJS-LAUNCH-BUILDS</code> and <code>JACK-IN-CIDER-NREPL-VERSION</code> from the command line, and <code>JACK_IN_PROJECT_ROOT_PATH</code> from the environment. It could be configured for use in a custom connect sequence like this:</p> <pre><code>    \"customJackInCommandLine\": \"../../custom-jack-in.bb --aliases JACK-IN-CLJS-LAUNCH-BUILDS --cider-nrepl-version JACK-IN-CIDER-NREPL-VERSION\",\n</code></pre> <p>Note how in this case the REPL is started two directories \u201ddown\u201d from the workspace root where the script resides.</p>","boost":6},{"location":"connect-sequences/#example-sequences","title":"Example Sequences","text":"<p>Whether you just want to speed up your workflow or encode some workflow/mechanics into it, it's often the case that you can create a custom sequence that helps.</p>","boost":6},{"location":"connect-sequences/#minimal-menus-with-full-stack-shadow-cljs-repls","title":"Minimal menus with full stack shadow-cljs REPLs","text":"<p>Minimize the amount of selecting from the Jack-in/Connect menu when working with a full-stack shadow-cljs + deps/lein project:</p> <pre><code>    {\n      \"name\": \"backend + frontend\",\n      \"projectType\": \"shadow-cljs\",\n      \"cljsType\": \"shadow-cljs\",\n      \"menuSelections\": {\n        \"cljsLaunchBuilds\": [\n          \":app\",\n          \":test\",\n        ],\n        \"cljsDefaultBuild\": \":app\"\n      }\n    }\n</code></pre> <p>See shadow-cljs + Clojure with Calva: The basics for how Calva and nREPL work with ClojureScript.</p>","boost":6},{"location":"connect-sequences/#polylith","title":"Polylith","text":"<p>This is the connect sequences used in the Polylith Real World App. The <code>(start)</code> sequence lets you jack-in to the project, and starts the Real World App without any prompts. The <code>(connect)</code> sequence can be used if you prefer to start the REPL manually, and want to connect without prompts.</p> <pre><code>    \"calva.replConnectSequences\": [\n        {\n            \"projectType\": \"deps.edn\",\n            \"afterCLJReplJackInCode\": \"(require '[dev.server] :reload) (in-ns 'dev.server) (start! 6003)\",\n            \"name\": \"Polylith RealWorld Server REPL (start)\",\n            \"autoSelectForJackIn\": true,\n            \"projectRootPath\": [\".\"],\n            \"cljsType\": \"none\",\n            \"menuSelections\": {\n                \"cljAliases\": [\"dev\", \"test\"]\n            }\n        },\n        {\n            \"projectType\": \"deps.edn\",\n            \"name\": \"Polylith RealWorld Server REPL (connect)\",\n            \"autoSelectForConnect\": true,\n            \"projectRootPath\": [\".\"],\n            \"cljsType\": \"none\",\n        }\n    ],\n    \"calva.autoConnectRepl\": true,\n</code></pre> <p>The <code>calva.autoConnectRepl</code>, when set to <code>true</code>, makes Calva, at project open, look for the nRepl port file and automatically connect the repl if the file exists. Therefore, you can leave the app running when you close the project in VS Code, and Calva will reconnect when you open the project again. (Alternatively, maybe you just need to reload the VS Code window and not lose the REPL state.)</p>","boost":6},{"location":"connect-sequences/#minimal-menus-with-full-stack-depsedn-and-figwheel-main-repls","title":"Minimal menus with full stack deps.edn and Figwheel Main REPLs","text":"<p>Setting for a full-stack application. It starts the backend server when the CLJ REPL has started. Then proceeds to create a custom CLJS REPL (calling in to the application code for this). And then connects to it.</p> <pre><code>{\n    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"Example Sequence\",\n            \"projectType\": \"Clojure-CLI\",\n            \"afterCLJReplJackInCode\": \"(go)\",\n            \"cljsType\": {\n                \"startCode\": \"(do (require '[cljs-test.main :refer :all])(start-nrepl+fig))\",\n                \"isReadyToStartRegExp\": \"Prompt will show\",\n                \"connectCode\": \"(do (use 'cljs-test.main) (cljs-repl))\",\n                \"isConnectedRegExp\": \"To quit, type: :cljs/quit\",\n                \"printThisLineRegExp\": \"\\\\[Figwheel\\\\] Starting Server at.*\"\n            }\n        }\n    ]\n}\n</code></pre>","boost":6},{"location":"connect-sequences/#juxt-edge","title":"JUXT Edge","text":"<p>Here is an example from the JUXT Edge project template. It adds two sequences, one for when only the Clojure REPL should be launched and one for when the customized Edge cljs repl should also be connected. The Edge backend + frontend sequence specifies that the web app should be opened by Calva, making cljs repl connection more stable, and also adds <code>menuSelections</code> to skip the launch aliases prompt.</p> <pre><code>{\n    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"Edge backend only\",\n            \"projectType\": \"deps.edn\"\n        },\n        {\n            \"name\": \"Edge backend + frontend\",\n            \"projectType\": \"deps.edn\",\n            \"cljsType\": {\n                \"dependsOn\": \"Figwheel Main\",\n                \"startCode\": \"(do (require 'dev-extras) (dev-extras/go) (println \\\"Edge Figwheel Main started\\\") ((resolve 'dev-extras/cljs-repl)))\",\n                \"isReadyToStartRegExp\": \"Edge Figwheel Main started\",\n                \"openUrlRegExp\": \"Website listening on: (?&lt;url&gt;\\\\S+)\",\n                \"printThisLineRegExp\": \"\\\\[Edge\\\\]\",\n                \"shouldOpenUrl\": true,\n                \"connectCode\": \"(do (require 'dev-extras) ((resolve 'dev-extras/cljs-repl)))\",\n                \"isConnectedRegExp\": \"To quit, type: :cljs/quit\",\n                \"buildsRequired\": false\n            },\n            \"menuSelections\": {\n                \"cljAliases\": [\n                    \"dev\",\n                    \"build\",\n                    \"dev/build\"\n                ],\n            }\n        }\n    ]\n}\n</code></pre>","boost":6},{"location":"connect-sequences/#plain-depsedn","title":"Plain deps.edn","text":"<p>A deps.edn sequence that does not promote the ClojureScript repl at all (leaving it a Clojure REPL), and leaves that up to you to do interactively. (Could be useful while you are developing a custom cljs repl.) The example is for when adapting a Figwheel Main repl.</p> <pre><code>{\n    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"Do not promote to cljs\",\n            \"projectType\": \"deps.edn\",\n            \"cljsType\": {\n                \"dependsOn\": \"Figwheel Main\",\n                \"connectCode\": \"\\\"Don't promote me bro!\\\"\",\n                \"isConnectedRegExp\": \"Don't promote me bro!\"\n            }\n        }\n    ]\n}\n</code></pre>","boost":6},{"location":"connect/","title":"Connect Calva to Your Project","text":"<p>When connected to your project's REPL Calva lets you evaluate code, supporting Interactive Programming. The REPL connection is also used to provide IDE functionality through the dynamic knowledge about the project that the REPL enables. The REPL communication depends on that your project has an nREPL server running, and that the cider-nrepl middleware is enabled.</p> <p>For the easiest way to provide your project with these dependencies, the recommended way to connect is to use the so called Jack-in command.</p>","boost":7},{"location":"connect/#jack-in-let-calva-start-the-repl-for-you","title":"Jack-in: Let Calva Start the REPL For You","text":"<p>This way Calva can make sure it is started with the dependencies needed for a working Clojure and/or ClojureScript session. This is often referred to as Jack in (because that is what it is called in CIDER).</p> <p>Jack-in supports both CLJ and for CLJS, and has built-in configurations for Leiningen, deps.edn, shadow-cljs, Gradle projects, as well as for the CLJS repl types: Figwheel Main, lein-figwheel (legacy Figwheel), shadow-cljs, and ClojureScript built-ins for both browser and node.js. Using jack-in provides your development environment with all the dependencies you need for Calva to work.</p> <p>It works like so:</p> <ol> <li>Open your project in VS Code.</li> <li>Issue the command Start a Project REPL and Connect: <code>ctrl+alt+c ctrl+alt+j</code>.</li> <li>Answer the quick-pick prompts telling Calva about project types and what profiles to start. (See the Jack-in Project Types and Profiles wiki page for more info if needed.)</li> </ol> <p>See also: Workspace Layouts</p> <p>About project roots</p> <p>You must have a project file, such as <code>project.clj</code> for Leiningen, or <code>deps.edn</code> for deps.edn, or <code>shadow-cljs.edn</code> for shadow-cljs, or <code>settings.gradle</code>/<code>settings.gradle.kts</code> for Gradle in the directory opened in VS Code in order for jack-in to work. If, after adding the project file, you experience an error during jack-in that says something could not be located, make sure you have the correct dependencies in your project file. For example, when using the Figwheel Main project type, you should have <code>com.bhauman/figwheel-main</code> in your project dependencies.</p> <p>See also below, regarding multiple projects in a workspace</p>","boost":7},{"location":"connect/#aliases-profiles-builds","title":"Aliases, Profiles, Builds","text":"<p>When Jack-in starts it will depend on the project type, and whether ClojureScript is involved or not, and if it is, what kind of ClojureScript project, what will happen next. Calva will analyze the project files and will then give you prompts with selections based on what is found there.</p> <p>You will need some basic knowledge about the project and the project type terminologies to answer the prompts.</p> <p>There are ways to tell Calva the answers to these prompts beforehand, so that Jack-in can be a zero-prompting command. Read on.</p>","boost":7},{"location":"connect/#customizing-jack-in","title":"Customizing Jack-in","text":"<p>The main mechanism for customizing your Jack-in, including automating menu selections, and custom CLJS REPL types is Custom Connect Sequences. See also Customizing Jack-in and Connect</p>","boost":7},{"location":"connect/#connecting-without-jack-in","title":"Connecting Without Jack-in","text":"<p>If, for whatever reasons, you can't use Jack-in with your project (possibly because the REPL is started as part of some other job) all is not lost. Old fashioned Connect to a running REPL is still there for you. For all features to work in Calva while connecting to a running REPL, your environment needs to have REPL related dependencies set up.</p> <p>However, just as before it can be tricky to get the dependencies right. Consider using Jack in to inform yourself on how to start your REPL to Calva's satisfaction. When you use Jack in, Calva starts a VS Code task for it and the command line used is displayed in the terminal pane used to handle the task. Reading that command line tells you what dependencies are needed for your project.</p> <p>Even better: Copying that command line gives you the command to start the REPL with the correct dependencies.</p> <p>All this said, I still recommend you challenge the conclusion that you can't use Jack-in.</p> <p>Copy the Jack-in command line</p> <p>There is a Calva command for copying the Jack-in command line to the clipboard. It will copy the command line including commands to change to the current REPL project root, avoiding hard-to-detect errors when starting the REPL in the wrong directory.</p> <p>The Generic Project Type</p> <p>A reason to use the connect to a running REPL way, can be that Calva does not have a built in connect sequence/project type for the particular REPL you want to connect to. Maybe it is something like Lingy which doesn't yet have a built in Calva connect sequence. As long as there is an nREPL server to connect to, you can Connect with Calva, using the Generic connect sequence/project type. (You can also create a connect sequence with a custom command line, and use Jack-in anyway.)</p> <p>See also Customizing Jack-in and Connect</p>","boost":7},{"location":"connect/#starting-the-repl-from-application-code","title":"Starting the REPL from application code?","text":"<p>If your project is setup so that the REPL server is started by the application code, you will need to get the cider-nrepl middleware in place. See the cider-nrepl docs about embedding nREPL in your application.</p>","boost":7},{"location":"connect/#auto-select-project-type-and-project-root","title":"Auto-select Project Type and Project Root","text":"<p>You can make both Jack-in and Connect stop prompting you for project type and project root path in projects where you always want to use the same. See Connect Sequences.</p>","boost":7},{"location":"connect/#monorepos-multiple-clojure-projects-in-one-workspace","title":"Monorepos / multiple Clojure projects in one workspace","text":"<p>If the workspace is a monorepo, Polylith repo or just a repository with more than one Clojure project, Calva will start the connect sequence with prompting for which project to start/connect to.</p> <p></p>","boost":7},{"location":"connect/#shadow-cljs","title":"shadow-cljs","text":"<p>Please see the shadow-cljs page.</p>","boost":7},{"location":"connect/#troubleshooting","title":"Troubleshooting","text":"","boost":7},{"location":"connect/#jack-in-and-main-opts","title":"Jack-in and <code>:main-opts</code>","text":"<p>When Calva starts the project REPL and connects to it (a.k.a. Jack-in), this is done by starting an nREPL server. For deps.edn projects this by default means that Calva will add <code>-m ...</code> with options that starts the server.</p> <p>However: If you choose an alias at Jack-in that specifies <code>:main-opts</code>, it will make the Clojure CLI to add main opts and Calva will then not override these by adding <code>-m ...</code> to the command line. This means that an alias that specify <code>:main-opts</code> must result in an nREPL server being started, or else Calva won't have a server to connect to. Calva won't further analyze this, but will just warn you at Jack-in.</p> <p>If you don't know if an alias starts an nREPL server or not, by all means, try it, if you have reasons for using that alias. You will notice if Jack-in works or not. If it doesn't work, you will need to run without that alias, or fix what happens when that alias is used so that an nREPL server is started. See https://nrepl.org/nrepl/usage/server.html about ways to do this.</p>","boost":7},{"location":"connect/#command-not-found-errors-when-jacking-in","title":"Command Not Found Errors When Jacking In","text":"<p>If you get <code>command not found</code> error when Calva tries to start your project, and you know you have the command installed, it's probably because VS Code starts from an environment where the command is not on the <code>$PATH</code>. It can look like so:</p> <pre><code>lein update-in :dependencies conj '[nrepl,\"0.8.3\"]' -- update-in :plugins conj '[cider/cider-nrepl,\"0.25.8\"]' -- update-in '[:repl-options,:nrepl-middleware]' conj '[\"cider.nrepl/cider-middleware\"]' -- repl :headless\n/bin/sh: lein: command not found\nJack-in process exited. Status: 127\n</code></pre> <p>The fix is to always start VS Code from the command line:</p> <pre><code>$ code\n</code></pre> <p>You might need to first run the Shell Command: Install <code>code</code> command in PATH.</p> <p>This will also make sure your REPL has access to the environment you probably expect it to have access to. See below.</p>","boost":7},{"location":"connect/#go-to-definition-not-working-for-java-definitions","title":"Go to Definition Not Working for Java Definitions","text":"<p>On some systems, the Java source may not be installed along with the JDK. The source must be present on your system in order to navigate to Java definitions. See this comment for more details.</p>","boost":7},{"location":"connect/#environment-variables-are-not-readable-from-repl","title":"Environment Variables Are Not Readable From REPL","text":"<p>If you've added environment variables in your OS, such as in your <code>~/.bashrc</code> file (Linux), in order for them to be read in a REPL created by Calva's jackin command, VS Code must be started from a shell where the environment variables are defined. For example, if you can open a bash terminal and run <code>echo $SOME_VAR</code> and see the value there, then open VS Code from that terminal with <code>code &lt;project path&gt;</code>.</p>","boost":7},{"location":"connect/#viewing-the-communication-between-nrepl-and-calva","title":"Viewing the Communication Between nREPL and Calva","text":"<p>It may be helpful to view the messages sent between nREPL and Calva when troubleshooting an issue related to the REPL. See how to do that here.</p>","boost":7},{"location":"contribute/","title":"Contribute to Calva","text":"<p>There are many ways to contribute:</p> <ul> <li>Become a sponsor</li> <li>Give us feedback:</li> <li>File issues</li> <li>Talk to us via the #calva channel at the Clojurians Slack (use the latter link to grab an invite)</li> <li>Provide PRs, see the Calva wiki about How to Hack on Calva</li> <li>Give us feedback, preferably via that <code>#calva</code> channel</li> <li>Cheer us on. (Same channel)</li> <li>Help us test things like reported issues, new features, etcetera. See Testing VSIX Packages and Smoke Testing</li> <li>Make tutorials, write blog articles, spread the word</li> <li>Star the Calva repository</li> <li>Help us help beginners with Calva and Clojure, on Slack as well as IRL and wherever.</li> </ul> <p>Be creative!</p>"},{"location":"contribute/#please-star-the-calva-repo","title":"Please star the Calva repo!","text":"<p>Happy Coding! \u2764\ufe0f</p>"},{"location":"custom-commands/","title":"Custom REPL Commands","text":"<p>Calva supports configuration of custom command snippets that you can evaluate in the REPL at will. This is useful if your workflow has you repeatedly evaluating a particular piece of code. There are two ways to use these:</p> <ol> <li>You can use the setting <code>calva.customREPLCommandSnippets</code> to configure it. Then either bind keyboard shortcuts to them or use the command Run Custom REPL Command to access it. The command will give you a menu with the snippets you have configured.</li> <li>You can bind a keyboard shortcut directly to a custom command snippet by inlining it in the shortcut definition. See Binding Keyboard Shortcuts</li> </ol> <p>Joyride</p> <p>For some use cases you might be better served by/want to combine these with using the VS Code Extension API, and that of Calva, or any other extension, through Joyride.</p> <p>The <code>calva.customREPLCommandSnippets</code> is an array of objects with the following fields (required fields in bold):</p> <ul> <li><code>name</code>: The name of the snippet as it will appear in the picker menu</li> <li><code>snippet</code>: The code that will be evaluated</li> <li><code>key</code>: A key can be used to reference the snippet from Run Custom REPL Command keyboard shortcut arguments. It will also be used in the quick-pick menu.</li> <li><code>ns</code>: A namespace to evaluate the command in. If omitted the command will be executed in the namespace of the current editor.</li> <li><code>repl</code>: Which repl session to use for the evaluation. Either <code>\"clj\"</code> or <code>\"cljs\"</code>. Omit if you want to use the session of the current editor.</li> <li><code>evaluationSendCodeToOutputWindow</code>: (default <code>true</code>) Whether the evaluated code should be echoed to the Output/REPL window.</li> </ul> <p>There are also substitutions available, which will take elements from the current state of Calva and splice them in to the text of your command before executing it. They are</p> <ul> <li><code>$line</code>: Current line number in editor</li> <li><code>$column</code>: Current column number in editor</li> <li><code>$file</code>: Full name of the current file edited</li> <li><code>$file-text</code>: The text of the current file edited</li> <li><code>$ns</code>: The namespace used for evaluating the command</li> <li><code>$editor-ns</code>: The namespace of the editor from which the command was run</li> <li><code>$selection</code>: The currently selected text</li> <li><code>$current-form</code>: The text of the current form</li> <li><code>$current-pair</code>: The text of the current pair if in a binding, otherwise empty string</li> <li><code>$enclosing-form</code>: The text of the current enclosing form</li> <li><code>$top-level-form</code> The text of the current top level form</li> <li><code>$current-fn</code>: The sexpr/form at call position in the current list, e.g. <code>str</code> with <code>(defn foo [] (str \"foo\" \"bar|\"))</code></li> <li><code>$top-level-defined-symbol</code>: The second symbol of the top level form, e.g. <code>foo</code> with <code>(defn foo [] (str \"foo\" \"bar|\"))</code></li> <li><code>$head</code>: The text between the start of the current list to the cursor</li> <li><code>$tail</code>: The text between the cursor and the end of the current list</li> </ul>","boost":4},{"location":"custom-commands/#user-and-workspace-settings","title":"User and Workspace Settings","text":"<p>Settings from your User (global) level and the workspace are merged.</p> <p>With these User settings:</p> <pre><code>    \"calva.customREPLCommandSnippets\": [\n        {\n            \"name\": \"Call Current Form\",\n            \"key\": \"c\",\n            \"snippet\": \"($current-form)\"\n        },\n        {\n            \"name\": \"Call Current Top Level Form\",\n            \"key\": \"t\",\n            \"snippet\": \"($top-level-form)\"\n        },\n        {\n            \"name\": \"CLJ Test Top Level Defined Symbol\",\n            \"repl\": \"clj\",\n            \"snippet\": \"(clojure.test/test-var #'$top-level-defined-symbol)\"\n        },\n        {\n            \"name\": \"CLJS Test Top Level Defined Symbol\",\n            \"repl\": \"cljs\",\n            \"snippet\": \"(cljs.test/test-var #'$top-level-defined-symbol)\",\n            \"key\": \"tab\"\n        }\n    ],\n</code></pre> <p>And these Workspace settings:</p> <pre><code>    \"calva.customREPLCommandSnippets\": [\n        {\n            \"name\": \"Remount CLJS App\",\n            \"key\": \"r\",\n            \"repl\": \"cljs\",\n            \"ns\": \"example.app\",\n            \"snippet\": \"(start)\"\n        }\n    ],\n</code></pre> <p>Issuing Run Custom REPL Command will then render this VS Code menu:</p> <p></p> <p>The default keyboard shortcut for the command is <code>ctrl+alt+space space</code>. (Beware: on MacOS it may conflict with the default shortuct for Input Sources - Select next source in Input menu.)</p>","boost":4},{"location":"custom-commands/#binding-keyboard-shortcuts","title":"Binding Keyboard Shortcuts","text":"<p>There are four ways to bind shortcuts to custom commands:</p> <ol> <li>Use a predefined <code>key</code> shortcut. These are predefined as <code>ctrl+alt+space &lt;something&gt;</code>, where <code>&lt;something&gt;</code> is one of:<ul> <li>The digits <code>0</code> through <code>9</code></li> <li>The English letters <code>a</code> through <code>z</code></li> <li>Arrow keys <code>right</code>, <code>left</code>, <code>up</code>, or <code>down</code></li> <li>One of <code>tab</code>, <code>backspace</code>, <code>,</code>, <code>.</code>, or <code>-</code> </li> </ul> </li> <li>Bind <code>calva.runCustomREPLCommand</code> to a shortcut with whatever code you want to evaluate in the <code>args</code> slot. You have access to the substitution variables here as well.</li> <li>Bind <code>calva.runCustomREPLCommand</code> to a keyboard shortcut referencing the <code>key</code> of one of your <code>calva.customREPLCommandSnippets</code>. (If not using any of the <code>key</code>s mentioned in 1.)</li> <li>Bind <code>calva.runCustomREPLCommand</code> to a shortcut with a <code>customREPLCommandSnippets</code> in the <code>args</code> slot. You have access to the substitution variables here as well.</li> </ol> <p>Here's an example shortcut entry for the 4th option:</p> <pre><code>    {\n        \"key\": \"ctrl+cmd+u alt+enter\",\n        \"command\": \"calva.runCustomREPLCommand\",\n        \"args\": {\n            \"ns\": \"user\",\n            \"snippet\": \"$current-form\",\n        }\n    },\n</code></pre> <p>This would evaluate the current form in the <code>user</code> namespace. Please note that this Custom REPL Command will not show up in the custom commands menu mentioned above.</p>","boost":4},{"location":"custom-commands/#custom-repl-hover-snippets","title":"Custom REPL Hover Snippets","text":"<p>Calva supports custom snippets that will display their result inside the tooltip. They will only work when connected to a repl, since they eval code in it. This is mostly useful for tooling authors that want to integrate with calva. Be careful with these, since they will be executed anytime Calva displays a tooltip. So they should be fast and probably not have any side effects.</p> <p>The hover snippets accept the same inputs as the Custom REPL Commands, except for the hotkey:</p> <pre><code>    \"calva.customREPLHoverSnippets\": [\n        {\n            \"name\": \"eval text on hover\",\n            \"repl\": \"clj\",\n            \"ns\": \"example.app\",\n            \"snippet\": \"(str \\\"$hover-text\\\")\"\n        }\n    ]\n</code></pre> <p>With this setting anything the mouse is over will also be shown inside its tooltip. There are now also <code>hover-</code> versions of most substitutions. Those currently only work inside the hover snippets.</p>","boost":4},{"location":"custom-commands/#configedn","title":"config.edn","text":"<p><code>:customREPLCommandSnippets</code> and <code>:customREPLHoverSnippets</code> can be also be configured in your user config at <code>.config/calva/config.edn</code> realative to your system home directory, or <code>.calva/config.edn</code> relative to the workspace root. Three things to note about this:</p> <ol> <li>None of these two configs get synced through VS Code Settings Sync.</li> <li>Changes to workspace <code>.calva/config.edn</code> will be automatically noticed by Calva, and refresh the config. This will not happen with the user config file.</li> <li>Internally in Calva, the settings are keyed on the snippet <code>:name</code> entry, and if you change the name, the old entry won't be removed until the VS Code window is reloaded.</li> </ol> <p>As for 2.: There is a command Calva: Refresh REPL snippets from User config.edn.</p> <p>There is also a command to open the User config.edn, for convenience: Calva: Open REPL snippets User config.edn. This command creates the file if it doesn't previously exist.</p>","boost":4},{"location":"custom-commands/#snippets-inside-deps","title":"Snippets Inside Deps","text":"<p>A new experimental feature lets library authors ship snippets inside their jar files. These accept the same options as above but should be placed in \"resources/calva.exports/config.edn\" inside the jar.</p> <pre><code>{:customREPLCommandSnippets\n [{:name \"edn test\"\n   :key \"a\"\n   :snippet ($current-form)}]\n :customREPLHoverSnippets\n [{:name \"edn hover\"\n   :snippet (str \"$hover-tex\")}\n  {:name \"edn hover show val\"\n   :snippet (str \"### EDN show val\\n```clojure\\n\" (pr-str (eval (symbol (str \"$ns\" \"/\" \"$hover-top-level-defined-symbol\")))) \"\\n```\")}]}\n</code></pre>","boost":4},{"location":"customizing-jack-in-and-connect/","title":"Customize Jack-in and Connect","text":"<p>Since Jack-in and connect both are about connecting the REPL, and only differ in how the REPL is started, many settings and configuration points are shared between the two concepts. A major customization point is Custom Connect Sequences, which are relevant for both Jack-in and Standalone Connect scenarios.</p> <p>This page lists some more Jack-in and Connect configuration options.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#auto-evaluate-code-on-connect","title":"Auto-evaluate Code on Connect","text":"<p>You can have Calva evaluate code whenever a REPL has been connected via the <code>calva.autoEvaluateCode.onConnect</code> setting. It has two entries <code>clj</code> and <code>cljs</code>:</p> <ul> <li><code>clj</code>: \"Code to evaluate when the Clojure REPL has been connected.<ul> <li>The default is code that refer in the <code>repl-requires</code>/REPL utilities (like <code>source</code>, <code>doc</code>, etcetera). (Note that there is also a command to do this on demand.).</li> <li>Overriding the default replaces it. If you want to add code to be evaluated on connect this way, and keep the behaviour of auto-refering REPL utilities, you need to provide code for the latter (copy/pasting the default code will do). See also note below about concatenation of configurations.</li> <li>The code will be evaluated before the <code>afterCLJReplJackInCode</code> in any connect sequence used.</li> </ul> </li> <li><code>cljs</code>: Code to evaluate when the ClojureScript REPL has been connected.<ul> <li>The default is code that refer in the <code>repl-requires</code>/REPL utilities (like <code>source</code>, <code>doc</code>, etcetera). (Note that there is also a command to do this on demand.).</li> <li>Same deal with overriding the default as with <code>clj</code>.</li> </ul> </li> </ul> <p>Set either of these to <code>null</code> to disable the feature for that REPL type. (The Settings linter will complain, but it works.)</p> <p>For Clojure this is in addition to <code>afterCLJReplJackInCode</code></p> <p>There are two mechanisms for evaluating code when a Clojure REPL is connected. The <code>afterCLJReplJackInCode</code> setting of custom connect sequences, and this <code>calva.autoEvaluateCode.onConnect.clj</code> setting. There is no fundamental difference between them. This one has a default function of auto-refering in the Clojure REPL utilities. And it will be run before the connect sequence after-Jack-in code.</p> <p>All configured code is concatenated</p> <p>If you configure this both in User/global settings and in a Workspace, the workspace configured code will be concatenated on the user level code. Meaning both code snippets will be evaluated, first the User level code, then the Workspace level code. Also <code>null</code> disables the feature:</p> <ul> <li>If you use <code>null</code> in the User level code, you will disable the onConnect code evaluation for all workspaces that do not configure code for this.</li> <li>If you configure code on the User level it will be evaluated in all workspaces, except those that disable the feature by configuring <code>null</code>. </li> </ul>","boost":7},{"location":"customizing-jack-in-and-connect/#auto-evaluate-code-at-filenamespace-loadevaluation","title":"Auto-evaluate Code at file/namespace load/evaluation","text":"<p>You can also make Calva auto-evaluate code when a file has been loaded in the REPL (via the Calva command for loading files). You add code for this via the <code>calva.autoEvaluateCode.onFileLoaded</code> setting. Like with <code>onConnect</code> you provide code for <code>clj</code> and <code>cljs</code> separately.</p> <ul> <li>Note that custom commands substitutions are in play here as well.</li> <li>Calva's does not provide defaults for this setting.</li> <li>Merging works the same as with <code>onConnect</code>.</li> </ul>","boost":7},{"location":"customizing-jack-in-and-connect/#customizing-connect","title":"Customizing Connect","text":"<p>If there is an nRepl port file, Calva will use it and not prompt for <code>host:port</code> when connecting. You can make Calva prompt for this by setting the boolean config <code>calva.autoSelectNReplPortFromPortFile</code> to <code>false</code>.</p> <p>With the setting <code>calva.autoConnectRepl</code> you can make Calva automatically connect the REPL if there is an nRepl port file present when the project is opened.</p> <p>With this and the below mentioned auto-select options you can make connect a prompt-less experience. See: Connect Sequences.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#options-for-the-connect-command","title":"Options for the Connect Command","text":"<p>The <code>calva.connect</code> command takes an optional options argument defined like so:</p> <pre><code>  options?: {\n    host?: string;\n    port?: string;\n    connectSequence?: string | ReplConnectSequence;\n    disableAutoSelect?: boolean;\n  }\n</code></pre> <p>Where <code>ReplConnectSequence</code> is a Connect Sequences. If you provide a string it needs to match against a built-in or custom connect sequence. With <code>disableAutoSelect</code> you can force the connect menus to be provided even if a custom connect sequence is set to be autoSelected.</p> <p>You can provide these options from keyboard shortcuts or from Joyride scripts.</p> <p>Here's a keyboard shortcut for connecting to a running REPL bypassing any connect sequence with <code>autoSelectForConnect</code>.</p> <pre><code>    {\n        \"command\": \"calva.connect\",\n        \"args\": {\"disableAutoSelect\": true},\n        \"key\": \"ctrl+alt+c shift+c\",\n    },\n</code></pre> <p>A Joyride command for connecting to a REPL on port 55555, without being asked for project type:</p> <pre><code>(vscode/commands.executeCommand \"calva.connect\" (clj-&gt;js {:port \"55555\" :connectSequence \"Generic\"}))\n</code></pre>","boost":7},{"location":"customizing-jack-in-and-connect/#customizing-jack-in","title":"Customizing Jack-in","text":"<p>The main mechanism for customizing your Jack-in, including automating menu selections, and custom CLJS REPL types is Custom Connect Sequences.</p> <p>There are also these settings:</p> <ul> <li><code>calva.jackInEnv</code>: An object with environment variables that will be added to the environment of the Jack-in process.</li> <li><code>calva.myCljAliases</code>: An array of <code>deps.edn</code> aliases not found in the project file. Use this to tell Calva Jack-in to launch your REPL using your user defined aliases.</li> <li><code>calva.myLeinProfiles</code>: An array of Leiningen profiles not found in <code>project.clj</code>. Use this to tell Calva Jack-in to launch your REPL using your user defined profiles.</li> <li><code>calva.openBrowserWhenFigwheelStarted</code>: For Legacy Figwheel only. A boolean controlling if Calva should automatically launch your ClojureScript app, once it is compiled by Figwheel. Defaults to <code>true</code>.</li> <li><code>calva.depsEdnJackInExecutable</code>: A string which should either be <code>clojure</code> or <code>deps.clj</code>, or <code>clojure or deps.clj</code> (default). It determines which executable Calva Jack-in should use for starting a <code>deps.edn</code> project. With this setting at its default, <code>clojure or deps.clj</code>, Calva will test if the <code>clojure</code> executable works, and use it if it does, otherwise <code>deps.clj</code> will be used, which is bundled with Calva.</li> </ul> <p>Note</p> <p>When processing the <code>calva.jackInEnv</code> setting you can refer to existing ENV variables with <code>${env:VARIABLE}</code>.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#options-for-the-jack-in-command","title":"Options for the Jack-in Command","text":"<p>The <code>calva.jackIn</code> command takes an optional options argument defined like so:</p> <pre><code>  options?: {\n    connectSequence?: string | ReplConnectSequence;\n    disableAutoSelect?: boolean;\n  }\n</code></pre> <p>Where <code>ReplConnectSequence</code> is a Connect Sequences. If you provide a string it needs to match against a built-in or custom connect sequence. With <code>disableAutoSelect</code> you can force the jack-in menus to be provided even if a custom connect sequence is set to be autoSelected.</p> <p>You can provide these options from keyboard shortcuts or from Joyride scripts.</p> <p>Here's a keyboard shortcut for connecting to a running REPL bypassing any connect sequence with <code>autoSelectForConnect</code>.</p> <pre><code>    {\n        \"command\": \"calva.jackIn\",\n        \"args\": {\"disableAutoSelect\": true},\n        \"key\": \"ctrl+alt+c shift+j\",\n    },\n</code></pre> <p>A Joyride command for starting a <code>deps.edn</code> REPL for a project in the root of the workspace.</p> <pre><code>(vscode/commands.executeCommand\n \"calva.jackIn\"\n (clj-&gt;js {:connectSequence {:projectType \"deps.edn\"\n                             :projectRootPath [\".\"]}}))\n</code></pre> <p>It will prompt for any aliases it finds in the <code>deps.edn</code> file.    </p>","boost":7},{"location":"customizing-jack-in-and-connect/#starting-the-repl-from-application-code","title":"Starting the REPL from application code?","text":"<p>If your project is setup so that the REPL server is started by the application code, you will need to get the cider-nrepl middleware in place. See the cider-nrepl docs about embedding nREPL in your application.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#auto-select-project-type-and-project-root","title":"Auto-select Project Type and Project Root","text":"<p>You can make both Jack-in and Connect stop prompting you for project type and project root path in projects where you always want to use the same. See Connect Sequences.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#project-roots-search-globing","title":"Project roots search globing","text":"<p>When searching for project roots in your workspace, Calva will glob for all files matching <code>project.clj</code>, <code>deps.edn</code>, or <code>shadow-cljs.edn</code>. This is done using VS Code's workspace search engine, and is very efficient. However, in a large monorepo, it is still a substantial task. In order to not waste resources Calva will exclude any directories in the setting <code>calva.projectRootsSearchExclude</code>. </p> <p></p> <p>Exclude entry globs</p> <p>Each entry is a partial glob and will be part of a resulting glob of the form <code>**/{glob1,glob2,...,globN}</code>. This means that all directories in the workspace matching an entry will be excluded, regardless of where in the workspace they reside.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#viewing-the-communication-between-nrepl-and-calva","title":"Viewing the Communication Between nREPL and Calva","text":"<p>It may be helpful to view the messages sent between nREPL and Calva when troubleshooting an issue related to the REPL. See how to do that here.</p>","boost":7},{"location":"customizing/","title":"Customizing Calva","text":"<p>Don't like the defaults? On this page we can collect some of the customizations that people have done, and maybe write a thing or two about it some day.</p> <p>Tip for VS Code newcomers: The search box in Settings is your friend. Also, some Calva settings are more complex than the Settings UI can handle. VS Code will then show you a link to <code>settings.json</code>. And VS Code's built-in <code>json</code> extension is awesome. To add settings for Calva's Pretty Printing, for example, search for \u201dprettyprint\u201d in VS Code Settings and follow the link to <code>settings.json</code>. Start typing \u201dcalvapretty\u201d until auto-complete suggests <code>calva.prettyPrintingOptions</code>. Press ENTER and VS Code will fill in these defaults:</p> <pre><code>    \"calva.prettyPrintingOptions\": {\n        \"enabled\": true,\n        \"printEngine\": \"pprint\",\n        \"width\": 40\n    },\n</code></pre>"},{"location":"customizing/#clojure-defaults","title":"Clojure Defaults","text":"<p>Calva sets some VS Code settings for all Clojure files. Some of these are needed for Calva to function correctly, which should not be tampered with unless you really know what you are doing, and some of them are convenient defaults. If you add a setting to your <code>settings.json</code> and accept the snippet help you get when you type <code>\"[clojure]\"</code>, you will get the Calva defaults pasted:</p> <pre><code>    \"[clojure]\": {\n        \"editor.wordSeparators\": \"\\t ()\\\"':,;~@#$%^&amp;{}[]`\",\n        \"editor.autoClosingBrackets\": \"always\",\n        \"editor.autoClosingQuotes\": \"always\",\n        \"editor.autoClosingQuotes\": \"always\",\n        \"editor.formatOnType\": true,\n        \"editor.autoIndent\": \"full\",\n        \"editor.formatOnPaste\": true,\n        \"editor.matchBrackets\": \"never\",\n        \"editor.renderIndentGuides\": false,\n        \"editor.parameterHints.enabled\": false\n    }\n</code></pre> <p>Note</p> <p>The above <code>editor.wordSeparators</code> setting establish Clojure word boundaries. E.g <code>-</code> is considered to be part of words. This affects what happens when double-clicking symbols and other things. If you want to include <code>-</code> or something else as a word boundary, just add it to the setting.</p>"},{"location":"customizing/#pretty-printing","title":"Pretty Printing","text":"<p>Calva's pretty printing mode can be configured a bit. See Pretty Printing.</p>"},{"location":"customizing/#calva-highlight","title":"Calva Highlight","text":"<p>This is highly customizable. See Syntax highlighting</p>"},{"location":"customizing/#color-customizations","title":"Color customizations","text":"<p>Calva defines a set of themable colors which can be provided by the user using workbench.colorCustomizations.</p> <pre><code>    \"workbench.colorCustomizations\": {\n        \"calva.inlineErrorForegroundColor\": \"#ff0000\",\n        \"calva.inlineForegroundColor\": \"#ff9000\"\n    }\n</code></pre> <p></p>"},{"location":"customizing/#automatic-parameter-hints-poppup","title":"Automatic Parameter Hints Poppup","text":"<p>Calva has helpful parameter hints to aid when typing function calls. They look like so:</p> <p></p> <p>To have the hints automatically pop up when you are typing, set <code>editor.parameterHints.enabled</code> to <code>true</code> in the above <code>[clojure]</code> scoped setting. (To call them up on demand the default VS Code keybindings are <code>cmd+shift+space</code> on Mac and <code>ctrl+shift+space</code> on Linux/Windows.)</p>"},{"location":"customizing/#code-formatting","title":"Code Formatting","text":"<p>See Formatting for information on how to configure this.</p>"},{"location":"customizing/#jack-in-and-connect","title":"Jack-in and Connect","text":"<p>Jack-in and Connect are very customizable through Custom Connect Sequences.</p>"},{"location":"customizing/#jack-in-dependency-versions","title":"Jack-in Dependency Versions","text":"<p>Calva Jack-in injects the following dependencies in order for the REPL session to support IDE features</p> <ul> <li>nrepl: nREPL is the wonderful piece of software that gives Calva a structured and extensible connection to the REPL in your Clojure and ClojureScript projects.</li> <li>cider-nrepl: cider-nrepl is middleware that extends the nREPL connection with all sorts of nice stuff that Calva uses to give you a delightful IDE experience.</li> <li>cider/piggieback: Piggieback is used to create nREPL sessions in ClojureScript projects. (Not with shadow-cljs projects though, which provides its own middleware for this.)</li> </ul> <p>The versions used are configurable via the VS Code settings <code>calva.jackInDependencyVersions</code>.</p>"},{"location":"customizing/#key-bindings","title":"Key bindings","text":"<p>Most of Calva's commands have default keybindings. They are only defaults, though, and you can change keybindings as you wish. To facilitate precision in binding keys Calva keeps some when clause contexts updated.</p>"},{"location":"customizing/#when-clause-contexts","title":"When Clause Contexts","text":"<p>The following contexts are available with Calva:</p> <ul> <li><code>calva:keybindingsEnabled</code>: a master switch that you find in the settings</li> <li><code>paredit:keyMap</code>: <code>strict</code>, <code>original</code>, or <code>none</code> from the corresponding Calva setting (see Paredit)</li> <li><code>calva:connected</code>: <code>true</code> when Calva is connected to a REPL (there is also <code>calva:connecting</code> || <code>calva:launching</code>)</li> <li><code>calva:outputWindowActive</code>: <code>true</code> when the Output/REPL window has input focus</li> <li><code>calva:replHistoryCommandsActive</code>: <code>true</code> when the cursor is in the Output/REPL window at the top level after the last prompt</li> <li><code>calva:replWindowSubmitOnEnter</code>: <code>true</code> when the cursor is adjacent after the last top level form in the Output/REPL window</li> <li><code>calva:cursorInString</code>: <code>true</code> when the cursor/caret is in a string or a regexp</li> <li><code>calva:cursorInComment</code>: <code>true</code> when the cursor is in, or adjacent to a line comment</li> <li><code>calva:cursorBeforeComment</code>: <code>true</code> when the cursor is adjacent before a line comment</li> <li><code>calva:cursorAfterComment</code>: <code>true</code> when the cursor is adjacent after a line comment</li> <li><code>calva:cursorAtStartOfLine</code>: <code>true</code> when the cursor is at the start of a line including any leading whitespace</li> <li><code>calva:cursorAtEndOfLine</code>: <code>true</code> when the cursor is at the end of a line including any trailing whitespace</li> </ul>"},{"location":"customizing/#some-custom-bindings","title":"Some Custom Bindings","text":"<p>Here is a collection of custom keybindings from here and there.</p> <ul> <li>Replace all Calva <code>ctrl+alt+...</code> key bindings with <code>ctrl+shift+...</code>, for keyboards lacking <code>alt</code> key: this gist</li> <li>Replace the default Calva \u201dprefix\u201d, <code>ctrl+alt+c</code> to just <code>alt+v</code>: WebWItch's keybindings.json (Please note, that <code>alt+v</code> does not work for some locales, but for when it works it is much less clunky than the default prefix).</li> <li>Here the Calva key is switched for <code>ctrl+,</code>: manas_marthi's keybindings</li> <li>Keybindings for Emacs users</li> <li>Use modifiers and WASD keys for movement and manipulation: isaksky's keybindings</li> </ul> <p>Are you a vim extension user? See: Using with VIM extension.</p>"},{"location":"customizing/#move-by-word","title":"Move by word","text":"<p>By default Calva changes the move-by-word key bindings to move by sexpr/form when the cursor is in structural Clojure code. Within line comments the editor default word movement is active.</p> <p>If you want the VS Code default word movement shortcuts, use these settings:</p> <pre><code>    {\n        \"key\": \"ctrl+right\",\n        \"win\": \"ctrl+right\",\n        \"mac\": \"alt+right\",\n        \"command\": \"cursorWordRight\"\n    },\n    {\n        \"key\": \"ctrl+left\",\n        \"win\": \"ctrl+left\",\n        \"mac\": \"alt+left\",\n        \"command\": \"cursorWordLeft\"\n    },\n    {\n        \"key\": \"ctrl+right\",\n        \"mac\": \"ctrl+right\",\n        \"win\": \"alt+right\",\n        \"command\": \"paredit.forwardSexp\",\n        \"when\": \"calva:keybindingsEnabled &amp;&amp; editorTextFocus &amp;&amp; editorLangId == 'clojure' &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+left\",\n        \"mac\": \"ctrl+left\",\n        \"win\": \"alt+left\",\n        \"command\": \"paredit.backwardSexp\",\n        \"when\": \"calva:keybindingsEnabled &amp;&amp; editorTextFocus &amp;&amp; editorLangId == 'clojure' &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    }\n</code></pre> <p>Use it as an inspiration for customizing things to your own liking. \ud83d\ude04</p>"},{"location":"customizing/#wrap-using-like-cursive","title":"Wrap using <code>(</code>, <code>[</code>, <code>{</code> (like Cursive)","text":"<p>Something I use in IntelliJ/Cursive is the ability to select an expression and hit one of <code>(</code>, <code>[</code>, <code>{</code> to wrap it. And after wrapping the expression I don't want the selection anymore, so if I were wrapping <code>(foo)</code> then I would want to get <code>( | (foo))</code> where <code>|</code> would be my cursor.</p> <p>Here's how you can make this work with Calva Paredit: Update all of the <code>Paredit: Wrap Around ...</code> commands so that their respective shortcuts are the wrappers themselves and update the <code>when</code> clause to include <code>editorHasSelection</code> (otherwise when you open a paren the next expression would get slurped in).</p> <p>The change would look like this in your <code>keybindings.json</code>:</p> <pre><code>    {\n        \"key\": \"shift+9\",\n        \"command\": \"paredit.wrapAroundParens\",\n        \"when\": \"editorTextFocus &amp;&amp; editorHasSelection &amp;&amp; !editorReadOnly &amp;&amp; editorLangId =~ /clojure|scheme|lisp/ &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"[\",\n        \"command\": \"paredit.wrapAroundSquare\",\n        \"when\": \"editorHasSelection &amp;&amp; editorTextFocus &amp;&amp; !editorReadOnly &amp;&amp; editorLangId =~ /clojure|scheme|lisp/ &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"shift+[\",\n        \"command\": \"paredit.wrapAroundCurly\",\n        \"when\": \"editorHasSelection &amp;&amp; editorTextFocus &amp;&amp; !editorReadOnly &amp;&amp; editorLangId =~ /clojure|scheme|lisp/ &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    }\n</code></pre>"},{"location":"debugger/","title":"Debugger","text":"<p>Calva comes with a powerful expression-based debugger, inspired by Cider's debugger, and using the same underlying library, cider-nrepl. We hope you love it!</p> <p></p> <p>Note</p> <p>The debugger currently does not support ClojureScript. Calva's debugger utilizes cider-nrepl for debugging. See this Cider issue for more information.</p>"},{"location":"debugger/#features","title":"Features","text":""},{"location":"debugger/#current","title":"Current","text":"<ul> <li>Instrument functions for debugging with <code>ctrl+alt+c i</code></li> <li>Instrument a function manually with <code>#dbg</code> (as opposed to the above command)</li> <li>Set individual breakpoints with <code>#break</code></li> <li>Continue to next breakpoint</li> <li>Step over form</li> <li>Step into form</li> <li>Step out of form</li> <li>Evaluate code in the debug context</li> <li>See variable values in the debugger side pane</li> <li>See variable values on hover in the editor</li> </ul>"},{"location":"debugger/#future-goals","title":"Future goals","text":"<ul> <li>See structured variables in the debugger side pane (currently maps and collections are just shown as strings)</li> <li>Inject values into the debug context</li> <li>Trace: continue, printing expressions and their values</li> </ul>"},{"location":"debugger/#dependencies","title":"Dependencies","text":"<p>The debugger itself relies pretty heavily on cider-nrepl, as do other parts of Calva. This library is loaded as a dependency when you use Calva Jack-in. If you are not using Calva Jack-in, you can add these dependencies in your project definition or user profile. See the Calva Jack-in guide for more information.</p>"},{"location":"debugger/#using-the-debugger","title":"Using the Debugger","text":"<p>If you're new to Clojure or expression-based debuggers, this debugger may function differently than what you're used to. Instead of placing breakpoints in the side margin and then hitting F5 to start debugging, you instead use Clojure reader tags, <code>#break</code> and <code>#dbg</code>, to denote breakpoints anywhere in a Clojure form. When you evaluate a call to a function that has been evaluated with that reader tag, the debugger will start when execution reaches the first breakpoint. There's also a convenience command to instrument functions. Read below about both options.</p> <p>Note</p> <p>The debugger is not configured via a <code>launch.json</code> file, and is not started in the same way as you may be used to when working with other languages in VS Code. The debugger is used by way of the REPL. If you are new to Clojure, please visit the Getting Started section of the documentation and get familiar with evaluating code using the REPL before using the debugger.</p>"},{"location":"debugger/#instrumenting-a-function","title":"Instrumenting a Function","text":"<p>You can instrument a top level function for debugging with <code>ctrl+alt+c i</code>. This places invisible breakpoints throughout the function where pausing makes sense. When you evaluate a call to this function, the debugger will start and execution will pause at the first breakpoint. Annotations show the value of the form at the cursor.</p> <p>A border is placed around the definition of the instrumented function and its references to show that it's instrumented. You can remove instrumentation by evaluating the function again normally, such as with <code>alt+enter</code>.</p> <p></p>"},{"location":"debugger/#setting-breakpoints-with-break","title":"Setting Breakpoints with <code>#break</code>","text":"<p>You can insert a breakpoint manually into any code by placing a <code>#break</code> in front of the form where you want execution to pause, and then evaluating the top level form with <code>alt+enter</code>. When you evaluate a call to this code the VS Code debugger will start, the cursor will move to right after the form that's preceded by <code>#break</code>, and the line will be highlighted to show execution is paused there.</p> <p></p> <p>Note</p> <p>Code will be executed up to and including the form after the breakpoint.</p>"},{"location":"debugger/#conditional-breakpoints","title":"Conditional Breakpoints","text":"<p>You can set conditional breakpoints by adding metadata before the form that the <code>#break</code> applies to.</p> <pre><code>(defn print-nums [n]\n  (dotimes [i n]\n    #break ^{:break/when (= i 7)} ;; This breakpoint will only be hit when i equals 7\n    (prn i)))\n</code></pre>"},{"location":"debugger/#instrumenting-a-form-with-dbg","title":"Instrumenting a Form with <code>#dbg</code>","text":"<p>Adding <code>#dbg</code> before a form then evaluating the form with <code>alt+enter</code> will instrument the form. This has the same effect as using the instrument command.</p> <p></p> <p></p>"},{"location":"debugger/#evaluating-code-in-the-paused-context","title":"Evaluating Code in the Paused Context","text":"<p>When execution is paused at a breakpoint, you can evaluate code in that context. This can be done in the editor or in the REPL window, as usual.</p> <p></p>"},{"location":"debugger/#viewing-variable-values","title":"Viewing Variable Values","text":"<p>While debugging, you can view the values of variables in VS Code's debugger side pane. You can also view values by hovering over the variables in the editor.</p> <p></p> <p>Metadata not available</p> <p>The variable viewer does not have access to any metadata attached to the variable values.</p>"},{"location":"debugger/#viewing-the-call-stack","title":"Viewing the Call Stack","text":"<p>While debugging, you can view the call stack in VS Code's call stack side pane. Clicking the stack frames will show the related line of code in an editor.</p> <p>Note</p> <p>You may only see one stack frame in the call stack side pane, as the change for adding additional frames was rolled back due to an issue. You can follow the change for this at #1150.</p> <p></p>"},{"location":"debugger/#stepping-commands","title":"Stepping Commands","text":"<p>You can use VS Code's debugger UI to advance execution while debugging.</p> <p></p> <p>Note</p> <p>Clicking restart does nothing, since this functionality does not make sense for our debugger.</p> <ul> <li>Continue - Continues without stopping for the current breakpoint</li> <li>Step over - Continues to the next breakpoint</li> <li>Step in - Steps in to the function about to be called. If the next breakpoint is not around a function call, does the same as next. Note that not all functions can be stepped in to - only normal functions stored in vars, for which cider-nrepl can find the source. You cannot currently step in to multimethods, protocol functions, or functions in clojure.core (although multimethods and protocols can be instrumented manually).</li> <li>Step out - Steps to the next breakpoint that is outside of the current sexp</li> <li>Restart - Does nothing. To restart debugging, you can hit disconnect or continue execution through the final result, then re-evaluate the expression that started the debugger.</li> <li>Disconnect - Disconnects the debugger</li> </ul>"},{"location":"debugger/#caveats","title":"Caveats","text":""},{"location":"debugger/#breakpoints-in-looprecur","title":"Breakpoints in loop/recur","text":"<p>One construct where the debugger is limited is <code>loop</code>/<code>recur</code>. As recur always has to appear in a tail-position inside a <code>loop</code> or a <code>fn</code> and the debugger uses macros to interleave breakpoints in the forms, it might happen that a <code>recur</code> no longer appears in a tail position. In that case we have to avoid setting up the breakpoint. An example of such a case is:</p> <pre><code>(loop [i 0]\n  #break\n  (when (&lt; i 10)\n    (println i)\n    (recur (inc i))))\n</code></pre> <p>Here the breakpoint is exactly in front of a form that contains as its last expression a <code>recur</code> which is wrapped in a loop. This breakpoint has no effect. This does not mean you cannot use the debugger with <code>loop</code>, it just means you have to set your debug statements more carefully.</p>"},{"location":"debugger/#loading-the-file-and-eval-on-save","title":"Loading the File and \"Eval On Save\"","text":"<p>When you load a file, any breakpoints that were previously set in functions will be unset. If you have the \"Eval On Save\" setting enabled, your file is also loaded with each save, therefore saving the file will remove breakpoints previously set.</p>"},{"location":"debugger/#troubleshooting","title":"Troubleshooting","text":""},{"location":"debugger/#debugger-hangs-when-stepping-over-infinite-seqs","title":"Debugger hangs when stepping over infinite seqs","text":"<p>This is because the debugger tries to evaluate the form when it's stepped over, and if <code>clojure.core/*print-length*</code> is set to <code>nil</code> as it is by default, evaluation will never complete. If you want to debug a form with an infinite seq, make sure to set <code>*print-length*</code> beforehand. For example:</p> <pre><code>(set! *print-length* 3)\n;; Or, to be more precise\n(set! clojure.core/*print-length* 3)\n</code></pre> <p>Calva does not set this for you during debug mode, instead leaving it up to you to decide the value.</p>"},{"location":"debugger/#my-breakpoint-isnt-being-hit","title":"My breakpoint isn't being hit","text":"<p>It's likely that your breakpoint is in a place that cider-nrepl does not see as an appropriate place to break execution. For example, if you put a breakpoint before a literal number, it will not be hit, because there's no need to show the value of a literal.</p> <pre><code>(defn simple [x]\n  (+ 1 #break 1)) ;; This breakpoint will not be hit\n</code></pre> <p>Another possible issue is that you're loading the file again after setting breakpoints, which unsets them. See Loading the File and \"Eval On Save\" under Caveats.</p>"},{"location":"debugger/#my-breakpoint-in-a-test-isnt-being-hit","title":"My breakpoint in a test isn't being hit","text":"<p>If you're using the test commands like \"Run current test\" to run your tests, breakpoints will not be hit. This is because Calva loads the file before running the tests to make sure the latest version of test code is being run, and when the file is loaded, breakpoints are unset.</p> <p>If you want a breakpoint to work within the test, evaluate the test form with a breakpoint tag in it, then call the test directly.</p> <p></p>"},{"location":"debugger/#no-reader-function-for-tag-error","title":"\"No reader function for tag\" error","text":"<p>If you get an error like this, it's likely that you connected to a REPL instead of jacking in, and you don't have the proper dependencies loaded in your REPL. You can run the command \"Copy Jack-in Command Line to Clipboard\" to see what command would be run if you jacked in.</p> <p>Most importantly, make sure you have <code>cider/cider-nrepl</code> as a dependency, and <code>cider.nrepl/cider-middleware</code> as middleware loaded in your REPL. For example, this is a jack-in command line for a deps.edn project:</p> <pre><code>clojure -Sdeps '{:deps {nrepl/nrepl {:mvn/version,\"0.8.3\"},cider/cider-nrepl {:mvn/version,\"0.25.8\"}}}' -m nrepl.cmdline --middleware \"[cider.nrepl/cider-middleware]\"\n</code></pre>"},{"location":"debugger/#passing-options-to-the-repl-jvm","title":"Passing options to the REPL JVM","text":"<p>There are times when Clojure debugging tools are not enough or not right for the job. This is usually true when use an (open source) Java library and you want to set some breakpoints in Java code. For those cases and others, you need to start the JVM in debug mode.</p> <p>Typical use cases:</p> <ul> <li>Change Java logger configuration for the REPL via java system properties: e.g <code>-Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE</code></li> <li>Enable JVM debugger, change VM memory size, etc.</li> </ul> <p>Calva supports passing environment variables via <code>jackInEnv</code>. You can set that option inside VSCode <code>settings.json</code> file.</p> <p>You can configure global <code>settings.json</code> file or a project wide version, inside <code>&lt;project-root&gt;/.vscode/settings.json</code>.</p> <p>Configuring the global option will impact all projects you work on using Calva, so be aware. See the documentation for <code>settings.json</code> for more information.</p> <p>The bellow snippet configures <code>JAVA_TOOL_OPTIONS</code> environment variable. We configure slf4j-simple logging level via a Java system property (<code>-D</code>) and JVM specific options (<code>-X</code>).</p> <p>NOTE: You can of course pass other env variables here.</p> <p>.vscode/settings.json</p> <pre><code>{\n    \"calva.jackInEnv\": {\n        \"JAVA_TOOL_OPTIONS\": \"${env:JAVA_TOOL_OPTIONS} -Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7896\"\n    }\n}\n</code></pre> <p>Once you saved the file, the next time you <code>Jack in</code> the project, this variable is read by the JVM and the configuration is applied accordingly.</p> <p>You should see something like the message below in the Calva terminal output window:</p> <pre><code>clojure -Sdeps '{:deps {nrepl/nrepl {:mvn/version,\"0.8.3\"},cider/cider-nrepl {:mvn/version,\"0.26.0\"}}}' -A:debug -m nrepl.cmdline --middleware \"[cider.nrepl/cider-middleware]\"\nPicked up JAVA_TOOL_OPTIONS:  -Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7896\nListening for transport dt_socket at address: 7896\nnREPL server started on port 46691 on host localhost - nrepl://localhost:46691\n</code></pre>"},{"location":"emacs-keybindings/","title":"Emacs Keybindings","text":"<p>Some keybindings to make it easier for Emacs users <pre><code>[\n    {\n        \"key\": \"ctrl+cmd+b\",\n        \"command\": \"paredit.backwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+alt+left\",\n        \"command\": \"-paredit.backwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"shift+cmd+]\",\n        \"command\": \"-workbench.action.nextEditor\"\n    },\n    {\n        \"key\": \"ctrl+shift+]\",\n        \"command\": \"paredit.barfSexpBackward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+right\",\n        \"command\": \"-paredit.barfSexpBackward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+[\",\n        \"command\": \"paredit.barfSexpForward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+left\",\n        \"command\": \"-paredit.barfSexpForward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+cmd+f\",\n        \"command\": \"paredit.forwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+alt+right\",\n        \"command\": \"-paredit.forwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+cmd+f\",\n        \"command\": \"-workbench.action.toggleFullScreen\"\n    },\n    {\n        \"key\": \"ctrl+shift+backspace\",\n        \"command\": \"-paredit.killSexpForward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"shift+cmd+k\",\n        \"command\": \"-editor.action.deleteLines\",\n        \"when\": \"textInputFocus &amp;&amp; !editorReadonly\"\n    },\n    {\n        \"key\": \"ctrl+shift+0\",\n        \"command\": \"paredit.slurpSexpForward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+right\",\n        \"command\": \"-paredit.slurpSexpForward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+9\",\n        \"command\": \"paredit.slurpSexpBackward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+left\",\n        \"command\": \"-paredit.slurpSexpBackward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+c ctrl+c\",\n        \"command\": \"calva.evaluateCurrentTopLevelForm\",\n        \"when\": \"calva:activated\"\n    },\n    {\n        \"key\": \"ctrl+alt+c space\",\n        \"command\": \"-calva.evaluateCurrentTopLevelForm\",\n        \"when\": \"calva:activated\"\n    },\n    {\n        \"key\": \"ctrl+x ctrl+e\",\n        \"command\": \"calva.evalCurrentTopLevelFormInREPLWindow\",\n        \"when\": \"calva:activated\"\n    },\n    {\n        \"key\": \"ctrl+alt+c ctrl+alt+space\",\n        \"command\": \"-calva.evalCurrentTopLevelFormInREPLWindow\",\n        \"when\": \"calva:activated\"\n    },\n    {\n        \"key\": \"ctrl+x ctrl+s\",\n        \"command\": \"workbench.action.files.save\"\n    },\n    {\n        \"key\": \"cmd+s\",\n        \"command\": \"-workbench.action.files.save\"\n    },\n    {\n        \"key\": \"cmd+s\",\n        \"command\": \"paredit.spliceSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+alt+s\",\n        \"command\": \"-paredit.spliceSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+cmd+k\",\n        \"command\": \"paredit.cutForwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+x right\",\n        \"command\": \"-paredit.cutForwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+cmd+backspace\",\n        \"command\": \"paredit.cutBackwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+x left\",\n        \"command\": \"-paredit.cutBackwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+1\",\n        \"command\": \"-workbench.action.openEditorAtIndex1\"\n    },\n    {\n        \"key\": \"ctrl+1\",\n        \"command\": \"editor.action.quickFix\",\n        \"when\": \"editorHasCodeActionsProvider &amp;&amp; editorTextFocus &amp;&amp; !editorReadonly\"\n    },\n    {\n        \"key\": \"cmd+.\",\n        \"command\": \"-editor.action.quickFix\",\n        \"when\": \"editorHasCodeActionsProvider &amp;&amp; editorTextFocus &amp;&amp; !editorReadonly\"\n    },\n    {\n        \"key\": \"cmd+.\",\n        \"command\": \"editor.action.revealDefinition\",\n        \"when\": \"editorHasDefinitionProvider &amp;&amp; editorTextFocus &amp;&amp; !isInEmbeddedEditor\"\n    },\n    {\n        \"key\": \"f12\",\n        \"command\": \"-editor.action.revealDefinition\",\n        \"when\": \"editorHasDefinitionProvider &amp;&amp; editorTextFocus &amp;&amp; !isInEmbeddedEditor\"\n    }\n]\n</code></pre></p>"},{"location":"eval-tips/","title":"Code Evaluation","text":"<p>Calva tries to make it easy to evaluate code, supporting interactive development. The fastest path to learning about it is to use the Fire up the Getting Started REPL command, which you can learn more about in the Getting Started section.</p> <p>NB: The below assumes you have read about Finding Calva Commands and Shortcuts.</p>","boost":7},{"location":"eval-tips/#interruptingstopping-running-evaluations","title":"Interrupting/stopping running evaluations","text":"<p>Sometimes you evaluate things that take a very long time to complete, or might not even ever complete (infinite loops, lazy sequences, things like that). Calva has a command for interrupting running evaluations. You find it in the VS Code command palette, as well as in the REPL status bar item menu, when the REPL is connected.</p>","boost":7},{"location":"eval-tips/#evaluation-in-a-file-editor","title":"Evaluation in a File Editor","text":"<p>Calva has many commands for evaluating forms, including the current form and the current top-level form.</p> <p>Some of the commands also let you choose what should happen with the results:</p> <ol> <li>Inline. This will display the results (or some of it, if it is long) inline in the editor.</li> <li>This also creates a hover pane including the full results and a button which will copy the results to the clipboard.</li> <li>There is also a command for copying the last result to the clipboard.</li> <li>The full results are always available in the output window.<ul> <li>There is a command for showing the output window, allowing for a workflow where you either generally have it closed, or have it as one of the tabs in the same editor group as the files you are working with.</li> </ul> </li> <li>To comments. This will add the results as line comments below the current line.</li> <li>Replace the evaluated code. This will do what it says, the evaluated code will be replaced with its results.</li> </ol>","boost":7},{"location":"eval-tips/#wait-current-form-top-level-form","title":"Wait, Current Form? Top-level Form?","text":"<p>These are important concepts in Calva in order for you to create your most effective workflow. This video explains it a bit:</p>","boost":7},{"location":"eval-tips/#current-form","title":"Current Form","text":"<p>Default shortcut for evaluating the current form: <code>ctrl+enter</code>.</p> <p>The current form either means the current selection, or otherwise is based on the cursor position. Play some with the command Calva: Select current form, <code>ctrl+alt+c s</code>, to figure out what Calva thinks is the current form for some different situations. Try it inside a symbol, adjacent to a symbol (both sides) and adjacent to an opening or closing bracket (again, both sides). Generally the current form is determined like so:</p> <ol> <li>If text is selected, then that text</li> <li>If the cursor is \u201din\u201d a symbol, then that symbol    <pre><code>foob|ar ; foobar\n</code></pre></li> <li>If the cursor is adjacent to a form (a symbol or a list of some kind), then that form    <pre><code>(foo bar |(baz)) ; (baz)\n</code></pre></li> <li>If the cursor is between to forms, then the left side form    <pre><code>(foo bar | (baz)) ; bar\n</code></pre></li> <li>If the cursor is before the first form of a line, then that form    <pre><code>(foo\n| bar (baz)) ; bar\n</code></pre></li> </ol>","boost":7},{"location":"eval-tips/#current-top-level-form","title":"Current Top-level Form","text":"<p>Default shortcut for evaluating the current top level form: <code>alt+enter</code>.</p> <p>The current top-level form means top-level in a structural sense. It is not the topmost form in the file. Typically in a Clojure file you will find <code>def</code> and <code>defn</code> (and <code>defwhatever</code>) forms at the top level, which also is one major intended use for evaluating top level form: to define and redefine variables. However, Calva does not check the contents of the form in order to determine it as a top-level forms: all forms not enclosed in any other form are top level forms.</p> <p>An \u201dexception\u201d is introduced by the <code>comment</code> form. It will create a new top level context, so that any forms immediately inside a <code>(comment ...)</code> form will be considered top-level by Calva. This is to support a workflow with what is often referred to the Rich Comments.</p> <p>At the top level the selection of which form is the current top level form follows the same rules as those for the current form.</p>","boost":7},{"location":"eval-tips/#evaluate-enclosing-form","title":"Evaluate Enclosing Form","text":"<p>The default keyboard shortcut for evaluating the current enclosing form (the list the cursor is in) is <code>ctrl+shift+enter</code>.</p> <pre><code>(let [foo :bar]\n  (when false (str| foo))) ; =&gt; \":bar\"\n</code></pre>","boost":7},{"location":"eval-tips/#evaluate-to-cursor","title":"Evaluate to Cursor","text":"<p>There are several commands for evaluating a piece of code, closing brackets. It's good, especially in threads, but can also come in handy in other situations, for instance when you want to evaluate something that depends on bindings, such as in a <code>let</code> form.</p>","boost":7},{"location":"eval-tips/#evaluate-from-start-of-list-to-cursor-closing-brackets","title":"Evaluate From Start of List to Cursor, Closing Brackets","text":"<p>This command evaluates the text from the start of the current enclosing list to where the cursor is, and it adds the missing closing bracket for you. Convenient for checking intermediate results in thread or <code>doto</code>, or similar pipelines. The cursor is right behind <code>:d</code> in this form:</p> <pre><code>  (-&gt;&gt; [1 1 2 3 5 8 13 21]\n       (partition 2)\n       (zipmap [:a :b :c :d])\n       :d| ; =&gt; (13 21)\n       (apply -)\n       (Math/abs))\n</code></pre> <p>The default shortcut for this command is ctrl+alt+enter.</p>","boost":7},{"location":"eval-tips/#evaluate-selection-closing-brackets","title":"Evaluate Selection, Closing Brackets","text":"<p>This is the most versatile of the \u201devaluation, closing brackets\u201d commands. It will do what it says. \ud83d\ude04 It's extra handy in combination with the command Paredit: Select Backward Up Sexp/Form (shift+ctrl+up). Consider this contrieved form (buggy code, because it was supposed to result in <code>42</code>, not <code>-42</code>):</p> <pre><code>(defn fortytwo-from-thirty\n  []\n  (let [thirty 30]\n    (-&gt; thirty\n        inc            ;1\n        (send-off)\n        (+ 1 2 3)\n        (-&gt;&gt;\n         (+ 2 2)       ;2\n         (+))\n        list\n        (-&gt;&gt;\n         (into [1])\n         (reduce + 1))\n        (- 1)          ;3\n        (* -1))))\n</code></pre> <p>At <code>;1</code>, you can do backward up sexp (shift+ctrl+up) twice to select up to the <code>(let ..)</code>, then issue Evaluate Selection, Closing Brackets. It has the same default keybinding as the command for evaluating the current list up to the cursor: ctrl+alt+enter.</p> <p>At <code>;2</code> you need select backwards up three times.</p> <p><code>;3</code> is included because it is close to the bug. (Which was introduced when the thread-last, <code>-&gt;&gt;</code> was added to make this example.) Please practice the Evaluate Selection, Closing Brackets command to fix the bug.</p>","boost":7},{"location":"eval-tips/#evaluate-from-start-of-top-level-form-to-cursor-closing-brackets","title":"Evaluate From Start of Top Level Form to Cursor, Closing Brackets","text":"<p>This command has a default shortcut keybinding of <code>shift+alt+enter</code>. It will create a form from the start of the current top level form, up to the cursor, close all brackets, and this will then be evaluated. Good for examining code blocks up to a certain point. Often comes in handy in Rich comments (<code>(comment ...)</code>).</p> <p>Take this example and paste it in a file loaded into the REPL, then place the cursor in front of each line comment and try the command.</p> <pre><code>(comment\n (do\n   (def colt-express\n     {:name \"Colt Express\"\n      :categories [\"Family\"\n                   \"Strategy\"]\n      :play-time 40\n      :ratings {:pez 5.0\n                :kat 5.0\n                :wiw 5.0   ; 1, then eval `colt-express`\n                :vig 3.0\n                :rex 5.0\n                :lun 4.0}})\n\n   (defn average [coll]\n     (/ (apply + coll) (count coll)))\n\n   (let [foo-express (-&gt; colt-express\n                         (assoc :name \"Foo Express\")\n                         (assoc-in [:ratings :lyr] 5.0)\n                         (update-in [:ratings :vig] inc))]\n     (-&gt;&gt; foo-express   ; 2\n          :ratings      ; 3\n          vals          ; 4\n          average       ; 5\n          ))))\n</code></pre>","boost":7},{"location":"eval-tips/#evaluate-from-start-of-file-to-cursor-closing-brackets","title":"Evaluate From Start of File to Cursor, Closing Brackets","text":"<p>Yup, that command also exists. \ud83d\ude04</p>","boost":7},{"location":"eval-tips/#copying-the-inline-results","title":"Copying the inline results","text":"<p>There is a command called Copy last evaluation results, <code>ctrl+alt+c ctrl+c</code>.</p> <p>This works regardless if you have evaluated in a file editor or in a REPL window.</p>","boost":7},{"location":"eval-tips/#evaluating-in-a-repl-window","title":"Evaluating in a REPL window","text":"<p>Since the REPL Window is mostly just a regular file, things work pretty similar at the REPL prompt. You use <code>alt+enter</code> to evaluate. Selecting the current form (default key binding <code>ctrl+w</code> on Mac and <code>shift+alt+right</code> on Windows and Linux) after evaluating will select the result.</p>","boost":7},{"location":"evaluation/","title":"Code Evaluation","text":"<p>Calva tries to make it easy to evaluate code, supporting interactive development. The fastest path to learning about it is to use the Fire up the Getting Started REPL command, which you can learn more about in the Getting Started section.</p> <p>NB: The below assumes you have read about Finding Calva Commands and Shortcuts.</p>","boost":7},{"location":"evaluation/#interruptingstopping-running-evaluations","title":"Interrupting/stopping running evaluations","text":"<p>Sometimes you evaluate things that take a very long time to complete, or might not even ever complete (infinite loops, lazy sequences, things like that). Calva has a command for interrupting running evaluations. You find it in the VS Code command palette, as well as in the REPL status bar item menu, when the REPL is connected.</p>","boost":7},{"location":"evaluation/#evaluation-in-a-file-editor","title":"Evaluation in a File Editor","text":"<p>Calva has many commands for evaluating forms, including the current form and the current top-level form.</p> <p>Some of the commands also let you choose what should happen with the results:</p> <ol> <li>Inline. This will display the results (or some of it, if it is long) inline in the editor.</li> <li>This also creates a hover pane including the full results and a button which will copy the results to the clipboard.</li> <li>There is also a command for copying the last result to the clipboard.</li> <li>The full results are always available in the output window.<ul> <li>There is a command for showing the output window, allowing for a workflow where you either generally have it closed, or have it as one of the tabs in the same editor group as the files you are working with.</li> </ul> </li> <li>To comments. This will add the results as line comments below the current line.</li> <li>Replace the evaluated code. This will do what it says, the evaluated code will be replaced with its results.</li> </ol>","boost":7},{"location":"evaluation/#wait-current-form-top-level-form","title":"Wait, Current Form? Top-level Form?","text":"<p>These are important concepts in Calva in order for you to create your most effective workflow. This video explains it a bit:</p>","boost":7},{"location":"evaluation/#current-form","title":"Current Form","text":"<p>Default shortcut for evaluating the current form: <code>ctrl+enter</code>.</p> <p>The current form either means the current selection, or otherwise is based on the cursor position. Play some with the command Calva: Select current form, <code>ctrl+alt+c s</code>, to figure out what Calva thinks is the current form for some different situations. Try it inside a symbol, adjacent to a symbol (both sides) and adjacent to an opening or closing bracket (again, both sides). Generally the current form is determined like so:</p> <ol> <li>If text is selected, then that text</li> <li>If the cursor is \u201din\u201d a symbol, then that symbol    <pre><code>foob|ar ; foobar\n</code></pre></li> <li>If the cursor is adjacent to a form (a symbol or a list of some kind), then that form    <pre><code>(foo bar |(baz)) ; (baz)\n</code></pre></li> <li>If the cursor is between to forms, then the left side form    <pre><code>(foo bar | (baz)) ; bar\n</code></pre></li> <li>If the cursor is before the first form of a line, then that form    <pre><code>(foo\n| bar (baz)) ; bar\n</code></pre></li> </ol>","boost":7},{"location":"evaluation/#current-top-level-form","title":"Current Top-level Form","text":"<p>Default shortcut for evaluating the current top level form: <code>alt+enter</code>.</p> <p>The current top-level form means top-level in a structural sense. It is not the topmost form in the file. Typically in a Clojure file you will find <code>def</code> and <code>defn</code> (and <code>defwhatever</code>) forms at the top level, which also is one major intended use for evaluating top level form: to define and redefine variables. However, Calva does not check the contents of the form in order to determine it as a top-level forms: all forms not enclosed in any other form are top level forms.</p> <p>An \u201dexception\u201d is introduced by the <code>comment</code> form. It will create a new top level context, so that any forms immediately inside a <code>(comment ...)</code> form will be considered top-level by Calva. This is to support a workflow with what is often referred to the Rich Comments.</p> <p>At the top level the selection of which form is the current top level form follows the same rules as those for the current form.</p>","boost":7},{"location":"evaluation/#evaluate-enclosing-form","title":"Evaluate Enclosing Form","text":"<p>The default keyboard shortcut for evaluating the current enclosing form (the list the cursor is in) is <code>ctrl+shift+enter</code>.</p> <pre><code>(let [foo :bar]\n  (when false (str| foo))) ; =&gt; \":bar\"\n</code></pre>","boost":7},{"location":"evaluation/#evaluate-to-cursor","title":"Evaluate to Cursor","text":"<p>There are several commands for evaluating a piece of code, closing brackets. It's good, especially in threads, but can also come in handy in other situations, for instance when you want to evaluate something that depends on bindings, such as in a <code>let</code> form.</p>","boost":7},{"location":"evaluation/#evaluate-from-start-of-list-to-cursor-closing-brackets","title":"Evaluate From Start of List to Cursor, Closing Brackets","text":"<p>This command evaluates the text from the start of the current enclosing list to where the cursor is, and it adds the missing closing bracket for you. Convenient for checking intermediate results in thread or <code>doto</code>, or similar pipelines. The cursor is right behind <code>:d</code> in this form:</p> <pre><code>  (-&gt;&gt; [1 1 2 3 5 8 13 21]\n       (partition 2)\n       (zipmap [:a :b :c :d])\n       :d| ; =&gt; (13 21)\n       (apply -)\n       (Math/abs))\n</code></pre> <p>The default shortcut for this command is ctrl+alt+enter.</p>","boost":7},{"location":"evaluation/#evaluate-selection-closing-brackets","title":"Evaluate Selection, Closing Brackets","text":"<p>This is the most versatile of the \u201devaluation, closing brackets\u201d commands. It will do what it says. \ud83d\ude04 It's extra handy in combination with the command Paredit: Select Backward Up Sexp/Form (shift+ctrl+up). Consider this contrieved form (buggy code, because it was supposed to result in <code>42</code>, not <code>-42</code>):</p> <pre><code>(defn fortytwo-from-thirty\n  []\n  (let [thirty 30]\n    (-&gt; thirty\n        inc            ;1\n        (send-off)\n        (+ 1 2 3)\n        (-&gt;&gt;\n         (+ 2 2)       ;2\n         (+))\n        list\n        (-&gt;&gt;\n         (into [1])\n         (reduce + 1))\n        (- 1)          ;3\n        (* -1))))\n</code></pre> <p>At <code>;1</code>, you can do backward up sexp (shift+ctrl+up) twice to select up to the <code>(let ..)</code>, then issue Evaluate Selection, Closing Brackets. It has the same default keybinding as the command for evaluating the current list up to the cursor: ctrl+alt+enter.</p> <p>At <code>;2</code> you need select backwards up three times.</p> <p><code>;3</code> is included because it is close to the bug. (Which was introduced when the thread-last, <code>-&gt;&gt;</code> was added to make this example.) Please practice the Evaluate Selection, Closing Brackets command to fix the bug.</p>","boost":7},{"location":"evaluation/#evaluate-from-start-of-top-level-form-to-cursor-closing-brackets","title":"Evaluate From Start of Top Level Form to Cursor, Closing Brackets","text":"<p>This command has a default shortcut keybinding of <code>shift+alt+enter</code>. It will create a form from the start of the current top level form, up to the cursor, close all brackets, and this will then be evaluated. Good for examining code blocks up to a certain point. Often comes in handy in Rich comments (<code>(comment ...)</code>).</p> <p>Take this example and paste it in a file loaded into the REPL, then place the cursor in front of each line comment and try the command.</p> <pre><code>(comment\n (do\n   (def colt-express\n     {:name \"Colt Express\"\n      :categories [\"Family\"\n                   \"Strategy\"]\n      :play-time 40\n      :ratings {:pez 5.0\n                :kat 5.0\n                :wiw 5.0   ; 1, then eval `colt-express`\n                :vig 3.0\n                :rex 5.0\n                :lun 4.0}})\n\n   (defn average [coll]\n     (/ (apply + coll) (count coll)))\n\n   (let [foo-express (-&gt; colt-express\n                         (assoc :name \"Foo Express\")\n                         (assoc-in [:ratings :lyr] 5.0)\n                         (update-in [:ratings :vig] inc))]\n     (-&gt;&gt; foo-express   ; 2\n          :ratings      ; 3\n          vals          ; 4\n          average       ; 5\n          ))))\n</code></pre>","boost":7},{"location":"evaluation/#evaluate-from-start-of-file-to-cursor-closing-brackets","title":"Evaluate From Start of File to Cursor, Closing Brackets","text":"<p>Yup, that command also exists. \ud83d\ude04</p>","boost":7},{"location":"evaluation/#copying-the-inline-results","title":"Copying the inline results","text":"<p>There is a command called Copy last evaluation results, <code>ctrl+alt+c ctrl+c</code>.</p> <p>This works regardless if you have evaluated in a file editor or in a REPL window.</p>","boost":7},{"location":"evaluation/#evaluating-in-a-repl-window","title":"Evaluating in a REPL window","text":"<p>Since the REPL Window is mostly just a regular file, things work pretty similar at the REPL prompt. You use <code>alt+enter</code> to evaluate. Selecting the current form (default key binding <code>ctrl+w</code> on Mac and <code>shift+alt+right</code> on Windows and Linux) after evaluating will select the result.</p>","boost":7},{"location":"fiddle-files/","title":"Fiddle Files Support","text":"<p>In the podcast Functional Design in Clojure, Episode 014: Fiddle with the REPL, they discuss a workflow in which you keep some of your exploratory code in separate files, which they call Fiddle Files. It's like Rich Comments, 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 your project. Some developers keep personal fiddle files. In some projects they are meant to be shared, and in other projects it's a combination.</p> <p>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 a little configuration.</p>","boost":5},{"location":"fiddle-files/#the-three-fiddle-file-commands","title":"The Three Fiddle File Commands","text":"<p>The commands let you quickly navigate between your implementation code (called Source here) and your Fiddle file, and to evaluate the Fiddle file without leaving the Source file.</p> Command Action Shortcut Active Calva: Open Fiddle File for Current File Opens the Fiddle file corresponding to the current Clojure Source file. ctrl+alt+cf 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. ctrl+alt+cf 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. ctrl+alt+cctrl+alt+f When the currently active file is not a Fiddle file. <p>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 command will not offer to create the target file.</p> <p>What does corresponding mean here? Without any configuration Calva will look for \u201csibling\u201d files, where files with Clojure file extensions (E.g. <code>.clj</code>, <code>.cljs</code>, <code>.bb</code>) will be treated as Source files, and files with the <code>.fiddle</code> 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.</p>","boost":5},{"location":"fiddle-files/#the-fiddle-file-configuration","title":"The Fiddle File Configuration","text":"<p>To know how to map between Fiddle &lt;-&gt; Source files, Calva has three different modes of operation:</p> <ol> <li>The sibling files, as described above. This is the default. Example:<ul> <li><code>src</code><code>/a/b/c.cljc</code> corresponding to:</li> <li><code>src</code><code>/a/b/c.fiddle</code></li> </ul> </li> <li>Parallel directory structures. Mapping a Source directory tree to a Fiddle directory tree. Example:<ul> <li><code>src</code><code>/a/b/c.cljc</code> corresponding to:</li> <li><code>env/dev/fiddles</code><code>/a/b/c.cljc</code></li> </ul> </li> <li>A dedicated Fiddle file for a Source directory tree. E.g. both:<ul> <li><code>src</code><code>/a/b/c.cljc</code> and:</li> <li><code>src</code><code>/d/e/f.cljc</code> corresponding to:</li> <li><code>env/dev/fiddles</code><code>/x.cljc</code></li> </ul> </li> </ol> <p>The setting is named <code>calva.fiddleFilePaths</code> and is an array of <code>source</code> and <code>fiddle</code> root paths, relative to the project root.</p> <p>The Project Root</p> <p>It is important to note that the project root depends on whether you are connected to a REPL or not, and to which project you are connected, in case the workspace contains several projects.</p> <p>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.</p> <p>With a REPL connection, the project root will be the root of the project, i.e. where the project file (<code>deps.edn</code>, <code>project.clj</code>, <code>shadow-cljs.edn</code>) is.</p>","boost":5},{"location":"fiddle-files/#example-configurations","title":"Example Configurations","text":"","boost":5},{"location":"fiddle-files/#single-parallel-directory-structure","title":"Single Parallel Directory Structure","text":"<pre><code>\"calva.fiddleFilePaths\": [\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddles\"]\n  }\n]\n</code></pre> <p>This will make any file in the <code>src</code> directory tree correspond to a matching file with the same relative path. E.g.:</p> <ul> <li><code>src/a/b/c.clj</code> -&gt; <code>env/dev/fiddles/a/b/c.clj</code>, for both the open and evaluate commands</li> <li><code>env/dev/fiddles/a/b/c.clj</code> -&gt; <code>src/a/b/c.clj</code></li> </ul>","boost":5},{"location":"fiddle-files/#single-dedicated-fiddle-file","title":"Single Dedicated Fiddle File","text":"<p>If you generally work with one Fiddle file at a time, you can configure a mapping to a Dedicated Fiddle file. E.g.:</p> <pre><code>\"calva.fiddleFilePaths\": [\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddle.clj\"]\n  },\n]\n</code></pre> <p>This will make any file in the <code>src</code> directory tree correspond to the same Fiddle file. E.g.:</p> <ul> <li><code>src/a/b/c.clj</code> -&gt; <code>env/dev/fiddle.clj</code>, for both the open and evaluate commands</li> <li><code>src/d/e/f.clj</code> -&gt; <code>env/dev/fiddle.clj</code>, ditto</li> <li><code>env/dev/fiddle.clj</code> -&gt; Won't correspond to a Source file in this case</li> </ul> <p>Jumping from a dedicated fiddle to a source file</p> <p>Calva's command for opening the corresponding source file won't work in this case because it is a one-&gt;many situation. If you want to open the last file you worked with before using Open Fiddle File for Current File, consider using the VS Code command: Go Previous.</p>","boost":5},{"location":"fiddle-files/#multiple-mappings","title":"Multiple Mappings","text":"<p>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.</p> <pre><code>\"calva.fiddleFilePaths\": [\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddles\"]\n  },\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddle.clj\"]\n  },\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddle.cljs\"]\n  },\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddle.bb\"]\n  },\n  {\n    \"source\": [\"src\", \"b\"],\n    \"fiddle\": [\"env\", \"dev\", \"b-fiddles\"]\n  },\n]\n</code></pre> <p>With this configuration we would get a behaviour like so:</p> <ul> <li><code>src/a/b/c.clj</code> -&gt; <code>env/dev/fiddle.clj</code>, because all four first <code>[\"src\"]</code> mappings match, but the second one is a dedicated fiddle file, and matches the <code>.clj</code> extension.</li> <li><code>src/a/b/c/d.bb</code> -&gt; <code>env/dev/fiddle.bb</code>, because all four first <code>[\"src\"]</code> mappings match, but the second one is a dedicated fiddle file, and matches the <code>.bb</code> extension.</li> <li><code>src/a/b/c/d.cljc</code> -&gt; <code>env/dev/fiddle.clj</code>, because all four first <code>[\"src\"]</code> mappings match, but the second one is a dedicated fiddle file, without a matching  file extension, (so the first dedicated fiddle file is picked).</li> <li><code>src/b/c/d.clj</code> -&gt; <code>env/dev/b-fiddles/c/d.clj</code>, because the <code>[\"src\", \"b\"]</code> mapping is longer than the also matching <code>[\"src\"]</code> mappings.</li> </ul>","boost":5},{"location":"fiddle-files/#tips","title":"Tips","text":"<p>Organize your Fiddle files such that they do not get automatically loaded as part of your application. This can lead to strange errors and hard-to-detect bugs. Most often it should only be you manually loading the fiddle file, not clj/clojure or Leiningen or any such system which loads your application.</p> <p>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 happily comply.</p> <p>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.</p> <p>The linter and fiddle files</p> <p>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. You might find yourself wanting to silence some linters for some fiddle files. E.g. like this:</p> <pre><code>(ns main.core\n  {:clj-kondo/config\n   '{:linters {:unresolved-symbol {:level :off}}}})\n</code></pre> <p>See clj-kondo Configuration for more on what options you have for this.</p>","boost":5},{"location":"fiddle-files/#see-also","title":"See Also","text":"<ul> <li>Rich Comments</li> <li>Functional Design in Clojure Episode 014: Fiddle with the REPL</li> <li>The Polylith Development page mentions good practice for where to put your fiddle files (not called fiddle files there, but it is the same concept).</li> </ul>","boost":5},{"location":"finding-commands/","title":"Finding Calva Commands","text":"<p>Calva relies a lot on that VS Code makes it really easy to find commands by opening the command palette: <code>ctrl+shift+p</code> (Windows/Linux), <code>cmd+shift+p</code> (Mac), and then start typing some words (or parts of words) that you think might be in the command.</p> <p>To leverage this, all Calva commands are prefixed with <code>Calva</code>. As an example, say you want to find commands related to evaluating the top level form. Then you can do this:</p> <ol> <li>Open the command palette</li> <li>Type <code>calevtop</code></li> </ol> <p>VS Code will match <code>cal</code> to \u201dCalva\u201d, <code>ev</code> to \u201dEvaluate\u201d, and <code>top</code> to \u201dTop\u201d. It looks like so:</p> <p></p> <p>As you can see on the screenshot, VS Code will also reveal the keyboard shortcut for each command. My advice is to make it a habit to try to remember those shortcuts and use them for a more effective workflow.</p> <p>Now might be a good time to see Calva Top 10 Commands</p>"},{"location":"finding-commands/#all-the-settings-and-commands","title":"All the Settings and Commands","text":"<p>Did you know? There is a complete list of Calva settings and commands in the Contributions tab of the Calva entry in the Extensions pane in VS Code.</p> <p></p>"},{"location":"finding-commands/#toggling-keyboard-shortcuts-onoff","title":"Toggling Keyboard Shortcuts On/Off","text":"<p>The command <code>calva.toggleKeybindingsEnabled</code> can be used to quickly enable and disable (almost) all keyboard shortcuts. This allows you to quickly toggle between Calva keybindings and other keybindings which would otherwise not be available when Calva is enabled. This is particularly useful with the Paredit keyboard shortcuts, whose default shortcuts conflict with the default VS Code shortcuts for textual (non-structural) editing.</p> <p>By default it is not bound to a shortcut so as not to cause confusion by users unwittingly pressing it, but if this is something you'd like to use often, you may want to bind it to a shortcut.</p>"},{"location":"formatting/","title":"Formatting","text":"<p>We have tried to make Calva's formatter so that it just works. It is enabled by default for Clojure files, and with the default configuration it mostly follows Bozhidar Batsov's Clojure Style Guide. Calva uses cljfmt for the formatting.</p> <p>Tab formats the current surrounding form</p> <p>Calva's code formatter sets the default keybinding of its Format Current Form command to <code>tab</code>. Meaning that most often when things look a bit untidy, you can press <code>tab</code> to make things look pretty. Good to know, right? For performance reasons it only formats the current enclosing form, so sometimes you want to move the cursor up/out a form (<code>ctrl+up</code>) first. See The Paredit Guide for more on moving the cursor structurally through your code.</p> <p>With the default settings, Calva's formatting behaves like so:</p> <ul> <li>indents as you type (when entering new lines)</li> <li>formats the current enclosing form when you hit <code>tab</code></li> <li>formats pasted code</li> <li>formats according to community standards</li> <li>formats the current form, aligning map keys and values, when you press <code>ctrl+alt+l</code></li> <li>formats <code>(comment ...)</code> forms special, see rich comments</li> </ul> <p>Infer parens at will</p> <p>Calva has a command that will \u201dheal\u201d the bracket structure if it is correctly indented using Parinfer Infer parens. This command is default bound to <code>ctrl+alt+p i</code>.</p> <p>Also: If you have Format on Save enabled in VS Code, it will be Calva doing the formatting for Clojure files.</p> <p>Calva's formatting is mostly about indenting, but it also (again, defaults):</p> <ul> <li>trims whitespace at the end of the line</li> <li>trims whitespace inside brackets<ul> <li>this also folds trailing brackets (a k a the paren trail) up on the same line</li> </ul> </li> <li>inserts whitespace between forms</li> </ul> <p>Not a fan of some default setting? The formatter is quite configurable.</p>"},{"location":"formatting/#format-current-form-command-variants","title":"Format current form command variants","text":"<p>There are three special commands for formatting the current form:</p>"},{"location":"formatting/#1-format-and-align-current-form","title":"1. Format and Align Current Form","text":"<p>Aligns associative structures and bindings in two columns. See more below.</p>"},{"location":"formatting/#2-format-current-form-and-trim-space-between-forms","title":"2. Format Current Form and trim space between forms","text":"<p>This formats the text, and trims consecutive, non-indent, whitespace on a line to just one space. Something like:</p> <pre><code>(let [a    :b]\n(str \"foo\"     \"bar\" \"baz\"\n\"a\"    a))\n</code></pre> <p>Becomes:</p> <pre><code>(let [a :b]\n  (str \"foo\" \"bar\" \"baz\"\n       \"a\" a))\n</code></pre> <p>Basically, it behaves like if <code>:remove-multiple-non-indenting-spaces? true</code> was added to the <code>cljfmt</code> config. Which, in fact, is what happens. Calva merges that onto your cljfmt config when this command is used.</p>"},{"location":"formatting/#3-replace-current-form-or-selection-with-pretty-printed-form","title":"3. Replace Current Form (or Selection) with Pretty Printed Form","text":"<p>This command will run the code of the Current Form through Calva's pretty printer (the engine named <code>calva</code>, which is using zprint) and replace the current form inline in the editor with the pretty printed results.</p> <p>Unlike with the \u201dreal\u201d Calva Formatter, which never breaks up lines, this one will follow your pretty printing options and break up lines if you have set <code>maxWidth</code> to something that calls for breaking up lines.</p> <p>Applies to the other Current Form</p> <p>Unlike the other Format commands, which applies to the current enclosing form, this one applies to the Current Form, same as with evaluations. That is because this is not really part of the Calva formatter, but rather is a convenience command for tidying up code or data.</p>"},{"location":"formatting/#configuration","title":"Configuration","text":"<p>You can adjust the above mentioned defaults, and the default indents, by configuring the formatting using cljfmt's configuration EDN.</p> <p>This configuration can either be provided via a file or via clojure-lsp. See Providing configuration via clojure-lsp below.</p>"},{"location":"formatting/#providing-configuration-via-a-config-file","title":"Providing configuration via a config file","text":"<p>Calva will look for the configuration in one  of the default cljfmt paths ('.cljfmt.edn', '.cljfmt.clj', 'cljfmt.edn', or 'cljfmt.clj' in the workspace root). If your file is somewhere else use the <code>calva.fmt.configPath</code> to tell Calva where to find it. The path should either be absolute, or relative to the workspace root directory. If your config file is somewhere in the workspace root, Calva will hot reload it when you update it.</p> <p>Wherever the config file is, a suggested path for providing your configuration is to start changing the Calva formatting defaults by pasting the following map into a file and save it.</p> <pre><code>{:remove-surrounding-whitespace? true\n :remove-trailing-whitespace? true\n :remove-consecutive-blank-lines? false\n :insert-missing-whitespace? true\n :remove-multiple-non-indenting-spaces? false}\n</code></pre> <p>If the file is in the workspace, you can quickly test how different settings affect the formatting. Try:</p> <ol> <li>Adding <code>:align-associative? true</code> to the config</li> <li>then save</li> <li>then hit <code>tab</code>, and see what happens.</li> </ol> <code>:align-associative?</code> is experimental <p>This particular setting is experimental and known to cause trouble together with namespaced keywords. Consider using <code>ctrl+alt+l</code> instead of <code>tab</code> as your formatting command, instead of enabling this setting. See below for more info about this. See more below about this.</p> No Leiningen config support <p>The cljfmt docs mention the <code>:cljfmt</code> config key of Leiningen projects. Calva does not yet read the config from there, so if your Leiningen project has such a configuration, you will need to copy it out into a file.</p>"},{"location":"formatting/#providing-configuration-via-clojure-lsp","title":"Providing configuration via clojure-lsp","text":"<p>If you work in a team where some members use clojure-lsp for formatting, you can make Calva format using the same configuration by telling setting <code>calva.fmt.configPath</code> to <code>CLOJURE-LSP</code> (case sensitive). See Clojure LSP Settings) for how to provide the configuration. (It might not be provided from where you think it is, specifically check clojure-lsp's global config in you user home directory.) Use the command Calva Diagnostics: Clojure-lsp Server Info to see what cljfmt configuration is being used (under the <code>cljfmt-raw</code> key).</p> <p>Note that doing this you will not have hot reload of the formatting configuration, and of course you will be depending on that clojure-lsp is running and functioning.</p>"},{"location":"formatting/#indentation-rules","title":"Indentation rules","text":"<p>The <code>cljfmt</code> indents are highly configurable. They, and the rest of the configuration options, are masterly detailed here.</p> <p><code>:extra-indents</code> vs <code>:indents</code></p> <p>Since Calva <code>v2.0.383</code> we are using cljfmt <code>0.11.x</code> which has a breaking configuration change. From the cljfmt README:</p> <p>The <code>:indents</code> key has been split into <code>:indents</code> and :extra-indents. The <code>:indents</code> key replaces all default indents, while the <code>:extra-indents</code> key will append to the default indents.</p> <p>If something prevents you from using a config with <code>:extra-indents</code>, there's an escape hatch to keep using the <code>:indents</code> key as before, by adding <code>:legacy/merge-indents? true</code> to the config map.</p> <p>Calva is an extra good tool for experimenting with these settings. <code>cljfmt</code> doesn't care about keys in the map that it doesn't know about so you can sneak in test code there to quickly see how it will get formatted by certain rules. Try this, for instance:</p> <pre><code>{:remove-surrounding-whitespace? true\n :remove-trailing-whitespace? true\n :remove-consecutive-blank-lines? false\n :insert-missing-whitespace? false\n :indents {#re \"^\\w\" [[:inner 0]]}\n :test-code\n (concat [2]\n         (map #(inc (* % 2))\n              (filter #(aget sieved %)\n                      (range 1 hn))))}\n</code></pre> <p>Save, then hit <code>tab</code>, and the code should get formatted like so:</p> <pre><code> :test-code\n (concat [2]\n    (map #(inc (* % 2))\n      (filter #(aget sieved %)\n        (range 1 hn))))\n</code></pre> <p>That's somewhat similar to Nikita Prokopov's Better Clojure Formatting suggestion. (Please be aware that this setting might not be sufficient to get complete Tonsky Formatting, please share any settings you use to get full compliance.)</p>"},{"location":"formatting/#rich-comments","title":"Rich Comments","text":"<p>To encourage use of <code>(comment ...)</code> forms for development, the default settings give these forms get a special treatment when formatting. Use the <code>calva.fmt.keepCommentTrailParenOnOwnLine</code> setting to control this behaviour. See Rich Comments first.</p>"},{"location":"formatting/#etecetera","title":"Etecetera","text":""},{"location":"formatting/#about-aligning-associative-forms","title":"About aligning associative forms","text":"<p>Calva loooks in the config map for the key <code>:align-associative?</code> and if it is <code>true</code> it will use an old version of cljfmt which is patched with functionality for doing this alignment. Note, though:</p> <ul> <li>The implementation is a bit buggy and can do a bit crazy formatting on certain forms.</li> <li>The older version of cljfmt lacks updates for some new Clojure features and also some bugs fixed since the fork are not applied.</li> </ul> <p>You are hereby warned, and let us also remind you about the Format and Align Current Form command which lets you apply this formatting a bit more surgically, and on demand.</p> <p>This old version of cljfmt is inlined in the Calva repository along with the discontinued <code>rewrite-cljs</code> project. Regard it as frozen code. If you want Calva's formatter to have full support for newer Clojure constructs and the bugs in the alignment code fixed, contribute to cljfmt. See this issue for starting to collect context.</p>"},{"location":"get-started-with-clojure/","title":"Get Started with Clojure","text":"<p>Welcome to a zero-install, interactive, guide to get you started with Clojure using:</p> <ul> <li>Clojure</li> <li>Gitpod (A development environment delivered via the web browser)</li> <li>VS Code (Or Gitpod Code, actually. In your web browser.)</li> <li>Calva (A Clojure extension to VS Code. The thing this site is about.)</li> <li>Calva's Getting Started REPL</li> </ul> I have VS Code and Java <p>Clojure runs on the JVM. How to install it is a big topic. Since you have already done that, you can, if you want, choose to install Calva in your local VS Code and fire up the Getting Started REPL. By all means read this page anyway, you can just skip the Gitpod parts.</p> <p>Also: If you are using Windows your Java might have a bug that prevents things from working. Then you might want to defer fixing that and use the zero-install option first.</p> Is Gitpod Code exactly as VS Code? <p>Almost! But, yeah, there are some difference between regular VS Code and Gitpod's ditto. Most of it doesn't matter, but finding the main menu can be a bit tricky: </p>","boost":10},{"location":"get-started-with-clojure/#what-youll-learn","title":"What you'll learn","text":"<ul> <li>The basics of the Clojure language (at least the start of the basics)</li> <li>The basics of the ClojureScript language (we won't be using ClojureScript, but it is same language \ud83d\ude00)</li> <li>The basics of Calva (It's a bit as a side effect. You need it to learn Clojure this way, and by learning Clojure this way, Calva knowledge trickles in.)</li> <li>What is meant by, and some ways to perform, Interactive Programming (aka REPL Driven Development)</li> <li>Where to find Clojurians, i.e. folks who use Clojure and care about it (you will thus find help, the friendliest help you have ever seen a community provide)</li> </ul> I am not convinced I should spend time on learning Clojure <p>Fair enough. We can recommend watching any or all of these videos to get excited about Clojure and the rather unique mood of development it offers:</p> <p></p> <ul> <li>Solving Problems the Clojure Way - with Rafal Dittwald (using JavaScript, so no new syntax to grasp to get the message)</li> <li>Developer Ergonomics with VS Code, Clojure, and ClojureScript - with Peter Str\u00f6mberg</li> <li>Clojure in VS Code Workflow using FizzBuzz - with Peter Str\u00f6mberg</li> </ul>","boost":10},{"location":"get-started-with-clojure/#what-you-wont-learn","title":"What you won't learn","text":"<ul> <li>How to install Clojure for your operating system of choice</li> <li>About various old and new build and dependency tools</li> <li>How to create projects and do real stuff</li> </ul> Why won't I learn about this? <p>All in due time. \ud83d\ude04 It can be a bit confusing with all the things you find out about installing Clojure and creating projects when searching for information about it. We want you to relax about all that and just enjoy learning a bit about this fantastic programming language and the wonderful mode of development it offers.</p> <p>There is a lot of info about this out there already. And since you will learn where to find Clojurians, you will also find guidance. But we suggest do these things later. First, let's focus on having fun with Interactive Programming!</p>","boost":10},{"location":"get-started-with-clojure/#what-you-need","title":"What you need","text":"<ul> <li>Curiosity about Clojure</li> <li>A web browser</li> </ul> The browser ate my keyboard shortcuts! <p>There is always a competition for which system gets to catch keyboard shortcuts first. This worsens a bit when an application like VS Code runs in the web browser. Remember this if some shortcut/command doesn't work.</p> <p>On some machines, with some web browsers, some shortcuts are caught by the web browser and instead re-opening a closed tab or whatever. These have been observed:</p> <ul> <li>Undo (undoing something web browser related)</li> <li>Select the line (focusing the browser URL input)</li> <li>Open the command palette (opening a private browsing window. Looking at you Firefox.)</li> <li>Escape key shortcuts (are you using VIM bindings in your browser?)</li> </ul> <p>Sometimes the workaround is to redefine the shortcuts in VS Code, sometimes making your web browser stop catching the shortcut.</p> I am new to VS Code <p>You might want to have a look at this Getting Started with VS Code video. (You can of course ignore the parts about installing for now.) Also, have this overview of the VS Code interface handy.</p>","boost":10},{"location":"get-started-with-clojure/#how-it-works","title":"How it works","text":"<ol> <li>You will open an instance of VS Code in a development environment running in the browser. The environment will have Java, Clojure tools, and Calva installed.<ul> <li> Gitpod Sign-in    You will be asked to sign in to Gitpod, if you aren't already. You need to use the \u201dSign in with GitHub\u201d option. </li> </ul> </li> <li>Instructions will be automatically displayed (very brief such, because it is mainly about firing up the Getting Started REPL)</li> <li>The guides are a mix of prose (in Clojure line comments), Clojure code, and exercises. What's extra poetic is that you will use Calva and Clojure to learn Calva and Clojure.</li> </ol> <p>Use a desktop/laptop computer. Even if it actually works on the phone, it is far from convenient.</p> <p>It sometimes takes a while (several minutes) for the environment to initialize. Take some deep breaths and be patient. \ud83d\ude0e</p>","boost":10},{"location":"get-started-with-clojure/#lets-go","title":"Let's go!","text":"<p>Ready? Awesome. Click this button to start the guide in a new browser tab.</p> https://gitpod.io/#https://github.com/PEZ/get-started-with-clojure Stuck? Something not working? Or just unclear? <p>Please don't hesitate to reach out for help, should you get stuck. See below for where to find Clojurians. As for the Calva team, we are almost always (true story) to be found at the Clojurians Slack, especially in the <code>#calva</code> Channel. We are <code>@pez</code> and <code>@bringe</code> there.</p> <p>Happy Interactive Programming! \u2764\ufe0f</p>","boost":10},{"location":"get-started-with-clojure/#and-where-do-i-find-those-clojurians","title":"And where do I find those Clojurians?","text":"<p>We Clojurians inhabit a lot of community platforms. I'll list some of the more popular ones here in some order of popularity.</p> <ul> <li>The Clojurians Slack - by far the largest and most active Clojure community, the <code>#beginners</code> channel is spectacularly fantastic</li> <li>ClojureVerse - a web forum. Lots of Clojurians, lots of Clojure knowledge collected, easy to search, easy to join</li> <li>/r/Clojure - Reddit when Reddit is at its best, lots of Clojurians here</li> <li>Clojurians on Zulip - An other web forum using the Zulip platform</li> <li>On Discord there are two active servers: Clojurians and Discord</li> </ul> <p>You can also ask questions, and find answers, about Clojure at ask.clojure.org</p>","boost":10},{"location":"get-started-with-clojure/#learn-and-practice-clojure-using-rich-4clojure","title":"Learn and Practice Clojure using Rich 4Clojure","text":"<p>If you like the style of interactive learning that this guide provides, you should definitely check Rich 4Clojure out. It also can be used in the zero-installed way.</p> <p>You can regard it as a companion to this guide. It is aimed at practicing Clojure, starting at the elementary levels, bringing you to advanced stuff.</p> Can I use Rich 4Clojure instead of this guide? <p>We suggest you start by opening up this guide and do the Calva part of the excerises. Then use the <code>welcome_to_clojure.clj</code> guide in combination with Rich 4Clojure..</p>","boost":10},{"location":"get-started-with-clojure/#run-the-clojure-exercism-track-in-your-browser","title":"Run the Clojure Exercism Track in your browser","text":"<p>In a similar manner to the Get Started with Clojure project, you can run the Clojure Exercism Track in your browser without installing anything and with full Interactive Programming enabled using this Template project.</p>","boost":10},{"location":"get-started-with-clojure/#clojuredocs","title":"ClojureDocs","text":"<p>Clojurians draw tremendous value from ClojureDocs. At ClojureDocs the concise documentation for Clojure core functions, etcetera, are amended with examples and advice from fellow Clojurians. Crowdsourcing at its very best! It is a big part of the reason why you won't find an abundance of Clojure information at StackOverflow.</p>","boost":10},{"location":"get-started-with-clojure/#other-learning-resources","title":"Other learning resources","text":"<ul> <li>CalvaTV - Calva's YouTube channel often focuses on beginning with Clojure and ClojureScript. Subscribe, please!</li> <li>Clojure Beginner Resources - a much more comprehensive list than this one</li> <li>clojure.org Getting Started - the source of truth, includes installing and stuff</li> <li>The Exercism Clojure track - Learn solving carefully crafted Clojure exercises, get mentor feedback if you like.</li> <li>Clojure for the Brave and True - helping you from beginner to pretty advanced stuff, very popular among Clojurians</li> <li>on the code again - often features Clojure concepts, with snappy, well communicated, and entertaining videos</li> <li>Clojure Koans with VS Code/Calva instructions</li> </ul>","boost":10},{"location":"get-started-with-clojure/#help-us-help-beginners","title":"Help us help beginners","text":"<p>Give us feedback. Spread the word. Please consider:</p> <ul> <li>Join the <code>#improve-getting-started</code> channel at the Clojurian Slack</li> <li>Linking to this page from your blog</li> <li>Tweeting about this guide</li> <li>Contributing to the Calva project</li> <li>Wearing Calva and RFC T-shirts</li> <li>Starring these repositories:<ul> <li>Get Started with Clojure - (the repository powering this guide)</li> <li>Rich 4Clojure</li> <li>Clojure Exercism Track Template</li> <li>Calva</li> <li>Dram - Where this guide (the Getting Started REPL) is authored</li> </ul> </li> <li>What do beginners struggle with? - a ClojureVerse thread, where you can tell us about what you have found hard in picking up Clojure. It's what spawned the creation of this guide.</li> </ul> <p>Please also consider other ways to contribute.</p> <p>Thanks! \ud83d\ude4f</p>","boost":10},{"location":"getting-started/","title":"Getting Started","text":"<p>Depending on wether you want to just start a Clojure REPL or you have a project you want to work with, getting started looks similar but a bit different. Regardless, you need to first:</p>","boost":10},{"location":"getting-started/#install-vs-code-and-calva","title":"Install VS Code and Calva","text":"<ol> <li>Downloading VS Code and run the installer.<ul> <li>Also get aquainted to the basics of VS Code, if you aren't already. Here's an excellent intro: Getting Started with VS Code</li> </ul> </li> <li>Install Calva. The easiest way to do that is to start VS Code and search for <code>Calva</code> in the VS Code Extension pane, then click Install.</li> </ol>","boost":10},{"location":"getting-started/#say-hello-to-calva","title":"Say hello to Calva","text":"<p>If you have a Clojure or ClojureScript project, you will be interested in how to get Calva connected to the REPL of your project. But before you run over there, you might want to familiarize yourself with Calva a bit, which you can do without a project.</p> <p>The demo tells you about the command (and some about the Clojure Beginner's material that it makes available).</p> I am completely new to Clojure <p>The \u201dGetting Started\u201d REPL below introduces you to Clojure as well as to Calva. You might however, not want to start with installing the right version of Java and such to run the guide. If so you should definitely check the Get Started with Clojure guide on this site.</p> <p>Three clicks will have you running Calva in your browser with the REPL ready to serve.</p> I don't have Java installed <p>If you like, you can defer installing anything at all and still get started with Calva (not kidding).</p> <p>See Get Started with Clojure.</p>","boost":10},{"location":"getting-started/#theres-a-getting-started-repl","title":"There's a \u201dGetting Started\u201d REPL","text":"<p>If you are new to Calva, a good place to start is using the command Fire up the \u201dGetting Started\u201d REPL. (You can open the command palette using the VS Code top menu by going to <code>View -&gt; Command Palette...</code> or by running the associated keyboard shortcut for your OS.) Demo:</p> <p></p> <p>It will open up a three files in a temporary directory, and start and connect a REPL. The files are:</p> <ul> <li><code>hello_repl.clj</code> \u2013 The basics of how to evaluate code in Calva</li> <li><code>hello_paredit.clj</code> - A super brief intro to Calva structural editing</li> <li><code>welcome_to_clojure.clj</code> - The very basics of the Clojure language</li> </ul> <p></p> <p>The only prerequisite here is that you have Java installed. No pre-installed clojure tools required. (You will want to install these tools later, of course.)</p> <p>Note</p> <p>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 <code>PATH</code> of its environment for this feature to work. See this issue on the Calva repo for more on this, including any progress.</p>","boost":10},{"location":"getting-started/#there-are-standalone-clojurescript-quick-start-repls","title":"There are standalone \u201dClojureScript Quick Start\u201d REPLs","text":"<p>Without creating a project structure or installing anything but Calva, you can start standalone ClojureScript REPLs both in a browser and for node:</p> <ul> <li>Fire up the ClojureScript Quick Start Browser REPL<ul> <li>Opens the files <code>core.cljs</code> and <code>index.html</code> and starts the ClojureScript app, opening it in the browser.</li> </ul> </li> <li>Fire up the ClojureScript Quick Start Node REPL<ul> <li>Opens a file, <code>core.cljs</code>, and starts a nodejs REPL where it loads the file.</li> </ul> </li> </ul> <p>The browser REPL app looks like so:</p> <p></p>","boost":10},{"location":"getting-started/#you-have-a-project","title":"You have a Project?","text":"<p>If you are new to Calva, please consider the above option first. Then when it will be time to get Calva connected to the REPL of your project.</p>","boost":10},{"location":"getting-started/#clojure-resources","title":"Clojure Resources","text":"<p>If you are new to Clojure or ClojureScript altogether, please check out the guide material on the respective official sites:</p> <ul> <li>Getting Started with Clojure</li> <li>ClojureScript Quick Start</li> </ul> <p>There are also many great books on Clojure. Clojure for the Brave and True can be read for free online. It is a great resource for beginners.</p>","boost":10},{"location":"getting-started/#there-is-also-standalone-repl","title":"There is also Standalone REPL","text":"<p>When you are more familiar with Calva, and want a standalone REPL, there is a separate command: Start a standalone REPL (not in project). It will open up a <code>user.clj</code> in a temporary directory, containing only an <code>(ns user)</code> form, and start and connect the REPL.</p>","boost":10},{"location":"getting-started/#dram-where-the-guides-live","title":"Dram - Where the Guides Live","text":"<p>The command for starting the Getting Started REPL will download the files from this repository. It is very much work in progress, and there is not even a finished Clojure Beginner's Guide there yet. When you run the command again, and from then on, you will get the option to download new files or keep using your existing. Downloading new ones will not overwrite your existing ones, because they will be downloaded to a new temp directory. You can find the directory easily using VS Codes context menu command for revealing a file in the Explorer/Finder.</p>","boost":10},{"location":"getting-started/#one-last-thing","title":"One Last Thing","text":"<p>Happy coding! \u2665\ufe0f</p>","boost":10},{"location":"hiccup/","title":"Converting HTML to Hiccup","text":"<p>Calva can help you convert HTML to Hiccup.</p>","boost":7},{"location":"hiccup/#features","title":"Features","text":"","boost":7},{"location":"hiccup/#three-commands","title":"Three commands","text":"<ul> <li>Convert HTML to Hiccup, will convert the selected text, or the entire file, to Hiccup and open up an Untitled Clojure file with the result.</li> <li>Copy HTML as Hiccup, will convert the selected text, or the entire file, to Hiccup and copy it to the clipboard.</li> <li>Paste HTML as Hiccup, will convert the contents of the clipboard to Hiccup and paste it. (The clipboard will then be restored to the original content.)</li> </ul> <p>The resulting data structure is formatted with zprint using it's <code>:style :hiccup</code> configuration.</p>","boost":7},{"location":"hiccup/#conversion-capabilities","title":"Conversion capabilities","text":"<p>In addition to, optionally, being able to convert style attributes to maps and kebab-case attributes, the conversion: </p> <ul> <li>Opts for producing compact Hiccup:<ul> <li>The <code>id</code> attribute and classes are made part of the tag, CSS selector style<ul> <li><code>&lt;foo id=\"bar\"&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo#bar]</code></li> <li><code>&lt;foo class=\"c1 c2\"&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo.c1.c2]</code></li> <li><code>&lt;foo id=\"bar\" class=\"c1 c2\"&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo#bar.c1.c2]</code></li> </ul> </li> <li>Though, if the id or any class is not valid as part of a keyword, they remain in the props/attributes map)<ul> <li><code>&lt;foo id='foo-[id]'&gt;&lt;/foo&gt;</code> =&gt;  <code>[:foo {:id \"foo-[id]\"}]</code></li> <li><code>&lt;foo class='clz1 clz[2]'&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo.clz1 {:class [\"clz[2]\"]}]</code></li> </ul> </li> <li>Whitespace is trimmed<ul> <li><code>&lt;foo&gt; \\nbar\\n &lt;/foo&gt;</code> =&gt; <code>[:foo \"bar\"]</code></li> <li><code>&lt;foo&gt; \\n &lt;/foo&gt;</code> =&gt; <code>[:foo]</code></li> </ul> </li> </ul> </li> <li>Handles boolean attributes<ul> <li><code>&lt;foo disabled&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo {:disabled true}]</code></li> <li><code>&lt;foo disabled=disabled&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo {:disabled \"disabled\"}]</code></li> </ul> </li> <li>Special case for camelCasing attributes <code>viewBox</code> and <code>baseProfile</code> (SVG is picky about it)<ul> <li><code>&lt;foo bAsePROFilE=bar viewbox=\"0 0 1 1\"&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo {:baseProfile \"bar\" :viewBox \"0 0 1 1\"}]</code></li> </ul> </li> <li>Comments are retained<ul> <li><code>&lt;foo&gt;&lt;!-- ... --&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo (comment \"...\")]</code></li> </ul> </li> <li>You can have several top level tags<ul> <li><code>&lt;foo&gt;&lt;/foo&gt;&lt;foo&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo]\\n[:foo]</code></li> </ul> </li> </ul>","boost":7},{"location":"hiccup/#it-is-somewhat-configurable","title":"It is somewhat configurable","text":"<p>The Hiccup converstion can be tweaked with two options using the setting <code>calva.html2HiccupOptions</code>, which is a map/object:</p> <ul> <li><code>mapify-style</code>: boolean, default <code>false</code>. When <code>true</code> any <code>style</code> attribute will be converted to a map (Reagent supports this)</li> <li><code>kebab-attrs?</code>: boolean, default <code>false</code>. When <code>true</code> attribute names will be converted from camelCase, or snake_case/SNAKE_CASE to kebab-case. (Reagent wants most attribute names like this.)</li> <li><code>add-classes-to-tag-keyword?</code>: boolean, default <code>true</code>. When <code>true</code> all class names will be added CSS-style to the tag keyword (<code>[:tag.clz1.clz2]</code>), as opposed to being kept in the class attribute. Keeping the class names in the attribute may be preferable with elements having a lot of class names, such as when using Tailwind CSS.</li> </ul>","boost":7},{"location":"hiccup/#copy-as-menus-copy-html-as-hiccup","title":"Copy as menus: Copy HTML as Hiccup","text":"<p>The Copy HTML as Hiccup command is available from VS Code's Edit menu, as well as the editor context menu, in both cases under the Copy as sub menu.</p> <p></p>","boost":7},{"location":"hiccup/#the-commands-take-arguments","title":"The commands take arguments","text":"<p>This options map can also be provided as an argument to the commands, so you can bind keyboard shortcuts to a particular configuration for the conversion. </p> <p>The command <code>calva.convertHtml2Hiccup</code> takes a map as an argument:</p> <ul> <li><code>toUntitled</code>: <code>boolean</code>, default <code>false</code>. When <code>false</code> the result of the conversion will be returned to the caller (This is intended for Joyride, or some other VS Code extension). When <code>true</code> it will behave like the default command does, placing the result of the conversion in an Untitled Clojure file.</li> <li><code>options</code>: Same as those <code>calva.html2HiccupOptions</code> mentioned above.</li> </ul> <p>The <code>calva.pasteHtmlAsHiccup</code> and <code>calva.copyHtmlAsHiccup</code> commands takes only a <code>calva.html2HiccupOptions</code> map.</p>","boost":7},{"location":"hiccup/#example-keyboard-shortcuts","title":"Example keyboard shortcuts","text":"<p>The commands have no default keyboard shortcuts, you use the Command Palette to execute them, or you bind your own shortcuts. Here are some examples:</p> <pre><code>    // calva.convertHtml2Hiccup\n    {\n        // With args, `\"toUntitled\": true` is necessary for keyboard shortcuts\n        // without it, the command just returns the result to the caller\n        \"key\": \"ctrl+alt+c ctrl+h\",\n        \"command\": \"calva.convertHtml2Hiccup\",\n        \"args\": {\"toUntitled\": true, \"options\": {\"mapify-style?\": false}}\n    },\n    {\n        // Only for completeness, providing the HTML is only useful from e.g. Joyride \n        \"key\": \"ctrl+alt+c shift+h\",\n        \"command\": \"calva.convertHtml2Hiccup\",\n        \"args\": {\"html\": \"&lt;foo style='a: b' bar='baz'&gt;gaz&lt;foo&gt;\", \"toUntitled\": true}\n    },\n    {\n        // Without args, the command uses the `calva.html2HiccupOptions` configuration\n        // And writes the results to an Untitled document\n        \"key\": \"ctrl+alt+c h\",\n        \"command\": \"calva.convertHtml2Hiccup\",\n    },\n\n    // calva.pasteHtmlAsHiccup\n    {\n        // Override the `calva.html2HiccupOptions` configuration\n        \"key\": \"ctrl+alt+h ctrl+v\",\n        \"command\": \"calva.pasteHtmlAsHiccup\",\n        \"args\": {\"mapify-style?\": true, \"kebab-attrs?\": true}\n    },\n    {\n        // Without args, the command uses the `calva.html2HiccupOptions` configuration\n        \"key\": \"ctrl+alt+h v\",\n        \"command\": \"calva.pasteHtmlAsHiccup\"\n    },\n\n    // calva.copyHtmlAsHiccup\n    {\n        // Override the `calva.html2HiccupOptions` configuration\n        \"key\": \"ctrl+alt+h ctrl+c\",\n        \"command\": \"calva.copyHtmlAsHiccup\",\n        \"args\": {\"mapify-style?\": false, \"kebab-attrs?\": true}\n    },\n    {\n        // Without args, the command uses the `calva.html2HiccupOptions` configuration\n        \"key\": \"ctrl+alt+h c\",\n        \"command\": \"calva.copyHtmlAsHiccup\"\n    },\n</code></pre> <p>The default/args-less bindings are placed last because reasons.</p>","boost":7},{"location":"hiccup/#using-from-joyride-or-some-other-vs-code-extension","title":"Using from Joyride (or some other VS Code extension)","text":"<p>As with any VS Code command using these from Joyride is a matter of calling <code>executeCommand</code>.</p>","boost":7},{"location":"hiccup/#calvapastehtmlashiccup-and-calvapastehtmlashiccup","title":"<code>calva.pasteHtmlAsHiccup</code> and <code>calva.pasteHtmlAsHiccup</code>","text":"<pre><code>(-&gt; (vscode/commands.executeCommand \"calva.pasteHtmlAsHiccup\"\n                                    #js {:mapify-style? true})\n    (.then ...))\n\n(-&gt; (vscode/commands.executeCommand \"calva.copyHtmlAsHiccup\"\n                                    #js {:mapify-style? true})\n    (.then ...))\n</code></pre>","boost":7},{"location":"hiccup/#calvaconverthtml2hiccup","title":"<code>calva.convertHtml2Hiccup</code>","text":"<p>Without options the command behaves just like selecting the command from the command palette. If there is a selection it will be converted, otherwise the whole file. The result will be opened in a new Untitled document.</p> <pre><code>(-&gt; (vscode/commands.executeCommand \"calva.convertHtml2Hiccup\")\n    (.then ...))\n</code></pre> <p>Called with arguments it will by default return an object with a <code>.-result</code> member which is a string with the Hiccup.</p> <pre><code>(-&gt; (vscode/commands.executeCommand \"calva.convertHtml2Hiccup\" \n                                    #js {:html \"&lt;foo class='clz1 clz2&gt;bar&lt;/foo&gt;\"})\n    (.then #(println (.-result %))))\n\n(-&gt; (vscode/commands.executeCommand \"calva.convertHtml2Hiccup\" \n                                    #js {:options #js {:mapify-style? false}})\n    (.then #(println (.-result %))))\n</code></pre> <p>To make it put the text in a new Untitled document instead, provide the argument option <code>:toUntitled true</code></p> <pre><code>(-&gt; (vscode/commands.executeCommand \"calva.convertHtml2Hiccup\" \n                                    #js {:toUntitled true\n                                         :html \"&lt;foo class='clz1 clz2&gt;bar&lt;/foo&gt;\"\n                                         :options #js {:mapify-style? true\n                                                       :kebab-attrs? true}})\n    (.then ...))\n</code></pre>","boost":7},{"location":"jack-in-guide/","title":"Learn about Calva Jack-in","text":"<p>The Calva Jack-In Academy, by @pez</p> <p>Like with CIDER Jack-in, Calva's let-me-help-you-start-your-project-and-connect feature might seem a bit mysterious. It really is helpful, but also really isn't mysterious. Here are a few things about it that is good to know about.</p> <p>Note</p> <p>If you came here to find out how to configure the versions of the dependencies that Calva Jack-in injects, see Customizing Calva - Jack-in Dependency Versions.</p>","boost":6},{"location":"jack-in-guide/#what-it-solves","title":"What it Solves","text":"<p>At first it might seem that something like <code>lein repl</code> in a terminal and then connecting Calva is enough. It sometimes might be, but only if you are in luck. To provide many of its IDE features, Calva relies on nREPL middleware, mainly cider-nrepl and, for ClojureScript, piggieback. When starting your Clojure(Script) app and its REPL, it needs to be started with these dependencies satisfied. There are mainly three ways this can be achieved.</p> <ol> <li>In the project definition (files like <code>project.clj</code>, <code>deps.edn</code>, <code>shadow-cljs.edn</code>, and combination of these).</li> <li>In your user profile (files like <code>~/.lein/profiles.clj</code> and <code>~/.clojure/deps.edn</code>).</li> <li>On the command line.</li> </ol> <p>Because 1 and 2 are hard to keep in sync with the various editor environments people in your project might be using, Calva Jack-In is about 3.</p> <p>Ideally, you will be able to rid your project files completely of editor dependencies when people working on the project can rely on the Jack-In features of their Clojure editor.</p>","boost":6},{"location":"jack-in-guide/#a-controlled-shell-command","title":"A Controlled Shell Command","text":"<p>At its core Calva Jack-In is just a glorified, REPL-starting, command-line. No, it is more than that, but anyway. The command line can look like so for a Leiningen project using legacy Figwheel for its ClojureScript assistance:</p> <pre><code>lein update-in :dependencies conj '[nrepl\"0.6.0\"]' -- update-in :dependencies conj '[cider/piggieback\"0.4.1\"]' -- update-in :dependencies conj '[figwheel-sidecar\"0.5.18\"]' -- update-in :plugins conj '[cider/cider-nrepl\"0.22.4\"]' -- update-in '[:repl-options :nrepl-middleware]' conj '[\"cider.nrepl/cider-middleware\"]' -- update-in '[:repl-options :nrepl-middleware]' conj '[\"cider.piggieback/wrap-cljs-repl\"]' -- with-profile +dev repl :headless\n</code></pre> <p>Even if a bit long, it might look simple enough. But actually it has taken quite some effort to make Calva craft it. Shell quoting can be really tricky. Look at how <code>'[nrepl\"0.6.0\"]'</code> doesn't have a space between <code>nrepl</code> and the version. That was the only way I could find that was cross platform enough to make all supported shells parse the command line. (The trick relies on that the string is read by the super reliable Clojure Reader, which does not need that space to tokenize it.)</p> <p>It is awesome that Clojure is used on so many platforms, but for a tool smith this also means more work. (I think Windows and its shell hell ate up about 95% of the many hours spent on getting the quoting good enough.)</p> <p>The command-line crafted is then used to start a shell command that Calva controls, but we are getting ahead of ourselves...</p>","boost":6},{"location":"jack-in-guide/#project-types-builds-aliases-profiles-etcetera","title":"Project Types, Builds, Aliases, Profiles, etcetera","text":"<p>In order to cook the right command for your project, Calva looks for project files, reads them, and figures out what possible project types and ClojureScript tools could be involved. Then Calva presents you with a menu with the options it has found. You need to know enough about your project to answer this question. It looks like this in a shadow-cljs project that uses a <code>deps.edn</code> file for setting up its classpath.</p> <p></p> <p>(I know enough about this particular project to know that I should choose the <code>shadow-cljs</code> project type.)</p> <p>But Calva isn't ready to cook the command-line just yet. Depending on the project type, and contents of your project files, more info is needed. E.g. in the case of shadow-cljs projects, Calva needs to know what builds to start.</p> <p></p> <p>Here you can select any combination of builds defined in the project, and Calva will cook a command line that starts them.</p> <p>You might get more prompts from Calva before it issues the command, but for this example project, Calva goes ahead, cooks the command line, and issues it. On my Mac, it looks like so:</p> <pre><code>npx shadow-cljs -d cider/piggieback:0.4.1 -d cider/cider-nrepl:0.22.4 watch :app\n</code></pre> <p>(Much shorter than the one with lein-figwheel, right? It is because shadow-cljs is aware of CIDER dependencies, so it doesn't need as many dependencies specified as some other project types do.)</p>","boost":6},{"location":"jack-in-guide/#connecting","title":"Connecting","text":"<p>When the command is issued Calva needs to wait until the REPL Server is started, before connecting to it and possibly continuing with starting a ClojureScript REPL and connecting to that as well. It also needs to know which port to connect to.</p> <p>Because reasons, Calva can't yet read the <code>stdout</code> of the shell command it has issued, so to know when the REPL server is started, and on which port, Calva monitors the filesystem for the <code>.nrepl-port</code> file. (This file is not always named like that. shadow-cljs, for instance, creates the file <code>.shadow-cljs/nrepl.port</code>.)</p> <p>When the port file is created, Calva picks up the port number from it and connects to the nREPL server. At this point you have a Clojure REPL backing your Calva session, providing all sorts of nice IDE help for you.</p>","boost":6},{"location":"jack-in-guide/#starting-your-clojure-app","title":"Starting Your Clojure App","text":"<p>Once you have the Clojure REPL connected you can start your Clojure app/server. See Custom Connect Sequences for how to let Calva do this for you automatically. See the same article for ways to automate more of the Jack-In process. It can be brought down to a single Jack-In command/action, even for a full stack Clojure and ClojureScript application.</p>","boost":6},{"location":"jack-in-guide/#clojurescript","title":"ClojureScript","text":"<p>For ClojureScript, things are not done yet, though, far from it. It turns out that cooking the command line was the easy part.</p> <p>In order for Calva to provide REPL power for ClojureScript projects, several things need to happen:</p> <ol> <li>A Clojure nREPL connection needs to be established. We've covered that above. Calva makes an nREPL session clone to use for the ClojureScript REPL and then:</li> <li>Your ClojureScript app needs to be compiled.</li> <li>Your ClojureScript app needs to be started.</li> <li>The Clojure nREPL session needs to be promoted to a ClojureScript nREPL session. (This is what piggieback helps with.)</li> </ol>","boost":6},{"location":"jack-in-guide/#compiling-the-app-and-watchers","title":"Compiling the App and Watchers","text":"<p>Depending on ClojureScript project type, Calva uses different methods to start the compilation and the watcher:</p> <ul> <li>Figwheel: The compilation and the watchers are started in the Clojure REPL session. (This is both for Figwheel Main and for lein-figwheel.)</li> <li>shadow-cljs: The compilation and the watchers are started with the Jack-In command line.</li> </ul> <p>This results in a bit of difference in the user interaction. Mainly that for shadow-cljs, the user needs to check the Jack-In Terminal tab to follow what's going on.</p>","boost":6},{"location":"jack-in-guide/#starting-the-app","title":"Starting the App","text":"<p>Number 3 above, the app needs to be started, might seem obvious, but it actually trips many people up. Because of this, Calva goes to quite some lengths to provide assistance. Many projects are configured not to spawn a browser session automatically, requesting the app once it has been compiled, so we can't rely on that.</p> <p>What Calva does instead is to monitor the output of the commands it uses for starting the compilation, looking for information that the app is ready to be requested/started. It then tells the user this, providing a URL, in case it is a browser app. (There are also settings that tell Calva to open the URL automatically for you, regardless what the project settings are.)</p>","boost":6},{"location":"jack-in-guide/#connecting_1","title":"Connecting","text":"<p>Meanwhile, Calva is monitoring the output and when it sees that the app is started, it continues to hook up the REPL connection to the editor.</p> <p>This whole connection sequence is quite configurable, using Custom Connect Sequences. In fact, Calva's built in ClojureScript sequences (Figwheel Main, lein-figwheel, shadow-cljs, and ClojureScript built-ins for both Browser and Node) are all built using those same settings mechanisms.</p>","boost":6},{"location":"jack-in-guide/#shadow-cljs-is-less-managed-by-calva","title":"shadow-cljs is Less Managed by Calva","text":"<p>NB: The managed way in which Calva creates and connects the ClojureScript REPL breaks apart a bit for shadow-cljs, which works a bit differently and also outputs most of the information Calva is looking for on the <code>stdout</code> of the REPL start command (where Calva can't see it, remember?). We'll figure out a better way to support shadow-cljs, but for now, the user needs to do more of this figuring out than is needed with Figwheel projects.</p>","boost":6},{"location":"jack-in-guide/#hack-away","title":"Hack Away","text":"<p>So, there are things going on when you start Jack-In, and even more things for ClojureScript projects, but Calva tries to keep it together, so as a user it is a matter of paying attention and responding to a few prompts/menus with pre-populated options (prompts which can be configured away, even).</p>","boost":6},{"location":"jack-in-guide/#switch-clojurescript-builds","title":"Switch ClojureScript Builds","text":"<p>Once the REPL is connected you might want to change which ClojureScript build you have Calva connected to. For this Calva has the Select CLJS Build Connection command. Please note that you can only switch between builds that you have started.</p>","boost":6},{"location":"jack-in-guide/#play-with-starting-the-cljs-repl-yourself","title":"Play With Starting the <code>cljs-repl</code> Yourself","text":"<p>To get a good grip on what is going on when creating and connecting the ClojureScript REPL, I can recommend making a custom connect sequence which leaves the REPL unpromoted (e.g. give it <code>nil</code> as <code>connectCode</code>), and then evaluate the <code>cljs-repl</code> start commands yourself. So for instance, promoting it to a ClojureScript Node.js REPL looks something like so:</p> <pre><code>user=&gt; (require 'cljs.repl.node)\nuser=&gt; (cider.piggieback/cljs-repl (cljs.repl.node/repl-env))\nClojureScript 1.10.844\nTo quit, type: :cljs/quit\nnil\ncljs.user=&gt; |\n</code></pre> <p>It is the piggieback middleware there telling you that you can unpromote the REPL by \u201devaluating\u201d <code>:cljs/quit</code>.</p>","boost":6},{"location":"jack-in-guide/#about-full-stack-applications","title":"About Full Stack Applications","text":"<p>Because Calva uses the Clojure REPL connection to spawn the ClojureScript REPL, and because Calva only handles one Clojure REPL per VS Code window, some projects need special handling by the user.</p> <p>If your full stack project is using shadow-cljs for the frontend, like this Fulcro template project does, maybe you first try to Jack-In to your backend Clojure REPL, and then to your shadow-cljs frontend. This works if you do it in separate VS Code windows, but if you do it in the same window, the second Jack-In will kill the backend session! See also connect shadow-cljs in fullstack projects.</p> <p>See Workspace Layouts for tips about how to open the same project folder in two separate VS Code windows.</p> <p>Please also consider to play around with starting the REPL and ClojureScript wiring entirely from the terminal, see this example project for some instructions on that. You can also use that project together with the <code>nil</code> for <code>connectCode</code> sequence mentioned above.</p>","boost":6},{"location":"jack-in-guide/#please-grab-your-calva-jack-in-certificate","title":"Please Grab your Calva Jack-In Certificate","text":"<p>There, you now know all there is to know about Calva Jack-In.</p> <p>Just kidding, there are a few more details to it, some of which might find their way into this article at a later time.</p> <p>To really get to know it all, you will need to spend some time with the Calva Jack-In code. Head over to the Calva Development Wiki to learn how to hack on Calva.</p>","boost":6},{"location":"joyride/","title":"Using Calva With Joyride","text":"<p>Joyride is a VS Code extension for user space scripting of VS Code itself. You find the extension here. The scripting language for Joyride is the best you language imaginable: Clojure. And, as is proper for a Clojure implementation, it has a REPL, even an nREPL server.</p> <p>This means you can connect Calva to Joyride and interactively develop your VS Code scripts.</p> <p>This video shows Joyride in action, using Calva as the nREPL client.</p>"},{"location":"joyride/#how-to-connect","title":"How to connect","text":"<p>Once you have the Joyride extension installed you can start its REPL and connect Calva to it (a.k.a Jack-in).</p> <p>Start the Joyride REPL and Connect</p> <p>This 1 minute video shows the following steps:</p> <ol> <li>Installing the Joyride Extension</li> <li>Isssuing the command Calva: Start a REPL in your Project and (a.k.a Jack-in)</li> <li>Selecting <code>joyride</code> project type</li> <li>Isssuing the command Calva: Load/Evaluate Current File and its Requires/Dependencies</li> <li>Evaluating some non-vscode code</li> <li>Evaluating code exercising something from the VS Code API</li> </ol> <p>(Right-click the video and choose Full Screeen if it is too tiny embedded.)</p>"},{"location":"joyride/#how-to-get-started-with-joyride","title":"How to Get Started with Joyride","text":"<p>The Joyride README has some Quick Start pointers for you. Please feel invited to the <code>#joyride</code> channel on the Clojurians Slack and chat with us and other Joyride users.</p> <p>Come on, Join the Joyride! \u2764\ufe0f</p>"},{"location":"krell/","title":"Using Calva With Krell","text":"<p>Krell is \u00e0 la carte ClojureScript tooling for React Native.</p> <p>Even if Calva does not yet have built-in support, all is not lost. You can add support yourself by way of a Custom REPL Connect Sequence. Here's how;</p>"},{"location":"krell/#starting-the-krell-clojurescript-repl","title":"Starting the Krell ClojureScript REPL","text":"<p>Add this REPL Connect Sequence to your workspace <code>settings.json</code>:</p> <pre><code>    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"deps.edn + Krell\",\n            \"projectType\": \"deps.edn\",\n            \"cljsType\": {\n                \"connectCode\": \"(require '[clojure.edn :as edn] \\n    '[clojure.java.io :as io]\\n    '[cider.piggieback] \\n    '[krell.api :as krell]\\n    '[krell.repl])\\n\\n(def config (edn/read-string (slurp (io/file \\\"build.edn\\\"))))\\n(apply cider.piggieback/cljs-repl (krell.repl/repl-env) (mapcat identity config))\",\n                \"dependsOn\": \"User provided\"\n            }\n        }\n    ]\n</code></pre> <p>Then issue the command Start a Project REPL and Connect (aka Jack-In). It start the project and connect to the Krell REPL once the app is running on a device (wether real or virtual/emulated).</p>"},{"location":"krell/#additional-vs-code-tips","title":"Additional VS Code Tips","text":"<p>For a smooth workflow you can also:</p> <ul> <li>Install the React Native Tools extension</li> <li>Install the Debugger for Chrome extension, and add this Launch Configuration <pre><code>        {\n            \"type\": \"chrome\",\n            \"request\": \"launch\",\n            \"name\": \"Launch Debugger\",\n            \"url\": \"http://localhost:8081/debugger-ui/\",\n            \"webRoot\": \"${workspaceFolder}\"\n        }\n</code></pre></li> </ul> <p>Together with the connect sequence this will make for a start of a Krell session like this:</p> <ol> <li>Open the project root in VS Code</li> <li>Issue the Jack-in command</li> <li>Issue the React Native; Run Android on Emulator (or Run iOS on Simulator) command. (Disable Fast Refresh from the *React Native dev menu, if it is enabled.)</li> <li>Issue the React Native: Run Element Inspector command     (You might need to install the React Native inspector globally):     ```sh     yarn global add react-devtools     ````</li> <li>Launch Debugger (<code>F5</code>)</li> <li>Hack away, with hot reload and interactive REPL</li> </ol> <p>Once the debugger (a Chrome session) is running, you probably will want to enable Custom Formatters in order for clojure structures to be logged conveniently.</p>"},{"location":"linting/","title":"Linting","text":"<p>Calva does no linting, yet with Calva you get excellent linting. That is because Calva uses clojure-lsp, which provides linting powered by clj-kondo.</p> <p>clj-kondo comes with great default rules, and the configuration can be customized. One of your options for the configuration file is to  placed a <code>config.edn</code> file in <code>.clj-kondo/</code> at the root of your project. This folder may or may not already exist. It is safe to create it manually if it doesn't.</p> <p>The configuration will be merged with the default set of rules, you can only specify the rules you want to override. The full list of available options can be found on clj-kondo's github</p> <p>clojure-lsp is customizable, see Clojure LSP Settings for your options. It is safe to manually create the <code>.lsp</code> folder if it doesn't exist.</p> <p>You might want to read about how to configure clj-kondo. These two sections might be of extra interest:</p> <ul> <li>Unrecognized macros</li> <li>Lint a custom macro like a built-in macro</li> </ul> <p>If you see a linting squiggle under the first character of the file with an error you don't quite understand, it is probably something wrong with your clj-kondo configuration.</p> <p>Files are linted as they're being edited. If you want to lint the whole project, use the clj-kondo cli command. See https://github.com/borkdude/clj-kondo for more info on that. Windows users might like to know that they too can get a clj-kondo cli command now, via <code>npm install -g clj-kondo</code>. It'll be a bit slower to start than the native build, but for sure it's better than not having a clj-kondo command! See https://github.com/borkdude/clj-kondo/blob/master/doc/install.md#npm-linux-macos-windows for more on this.</p>"},{"location":"linting/#resolve-macro-as","title":"Resolve Macro As","text":"<p>When your cursor is on a macro form in the editor, you may notice a code action (click the light bulb that appears) called Resolve Macro As. Running this code action will ask you what macro you'd like to resolve the current macro as, and then what clj-kondo config file you want the macro to be saved to. This code action is also available as a command.</p>"},{"location":"live-share/","title":"Using Calva with Live Share","text":"<p>Live Share is a Microsoft provided VS Code extension.  It allows you to share the workspace that you have open in your computer with somebody else. Everybody is then working on the same source code files, namely those on your computer. You can edit files at the same time, everyone has their own caret. You can follow each other (i.e. when someone switches to a different file, you will as well). This is great for remote pair programming, for example.</p> <p>An extra nice thing is that each participant is using their own VSCode configuration, including fonts, colors, keyboard shortcuts, etc.</p> <p>Disable Calva Spritz to get rid of Notebooks interference</p> <p>The headline below Calva Supports Live Share is true. However, due to a bug in LiveShare, guest participants always get their Clojure files opened in the Calva Clojure Notebooks editor. To workaround this issue Calva uses a \u201dside-car\u201d extension named Calva Spritz for the Notebooks associations of Clojure files. You can disable that extension when participating in LiveShare sessions.</p>"},{"location":"live-share/#calva-supports-live-share","title":"Calva Supports Live Share","text":"<p>When using Calva, you can use Live Share as well. Editing works exactly the same as for any other programming language. What makes Calva a bit special, is the REPL. When using Live Share, Calva allows the host to share the REPL with guests as well. If you use any of the supported configuration, this will be pretty much automatic.</p> <p>You need to enable the LiveShare support</p> <p>Due to an issue in the LiveShare API, for some users, this feature stops Calva from connecting the REPL. Therefore the support is disabled by default. The setting is <code>calva.useLiveShare</code>.</p> <p>This is what a typical scenario looks like:</p> <ol> <li>The host jacks-in.</li> <li>The host shares its workspace using Live Share. Calva will detect that    the workspace is being shared, so it will offer to share the REPL port that    was opened when jacking in. The host clicks \"Allow\" to start sharing the    port. (Note: steps 1 and two can also be done in the reverse order.)    </li> <li>The host sends the Live Share URL to the guest(s).</li> <li>The guest joins the Live Share session using the URL it received.</li> <li>The guest connects to the host's REPL using the command \"Connect to a    running REPL server in the project\". If needed, the guest chooses the same    build configuration as the host.</li> </ol> <p>Voila! Both the guest and the host can now use the REPL that is running on the host. Things like documentation lookup now also work on the guest's machine.</p>"},{"location":"live-share/#control-visibility-of-calva-folder","title":"Control Visibility of <code>.calva</code> Folder","text":"<p>Calva depends on the <code>output.calva-repl</code> file to be available. If you have the <code>.calva</code> folder listed in your <code>.gitignore</code>, this also causes the folder to be hidden from guests in Live Share by default. In order to make the folder visible, you can put a file called <code>.vsls.json</code> in your project. In its simplest form, the contents can be this:</p> <pre><code>{\n  \"$schema\": \"http://json.schemastore.org/vsls\",\n  \"hideFiles\": [\n    \"!.calva\"\n  ]\n}\n</code></pre> <p>Now the <code>.calva</code> folder is shared as well. But also any other file and folder that you may have in your <code>.gitignore</code>. If you want to have more fine-grained control, please refer to the section Controlling file access and visibility of the Live Share documentation.</p>"},{"location":"live-share/#some-things-to-keep-in-mind","title":"Some Things To Keep In Mind","text":"<ul> <li>As a guest, you're connected to a REPL running on the host's machine. With   power comes responsibility; be nice, and be careful!</li> <li>There is only one <code>output.calva-repl</code> file, which all participants are   sharing. It may work better to evaluate things in the source code editors   instead of from the REPL window. Otherwise you will end up in a situation   where one person is typing something in the <code>output.calva-repl</code> window, and   somebody else is evaluating something (hence sending the output there) at the   same time. That gets confusing quickly.</li> <li>When you're working on a CLJS-based web development project, things may   get extra confusing. By default, Live Share will share any HTTP ports on the   host automatically, and also offer to open the URL on the guest. (You can   disable using the setting \"Liveshare: Open Shared Servers\".) As a guest, you   do not want to open that browser window normally. Think about it: where is   the REPL running? Yes: in the browser! But Calva connects to the REPL running   in the browser on the host's machine, so if you open a browser as a guest, you   will also get a REPL there, but you won't be connected to it in Calva.</li> <li>Currently Live Share does not allow Calva to know whether the workspace is   shared read-only or read-write. If you share read-only, and you don't want the   guests to have access to your REPL, don't click \"Allow\" when VSCode asks you   to share the REPL port.</li> </ul>"},{"location":"live-share/#calva-spritz","title":"Calva Spritz","text":"<p>Together with Calva there is an extension called Calva Spritz installed. All it does is to provide the association of Clojure file types to Clojure Notebooks. We do it this way because of the LiveShare issues mentioned above. So that you can disable the Notebook association when participating as a guest in LiveShare sessions. The issue is tracked here:</p> <ul> <li>Calva issue: LiveShare participants incorrectly opening every Clojure file as if via \"Open with Notebook\"</li> <li>LiveShare issue: Guest opens Clojure file as a notebook (incorrectly)</li> </ul> <p>Calva Spritz can be disabled and enabled at will, and it will take immediate effect, without any reload of VS Code needed.</p>"},{"location":"luminus/","title":"How to Use Calva with Luminus","text":"<p>Luminus is a powerful and versatile Leiningen template for creating web development projects. It comes with built in configuration which makes it easy to use Calva as your Clojure(Script) editor.</p>"},{"location":"luminus/#server-shadow-cljs","title":"Server + shadow-cljs","text":"<p>Basically this is the same wokflow as with Server only. Behind the scenes there is more happening, though. Such as the ClojureScript app being built and the CLJS REPL connected once the web app is running.</p> <ol> <li>If you haven't created the project yet, create a new shadow-cljs Luminus project. E.g.:     <pre><code>$ lein new luminus my-luminus-shadow +reagent +re-frame +shadow-cljs\n</code></pre></li> <li>Install npm dependencies     <pre><code>$ npm i\n</code></pre>     (Or <code>yarn</code> if you prefer.)</li> <li>This creates the folder <code>my-luminus-shadow</code>. Open it in VS Code:     <pre><code>$ code my-luminus-shadow\n</code></pre></li> <li>Use the Calva command Start a Project REPL and Connect (aka Jack-in): <code>ctrl+alt+c ctrl+alt+j</code></li> <li>Select to start my-luminus-shadow Server + Client, and wait for the Terminal Calva Jack-in output to say <code>[:app] Build completed.</code></li> <li>Open 127.0.0.1:3000 in your web browser and start hacking.</li> </ol> <p>Note</p> <p>Currently Calva has troubles following the app-start with shadow-cljs, so Calva will report <code>Jack-in done.</code> in the output window before shadow-cljs is actually done building the app. If you open the app page at that stage, you will see a message to \u201cPlease run <code>lein shadow watch app</code>\u201d. Rest assured that this is already underway. Follow the Jack-in process in the Terminal tab in VS Code for the message that the app is built, then reload the app page in the web browser.</p>"},{"location":"luminus/#server-only","title":"Server Only","text":"<p>The workflow here is really just: Jack-in and start hacking. However, the first time it will involve these steps:</p> <ol> <li>If you haven't created the project yet, create a new server only Luminus project. For a all-defaults setup it is like so:     <pre><code>$ lein new luminus my-luminus-server\n</code></pre></li> <li>This creates the folder <code>my-luminus-server</code>. Open it in VS Code:     <pre><code>$ code my-luminus-server\n</code></pre></li> <li>Use the Calva command Start a Project REPL and Connect (aka Jack-in): <code>ctrl+alt+c ctrl+alt+j</code><ul> <li>Select to start my-luminus-shadow Server and wait until you see <code>Jack-in done.</code> in the output window.</li> </ul> </li> <li>Open 127.0.0.1:3000 in your web browser and start hacking.</li> </ol>"},{"location":"luminus/#server-figwheel","title":"Server + Figwheel","text":"<p>This is Legacy Figwheel (lein-figwheel), so the recommendation is to use the shadow-cljs setup instead. As with the server only, the workflow here is really just: Jack-in and start hacking. The first time it involves these steps:</p> <ol> <li>If you haven't created the project yet, create a new server only Luminus project. E.g.:     <pre><code>$ lein new luminus my-fw +reagent\n</code></pre></li> <li>This creates the folder <code>my-fw</code>. Open it in VS Code:     <pre><code>$ code my-fw\n</code></pre></li> <li>Use the Calva command Start a Project REPL and Connect (aka Jack-in): <code>ctrl+alt+c ctrl+alt+j</code>, select Server + Client - my-fw in the Project type picker menu, and wait for the web app to pop open in your web browser.</li> <li>Start hacking.</li> </ol> <p>If you prefer to open the web app yourself, open <code>.vscode/settings.json</code> and change <code>\"shouldOpenUrl\"</code> to <code>false</code> in the pre-configured Calva connect sequence. Calva will then print the URL 127.0.0.1:3000 in the output, so that you can click it open.</p>"},{"location":"luminus/#etcetera","title":"Etcetera","text":"<p>You will have three Calva Custom Command Snippets configured. Invoke them by issuing the Run Custom REPL Command, <code>ctrl+alt+c .</code> (that's a dot). These commands control the Luminus server:</p> <ol> <li><code>Start &lt;project&gt; Server</code></li> <li><code>Stop &lt;project&gt; Server</code></li> <li><code>Restart &lt;project&gt; Server</code></li> </ol> <p>When used, Calva will open its REPL window and execute the command, if it is not already opened. You can close this window if you prefer to use the REPL directly from the Clojure files.</p> <p>Calva also opens the REPL window, and starts the Luminus server, as part of the Jack-in process.</p>"},{"location":"merch/","title":"Calva Merch","text":"<p>In this video, there is a question about where you can buy the Calva T-shirt:</p> <p>You couldn't, then. But now you can! On Amazon.</p> <p>Zero profit</p> <p>To keep the admin of this shop to a minimum the merch is sold at production prize (or as close to production prize as the respective store allows). There is no royalty going to anyone in the Calva team when you buy one of these t-shirts. You will represent, which is certainly a way to support the project. You are of course encouraged to support us via sponsoring as well:</p> <ul> <li>Sponsor Peter Str\u00f6mberg</li> <li>Sponsor Brandon Ringe</li> </ul> <p>Calva Merch is available on Zazzle and on Amazon</p>","boost":10},{"location":"merch/#zazzle","title":"Zazzle","text":"","boost":10},{"location":"merch/#calva-symbol-sticker","title":"Calva Symbol Sticker","text":"Calva Symbol Sticker by BetterThanTomorrow","boost":10},{"location":"merch/#joyride-symbol-sticker","title":"Joyride Symbol Sticker","text":"Joyride Symbol Sticker by BetterThanTomorrow","boost":10},{"location":"merch/#amazon-merch","title":"Amazon Merch","text":"","boost":10},{"location":"merch/#the-designs","title":"The designs","text":"<p>There are four design, all featuring the Calva symbol (the Calva glass), which are all available for a Standard T-shirt, in men's, women's and kid's cut, and in some different colors. In the <code>.com</code> store there are also Premium T-shirts**.</p>","boost":10},{"location":"merch/#symbol-logo","title":"Symbol + Logo","text":"<p>Available at:</p> <ul> <li>https://www.amazon.com/dp/B09BCVH9SC (Premium T-shirt)</li> <li>https://www.amazon.com/dp/B097TB5QFW</li> <li>https://www.amazon.de/dp/B098GWQC6M</li> <li>https://www.amazon.co.uk/dp/B098KM9XMF</li> <li>https://www.amazon.fr/dp/B0994TYXTN</li> <li>https://www.amazon.it/dp/B099KLJJV1</li> <li>https://www.amazon.es/dp/B099NXR71Y</li> <li>https://www.amazon.co.jp/dp/B097YZVMC4</li> </ul>","boost":10},{"location":"merch/#symbol-logo-we-do-it-with-rich-comments","title":"Symbol + Logo + We do it with Rich Comments","text":"<p>The Calva symbol and Logo front, Rich Comments back.</p> <p></p> <p>Available at:</p> <ul> <li>https://www.amazon.com/dp/B09C4PBH5N (Premium T-shirt)</li> <li>https://www.amazon.com/dp/B09BFMRCHL</li> <li>https://www.amazon.de/dp/B09C3VYZH8</li> <li>https://www.amazon.co.uk/dp/B09BLD2BVJ</li> <li>https://www.amazon.fr/dp/B09C3X1H7K</li> <li>https://www.amazon.it/dp/B09C3WV2JQ</li> <li>https://www.amazon.es/dp/B09C4P1GD1</li> <li>https://www.amazon.co.jp/dp/B09C4P45MR</li> </ul>","boost":10},{"location":"merch/#symbol-only","title":"Symbol Only","text":"<p>Available at:</p> <ul> <li>https://www.amazon.com/dp/B09B83481D (Premium T-shirt)</li> <li>https://www.amazon.com/dp/B097TB5QFW</li> <li>https://www.amazon.de/dp/B098434W9M</li> <li>https://www.amazon.co.uk/dp/B098KNGPBB</li> <li>https://www.amazon.fr/dp/B099RZGNN7</li> <li>https://www.amazon.it/dp/B099WYH94Z</li> <li>https://www.amazon.es/dp/B09B2TFCSR</li> <li>https://www.amazon.co.jp/dp/B09B4XN3HY</li> </ul>","boost":10},{"location":"merch/#symbol-we-do-it-with-rich-comments","title":"Symbol + We do it with Rich Comments","text":"<p>The Calva symbol front, Rich Comments Back.</p> <p></p> <p>Available at:</p> <ul> <li>https://www.amazon.com/dp/B098M34FKJ (Premium T-shirt)</li> <li>https://www.amazon.com/dp/B0993VCG7P</li> <li>https://www.amazon.de/dp/B098MF14PV</li> <li>https://www.amazon.co.uk/dp/B098P1MV44</li> <li>https://www.amazon.fr/dp/B098TPQFCJ</li> <li>https://www.amazon.it/dp/B098YP33ZL</li> <li>https://www.amazon.es/dp/B098RDPK55</li> <li>https://www.amazon.co.jp/dp/B0992MQYG6</li> </ul> <p>Note</p> <p>What's available on this or that Amazon site will vary a bit and it is a bit slow to add a particular design to a particular market. Eventually I hope to have both designs up on these markets: <code>.com</code>, <code>.co.uk</code>, <code>.de</code>, <code>.fr</code>, <code>.it</code>, <code>.es</code>, and <code>.co.jp</code></p>","boost":10},{"location":"namespace-form-auto-creation/","title":"Namespace Form Auto-creation","text":"<p>When you create a new clojure file, a file with <code>.clj</code>, <code>.cljc</code> or <code>.cljs</code> extension, an appropriate namespace form will be added to the file. This feature is provided by clojure-lsp.</p> <p></p>"},{"location":"nbb/","title":"Using Calva with nbb","text":"<p>Since nbb can be started such that it is an nREPL server, Calva can connect to it and a lot of the features will work.</p> <p>Calva can also start nbb and connect its REPL for you, using the Jack-in command. This will start an nbb nREPL server on a random port and connect Calva to it. Check out this video where they use Calva and nbb to create a CLI tool as an executable npm module:</p> <p>In that video they ask for a JavaScript to ClojureScript converter. And there is one: https://mauricioszabo.gitlab.io/js2cljs/</p> <p>Though if you are using Calva, this converter is easier to use directly via the command Calva: Convert JavaScript to ClojureScript:</p> <p>Errors jacking in to nbb on Windows?</p> <p>On some machines it seems necessary to first run <code>npx nbb</code> from the <code>CMD</code> prompt to make jack-in work. Or try first install it <code>npm i -g nbb</code>. (You probabl want nbb installed globally anyway.)</p> <p>Don't expect complete support</p> <p>nbb's nREPL server is completely new and and WIP. It will be a bit limited compared to a full cider-nrepl enhanced \"regular\" Clojure nREPL server. Things like function signatures, and more do not work.</p> <p>It's a bit hacky</p> <p>The nbb nREPL server is the first ClojureScript nREPL server around and throws Calva's assumption that an nREPL server is always started in a Clojure process out the window. The nbb Jack-in/connect option \u201dpretends\u201d it is connecting to a Clojure nREPL and then the code fro promoting the nREPL session to a ClojureScript one is just dummy code.</p> <p>This means that if you open a Clojure (<code>.clj</code>) file while connected to an nbb nREPL server, it will still be a ClojureScript session serving even though Calva will indicate that it is a Clojure one. Bare with us until we can fix this properly in Calva.</p>","boost":4},{"location":"notebooks/","title":"Clojure Notebooks","text":"<p>WIP: Notebook support is very basic and experimental</p> <ul> <li>You might experience loss of file contents when saving a Clojure Notebook. Have backups of any files you open as notebooks.</li> <li>Tooling around autocomplete, go to def, linting and such does not work at all yet.</li> <li>There is no Markdown support.</li> <li>Etcetera. As if this was not enough, notebooks can also interfere with LiveShare support.</li> </ul> <p>Please help test the feature. We're looking forward to your feedback!</p> <p>You can open any Clojure file as a notebook by right clicking the file -&gt; <code>Open with...</code> -&gt; <code>Clojure Notebook</code>.</p> <p>Running cells sends them to the REPL and pretty prints the results. If the return is a string that starts with <code>&lt;html</code> it will be displayed in an html webview.</p> <p>Forms inside <code>(comment)</code> blocks get shown as their own cells. When adding code blocks in between those cells they get saved with the same indentation as the first form.</p>","boost":1},{"location":"notebooks/#calva-spritz","title":"Calva Spritz","text":"<p>Together with Calva there is an extension called Calva Spritz installed. It only provides the association of Clojure file types to Clojure Notebooks. This is due to the LiveShare issues mentioned above. So that you can disable the Notebook association when participating as a guest in LiveShare sessions. The issue is tracked here:</p> <ul> <li>Calva issue: LiveShare participants incorrectly opening every Clojure file as if via \"Open with Notebook\"</li> <li>LiveShare issue: Guest opens Clojure file as a notebook (incorrectly)</li> </ul>","boost":1},{"location":"nrepl_and_cider-nrepl/","title":"nREPL and cider-nrepl","text":"<p>nREPL and cider-nrepl middleware enable Calva to support full Interactive Programming.</p>","boost":2},{"location":"nrepl_and_cider-nrepl/#about-nrepl","title":"About nREPL","text":"<p>The REPL is a Clojurists quintessential tool, it\u2019s what we use to do Interactive Development, the hallmark of the LISP style of development.</p> <p>In Interactive Development (more commonly but somewhat imprecisely referred to as REPL-driven development), the programmer\u2019s editor has a direct connection with the running application process. This allows evaluating pieces of code in the context of a running program, directly from where the code is written (and so not in some separate \u201cREPL place\u201d), inspecting and manipulating the innards of the process. This is helped along by the dynamic nature of Clojure in which any var can be redefined at any point, allowing for quick incremental and iterative experimentation and development.</p> <p>This is why it\u2019s essential to the Clojure development experience to have proper editor support, a plugin which bridges the gap between where the code is written and where the code is run. So we have CIDER for Emacs, Calva for VS Code, Cursive for IntelliJ, Conjure or Iced for Vim, and so forth. Often these will also leverage the same (or a parallel) connection into the process for other editor affordances, like navigation and completion.</p> <p>But for these editor plugins to connect to the Clojure process something needs to be listening on the other side, accepting connections, allowing the initiation of a program-to-program dialogue. The most common way to achieve this is by leveraging the nREPL protocol, an asynchronous message-based network protocol for driving interactive development. The application process is started with an embedded nREPL server, so that the editor can connect as an nREPL client.</p> <p>From: Lambda Island</p>","boost":2},{"location":"nrepl_and_cider-nrepl/#about-the-nrepl-server-and-middleware","title":"About the nREPL Server and Middleware","text":"<p>nREPL is an extensible protocol, the reference server implementation understands certain core operation types like \"eval\". More operations can be supported, or existing operations can be modified or augmented, through nREPL middleware. For example: the Piggieback middleware can intercept \"eval\" messages, and forward them to a ClojureScript environment, rather than evaluating them in the Clojure process itself.</p> <p>Which middleware to use will mostly depend on the editor you are using. You\u2019ll typically find that the Clojure-specific functionality for a given editor is partly implemented as a typical editor extension, for instance CIDER written in Emacs LISP, or Calva written in Typescript, and partly as nREPL middleware, providing the functionality the editor extension relies on. For instance, both CIDER and Calva rely on functionality provided by cider-nrepl.</p> <p>Also from: Lambda Island</p>","boost":2},{"location":"nrepl_and_cider-nrepl/#viewing-the-communication-between-calva-and-nrepl","title":"Viewing the Communication Between Calva and nREPL","text":"<p>You can view the messages sent between Calva and nREPL by running the command <code>Toggle nREPL Logging Enabled</code>. Enabling nREPL message logging triggers the creation of a VS Code output channel called <code>nREPL Messages</code> where the messages will be logged. Messages sent to nREPL from Calva will have <code>-&gt; sent</code> above them, and messages sent from nREPL to Calva will have <code>&lt;- received</code> above them. Disabling nREPL message logging causes the <code>nREPL Messages</code> channel to be removed and messages will no longer be logged.</p> <p>Each message is logged as JSON. If you find a need for the messages to be logged as EDN (for example, to transform and analyze them with Clojure) please open a GitHub issue for this change. A PR would be welcome too!</p> <p>The example below shows two messages logged when the cursor hovers over <code>println</code> in a Clojure file while a REPL is connected.</p> <pre><code>-&gt; sent\n{\n  op: 'info',\n  ns: 'test-lein.core',\n  symbol: 'println',\n  id: '7',\n  session: '1a080b66-b1b6-4b8c-8206-c4af2cc02747'\n}\n\n&lt;- received\n{\n  added: '1.0',\n  'arglists-str': '[&amp; more]',\n  column: 1,\n  doc: 'Same as print followed by (newline)',\n  file: 'jar:file:/Users/brandon/.m2/repository/org/clojure/clojure/1.10.1/clojure-1.10.1.jar!/clojure/core.clj',\n  id: '7',\n  line: 3733,\n  name: 'println',\n  ns: 'clojure.core',\n  resource: 'clojure/core.clj',\n  'see-also': [\n    'clojure.core/prn',\n    'clojure.core/print',\n    'clojure.core/println-str',\n    'clojure.pprint/pprint'\n  ],\n  session: '1a080b66-b1b6-4b8c-8206-c4af2cc02747',\n  static: 'true',\n  status: [ 'done' ]\n}\n</code></pre>","boost":2},{"location":"output/","title":"Output Destinations","text":"<p>Calva categorizes output into three types:</p> <ul> <li>evaluation results: Clojure data returned from an evaluation.</li> <li>evaluation output: stdout/stderr from an evaluation</li> <li>other output: Other messages, logs, etc</li> </ul> <p>With the setting <code>calva.outputDestinations</code>, you can configure where each category of output should go to:</p> <ul> <li>the REPL Window</li> <li>the Calva Says Output Channel</li> <li>the Calva Output (pseudo) Terminal</li> </ul> <p>The reason there are several options for this is partly legacy and partly because VS Code restricts the placement of different views in different ways. We hope you will find a combination of output destinations that suits you.</p>"},{"location":"output/#commands-for-showing-output-destinations","title":"Commands for showing output destinations","text":"<p>These are the commands and their default keyboard shortcuts for revealing output destinations</p> <ul> <li>Calva: Show/Open the result output destination - <code>ctrl+alt+o o</code></li> <li>Calva: Show/Open the Calva says Output Channel - <code>ctrl+alt+o c</code></li> <li>Calva: Show/Open the Calva Output Terminal - <code>ctrl+alt+o t</code></li> <li>Calva: Show/Open REPL Window - <code>ctrl+alt+o r</code></li> </ul>"},{"location":"output/#about-stdout-in-the-repl-window","title":"About stdout in the REPL Window","text":"<p>Since Calva v2.0.423 the REPL Window prints <code>stdout</code> prepended with <code>;</code> to make it into line comments. This is because stdout output easily breaks the Clojure structure of the REPL Window, making it misbehave in various ways. We made this change because as maintainers of Calva we have seen all too often how this hits users, and it is also taking too much of our Calva time to try mitigate the problem, which is fundamentally not fixable.</p> <p>There are now other output destinations that do not have this limitation.</p> <p>All that said. If you want to keep using the REPL Window for stdout output, and need the old behavior, you can enable the setting: <code>calva.legacyPrintBareReplWindowOutput</code>. Please note that at some point after we have created a dedicated Output Window, the REPL Window will be retired as a destination for output.</p>"},{"location":"output/#repl-process-output-stdout-and-stderr","title":"REPL process output (stdout and stderr)","text":"<p>When Calva is connected to the REPL, the Output window will by default print not only results of evaluations, but also:</p> <ol> <li>Things printed to <code>stdout</code> and <code>stderr</code> in the main thread of the evaluations</li> <li>Things printed to <code>stdout</code> and <code>stderr</code> from child threads of the evaluations</li> <li>Anything printed to <code>stdout</code> and <code>stderr</code> by the REPL process</li> </ol> <p>You can control the default via the <code>calva.redirectServerOutputToRepl</code> setting. It defaults to <code>true</code>. Setting it to <code>false</code> before connecting the REPL will result in that 2. and 3. will not get printed in the Output window. It will then instead be printed wherever the REPL process is printing its messages, usually the terminal from where it was started (the Jack-in terminal if Calva started the REPL).</p>"},{"location":"paredit/","title":"Paredit \u2013 a Visual Guide","text":"<p>Structural editing and navigation for Clojure.</p>","boost":7},{"location":"paredit/#what-is-paredit","title":"What is Paredit?","text":"<p>Calva Paredit helps you navigate, select and edit Clojure code in a structural way. LISP isn't line or character oriented, it is based around S-expressions, a.k.a forms. We strongly recommend that you take advantage of the structural nature of Clojure, and have therefore put a lot of work into making Calva Paredit extra awesome.</p> <p>If you are new to Paredit, consider starting with learning the Slurp Forward (pull in the next form into this form) and Barf Forward (push the last form out of this form). It will take you quite far.</p>","boost":7},{"location":"paredit/#strict-mode","title":"Strict Mode","text":"<p>To protect the integrity of your code, Strict mode is enabled by default.</p> Strict mode keybinding Action Description <code>backspace</code> Delete Backward Deletes one character backwards, unless it will unbalance a form. Otherwise moves past the character instead of deleting it. If the list is empty, it will remove both open and close brackets.  <code>delete</code> Delete Forward Deletes one character forwards, unless it will unbalance a form. Otherwise moves past the character instead of deleting it. If the list is empty, it is removed.  <code>alt+backspace</code> Force Delete Backward Deletes one character backwards, even if it will unbalance a form.  <code>alt+delete</code> Force Delete Forward Deletes one character forwards, even if it will unbalance a form.  <p>Disable at your own peril. Strict mode can be toggled on/off using the Toggle Paredit Mode command, and there is a status bar indicator telling you:</p> Indicator Paredit Mode <code>[\u03bb]</code> Strict <code>(\u03bb)</code> Cave Man (strict mode off) <code>\u03bb</code> No default key bindings <p>Toggle between Strict and Cave Man using: <code>ctrl+alt+p ctrl+alt+m</code></p>","boost":7},{"location":"paredit/#a-keybinding-for-protecting-the-structure-from-semi-colon","title":"A keybinding for protecting the structure from semi-colon","text":"<p>Semi-colons (<code>;</code>) in Clojure are non-structural because they comment out the rest of the line regardless of brackets. In a way they can delete brackets. There is a somewhat secret command in Paredit that can be used to insert <code>;</code> in a safe way:</p> <p><code>paredit.insertSemiColon</code></p> <p>Bind it to the <code>;</code> key with a <code>when</code> clause that activates it together with the other Strict mode commands:</p> <pre><code>{\n    \"command\": \"paredit.insertSemiColon\",\n    \"key\": \";\",\n    \"when\": \"calva:keybindingsEnabled &amp;&amp; editorLangId == clojure &amp;&amp; editorTextFocus &amp;&amp; paredit:keyMap == strict &amp;&amp; !editorReadOnly &amp;&amp; !editorHasMultipleSelections &amp;&amp; !calva:cursorInComment\"\n },\n</code></pre>","boost":7},{"location":"paredit/#commands","title":"Commands","text":"<p>The Paredit commands are sorted into Navigation, Selection, and Edit. As mentioned, Slurp and Barf are power commands, which go into the editing category. Learning to navigate structurally, using shortcuts, also saves time and adds precision to your editing. It has the double effect that you at the same time learn how to select structurally, because that is the same, just adding the shift key.</p> <p>To make the command descriptions a bit clearer, each entry is animated. When you try to figure out what is going on in the GIFs, focus on where the cursor is at the start of the animation loop.</p>","boost":7},{"location":"paredit/#strings-are-not-lists-but-anyway","title":"Strings are not Lists, but Anyway...","text":"<p>In Calva Paredit, strings are treated in much the same way as lists are. Here's an example showing Slurp and Barf, Forward/Backward List, and Expand Selection.</p> <p></p>","boost":7},{"location":"paredit/#navigating","title":"Navigating","text":"<p>(Modify these with <code>shift</code> to select rather than move, see below.)</p> Default keybinding Action Description <code>ctrl+right</code> (win/linux)<code>alt+right</code> (mac) Forward Sexp Moves the cursor forward, to the end of the current form. If at the end, moves to the end of the next form. Will not move out of lists. <code>ctrl+left</code> (win/linux)<code>alt+left</code> (mac) Backward Sexp Moves the cursor backward, to the start of the current form. If at the start, moves to the start of the previous form. Will not move out of lists. <code>ctrl+down</code> Forward Down Sexp Moves the cursor into the following list. <code>ctrl+alt+up</code> Backward Down Sexp Moves the cursor into the preceding list. <code>ctrl+alt+down</code> Forward Up Sexp Moves the cursor forwards, out of the current list. <code>ctrl+up</code> Backward Up Sexp Moves the cursor backwards, out of the current list. Unbound Forward Sexp Or Up Moves the cursor forward, to the end of the current form. If at the end, moves to the end of the next form. Moves out of the lists if at the end of it.  Unbound Backward Sexp Or Up Moves the cursor backward, to the start of the current form. If at the start, moves to the start of the previous form. Moves out of the list if at the start of it.  <code>ctrl+end</code> Forward to List End/Close Moves the cursor forwards, staying within the current list. <code>ctrl+home</code> Backward to List Start/Open Moves the cursor backwards, staying within the current list.","boost":7},{"location":"paredit/#selecting","title":"Selecting","text":"<p>Most of these commands are selecting \u201dversions\u201d of the navigation commands above. Repeated use will grow the current selection step by step.</p> Default keybinding Action Description <code>shift+alt+right</code> (win/linux)<code>ctrl+w</code> (mac) Expand Selection Starts from the cursor and selects the current form. Then will keep expanding to enclosing forms. <code>shift+alt+left</code> (win/linux)<code>ctrl+shift+w</code> (mac) Shrink Selection Contracts back from an expanded selection performed by any Paredit selection command. (In the animation the selection is first grown using a combination of Expand Selection and some lateral selection commands, then shrunk all the way back down to no selection.) <code>ctrl+alt+w space</code> Select Top Level Form Top level in a structural sense. Typically where your<code>(def ...)</code>/<code>(defn ...)</code> type forms. Please note that<code>(comment ...)</code> forms create a new top level.  <code>shift+ctrl+right</code> (win/linux)<code>shift+alt+right</code> (mac) Select Forward Sexp <code>ctrl+shift+k</code> Select Right Select forward to the end of the current form or the first newline. See Kill right below. (The animation also shows Shrink Selection). <code>shift+ctrl+left</code> (win/linux)<code>shift+alt+left</code>(mac) Select Backward Sexp <code>ctrl+shift+down</code> Select Forward Down Sexp (You probably do not need to select like this, but you can!) <code>ctrl+shift+alt+up</code> Select Backward Down Sexp (You probably do not need to select like this, but you can!) <code>ctrl+shift+alt+down</code> Select Forward Up Sexp (You probably do not need to select like this, but you can!) <code>ctrl+shift+up</code> Select Backward Up Sexp (You probably do not need to select like this, but you can!) Unbound Select Forward Sexp Or Up (You probably do not need to select like this, but you can!) Unbound Select Backward Sexp Or Up (You probably do not need to select like this, but you can!) <code>ctrl+shift+end</code> Select Forward to List End/Close <code>ctrl+shift+home</code> Select Backward to List Start/Open","boost":7},{"location":"paredit/#editing","title":"Editing","text":"Default keybinding Action Description <code>ctrl+alt+right</code> (mac/win)<code>ctrl+alt+.</code> (linux) Slurp Forward Moves the closing bracket forward, away from the cursor, past the following form, if any.  <code>ctrl+alt+left</code> (mac/win)<code>ctrl+alt+,</code> (linux) Barf Forward Moves the closing bracket backward, towards the cursor, past the preceding form.  <code>ctrl+alt+shift+left</code> Slurp Backward Moves the opening bracket backward, away from the cursor, past the preceding form, if any.  <code>ctrl+alt+shift+right</code> Barf Backward Moves the opening bracket forward, towards the cursor, past the following form.  <code>ctrl+alt+s</code> Splice Sexp Remove enclosing brackets.  <code>ctrl+shift+s</code> Split Sexp Splits a string, or a list, into two strings, or lists of the same type as the current.  <code>ctrl+shift+j</code> Join Sexps/Forms Joins two strings, or two lists of the same type, into one form (string/list).  <code>ctrl+alt+p ctrl+alt+r</code> Raise Sexp Replaces the enclosing list with the current form.  <code>ctrl+alt+t</code> Transpose Sexps/Forms Swaps place of the two forms surrounding the cursor.  <code>alt+up</code><code>alt+down</code> Drag Sexp Backward/Forward Moves the current form to the behind/in front of the previous/next one. (See below about behavior in maps and binding boxes.)  <code>ctrl+alt+shift</code> <code>u</code><code>ctrl+alt+shift</code> <code>d</code> Drag Sexp Backward UpDrag Sexp Forward Down Moves the current form up/out of the current list, backwards, and down/in to the following list, forwards, keeping the cursor within the sexpr being dragged. <code>ctrl+alt+shift</code> <code>k</code><code>ctrl+alt+shift</code> <code>j</code> Drag Sexp Forward UpDrag Sexp Backward Down Moves the current form up/out of the current list, forwards, and down/in to the preceding list, backwards, keeping the cursor within the sexpr being dragged. <code>ctrl+shift+c</code> Convolute \u00af\\_(\u30c4)_/\u00af  <code>ctrl+shift+delete</code> Kill Sexp Forward Deletes the next form in the same enclosing form as the cursor. <code>ctrl+k ctrl+k</code> (win/linux)<code>ctrl+k</code> (mac) Kill Right Delete forward to the end of the current form or the first newline. <code>ctrl+k ctrl+h</code> (win/linux)<code>cmd+backspace</code> (mac) Kill Left Delete backward to the start of the current form or the start of the line. <code>ctrl+alt+backspace</code> Kill Sexp Backward Deletes the previous form in the same enclosing form as the cursor. <code>ctrl+delete</code> Kill List Forward Deletes everything from the cursor to the closing of the current enclosing form. <code>ctrl+backspace</code> Kill List Backward Deletes everything from the cursor to the opening of the current enclosing form. <code>ctrl+alt+shift+delete</code> Splice Killing Forward Delete forward to end of the list, then Splice.  <code>ctrl+alt+shift+backspace</code> Splice Killing Backwards Delete backward to the start of the list, then Splice.  <code>ctrl+alt+shift+p</code> Wrap Around () Wraps the current form, or selection, with parens.  <code>ctrl+alt+shift+s</code> Wrap Around [] Wraps the current form, or selection, with square brackets.  <code>ctrl+alt+shift+c</code> Wrap Around {} Wraps the current form, or selection, with curlies.  <code>ctrl+alt+shift+q</code> Wrap Around \"\" Wraps the current form, or selection, with double quotes. Inside strings it will quote the quotes.  <code>ctrl+alt+r</code><code>ctrl+alt+p</code>/<code>s</code>/<code>c</code>/<code>q</code>/<code>h</code> Rewrap Changes enclosing brackets of the current form to parens/square brackets/curlies/double quotes and set (<code>#{}</code>)  <p>Copy to Clipboard when killing text</p> <p>You can have the kill commands always copy the deleted code to the clipboard by setting <code>calva.paredit.killAlsoCutsToClipboard</code> to <code>true</code>.  If you want to do this more on-demand, you can kill text by using the selection commands and then Cut once you have the selection.</p> <p>clojure-lsp drag fwd/back overlap</p> <p>As an experimental feature, the two commands for dragging forms forward and backward have clojure-lsp alternatives. See the clojure-lsp page.</p>","boost":7},{"location":"paredit/#drag-bindings-forwardbackward","title":"Drag bindings forward/backward","text":"<p>When dragging forms inside maps and binding boxes, such as with <code>let</code>, <code>for</code>, <code>binding</code>, etcetera, it often makes most sense to drag each binding as a pair. And this is what Calva will do. Like so:</p> <p></p> <p>And like so (wait for it):</p> <p></p>","boost":7},{"location":"paredit/#about-the-keyboard-shortcuts","title":"About the Keyboard Shortcuts","text":"<p>Care has been put in to making the default keybindings somewhat logical, easy to use, and work with most keyboard layouts. Slurp and barf forward are extra accessible to go with the recommendation to learn using these two super handy editing commands.</p> <p>You can relax how Paredit's shortcuts replace VS Code built in shortcuts a bit by setting <code>calva.paredit.hijackVSCodeDefaults</code> to <code>false</code>.</p> <p>There are some context keys you can utilize to configure keyboard shortcuts with precision. See Customizing Keyboard Shortcuts.</p> <p>The Nuclear Option: You can choose to disable all default key bindings by configuring <code>calva.paredit.defaultKeyMap</code> to <code>none</code>. (Then you probably also want to register your own shortcuts for the commands you often use.)</p> <p>In some instances built-in command defaults are the same as Paredit's defaults, and Paredit's functionality in a particular case is less than what the default is. This is true of Expand Selection and Shrink Selection for Windows/Linux when multiple lines are selected. In this particular case adding <code>!editorHasMultipleSelections</code> to the <code>when</code> clause of the binding makes for a better workflow. The point is that when the bindings overlap and default functionality is desired peaceful integration can be achieved with the right <code>when</code> clause. This is left out of Paredit's defaults to respect user preference, and ease of maintenance.</p> <p>Happy Editing! \u2764\ufe0f</p>","boost":7},{"location":"paredit/#experimental-feature-multicursor-support","title":"Experimental Feature: Multicursor support","text":"<p>There is an ongoing effort to support simultaneous multicursor editing with Paredit. This is an experimental feature and is not enabled by default. To enable it, set <code>calva.paredit.multicursor</code> to <code>true</code>. This feature is still in development and may not work as expected in all cases. Currently, this supports the following categories:</p> <ul> <li>Movement</li> <li>Selection (except for <code>Select Current Form</code> - coming soon!)</li> <li>Rewrap</li> </ul>","boost":7},{"location":"parinfer/","title":"Calva Parinfer Mode is Reverted","text":"<p>Reverted in Calva v2.0.228</p> <p>The changes in v2.0.227 seemed to cause problems for some users. Unclear yet if and why. But to not risk causing problems for more users these changes where reverted and Calva v2.0.228 does not contain them. Please consider using v2.0.227 and help find what the problems are about! Please note: Even in v2.0.227 this feature is currently disabled by default.</p> <p>Parinfer is a system for editing the structure of LISP text without explicit commands. The structure can be regarded as already being expressed through indentation. With Parinfer you can use your intuition about the structure inferred from the indentation to perform surprisingly many structural edits.</p>"},{"location":"parinfer/#quirks","title":"Quirks","text":"<p>There are some known quirks, of varying severity, with this feature. Some of them will need to be fixed before we move this feature out of Experimental status.</p> <p>For the most times you can always Undo to get back to where the document was fine. You just need to pay some attention and be aware when undo is needed.</p>"},{"location":"parinfer/#no-multi-cursor-support","title":"No multi-cursor support","text":"<p>The bracket inference will remove all cursors but the first one. So for instance if you edit with multiple cursors and it causes brackets to move, you'll end up with just one cursor and the subsequent edits will not be what you intended. This is particularly important to note when you have cursors that are not in the viewport. In such cases it might be better to turn Parinfer off while you do the edits, fix formatting and such manually and then switch Parinfer on again.</p>"},{"location":"parinfer/#wrong-inferences","title":"Wrong inferences","text":"<p>For yet unknown reasons an edit such as the following does the wrong thing (the cursor indicated by the vertical bar):</p> <pre><code>(foo| (bar)\n      (baz))\n</code></pre> <p>backspace =&gt; </p> <pre><code>(fo| (bar\n      (baz)))\n</code></pre> <p>That is <code>(baz)</code> is slurped. When what should happen is:</p> <pre><code>(fo| (bar)\n     (baz))\n</code></pre>"},{"location":"parinfer/#lag-causing-errors-when-fast-typing","title":"Lag causing errors when fast typing","text":"<p>The way that Calva Parinfer works is that for any edit of the document it first reformats the code around the cursor, then infer brackets. Currently these two steps are not atomic to VS Code, so if you type fast bracket inference might happen on the yet unformatted code, and thus not be correct. You might also see the cursor end up at the wrong position at times.</p>"},{"location":"parinfer/#infer-parens","title":"Infer Parens","text":"<p>This is no longer available in Calva</p> <p>See above about how to try this build anyway, warts and all.</p> <p>When you enable Calva's Parinfer it is all about infering brackets from indentation. There are no further Parinfer modes. Calva's auto-formatter will take care of keeping the code correctly indented.</p> <p>Enable it with from this setting: <code>calva.fmt.experimental.inferParensAsYouType</code> or from the status bar item.</p>"},{"location":"parinfer/#parinfer-status-bar-items","title":"Parinfer Status bar items","text":"<p>To the right on the status bar, right before the Paredit status bar item, you will have two items, Parinfer toggle ON/OFF and a health indicator.</p> <ol> <li>Parinfer ON/OFF indicator/button. \u2022() (The dot/circle indicates ON/OFF)</li> <li>Structure and indentation health indicator. \u2714\ufe0f/\u26a0/\u2298</li> </ol> <p>When Parinfer is ON, the health indicator will have three states:</p> <ol> <li>\u2714\ufe0f Healthy - meaning both structure and indentation is OK</li> <li>\u2298 Structure broken - you need to fix the the structure of the code</li> <li>\u26a0 Bad indentation - meaning that to Parinfer the structure and indentation do not match, _the item is now also a button with which you can fix the indentation.</li> </ol> <p>Parinfer will be disabled in both the unhealthy states.</p> <p>When Parinfer is OFF, only the first two states above are used.</p>"},{"location":"parinfer/#some-vs-code-settings-automatically-changed","title":"Some VS Code Settings automatically changed","text":"<p>In order for some automatic VS Code behaviour not to interfere with Parinfer the following settings are automatically configured when you toggle Parinfer ON:</p> <pre><code>    \"[clojure]\": {\n        \"editor.autoClosingBrackets\": \"never\",\n        \"editor.autoClosingOvertype\": \"never\",\n        \"editor.formatOnPaste\": false\n    },\n</code></pre> <p>And when you toggle Parinfer OFF:</p> <pre><code>    \"[clojure]\": {\n        \"editor.autoClosingBrackets\": \"always\",\n        \"editor.autoClosingOvertype\": \"always\",\n        \"editor.formatOnPaste\": true\n    },\n</code></pre> <p>It is recommended that you let Calva handle these settings to avoid weird behaviour.</p>"},{"location":"parinfer/#no-tab-indenting","title":"No Tab indenting","text":"<p>As the <code>tab</code> key is used for formatting the current form in Calva, it is \u201dtaken\u201d. The closest equivalents you have are <code>space</code> and <code>backspace</code>. At least for now. We'll see if we can find out a good way for supporting <code>tab</code> and <code>shift+tab</code> for indent and dedent.</p> <p><code>tab</code> for formatting is of course just a default key binding and you can assign it to something else to get it to do indenting. However, it will not be a very smart indent anyway, there is no Clojure awareness about it. You are hereby adviced to instead use some more spaces.</p>"},{"location":"parinfer/#paredit-is-still-there","title":"Paredit is still there","text":"<p>In Calva, Parinfer and Paredit are designed to coexist and both be there to let you edit the structure easily and efficiently. Since Paredit commands are always formatted, they leave the code in a state where Parinfer has what it needs to infer bracket placement as you either edit the indentation, or remove/add brackets.</p>"},{"location":"parinfer/#disable-the-parinfer-extension","title":"Disable the Parinfer Extension","text":"<p>If you want to have Parinfer you are probably best served by Calva's built-in version. It is designed, and will continue to be improved to function well together with Calva's other structural editing and formatting features. It will also probably conflict with the Parinfer Extension.</p>"},{"location":"parinfer/#see-also","title":"See also","text":"<ul> <li>Paredit</li> <li>Formatting</li> </ul>"},{"location":"polylith/","title":"How to Use Calva with Polylith","text":"<p>Polylith is an architecture for backend projects that maximizes development ergonomics and code reuse.</p> <p></p> <p>When developing a Polylith application you use one REPL for everything. And as such it is a rather vanilla <code>deps.edn</code> project, so there is really not much more to using Calva with Polylith than:</p> <ol> <li>Jack in, selecting the <code>deps.edn</code> project type</li> <li>Select aliases, most often <code>:dev</code> and <code>:test</code></li> <li>Hack away!</li> </ol>"},{"location":"polylith/#the-realworld-example","title":"The RealWorld Example","text":"<p>To make it easy to try Polylith out with Calva, the Polylith RealWorld example implementation has some Calva config to get the server started and Calva connected to its REPL quickly:</p> <ol> <li>Fork the project and open it in VS Code</li> <li>Jack-in, selecting the <code>Polylith RealWorld Server REPL</code> project type</li> <li>Wait for the REPL prompt to read <code>clj\ua789dev.server\ua789&gt;</code></li> <li>Evaluate <code>(start! 6003)</code></li> <li>Hack away!</li> </ol>"},{"location":"polylith/#try-it-with-a-frontend","title":"Try it with a Frontend","text":"<p>A ClojureScript frontend, of course:</p> <ol> <li>Fork the jacekschae/conduit project and open it in VS Code</li> <li>Edit the <code>api-url</code> definition in <code>events.cljs</code> file to be     <pre><code>(def api-url \"http://localhost:6003/api\")\n</code></pre></li> <li>Jack-in, selecting to start and connect to the <code>:app</code> build</li> <li>Wait for it to compile and then open http://localhost:3000</li> <li>Hack away!</li> </ol>"},{"location":"pprint/","title":"Pretty Printing","text":"<p>In Calva, pretty printing is a mode. Prettiness is on by default and all your evaluation results will get that treatment.</p> <p>You can also pretty print code on demand</p> <p>There is a command Replace Current Form (or Selection) with Pretty Printed Form. See Clojure Formmatting for more on this.</p>"},{"location":"pprint/#toggle-it","title":"Toggle it","text":"<p>There is a <code>pprint</code> indicator to the right in the status bar which shows the status of the mode. Click the indicator to toggle prettification on and off. There is also a Calva: Toggle Pretty Printing for All Evaluations command.</p> <p>Tip: If you have evaluated something time consuming, or that is not idempotent, with pretty printing mistakenly off: toggle it on and evaluate <code>*1</code>.</p>"},{"location":"pprint/#configuration","title":"Configuration","text":"<p>For most people the defaults will probably work, but Calva pretty printing comes a few knobs you can turn, and they are all available through the <code>calva.prettyPrintingOptions</code> settings. Things you can set are:</p> Setting Type Effect <code>enabled</code> boolean So this is a third way you can change this mode \ud83d\ude04 <code>printEngine</code> enum Which printer function that will be used. Default is <code>pprint</code>, more about this setting below <code>printFn</code> object You can configure Calva to use a custom <code>nREPL</code> compatible <code>print</code> function, more below. <code>width</code> number The maximum line length of printed output (or at least the printers will try) <code>maxLength</code> number The maximum number of elements printed in nested nodes, good for evaluating something like <code>(iterate inc 0)</code>, which you shouldn't do without setting <code>maxLength</code>. Most printers will indicate truncated lists with <code>...</code> at the end. <code>maxDepth</code> number The maximum number of levels deep that will get printed. Different printers mark a stop different ways. <code>puget</code> doesn't support it at all. <p>See Customizing Calva for some tips on adding settings like these.</p> <p>Here's an example of how <code>zprint</code> handles <code>maxDepth</code> (from the Calva implementation of it's client side pretty printing.).</p> <pre><code>  (pretty-print [[[[[[[[:deeper]]]]]]]] {:max-depth 4})\n  ;; =&gt; {:value \"[[[[##]]]]\"}\n</code></pre>"},{"location":"pprint/#your-selection-of-prettifiers","title":"Your Selection of Prettifiers","text":"<p>Pretty printing can happen on the server (i.e. in the JVM, via nREPL), or on the client (i.e. in node, via VS Code/Calva). Client side always uses <code>zprint</code>. Server side you can choose from these printers:</p> Print Engine Client or Server Side Comments <code>calva</code> client The nREPL server will plain print the results, and then Calva will pretty it (using <code>zprint</code>). <code>pprint</code> server Current Calva default. <code>clojure.core/pprint</code> is a bit basic, but it's tried and tested, and doesn't suffer from the issues with the other server side printing options, mentioned below. <code>fipp</code> server <code>puget</code> server Lacks <code>maxDepth</code> option. <code>zprint</code> server A very good option. However, it will need to be configured before Jack-in if you want Calva's help to inject its dependencies. (If you are not using Jack-in, you'll need to supply this dependency yourself.) <p>These particular server side functions were chosen because they have pre-configured print-functions in <code>cider-nrepl</code>.</p>"},{"location":"pprint/#or-configure-printfn","title":"Or configure <code>printFn</code>","text":"<p>If the selection of built-in <code>printEngine</code> support doesn't cut it, you can configure a custom function. This function will need to conform to the requirements of nREPL print functions. The VS Code settings editor will help you configure this one. (This is also a bit experimental, please consider giving feedback about how it works for you if you try it.)</p>"},{"location":"pprint/#why-does-server-or-client-side-matter","title":"Why does Server or Client Side Matter?","text":"<p>This matters because on the server all pretty printers, except <code>pprint</code> does more than just pretty print the result that would be printed with plain printing. Pretty printing results on the server causes some results to get expanded. This can have huge implications depending on the results and which printer is used. E.g. for Datomic transaction results, you will get the whole database printed. Twice. Depending on the database, you could be so unlucky that nothing gets printed, and instead you will soon have a very hot computer.</p> <p>Note: With the help of zprint creator, Kim Kinnear, we have found ways to compensate for this problem. Ways that are not yet implemented, but please stay tuned.</p> <p>Then why not always do it client side? It turns out that on the client side there are also things going on. Calva gets the results back as a string and therefore it needs to first be parsed back to EDN, before it can be pretty printed by <code>zprint</code>. And \u2013 here's the catch \u2013 all results are not valid EDN and therefore can't be pretty printed by <code>zprint</code>. Datomic transaction results are one example.</p>"},{"location":"pprint/#need-more-configurability","title":"Need More Configurability?","text":"<p>The current options are limited, because our time developing Calva is limited. But <code>cider-nrepl</code> really allows for fully configurable pretty printing, so it is within reach. Please feel invited to give us feedback on what you would want to configure for the printing of results. File issues and/or chat us up in #calva in the Clojurians slack.</p>"},{"location":"pprint/#troubleshooting","title":"Troubleshooting","text":""},{"location":"pprint/#pprint-is-not-working","title":"pprint is not working","text":"<p>If pprint is not working, try a different pprint engine or use Calva's jack-in to make sure the necessary dependencies are loaded in your REPL. If you are starting your REPL without jack-in and want to continue doing so, you can use the command <code>Copy Jack-in Command Line to Clipboard</code> then paste the command somewhere to see what dependencies it injects. You can then add these dependencies to your REPL in whatever way suits your needs.</p> <p>Enjoy Prettiful Printing! \u2764\ufe0f</p>"},{"location":"quirks/","title":"Quirks","text":"<p>Here's a shocker for ya': Calva isn't perfect. \ud83d\ude04</p> <p>There are quirks and things that flat out do not work. We'll try to collect info about such things here, providing workarounds when available (or, rather, known to us).</p>"},{"location":"quirks/#test-features-not-available-with-clojurescript","title":"Test features not available with ClojureScript","text":"<p>Currently <code>cider-nrepl</code> does not provide its test functionality for ClojureScript code. Please consider contributing to fixing that.</p>"},{"location":"quirks/#using-with-parinfer","title":"Using with Parinfer","text":"<p>See Using with Parinfer</p>"},{"location":"quirks/#calva-and-the-vim-extension","title":"Calva and the VIM Extension","text":"<p>See Using Calva with the VIM Extension.</p>"},{"location":"quirks/#command-not-found-errors-on-jack-in","title":"\u201dCommand not found\u201d Errors on Jack-in","text":"<p>Jack-in starts by running a command in a new terminal. You will need the commands used installed on your computer:</p> <ul> <li><code>clojure</code> for tools.deps/deps.edn</li> <li><code>lein</code> for Leiningen</li> <li><code>npx</code> for shadow-cljs</li> <li><code>gradlew</code> for Gradle (in your project)</li> </ul> <p>Also, in some circumstances VS Code is not spawned from a shell with the environment variables, especially <code>$PATH</code>, which might mean that even though you have the tools installed, they are not found when VS Code/Calva tries to execute them. To fix this you will need to do one of these two things:</p> <ol> <li>Figure out from where VS Code is spawned, and make sure the <code>$PATH</code> there includes the directory with the needed binary.</li> <li>Start VS Code from a terminal where the <code>$PATH</code> is correctly configured. (Using the <code>code</code> command.)</li> </ol> <p>See this issue for more clues on this problem.</p>"},{"location":"quirks/#strange-linting-errors","title":"Strange linting errors?","text":"<p>This is not really a quirk, and most linting errors are not strange when you learn about why they are there. Calva does not do any linting, btw, see also linting.</p>"},{"location":"quirks/#consider-uninstalling-these-extensions","title":"Consider uninstalling these extensions","text":"<p>Without Calva, many users install other nifty extensions (some of which are old pieces of Calva) that help with this or that problem. It might sometimes work together with Calva, sometimes not. Here's a list of some common extensions you should consider to at least disable:</p> <ul> <li>Strict Paredit - Calva Paredit has evolved a lot since that version</li> <li>Calva-fmt/Calva Formatter - Same here, evolution</li> <li>Clojure Warrior - Calva includes it, in a much evolved way</li> <li>Parinfer - This one you can actually keep, at some cost, see Using Calva with Parinfer.</li> </ul>"},{"location":"re-frame-template/","title":"How to use Calva with the re-frame template","text":"<p>The re-frame template creates a <code>shadow-cljs</code> project, making it easy to use with Calva.</p> <ol> <li><code>npm install</code></li> <li>From VS Code, issue the command Calva: Start a Project REPL and Connect (a.k.a Jack-in), <code>ctrl+alt+c ctrl+alt+j</code>.</li> <li>Calva will auto-detect that this is a <code>shadow-cljs</code> project and ask for which build to compile.</li> <li>Calva's output window will open and log some progress information.</li> <li>When prompted for which build to start, select <code>:app</code>.</li> <li><code>:app</code> is the only configured build, but the VS Code menu for this is a bit strange so make sure the <code>:app</code> checkbox is really ticked before proceeding.</li> <li>This will start the app, so in this workflow you don't do the Run application steps outlined below.</li> <li>When prompted for which build to connect to, select <code>:app</code>.<ul> <li>In the View menu of VS Code, you can tell it to show the Terminal view, where you see which command the jack-in process is started with, and it's output. <code>Ctrl+C</code> in this pane will kill your app and free up all resources it has allocated.</li> </ul> </li> <li>When the app is compiled<ol> <li>Open http://localhost:8280 in your browser.</li> <li>Confirm that it says Hello from re-frame. (Depending on how long the app takes to compile, you might need to reload the page a few times.)</li> </ol> </li> <li>Open the <code>views.cljs</code> file from <code>src/&lt;your-project-name&gt;</code> and issue Calva: Load/Evaluate Current File and its Requires/Dependencies. <code>ctrl+alt+c enter</code>.<ol> <li>Confirm that you are connected by adding evaluating <code>(js/alert \"Hello from Calva\")</code> (<code>alt+enter</code> and <code>ctrl+enter</code> are your friends).</li> <li>Confirm that Shadow is hot reloading by changing the greeting message.</li> </ol> </li> </ol>"},{"location":"rebl/","title":"How to Use Calva and REBL Together","text":"<p>REBL is a graphical, interactive tool for browsing Clojure data.</p>"},{"location":"rebl/#depsedn","title":"deps.edn","text":"<p>Add the following aliases to your deps.edn file. Use the deps.edn file in the <code>~/.clojure</code> directory to enable alias reuse across multiple projects. This is the configuration for REBL on openjdk 12. Check out the REBL github page for more info.</p> <pre><code>;; REBL Base\n:rebl\n{:extra-deps {org.clojure/core.async {:mvn/version \"0.4.490\"}\n                ;; deps for file datafication (0.9.149 or later)\n                org.clojure/data.csv {:mvn/version \"0.1.4\"}\n                org.clojure/data.json {:mvn/version \"0.2.3\"}\n                org.yaml/snakeyaml {:mvn/version \"1.23\"}\n                com.cognitect/rebl\n                ;; adjust to match your install location\n                {:local/root \"/Users/ozimos/REBL/latest/REBL.jar\"}}}\n\n;; REBL 12\n:rebl-12\n{:extra-deps {org.openjfx/javafx-fxml     {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-controls {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-graphics {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-media    {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-swing    {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-base     {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-web      {:mvn/version \"12.0.1\"}}}\n\n;; nREBL\n:nrebl {:extra-deps {rickmoynihan/nrebl.middleware {:mvn/version \"0.2.0\"}}\n            :main-opts [\"-e\" \"((requiring-resolve,'cognitect.rebl/ui))\" \"-m\" \"nrepl.cmdline\" \"--middleware\" \"[nrebl.middleware/wrap-nrebl]\" \"-I\"]}\n</code></pre> <p>Create a Calva custom connect sequence for your VSCode editor. (Read Custom REPL Connect Sequences if you haven't.) Add the following to your vscode settings.json:</p> <pre><code>{\n    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"Rebl Connect\",\n            \"projectType\": \"deps.edn\",\n            \"menuSelections\": {\n                \"cljAliases\": [\n                    \"rebl\",\n                    \"rebl-12\",\n                    \"nrebl\"\n                ]\n            }\n        }\n    ]\n}\n</code></pre>"},{"location":"rebl/#leiningen","title":"Leiningen","text":"<p>Add rebl profiles to your user-wide profiles so that they will be available for all your projects. Here's a sample user profile (located at <code>~/.lein/profiles.clj</code> on mac):</p> <p><pre><code>{:user {:plugins [[lein-ancient \"0.6.15\"]]}\n\n ;; REBL Base\n :rebl {:resource-paths [\"/Users/ozimos/REBL/latest/REBL.jar\"]\n        :dependencies [[org.clojure/core.async \"0.4.490\"]\n                       [org.clojure/data.csv \"0.1.4\"]\n                       [org.clojure/data.json \"0.2.3\"]\n                       [cljfmt \"0.6.4\"]\n                       [org.yaml/snakeyaml \"1.23\"]]}\n\n ;; REBL 12 for JDK 12.0.1. Swap out for your JDK version\n :rebl-12 {:dependencies [[org.openjfx/javafx-fxml  \"12.0.1\"]\n                          [org.openjfx/javafx-controls \"12.0.1\"]\n                          [org.openjfx/javafx-graphics \"12.0.1\"]\n                          [org.openjfx/javafx-media \"12.0.1\"]\n                          [org.openjfx/javafx-swing \"12.0.1\"]\n                          [org.openjfx/javafx-base  \"12.0.1\"]\n                          [org.openjfx/javafx-web \"12.0.1\"]]}\n\n;; NREBL https://github.com/RickMoynihan/nrebl.middleware\n :nrebl {:repl-options {:nrepl-middleware [nrebl.middleware/wrap-nrebl]}\n        :dependencies [[rickmoynihan/nrebl.middleware \"0.3.1\"]]}}\n</code></pre> More info here</p> <p>Create a Calva custom connect sequence for your VSCode editor. (Read Custom REPL Connect Sequences if you haven't.) Add the following to your vscode settings.json:</p> <pre><code>{\n    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"Lein REBL\",\n            \"projectType\": \"Leiningen\",\n            \"menuSelections\": {\n                \"leinProfiles\": [\"rebl\", \"rebl-12\", \":nrebl\"]\n            },\n            \"afterCLJReplJackInCode\": \"((requiring-resolve 'cognitect.rebl/ui))\"\n        }\n    ]\n}\n</code></pre>"},{"location":"rebl/#shadow-cljs-tbd","title":"shadow-cljs (TBD)","text":"<p>TBD. If you know how to do it, please update this page.</p>"},{"location":"refactoring/","title":"Refactoring","text":"<p>There are two \u201dflavours\u201d to refactoring support. Some (just a few) refactorings are made available as Quick Fix suggestions (the light bulb), the rest are regular commands in the clojure-lsp Refactoring category.</p> <p></p> <p>You can enable or disable the Quick Fix suggestion lightbulb using the VS Code setting <code>editor.lightbulb.enabled</code>.</p> <p>The refactoring commands do not have default keyboard shortcuts. You find them all by typing \u201dclojure-lsp Refactor\u201d in the Command Palette.</p>"},{"location":"refactoring/#commands","title":"Commands","text":"Command Title Command Key Description Clean NS Form <code>clojureLsp.refactor.cleanNs</code> Add Missing Require <code>clojureLsp.refactor.addMissingLibspec</code> Extract to New Function <code>clojureLsp.refactor.extractFunction</code> Cycle/Toggle Privacy <code>clojureLsp.refactor.cyclePrivacy</code> Inline Symbol <code>clojureLsp.refactor.inlineSymbol</code> Introduce let <code>clojureLsp.refactor.introduceLet</code> Creates a new let box with the binding. Follow up with \u201dExpand let\u201d to move it upwards. Expand Let <code>clojureLsp.refactor.expandLet</code> Move to Previous let Box <code>clojureLsp.refactor.moveToLet</code> Thread First <code>clojureLsp.refactor.threadFirst</code> Thread First All <code>clojureLsp.refactor.threadFirstAll</code> Thread Last <code>clojureLsp.refactor.threadLast</code> Thread Last All <code>clojureLsp.refactor.threadLastAll</code> Unwind All <code>clojureLsp.refactor.unwindAll</code> Unwind Thread <code>clojureLsp.refactor.unwindThread</code> <p>Formatting</p> <p>The way that some of the refactorings are applied to the document, makes it difficult for Calva to format the results. So, sometimes you'll need to navigate the cursor to the enclosing form and hit <code>tab</code> to tidy up the formatting after a refactoring. See also Formatting.</p>"},{"location":"refactoring/#thanks-to-clojure-lsp","title":"Thanks to clojure-lsp","text":"<p>Most of Calva's refactoring support is sourced directly from clojure-lsp. This also means that most often, if you find issues with refactoring, or have suggestions about it, the clojure-lsp repo is where to direct your reporting.</p>"},{"location":"remote-development/","title":"Using Calva with Remote Development","text":"<p>VS Code Remote Development is a new feature in version 1.35 of VS Code that allows a developer to use a container, remote machine, or the Windows Subsystem for Linux (WSL) as a full-featured development environment.</p> <p>I would recommend reading the introductory blog post and watching the videos. I find the feature extremely exciting and wish more IDEs would implement something like it.</p> <p>From a Clojure perspective it allows you to have VS Code installed on your Java-less, Clojure-less hardware and still use it to develop Clojure through it.</p>"},{"location":"remote-development/#a-use-case","title":"A use-case","text":"<ul> <li>For some reason your physical computer has to be running Windows (organizational rules etc.)</li> <li>Your deployment environment is Linux</li> <li>You want to edit files in an editor running on your physical computer</li> <li>Most Clojure tooling is made with *nix first in mind and there are incompatibilities with Windows</li> </ul>"},{"location":"remote-development/#how-to","title":"How to","text":"<p>Run Remote-Containers: Add Development Container Configuration Files... and pick a suitable Java base image. Then:</p>"},{"location":"remote-development/#modify-dockerfile-to-install-clojure-cli-and-optionally-lein","title":"Modify Dockerfile to install Clojure CLI (and optionally lein)","text":"<p>Add:</p> <pre><code># ...\n\n# Install Clojure - see https://github.com/Quantisan/docker-clojure/blob/master/target/openjdk-14-slim-buster/tools-deps/Dockerfile\nENV CLOJURE_VERSION=1.10.1.619\nWORKDIR /tmp\nRUN \\\napt-get update &amp;&amp; \\\napt-get install -y curl make rlwrap wget &amp;&amp; \\\nrm -rf /var/lib/apt/lists/* &amp;&amp; \\\nwget https://download.clojure.org/install/linux-install-$CLOJURE_VERSION.sh &amp;&amp; \\\nsha256sum linux-install-$CLOJURE_VERSION.sh &amp;&amp; \\\necho \"28b1652686426cdf856f83551b8ca01ff949b03bc9a533d270204d6511a8ca9d *linux-install-$CLOJURE_VERSION.sh\" | sha256sum -c - &amp;&amp; \\\nchmod +x linux-install-$CLOJURE_VERSION.sh &amp;&amp; \\\n./linux-install-$CLOJURE_VERSION.sh\nRUN \\\nsu vscode -c \"clojure -e '(clojure-version)'\" &amp;&amp; \\\nrm ./linux-install-$CLOJURE_VERSION.sh\n\n# Install Lein\nRUN \\\nwget https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein -O /bin/lein &amp;&amp; \\\nchmod uog+x /bin/lein\nRUN su vscode -c \"/bin/lein\"\n\n# Cleanup\nRUN apt-get purge -y --auto-remove curl wget\n\n# ...\n</code></pre>"},{"location":"remote-development/#modify-devcontainerjson","title":"Modify devcontainer.json","text":"<p>Add Calva and, optionally, forward some ports to the host::</p> <pre><code>\"extensions\": [\"betterthantomorrow.calva\"],\n\"forwardPorts\": [8088, 52162], // example: your webapp, your nREPL\n</code></pre>"},{"location":"remote-development/#build-and-start","title":"Build and start","text":"<p>Run Remote-Containers: Rebuild and Reopen in container</p>"},{"location":"remote-development/#wsl","title":"WSL","text":"<p>See Using Calva with WSL</p>"},{"location":"repl-window/","title":"The REPL Window/File","text":"<p>The Calva REPL Window is actually a regular file with some extra treatment from Calva, like displaying a prompt, offering evaluation history recall and generally \u201cfollowing\u201d the current namespace. This file is created and opened when Calva is connected to a REPL. You can use it for experimental code (though there are also Rich Comments and Fiddle Files for this). </p> <p>In ClojureScript projects, the window will be associated with the <code>cljs</code> REPL once it is connected. It will then look something like this:</p> <p></p> <p>The first prompt is from when the <code>clj</code> REPL is connected, and the second from <code>cljs</code>. The first part of the prompt tells you which REPL type the window is currently connected to.</p>"},{"location":"repl-window/#using-the-repl-window-for-output","title":"Using the REPL Window for output","text":"<p>By default the REPL Window doubles as the place where Calva sends output like stdout/stderr and other messages. See Calva Output for more about this and how to change this behaviour.</p>"},{"location":"repl-window/#finding-the-repl-window","title":"Finding the REPL Window","text":"<p>If you quickly want to open and/or switch to the REPL Window there is the command Calva: Show/Open REPL Window, <code>ctrl+alt+o r</code>.</p> <p>To sync the REPL window namespace with the current file before switching, use the Switch Namespace of the REPL Window to Current Namespace command, <code>ctrl+alt+c alt+n</code>.</p>"},{"location":"repl-window/#find-the-file-for-the-current-repl-window-namespace","title":"Find the File for the Current REPL Window Namespace","text":"<p>When you are editing things in the REPL window, and want to open the file that defines its current namespace, use the Show File for the Current REPL Window Namespace command, <code>ctrl+alt+o r</code>.</p> <p>Note</p> <p>This also works for Clojure core and library namespaces.</p>"},{"location":"repl-window/#evaluating-code","title":"Evaluating Code","text":"<p>The window will be automatically associated with the REPL and the namespace of any project Clojure/ClojureScript file you evaluate code in. So for instance if you evaluate this code in a <code>clj</code> file with the namespace <code>fresh-reagent.handler</code>:</p> <pre><code>(def mount-target\n  [:div#app\n   [:h2 \"Welcome to fresh-reagent\"]\n   [:p \"please wait while Figwheel is waking up ...\"]\n   [:p \"(Check the js console for hints if nothing exciting happens.)\"]])\n</code></pre> <p>If the REPL Window is the configured destination for evaluation results, the defined var will be printed there. Otherwise, it will be printed to the destination you've configured. In either case, the REPL window will print a new prompt reflecting the current REPL connection and namespace:</p> <p></p> <p>If you then switch to the output window (<code>ctrl+alt+o r</code>), and enter this at the prompt:</p> <pre><code>mount-target\n</code></pre> <p>then evaluate it using <code>alt+enter</code>, you'll get this:</p> <p></p> <p>... because the namespace \u201dfollowed\u201d the first evaluation in the REPL window.</p>"},{"location":"repl-window/#repl-history","title":"REPL History","text":"<p>Recently evaluated forms in the REPL file are persisted and can easily be shown again for modifying and re-evaluating.</p>"},{"location":"repl-window/#navigate-repl-history","title":"Navigate REPL History","text":"<p>You can navigate up and down the history of evaluated forms in the REPL file by pressing <code>alt+up</code> and <code>alt+down</code>, provided your cursor is at the end of the last form after the prompt. If the cursor is not at the end of the last form, then <code>alt+up</code> and <code>alt+down</code> will do whatever they are mapped to, which is by default \"Move Line Up\" and \"Move Line Down,\" respectively.</p> <p>If you have typed some text after the prompt before you start traversing up the history, this text will be preserved and will display when you traverse back down the history. If you modify some text in the history while traversing, the modification will be saved at that location in history.</p>"},{"location":"repl-window/#clear-repl-history","title":"Clear REPL History","text":"<p>You can clear the repl history by running the command \"Clear REPL History\" from the command palette.</p>"},{"location":"repl-window/#stack-traces","title":"Stack Traces","text":"<p>When an evaluation produces an error, it will automatically be printed in the REPL Window. If there is a stack trace associated with the error, it can now be printed on demand using the Calva: Print Last Stacktrace to the Output Window command. You can also print the stack trace for any error message printed to the REPL Window via the Codelens button below it.</p> <p></p> <p>For printed stacktraces, when source locations are available (Clojure files), you will be able to navigate to them by pressing <code>ctrl+click</code> (<code>cmd+click</code> on Mac) on the file name. You can also hover over symbols in the stack trace to see the symbol's documentation, and <code>ctrl+click</code> (<code>cmd+click</code> on Mac) the symbol to Peek Definition.</p> <p></p> <p>Output destinations</p> <p>If you have configured some other destination for stderr output, the error message will be printed there as well. But it will also be printed to the REPL Window, because the augmented stack traces need this (because reasons). </p>"},{"location":"repl-window/#load-current-namespace","title":"Load Current Namespace","text":"<p>When navigating namespaces it is easy to forget to first require them and that can be tricky to debug. To help with this, Calva's command Load/Evaluate Current File and its Requires/Dependencies also works in the REPL Window, but there, it acts like Load Current Namespace.</p> <p>Suppose you have two files, <code>pez/xxx.clj</code> and <code>pez/yyy.clj</code>, where <code>pez.yyy</code> requires <code>pez.xxx</code>.</p> <pre><code>(ns pez.xxx)\n\n(def a :xxx-a)\n\n(def b :xxx-b)\n</code></pre> <pre><code>(ns pez.yyy\n  (:require [pez.xxx]))\n\n(def a :yyy-a)\n\n(println \"Hello\" pez.xxx/a)\n</code></pre> <p>Then, with a freshly jacked-in REPL, you evaluate <code>(ns pez.yyy)</code> and want to work with the vars defined there, Clojure will complain. But if you Load/Evaluate Current File and its Requires/Dependencies, it will start working. Something like so:</p> <p></p> <p>Note</p> <p>This currently suffers from a limitation in Calva where it won't reload dependencies, so you will sometimes have to do this \u201dmanually\u201d anyways (by opening the files and loading them yourself). See Calva issue #907</p>"},{"location":"repl-window/#peek-current-namespace","title":"Peek Current Namespace","text":"<p>A somewhat hidden feature: You can peek, see documentation for, and navigate to a namespace by hovering on the namespace symbol in one of the REPL Window prompts (just like you would if it was not in the prompt \ud83d\ude04).</p>"},{"location":"repl-window/#paredit-enabled","title":"Paredit Enabled","text":"<p>The REPL Window is mostly a regular Calva Clojure/ClojureScript file, which makes everything that works in a regular file work in this file, including Paredit. This makes it easy to navigate the input and output there. For instance, to select the last evaluation results, you can press <code>ctrl+w</code> (<code>shift+alt+right</code> on Windows and Linux):</p> <p></p>"},{"location":"repl-window/#debugger-enabled","title":"Debugger Enabled","text":"<p>The output window is mostly a regular... (you get it), which means you also have the Calva debugger at your command at the REPL prompt (only for <code>clj</code> sessions, for now). So instead of evaluating a function definition using <code>alt+enter</code>, you can evaluate it and instrument it for debugging using <code>ctrl+alt+c i</code>, and then call the function.</p> <p></p>"},{"location":"repl-window/#it-is-ephemeral","title":"It is Ephemeral","text":"<p>The contents of the output/REPL window is written to a file named <code>output.repl</code> in the <code>.calva/output-window</code> directory of your project. The file is recreated every new session, so you should copy or save anything you want to preserve between sessions.</p> <p>You probably want to add <code>.calva/output-window/</code> to your <code>.&lt;something&gt;ignore</code> files. (There are some more files in that directory that you shouldn't keep under source control.)</p>"},{"location":"repl-window/#choose-clj-or-cljs-repl-connection","title":"Choose CLJ or CLJS REPL Connection","text":"<p>In full-stack projects, you will probably use the window as a REPL for both <code>clj</code> and <code>cljs</code>. You can toggle which REPL the window is connected to by using the command Calva: Toggle REPL Connection for CLJC files. There is also a button for this in the status bar:</p> <p></p>"},{"location":"repl-window/#known-quirks-and-caveats","title":"Known Quirks and Caveats","text":"<p>Due to limitations in the VS Code API it is hard for Calva to know if the REPL file is open, and if it was opened more than once. Therefore, we suggest you make it a habit to leave this window open, or even pinned. And if it is open in several tabs, expect evaluation printouts to be a bit unpredictable.</p> <p>If you save the REPL file (which most often does not make much sense, but anyway) you will sometimes be presented with a message about VS Code being confused about the file contents being out of sync. Just choose to Overwrite the currently saved version and you should be fine.</p>"},{"location":"reveal/","title":"How to use Calva and Reveal together","text":"<p>Reveal is a \"Read Eval Visualize Loop for Clojure\". This page describes how to use Reveal in your development setup based on Calva.</p> <p>Note</p> <p>See https://vlaaad.github.io/reveal for the latest version and use that wherever this page says <code>&lt;version&gt;</code>.</p>"},{"location":"reveal/#when-using-toolsdeps","title":"When using tools.deps","text":"<p>You can go for the nrepl middleware or just add the dependency. </p> <p>Please see the Calva test-data project minimal-reveal for an example.</p>"},{"location":"reveal/#middleware","title":"Middleware","text":"<p>This will make Reveal to start together with your project.</p> <p>Note</p> <p>This will make all Calva evaluations go to Reveal. Too chatty for you? Take the dependencies only approach.</p> <p>Add this alias <code>deps.edn</code>:</p> <pre><code>:aliases\n{:reveal-nrepl-middleware\n    {:extra-deps {vlaaad/reveal {:mvn/version \"&lt;version&gt;\"}}\n     :main-opts  [\"-m\" \"nrepl.cmdline\"\n                  \"--middleware\" \"[vlaaad.reveal.nrepl/middleware,cider.nrepl/cider-middleware]\"]}}\n</code></pre> <p>And then jack-in choosing the deps.edn option and then pick the <code>:reveal-nrepl-middleware</code> alias.</p>"},{"location":"reveal/#dependencies-only","title":"Dependencies only","text":"<p>If you don't want to use the nrepl-middleware you can configure just the dependency and then start Reveal yourself.</p> <p>The alias:</p> <pre><code>:reveal-dep-only\n  {:extra-deps {vlaaad/reveal {:mvn/version \"&lt;version&gt;\"}}}\n</code></pre> <p>A custom REPL command for starting Reveal in your project:</p> <pre><code>    \"calva.customREPLCommandSnippets\": [\n        ...\n        {\n            \"name\": \"Start Reveal Tapper\",\n            \"snippet\": \"(require '[vlaaad.reveal :as reveal])(add-tap (reveal/ui))\",\n            \"key\": \"sr\"\n        },\n        ...\n    ]\n</code></pre> <p>See Custom REPL Command for how to configure more commands, and bind shortcuts to them, to make Reveal integration nice for you.</p>"},{"location":"reveal/#when-using-leiningen","title":"When using Leiningen","text":"<p>In your <code>project.clj</code>, add a profile named \"reveal\":</p> <pre><code>:profiles {:reveal {:dependencies [[vlaaad/reveal \"&lt;version&gt;\"]]\n                    :repl-options {:nrepl-middleware [vlaaad.reveal.nrepl/middleware]}}}\n</code></pre> <p>Now when you jack-in using Calva, you enable this profile and Reveal will be started automatically. Please note that Reveal requires Java 8 or higher, and uses JavaFX. Depending on your setup, you may need to make sure it is available.</p>"},{"location":"reveal/#tips-about-font-size","title":"Tips about font size","text":"<p>If you find the font to small you can add a <code>:jvm-opts</code> key to make it a little bigger:</p> <pre><code>:aliases\n{:reveal\n    {:extra-deps {vlaaad/reveal {:mvn/version \"&lt;version&gt;\"}}\n     :jvm-opts   [\"-Dvlaaad.reveal.prefs={:font-size,17}\"]\n     :main-opts  [\"-m\" \"nrepl.cmdline\"\n                  \"--middleware\" \"[vlaaad.reveal.nrepl/middleware,cider.nrepl/cider-middleware]\"]}}\n</code></pre>"},{"location":"reveal/#using-java-11","title":"Using Java &gt; 11?","text":"<p>Reveal needs some reflective access to internal classes that has since Java 11 been restricted. You can relax this and get things working via JVM options. Tuck this into your reveal alias:</p> <pre><code>:jvm-opts [\"--add-opens\" \"javafx.graphics/com.sun.javafx.tk=ALL-UNNAMED\"]\n</code></pre> <p>(If you are using the font size tips, just add the options into the <code>:jvm-opts</code> vector.)</p> <p>See https://github.com/vlaaad/reveal/issues/1 for some more context around this issue.</p>"},{"location":"rich-comments/","title":"Rich Comments Support","text":"<p>Why bother with Rich comments? Read on. Consider watching this Youtube video for a demo of the workflow using the (in?)famous FizzBuzz problem as an example.</p>","boost":5},{"location":"rich-comments/#things-in-comment-are-not-evaluated","title":"Things in <code>comment</code> are not evaluated","text":"<p>The Clojure <code>comment</code> macro is defined like so:</p> <pre><code>(defmacro comment\n  \"Ignores body, yields nil\"\n  {:added \"1.0\"}\n  [&amp; body])\n</code></pre> <p>It has no forms in its body and will therefore always (as long as the Clojure Reader can read it) evaluate to <code>nil</code>. That is: nothing in the <code>(comment ...)</code> form will get evaluated when the file is loaded.</p> <p>This makes it a very good \u201dplace\u201d where you can develop code, experiment with code, and keep example code. Since you will be able to load/evaluate the current file without worrying that the code in the <code>comment</code> form will get evaluated. This also holds true when using tools that hot-reload the code on save, such as Figwheel, shadow-cljs and Krell.</p> <p>To develop or refine a function you might:</p> <ol> <li>Open up a <code>(comment ...)</code> form</li> <li>Inside this form, type a first, super simple, version (or refinement) of your function and evaluate it</li> <li>Inside the same <code>comment</code> form, type some code to test your function and evaluate that<ul> <li>Or type and evaluate some code you might need for your function</li> </ul> </li> <li>Repeat from 2., until the function does what you want it to do</li> <li>Move the function definition out of the <code>comment</code> form</li> <li>Clean up the <code>comment</code> form to keep some of the test code as example use, or \u201ddesign decision log\u201d for the function.</li> </ol> <p>Note</p> <p>Using <code>(comment ...)</code> forms for developing code is very common among Clojure coders. Rich Hickey is known for using it, which is why they are called Rich comments to begin with (even if it also is a very rich experience).</p>","boost":5},{"location":"rich-comments/#calva-encourages-rich-comments","title":"Calva encourages Rich comments","text":"<p>Calva has several features to facilitate the Rich comments workflow, e.g.</p> <ol> <li>A command that helps you create a new Rich comment form quickly: Calva: Add Rich Comment, ctrl+alt+r c</li> <li>A snippet for creating Rich comment form quickly. Typing <code>(rcf</code>, will make it appear.</li> <li>Special Syntax highlight. By default <code>comment</code> forms are rendered in italics</li> <li>Special top-level form context</li> <li>Special formatting</li> </ol> <p>Note that the command and snippet for creating Rich comments add the keyword <code>:rcf</code> right before the closing paren. This makes the closing paren stay and not fold when you format the code. The special formatting (see below) will treat this and also any ignored (with <code>#_</code>) form at the end of the form specially.</p>","boost":5},{"location":"rich-comments/#comment-is-top-level","title":"<code>comment</code> is top-level","text":"<p>To make it easy to evaluate forms in <code>(comment ...)</code> forms, they create a new top-level context. Instead of you having to place the cursor with precision before evaluating the current form, you can have the cursor anywhere within a <code>comment</code> enclosed form and Evaluate Top-Level Form.</p> <p>This carries over to all commands in Calva which deal with the top level form. Including custom command snippets.</p>","boost":5},{"location":"rich-comments/#special-formatting","title":"Special formatting","text":"<p>To invite a Rich comments workflow, the Calva command Format Current Form will not fold the closing bracket of the <code>(comment ...)</code> form. Instead it will place this bracket on a line of its own (or keep it there).</p> <pre><code>(comment\n  )\n</code></pre> <p>With the cursor somewhere directly inside the comment form (denoted with a <code>|</code>):</p> <pre><code>(comment\n  (def foo\n:foo)|)\n</code></pre> <p>tab</p> <pre><code>(comment\n  (def foo\n    :foo)\n  |)\n</code></pre> <p>!!! Note \"Only for the current comment form\u201d     The special formatting only applies in the current <code>comment</code> form. When outside it, formatting tucks the closing paren in again. That's why fold when done, below works like it does. This also applies to VS Code commands like Format Document, or when you have Format On Save enabled. There are several reasons for this, and one is that there is no <code>cljfmt</code> config for it and leaving the closing comment un-tucked might give you troubles with CI pipelines that enforce some cljfmt config be followed. (Another reason is that it would be pretty hard to do on the whole document.)</p>","boost":5},{"location":"rich-comments/#special-formatting-disabled-for-trailing-rcf","title":"Special formatting disabled for trailing <code>:rcf</code>","text":"<p>If the Rich comment ends with <code>:rcf</code> (or an ignored form), the special formatting doesn't happen. So if you have:</p> <pre><code>(comment\n  (def foo\n:foo)\n  |\n  :rcf)\n</code></pre> <p>And hit tab, you will get:</p> <pre><code>(comment\n  (def foo\n    :foo)\n  |\n  :rcf)\n</code></pre>","boost":5},{"location":"rich-comments/#thinking-space-is-kept","title":"Thinking space is kept","text":"<p>The formatter will not remove newlines between the cursor and the closing bracket. So if you have entered a few lines to get \u201dthinking\u201d room:</p> <pre><code>(comment\n  (def foo\n:foo)\n\n|\n\n)\n</code></pre> <p>tab</p> <pre><code>(comment\n  (def foo\n    :foo)\n\n  |\n\n  )\n</code></pre>","boost":5},{"location":"rich-comments/#fold-when-done","title":"Fold when done","text":"<p>To fold the trailing paren automatically, place the cursor immediately outside (before or after) the form:</p> <pre><code>(comment\n  (def foo\n:foo))|\n</code></pre> <p>tab</p> <pre><code>(comment\n  (def foo\n    :foo))|\n</code></pre>","boost":5},{"location":"rich-comments/#enabled-by-default","title":"Enabled by default","text":"<p>You can disable this behavior with the setting: <code>calva.fmt.keepCommentTrailParenOnOwnLine</code>.</p>","boost":5},{"location":"rich-comments/#only-for-the-current-form","title":"Only for the Current Form","text":"<p>Note</p> <p>This treatment only applies to formatting of the current form. With fold when done as an exception.</p>","boost":5},{"location":"shadow-cljs/","title":"shadow-cljs","text":"<p>Calva supports most any JVM hosted ClojureScript environment (and some others, including SCI based, too), but shadow-cljs gets some special treatment to try make it extra convenient to use.</p> <p>With many shadow-cljs projects, Calva's connect project type shadow-cljs, is the right choice. Projects that use Leiningen or deps.edn can be used both with the Leiningen/deps.edn and shadow-cljs type, depending on configuration see below for more on this.</p>","boost":7},{"location":"shadow-cljs/#shadow-cljs-browser-quickstart","title":"shadow-cljs - browser quickstart","text":"<p>Here's how you start a shadow-cljs ClojureScript REPL and connect Calva with the shadow-cljs - browser quickstart example project:</p> <p>Prep:</p> <ol> <li>Clone the project to your machine and open its root folder in VS Code.</li> <li>Open a terminal and run <code>npm install</code></li> </ol> <p>Connect Calva:</p> <ol> <li>Run the command Calva: Start a Project REPL and Connect (a.k.a. Jack-in)</li> <li>Select project type shadow-cljs</li> <li>Select to start the build :app</li> <li>Select to connect to the build :app</li> <li>Wait for the build to complete</li> <li>Open http://localhost:8020/ in the browser</li> <li>Open browser.cljs file and load it in the REPL: Calva: Load/Evaluate Current File and Dependencies</li> </ol> <p>Now you can should be able to evaluate forms, e.g.:</p> <ul> <li>The current form or selection with ctrl+enter, or</li> <li>Top-level forms with alt/option+enter.</li> </ul> <p>(See Code Evaluation)</p>","boost":7},{"location":"shadow-cljs/#shadow-cljs-in-full-stack-projects","title":"shadow-cljs in full stack projects","text":"<p>shadow-cljs is a bit special in regards to Calva REPL connection. Mainly because you can start shadow-cljs and it's nREPL server in two ways:</p> <ol> <li>Using the shadow-cljs npm executable</li> <li>Via the Clojure REPL in your Leiningen or deps.edn project</li> </ol> <p>These options show up as project types when connecting or jacking in:</p> <ol> <li>Project type: shadow-cljs</li> <li>Project type: deps.edn + shadow-cljs or Leiningen + shadow-cljs</li> </ol> <p>The technical difference here is wether you let shadow-cljs start clojure/Leiningen (the first option) or if you let Calva do it (the second option). If you let Calva do it, Calva will then start the shadow-cljs watcher from the Clojure process. From a usage perspective the two approaches will result in different channeling of shadow-cljs output, e.g. test runner results. With the first option (the shadow-cljs project type), shadow-cljs output will be channeled to the Jack-in terminal. With the deps.edn/Leiningen option, that output will be channeled to the Output/REPL window.</p> <p>See shadow-cljs + Clojure with Calva: The basics for some more discussion on how the REPL connection works.</p> <p>shadow-cljs and <code>clojure</code> aliases</p> <p>The shadow-cljs project type will not prompt you for any aliases found in the <code>deps.edn</code> file. Usually you should provide such aliases in <code>shadow-cljs.edn</code> like <code>:deps {:aliases [...]}</code>. If, for whatever reason you can't provide the aliases that way, you can configure a Custom REPL Connect Sequence and provide the aliases as <code>menuSelections</code> -&gt; <code>cljAliases</code>.</p> <p>Leiningen + shadow-cljs middleware issue</p> <p>Please note that for Leiningen, the command line dependency injection of the shadow-cljs nrepl middleware doesn't work. You need to add it to your <code>project.clj</code>:</p> <pre><code>:repl-options {:nrepl-middleware [shadow.cljs.devtools.server.nrepl/middleware]}\n</code></pre>","boost":7},{"location":"shadow-cljs/#see-also","title":"See also:","text":"<ul> <li>Connect the REPL</li> <li>Custom REPL Connect Sequences</li> <li>shadow-cljs + Clojure with Calva: The basics</li> </ul>","boost":7},{"location":"sponsors/","title":"Calva Sponsors","text":"<p>Calva is open source and free to use. It is actively maintained during our free time, and it keeps improving. You can contribute in many different ways, one of which is sponsoring. You can sponsor Calva by directly sponsoring any of us.</p> <p>If you are working at a company which benefits from Calva's existence and continued development, please consider sponsoring at the Calva Gold Sponsor tier.</p> <p>Please see this statement from Cognitect about the importance of supporting open source developers.</p>","boost":7},{"location":"sponsors/#patrons","title":"Patrons","text":"The right kind of different","boost":7},{"location":"sponsors/#gold-sponsors","title":"Gold Sponsors","text":"Scale your growth on mobile MAKE. DO. SHIP.","boost":7},{"location":"sponsors/#silver-sponsors","title":"Silver Sponsors","text":"","boost":7},{"location":"sponsors/#clojurists-together","title":"Clojurists Together","text":"<p>Significant additions to Calva have been made possible by funding from Clojurists Together. And this has often been transformational for the whole project. Calva would not be where it is today without Clojurists Together.</p>","boost":7},{"location":"sponsors/#our-sponsoring-profiles","title":"Our Sponsoring Profiles","text":"<p>These are the sponsoring profiles for the active maintainers of Calva (a.k.a. The Calva Team).</p> <ul> <li>Peter Str\u00f6mberg</li> <li>Brandon Ringe</li> <li>Cora Sutton</li> <li>Lukas Domagala</li> <li>Rayat Rahman</li> </ul>","boost":7},{"location":"sponsors/#readme-visibility","title":"README visibility","text":"<p>There is also a sponsors section in the README of the Calva project (which means it is also displayed in the VS Code Extension Marketlace).</p>","boost":7},{"location":"syntax-highlighting/","title":"Calva Highlight","text":"<p>Calva takes care of syntax highlighting, and also provides some features not available through VS Code's highlighting mechanism. These extras include rainbow parens, sane bracket matching, and comment form dimming/highlighting.</p>"},{"location":"syntax-highlighting/#syntax-highlighting","title":"Syntax Highlighting","text":"<p>When using Calva, you are also using its TMLanguage grammar (the core mechanism VS Code uses for syntax highlighting).</p> <p>Our grammar tokenizes Clojure keywords as <code>constant.keyword.clojure</code>. Since it is pretty uncommon with keyword constants in the programming languages out there, your theme might not have a highlight defined for this scope. Try find a grammar that highlights keywords! If you are very fond of some theme lacking this, you can help it with a setting:</p> <pre><code>\"editor.tokenColorCustomizations\": {\n    \"[Default Dark+]\": {\n        \"textMateRules\": [\n            {\n                \"scope\": [\n                    \"constant.keyword.clojure\"\n                ],\n                \"settings\": {\n                    \"foreground\": \"#6fbfff\"\n                }\n            }\n        ]\n    }\n},\n</code></pre> <p>Instead of <code>Default Dark+</code> you should use your theme's name/key. And choose a color you like, of course.</p>"},{"location":"syntax-highlighting/#extra-highlighting","title":"Extra Highlighting","text":"<p>You are in charge of how brackets and comments are highlighted via the <code>calva.highlight.&lt;setting&gt;</code> settings:</p> Setting Meaning Example <code>enableBracketColors</code> Enable rainbow colors <code>true</code> <code>rainbowIndentGuides</code> Enable rainbow indent guides <code>true</code> <code>highlightActiveIndent</code> Highlight the active indent guide <code>true</code> <code>bracketColors</code> Which colors to use <code>[\"#000\", \"#999\"]</code> <code>cycleBracketColors</code> Whether same colors should be  reused for deeply nested brackets <code>true</code> <code>misplacedBracketStyle</code> Style of misplaced bracket <code>{ \"border\": \"2px solid #c33\" }</code> <code>matchedBracketStyle</code> Style of bracket pair highlight <code>{\"backgroundColor\": \"#E0E0E0\"}</code> <code>ignoredFormStyle</code> Style of <code>#_...</code> form <code>{\"textDecoration\": \"none; opacity: 0.5\"}</code> <code>commentFormStyle</code> Style of <code>(comment ...)</code> form <code>{\"fontStyle\": \"italic\"}</code> <p>Calva disables the VS Code built-in indent guides</p> <p>The VS Code built-in settings <code>editor.renderIndentGuides</code> and <code>editor.highlightActiveIndent</code> do not have any effect, since the former is switched off by the Clojure Defaults, mentioned above. Use Calva Highlight's <code>rainbowIndentGuides</code> and <code>highlightActiveIndent</code> instead. They are different from the built in ones in that they are independent, meaning you can choose to have active indent highlighted while the guides generally are not rendered (this is the default, even).</p> <p>VS Code bracket coloring vs Calva's</p> <p>Calva's bracket coloring is more Clojure aware than VS Code's built-in coloring. And also will chime better with Calva's indent guides. If you like to have bracket coloring outside Clojure code, by all means enable it. Calva's bracket coloring will \u201dover paint\u201d in Clojure files, when enabled. These settings work nicely:</p> <pre><code>\"calva.highlight.highlightActiveIndent\": true,\n\"editor.bracketPairColorization.enabled\": true,\n</code></pre> <p>The <code>calva.highlight.bracketColors</code> setting can be used to harmonize the coloring between VS Code and Calva.</p>"},{"location":"tao/","title":"The Tao of Calva","text":"<p>Calva, the spirit, gains much of its taste and color from the Cider it is distilled from, and the oak it is matured in. I started to wonder what it is that shapes Calva, the VS Code Clojure Extension. I should know, being the master distiller, right?. Indeed. Poking some at the question, I do find that I have some answers.</p> <p>Please read the following to learn what Calva is, and, to some extent, is not, about. Read it to get an idea about which path Calva is following, where we are headed with the project, and how you can contribute to the journey.</p>"},{"location":"tao/#why-calva","title":"Why Calva?","text":"<p>Calva's raison d\u00b4\u00eatre is to provide Visual Studio Code users with an easy to use and productive environment for Clojure and ClojureScript development. See the Why Calva? page for some evidence that we are succeeding.</p> <p>While Calva draws a lot of inspiration from CIDER, Cursive, Fireplace, and other Clojure development environments, it does not try to compete with them. Reading r/Clojure and elsewhere, it is easy to get the impression that the most common question is \"Which editor should I use for Clojure development?\u201d. I think a much more common question is \u201dHow do I use my favorite editor for Clojure development?\u201d. For VS Code users, that is where Calva should be a good choice.</p> <p>I also have an ambition to leverage VS Code for easing the path to Clojure. Given that it is the favorite editor for so many developers, it is important to have a good development environment in place on this platform, and to make it as easy to use as we possibly can, while also being productive and something that you want to stick with, once you are hooked on Clojure.</p> <p>That said, and therefore: For people who want to start out with Clojure, and do ask about what development environment would make it the most enjoyable, I'd like for Calva to be a really good option, an option so good that Clojurians feel they can recommend it.</p>"},{"location":"tao/#design-goals","title":"Design Goals","text":"<p>Calva should be easy to start with and productive enough to stick with. It should support Clojure Best Practices, and be pleasant and enjoyable to use. It should also be easy to hack on, and to contribute to. The ClojureScript story keeps getting more important. Calva should contribute to making the development experience with ClojureScript delightful.</p>"},{"location":"tao/#easy-to-start-with","title":"Easy to Start With","text":"<p>There are reasons as to why VS Code is so popular. Among those, one stands out to me: It is the most approachable code editor out there. There is nothing you need to learn when you start using it. The editor makes it obvious that you can start typing, deleting, cutting, pasting and undoing, without having to figure anything out. Then you learn how to bring up the command palette and get a boost few other environments can provide with such immediacy.</p> <p>A language extension for VS Code can leverage this, by recognizing that what's old is old, and that what's new should be as easy as possible to pick up. Coming to a new language, people bring with them a lot of expectations from the languages they are used to. This is also true for the editor support. Syntax highlighting and formatting should just work, as should documentation lookup, linting and other IDE commodities.</p> <p>Clojure brings some new concepts to the table. Chief among these: The REPL. It does take some time to grasp it. Calva needs to remove any obstacles it can when it comes to helping the user to reach the REPL, in order to help getting it, and start loving it.</p> <p>To help the users to quickly focus on Clojure, we provide a package that is all-inclusive, with few knobs to turn, and with sane defaults for the knobs that still need to be there.</p>"},{"location":"tao/#productive-enough-to-stick-with","title":"Productive Enough to Stick With","text":"<p>I think VS Code brings inspiration also when it comes to following up its excellent Getting Started story. You do not have to dig very deep under its surface to find that there is a lot more power to be unleashed. VS Code makes it easy to pick up more features as you get ready for it, and each little piece makes you more productive. To me, only Vim beats VS Code in this game.</p> <p>Most often there should be no contradiction between Easy to Start With and Productive. Quite the contrary. This story is mainly about being feature complete with the most important tools. As beginners start to pick up the first few features, they should be rewarded with finding more productive tools when they go looking for them. The VS Code way is Calva's way.</p>"},{"location":"tao/#pleasant-and-enjoyable","title":"Pleasant and Enjoyable","text":"<p>Enjoyable starts with that Calva shouldn't be an experience full of pains. I think Calva is living up to this first bar of enjoyability. The next step is making it delightful!</p> <p>Calva has two main assets it can leverage for being delightful to use: Clojure and VS Code:</p> <p>Clojure is plain wonderful and also has this totally awesome REPL thing. Wherever we can, Calva should use the REPL to make the editor spark and bring joy to the developer.</p> <p>VS Code is a sweet development environment, offering its power in a consistent way across languages. Even if Clojure is very special, most of Calva's features are surfaced in the ways that VS Code encourages. It makes for less to learn for the user, and most often also makes it easier to implement functionality.</p>"},{"location":"tao/#support-clojure-best-practices","title":"Support Clojure Best Practices","text":"<p>Mainly, I think Stuart Halloway is right about the REPL being best used from inside the files you are editing rather than from the prompt. It doesn't mean that Calva's REPL window should be neglected, but efforts should be directed such that the file editor REPL is our first way to improve the experience. Expect the Calva REPL window to get much less \u201din your face\u201d, than it is today, as the editor REPL gets stronger.</p> <p>Halloway also gives me some peace of mind with his reasoning of keeping a spartan setup. Calva does not need to pack every feature imaginable. If we can get the right features in place, in the right way, the mission is accomplished.</p> <p>Clojure is data centric. Calva should make it easy to examine data and how our code affects it. Today, this is not good enough when it comes to data structures larger than a few elements.</p> <p>Clojure is a LISP. Thus Structural Editing is possible, and TBH, desirable. Calva should support this and encourage it. There is little we can do about Parinfer not playing well with VS Code, but there is Paredit, and Paredit rocks! Calva's Paredit plays in the top league of Paredits, for this reason.</p>"},{"location":"tao/#made-from-the-produce-of-the-orchard","title":"Made from the Produce of the Orchard","text":"<p>Calva is distilled from CIDER, which in turn is brewed from the products of The Orchard. This makes a lot of Calva's features thin wrappers around cider-nrepl and related middleware. It also should mean that we strive for adding features by thinking \u201dThe Orchard\u201d first. If it lacks what we need, we should assist in providing it there. We need to up this game a bit from where we are today, I think.</p>"},{"location":"tao/#leveraging-clojure-lsp","title":"Leveraging clojure-lsp","text":"<p>Today, Calva draws a lot of its static power from clojure-lsp. As does a lot of other Clojure tooling out there. The Calva and the clojure-lsp teams work very nicely together, which is something we cherish and should take care to maintain.</p>"},{"location":"tao/#project-stewardship","title":"Project Stewardship","text":"<p>Here Calva takes inspiration from many Clojure related projects, and perhaps most so from CIDER,shadow-cljs, and clojure-lsp. Bozhidar Batsov, Thomas Heller, and Eric Dallo all lead their projects with clarity and with gusto. You can feel how they really care about their products and their users. They are there. They listen. They respond. And they relentlessly keep improving their products.</p> <p>So we are there. We listen. We respond. And we keep trying to improve Calva.</p> <p>The Calva team cares deeply about the user experience. That is a major part of why we do this. When implementing a new feature, or changing a feature, Ux is always the first thing on our mind. Personally, to keep that direction I often start with the documentation of the feature. Reading the documentation before implementation reveals a lot about if the Ux design is within the ballpark or not.</p> <p>We have limited time on our hands, however, and we must cut some corners. We can't afford to spend very much time in Ux design. Rather we will use our Ux intuition, iterate the documentation quickly, and be fast to get things out. Then we are responsive in tweaking those things, based on user feedback. This also has impact on general quality at times. We only can do so much QA, and it happens that some releases of Calva cause disruptions in people's workflow because of things we haven't thought of, or not found during our testing. Again, we try to be attentive to feedback and quick to fix. Apologies in advance for any inconveniences caused!</p> <p>A super major part of our love for Ux is that Calva should be serving its users. That's why we treat feedback as a gift, listen intently, and use the feedback as a major ingredient in shaping Calva.</p> <p>Calva develops from user feedback in more direct ways as well. It is quite astonishing how many people have decided to improve on it by hacking it to do some small or big thing differently. That's great! We should make sure Calva is super easy to contribute to. </p> <p>There has been quite a lot of work put into improving the development process. Starting to hack on Calva is just a few steps, taking less than three minutes from cloning to running a dev version in the VS Code debugger. We encourage contributions, from the tiniest typo to whole new features. And we are ready to spend time helping people get their contributions integrated.</p> <p>However, Calva can't be what everyone wants it to be, that would make it useless. It needs direction and aim. And it is we, the Calva Team, who are the stewards. We need to be in charge of what Calva is about, and what it is not about.</p>"},{"location":"tao/#the-road-ahead","title":"The Road Ahead","text":"<p>Tying back to Stuart Halloway, I don't think he means that spartan needs to also mean poor. The products he helps to bring to the market tell another story. VS Code and Clojure brought together has the capacity to create something amazingly rich and luxurious. And I want Calva to tap into that potential.</p> <p>On the Calva journey we will allow ourselves to change our minds about how things work. Calva is not a library. Its an interface between Clojure and human beings. Human beings can adapt. And they will need to enjoy adapting in order to enjoy Calva. \ud83d\ude04</p> <p>By now it should be clear that you can expect Calva to keep evolving, keep being tended and maintained, and keep getting ever more enjoyable to use. Lately we have been improving Calva pretty rapidly. It would be great to keep it up like that, but I think it is good to expect a more humble and sustainable pace.</p> <p>Calva is still quite new. A bit like freshly distilled Calvados. It will need time in those oak barrels to develop its full bouquet of flavors. And time is what we will give it. Our time, our creativity, and our passion.</p>"},{"location":"test-runner/","title":"Test Runner","text":"<p>Calva provides commands that make running your Clojure tests easier.</p> <p>Note</p> <p>Since the test commands utilize cider-nrepl, they only work with Clojure, not ClojureScript. See this issue for more details.</p>"},{"location":"test-runner/#test-commands","title":"Test Commands","text":"Command Shortcut Description Run All Tests <code>ctrl+alt+c shift+t</code> Runs all tests Run Failing Tests <code>ctrl+alt+c ctrl+t</code> Runs the tests that failed Run Tests for Current Namespace <code>ctrl+alt+c t</code> Runs the tests for the current namespace. If not a <code>-test</code> namespace, tests for the current namespace plus its corresponding <code>&lt;current-namespace&gt;-test</code> namespace will be run. Run Current Test <code>ctrl+alt+c ctrl+alt+t</code> Runs the test at the cursor. This includes a <code>defn</code> with a <code>:test</code> in its metadata, a <code>defn</code> defined in a <code>with-test</code>, and a <code>deftest</code>. Toggle between implementation and test - Switches the file between implementation and test, prompts to create a new file if not found."},{"location":"test-runner/#test-on-save","title":"Test on Save","text":"<p>You can enable the Calva setting \"Test on Save\" to have tests for the current namespace run on file save.</p>"},{"location":"test-runner/#vs-code-test-ui","title":"VS Code Test UI","text":"<p>Calva has experimental support for showing test results in VS Code's Test UI. You can enable this support by setting <code>calva.useTestExplorer</code> to <code>true</code>. When you enable this setting, the Testing icon will appear in the Testing tab of VS Code's Activity Bar.</p> <p>With this feature enabled you will be able to browse and run tests directly from the Testing tab.</p> <p>Please join the #calva channel on the Clojurians Slack if you have any feedback on this new feature.</p>"},{"location":"test-runner/#troubleshooting","title":"Troubleshooting","text":""},{"location":"test-runner/#tests-are-not-found","title":"Tests Are Not Found","text":"<p>Calva will not load namespaces in the REPL that you haven't loaded. This is so that you can be in control of what is loaded in the REPL. However, it also means that commands like Run All tests actually mean Run All Tests That are Loaded in the REPL, since the test-runner only runs tests that it knows about, i.e. are loaded in the REPL. Some developers choose to make sure all test namespaces are loaded as part of starting their REPL. Others register a custom REPL command for loading test namepaces. (Yet others use test-runners such as Cognitect's test-runner, Kaocha, poly test, or some other that runner allows for tests being run automatically, separate from the REPL used for development.)</p> <p>If you have tests in a test directory separate from your source directory, and those tests are not being found by the test runner, make sure the test directory is included in your paths. This will not be the case by default with a tools.deps (deps.edn) project. If your project is a tools.deps project, you can create an alias in your deps.edn file with <code>:extra-paths</code> that includes <code>\"test\"</code> (or the name of your test directory).</p> <pre><code>{:aliases {:dev {:extra-paths [\"test\"]}}}\n</code></pre>"},{"location":"test-runner/#changes-arent-taking-effect-when-running-tests","title":"Changes Aren't Taking Effect When Running Tests","text":"<p>In order for changes in code to take effect, you need to load the file or evaluate the changed code before running a test command. Prior to version 2.0.301, Calva would load the file for you when running some test commands, but that behavior was removed in favor of leaving control to the user, and to avoid a potential issue.</p> <p>Having added the above to your deps.edn, when you jack-in, choose the <code>:dev</code> alias and the <code>test</code> directory will be added to your paths, which will allow tests located in the directory to be found by the test runner.</p>"},{"location":"test-runner/#toggle-between-implementation-and-test-command-not-working-as-intended","title":"Toggle between implementation and test command not working as intended","text":"<p>This feature mostly works with projects that has leiningen style folder structure and makes some assumption about your folder structure and test file names.</p> <ul> <li>It assumes that the test files ends with <code>_test</code> prefix.</li> <li>It assumes that your implementation files are in <code>src</code> folder and the test files are in <code>test</code> folder.</li> </ul> <p>If you are using any non leiningen style folder structure, you may have to add source paths inside <code>.lsp/config.edn</code>.</p>"},{"location":"try-first/","title":"Something to Try First (After Connecting)","text":"<p>You should start with loading the file you are working with. Do this with Load/Evaluate Current File and its Requires/Dependencies, <code>ctrl+alt+c enter</code>.</p> <p>To get a feeling for evaluating code in the editor and get immediate response from the REPL try this:</p> <ul> <li>On a new line, type a <code>comment</code> form and put some code inside it:</li> </ul> <pre><code>(comment\n  (+ (* 2 2)\n      2)\n  (Math/abs -1)\n  (hello \"Calva REPL\")\n  (defn hello [s]\n    (str \"Hello \" s))\n  (range 10)\n  \"I \u2665\ufe0f Clojure\")\n</code></pre> <p>Then:</p> <ol> <li>Place the cursor behind the form <code>(* 2 2)</code> and issue the command Calva: Evaluate Current Form, <code>ctrl+enter</code>.<ul> <li>You should see the result being displayed inline. Press <code>esc</code> to dismiss it.</li> </ul> </li> <li>Now issue the command Evaluate Current Top Level Form (defun), <code>alt+enter</code>.<ul> <li>You should see the whole form <code>(+ (* 2 2) 2)</code> getting highlighted and the result of that expression being displayed inline.</li> </ul> </li> <li>Evaluate each form inside the comment form using the Top Level command.<ul> <li>You should see each one of them evaluated.</li> <li>Evaluating the <code>(hello \"Calva REPL\")</code> form before the <code>(defn hello...</code> form should result in an error/exception. A stacktrace is then printed in the output window</li> <li>Try it again after having evaluated the <code>defn</code>form.</li> </ul> </li> </ol> <p>Demo:</p> <p></p>"},{"location":"try-first/#how-does-this-work","title":"How does this work?","text":"<p>Calva has this notion about the current form. Issue the Evaluate Current Form command, with the cursor placed in different locations to get a feeling for how the current form is determined.</p> <p>There is also a concept about the current top level form. Good for evaluating  various <code>def</code>s <code>defn</code>, <code>defthis</code>, <code>defthat</code>. With your cursor placed anywhere inside such a form.</p> <p>The Top Level command also works inside <code>(comment ...)</code> forms, treating the <code>comment</code> as creating a new top level context. It is good for in-file code experimentation.</p>"},{"location":"try-first/#see-also","title":"See also","text":"<ul> <li>Calva Top 10 Commands.</li> <li>Code Evaluation Tips</li> </ul>"},{"location":"vim/","title":"Calva and the VIM Extension","text":"<p>First thing first. The VIM Extension and Calva has a history of friction between them. Less so these days, but you might still encounter some rough edges. Please don't hesitate to reach out to the Calva team, as we might be able to fix things if only we are aware of them.</p>"},{"location":"vim/#key-bindings","title":"Key bindings","text":"<p>In general Calva's default key bindings are not very VI-ish.</p>"},{"location":"vim/#expand-selection-on-mac","title":"Expand selection on Mac","text":"<p>On Mac, Calva binds expand selection to <code>ctrl+w</code>. This conflicts with the VIM Extension's default mapping of window splitting shortcuts. You'll need to remap it either with Calva or with the VIM Extension.</p>"},{"location":"vim/#the-esc-key","title":"The <code>esc</code> key","text":"<p>While showing inline evaluation results, Calva binds the <code>esc</code> key to dismiss the display of inline results. If you want to be able to use the <code>esc</code> key to enter command mode while inline results are showing, you'll need to rebind Calva's command for dismissing the inline results.</p>"},{"location":"vim/#remap-calvas-clearinlineresults","title":"Remap Calva's <code>clearInlineResults</code>","text":"<ul> <li>Open the Keyboard Shortcuts JSON file from the Command Palette</li> <li>Disable <code>clearInlineResults</code> and remap the command e.g.</li> </ul> <pre><code>// Place your key bindings in this file to override the defaults\n[\n  {\n    \"key\": \"escape\",\n    \"command\": \"-calva.clearInlineResults\"\n  },\n  {\n    \"key\": \"shift+escape\",\n    \"command\": \"calva.clearInlineResults\",\n    \"when\": \"editorTextFocus &amp;&amp; !editorHasMultipleSelections &amp;&amp; !editorReadOnly &amp;&amp; !hasOtherSuggestions &amp;&amp; !suggestWidgetVisible &amp;&amp; editorLangId == 'clojure'\"\n  }\n]\n</code></pre> <p>If you run into issues, refer to the commands in the default Keyboard Shortcuts JSON file.</p>"},{"location":"vim/#remap-vims-insert-mode","title":"Remap Vim's Insert Mode","text":"<p>Remap vim's insert mode keybinding to go into command mode by adding the following to your user settings:</p> <pre><code>\"vim.insertModeKeyBindings\": [\n    {\n        \"before\": [\"j\", \"k\"],\n        \"after\": [\"&lt;esc&gt;\"]\n    }\n]\n</code></pre> <p>(Change <code>before</code> to whatever keybinding you are comfortable with!)</p>"},{"location":"vim/#vim-fireplace-ish-keybindings","title":"Vim Fireplace-ish keybindings","text":"<p>You can add these keybindings to your <code>init.vim</code> if you are using the VSCode Neovim extension. It is inspired by and tries to emulate the keybindings found in vim-fireplace which is the most popular vim plugin for Clojure.</p> <pre><code>nmap cqp :call VSCodeNotify('calva.jackIn')&lt;CR&gt;\nnmap cqq :call VSCodeNotify('calva.disconnect')&lt;CR&gt;\nnmap cpr :call VSCodeNotify('calva.loadFile')&lt;CR&gt;\nnmap cpR :call VSCodeNotify('calva.loadNamespace')&lt;CR&gt;\nnmap cpp :call VSCodeNotify('calva.evaluateSelection')&lt;CR&gt;\nnmap cqc :call VSCodeNotify('calva.evalCurrentFormInREPLWindow')&lt;CR&gt;\n</code></pre> <p>Unfortunately these key combinations will not work in the normal VIM extension as <code>c</code> is an operator key and cannot be remapped. This is a call for someone to share their VIM re-mappings.</p>"},{"location":"when-clauses/","title":"Calva When Clause Contexts","text":"<p>When clause contexts is a powerful customization mechanism in VS Code. The most common use for end users is with keyboard shortcut bindings. Extensions can provide their own. The following contexts are available with Calva:</p> <ul> <li><code>calva:keybindingsEnabled</code>: a master switch that you find in the settings</li> <li><code>paredit:keyMap</code>: <code>strict</code>, <code>original</code>, or <code>none</code> from the corresponding Calva setting (see Paredit)</li> <li><code>calva:connected</code>: <code>true</code> when Calva is connected to a REPL (there is also <code>calva:connecting</code> || <code>calva:launching</code>)</li> <li><code>calva:outputWindowActive</code>: <code>true</code> when the Output/REPL window has input focus</li> <li><code>calva:replHistoryCommandsActive</code>: <code>true</code> when the cursor is in the Output/REPL window at the top level after the last prompt</li> <li><code>calva:replWindowSubmitOnEnter</code>: <code>true</code> when the cursor is adjacent after the last top level form in the Output/REPL window</li> <li><code>calva:cursorInString</code>: <code>true</code> when the cursor/caret is in a string or a regexp</li> <li><code>calva:cursorInComment</code>: <code>true</code> when the cursor is in, or adjacent to a line comment</li> <li><code>calva:cursorBeforeComment</code>: <code>true</code> when the cursor is adjacent before a line comment</li> <li><code>calva:cursorAfterComment</code>: <code>true</code> when the cursor is adjacent after a line comment</li> <li><code>calva:cursorAtStartOfLine</code>: <code>true</code> when the cursor is at the start of a line including any leading whitespace</li> <li><code>calva:cursorAtEndOfLine</code>: <code>true</code> when the cursor is at the end of a line including any trailing whitespace</li> </ul>"},{"location":"why-calva/","title":"Why Calva?","text":"<p>The main reason you would choose Calva for your Clojure and/or ClojureScript coding is that you want to use Visual Studio Code. Calva provides VS Code users with a comprehensive set of features to keep you productive and make it easy to follow Clojure coding best practices. This also means that if your choice of editor is not made yet, we think you should give VS Code and Calva a try.</p> <p>While Calva is a good choice for professional and experienced Clojure developers, great care has been taken in making Calva a really good choice for beginners of Clojure as well.</p> <p>We who make Calva are actively stewarding, maintaining, documenting and supporting it. We are also very active Clojure (and Calva) users, participating in the community. Clojure is dear to us, a lot because it keeps programming fun and rewarding.</p> <p>Calva has very happy users! Check out the Programming Languages section on the Visual Studio Code Marketplace, sorted by rating:</p> <p></p> <p>Recently there was a thread over at ClojureVerse, asking about how Calva Compares to Emacs with CIDER. It is well worth reading. We would like to highlight the answer by Nick Cernis, which focuses on Calva. We'll even quote parts of it. \ud83d\ude0d</p>"},{"location":"why-calva/#nick-cernis-on-clojureverse","title":"Nick Cernis on ClojureVerse","text":"<p>My advice to anyone starting their Clojure journey who is unsure about what editor to use:</p> <ul> <li>Pick something today and start writing Clojure.</li> <li>Probably pick an editor you are familiar with already.</li> <li>If you\u2019re not familiar with any editor yet or you don\u2019t have a strong allegiance to one, choose VS Code and Calva.</li> <li>Switch to something else only if you encounter persistent annoyances that you can\u2019t remove with plugins, code/config changes, help from the community, or more sleep.</li> </ul> <p>I now use VS Code with Calva every day but went through a long journey trying almost every other editor and plugin combo first. I switched from Emacs to VS Code, which might make my perspective different to others here.</p> <p>\u2026</p> <p>I started with the jaded assumption that VS Code was probably bad because it's built by committee at Microsoft on a web-tech based Electron stack, only to find that it succeeds in embodying the spirit of a \u201chacker's editor\u201d more than even Emacs does in many ways: </p> <p>\u2026</p> <p>On the benefits of Calva:</p> <ul> <li> <p>Of all the amazing Clojure community projects, Calva seems most likely to encourage new users to try Clojure and ClojureScript. A lot of developers use VS Code. It\u2019s been tricky to convince frontend developer friends to try ClojureScript, but at least they don\u2019t have the excuse that they\u2019ll need to switch editors to even try it now. I think as a community we should try to support the projects that encourage Clojure\u2019s adoption and ease of use, including by using those products ourselves.</p> </li> <li> <p>Calva provides a better first-time experience than any other editor/plugin combo whether you\u2019re new to Clojure or not. You can install the plugin and be chatting with your REPL in under a minute without any knowledge of Elisp or VimScript/Lua or how to configure Run Configurations in IntelliJ.</p> </li> <li>The default key bindings are good and the commands are easily discoverable.</li> <li>For its age it\u2019s surprisingly feature rich.</li> </ul>"},{"location":"why-calva/#100-five-star-marketplace-reviews","title":"100% Five-star Marketplace Reviews","text":"<p>We are super proud of the Calva reviews on the Visual Studio Code Marketplace. Please read them all. \ud83d\ude04 Here's a selection that we think captures what we focus on in when developing Calva:</p> <p>\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f Calva has become an essential part of my Clojure workflow.</p> <p>It's an incredible piece of work by the team behind it.</p> <p>Sean Corfield</p> <p>\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f Calva hits the sweet spot of being both approachable for new users and powerful for seasoned ones.</p> <p>The creators/maintainers are fantastic individuals that care deeply about streamlining the user experience, and it shows.</p> <p>Good stuff, check it out.</p> <p>Clay Hopperdietzel</p> <p>\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f I switched from IntelliJ / Cursive to VS Code and Calva and it's been amazing.</p> <p>...</p> <p>That is the biggest thing I can say for Calva, it just works. I was never a fan of VS Code before, but VS Code + Calva for Clojure is now my favorite language / IDE experience.</p> <p>Plus, the #calva on the clojurians slack is brilliant, always someone there to help if you have issues (although any issue I've had has been squarely on me, and never Calva itself).</p> <p>I often feel we live in an age where so much software is badly written, without care, slow, buggy and just generally awful. Calva is the complete opposite. I think the maintainers want to, and have, made a wonderful piece of software for Clojure developers.</p> <p>Stuart Stein</p> <p>\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f This is great, and makes VS Code a truly viable IDE/editor for clojure development.</p> <p>It already has great REPL support (including inline evaluation), an extensive Paredit implementation, and excellent linting (care of the bundled clj-kondo). Calva is being improved on at an impressive clip by maintainers who appear solidly committed to its ongoing development. It's well-documented, and manages to be both approachable and capable.</p> <p>A no-brainer if you're already a VS Code user, and well worth a look if you're not.</p> <p>Crispin Bennett</p> <p>\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f I'm using Calva now for a few months and I'm loving it.</p> <p>I joined the Slack channel about 2 wks ago and I must say that I'm very impressed by how active and responsive this community is. Already 2 of my issues fixed and I really like Calva (and the extensions it uses!).</p> <p>These are professional people and they make me very happy!</p> <p>Uitbeijerse, E (Eric)</p>"},{"location":"workspace-layouts/","title":"Workspace Layouts","text":"<p>Project directory layouts can vary quite a lot. From the \u201dtemplate\u201d projects where the Clojure project files are at the root, to, well, let's just say that the project files are not always at the root. And sometimes there is more than one project (read here how to get clojure-lsp support with a Leiningen project in a subfolder).</p> <p>Calva only really supports working with one project at a time per VS Code window. Here's a short guide for some different setups:</p> <ol> <li>You have one project in the workspace, the project files are in there somewhere.<ul> <li>Use a regular VS Code \u201dfolder window\u201d or a Workspace proper, both will totally work.</li> </ul> </li> <li>You have more than one project in the repository, but only really work with one at a tine.<ul> <li>Use a Workspace proper and add the different project directories as separate Workspace Folders.</li> <li>You can only jack-in/connect to one project at a time.</li> </ul> </li> <li>You have more than one project in the repository, and need to work with them in parallell.<ul> <li>Open each project you want to work with in a separate VS Code window.</li> </ul> </li> </ol>"},{"location":"workspace-layouts/#one-folder-two-windows","title":"One Folder - Two Windows?","text":"<p>As is mentioned in the Calva Jack-In Guide, if you have a full stack project using a Clojure backend and a shadow-cljs frontend, you will need to open the same project in two separate VS Code windows, one for the backend and one for the frontend. This is how you can do that:</p> <ol> <li>Open a new VS Code window.</li> <li>Select File-&gt;Add Folder to Workspace.... Save the workspace as, say, <code>Server.code-workspace</code>.</li> <li>Open a new VS Code window.</li> <li>Select File-&gt;Add Folder to Workspace.... Save the workspace as, say, <code>Client.code-workspace</code>.</li> </ol> <p>Now, whenever you want to Jack-in to the backend and/or frontend, do it from the Server and/or Client workspace, respectively.</p>"},{"location":"wsl/","title":"Calva \u2764\ufe0f WSL","text":"<p>The use of Calva with WSL (Windows Subsystem for Linux) is fully supported through the Remote - WSL extension. Simply install the extension and open your project with one of the <code>Remote-WSL</code> commands. Calva will run directly in the WSL environment and no further configuration is required.</p>"},{"location":"wsl/#steps-involved","title":"Steps Involved","text":"<ol> <li>Enable WSL</li> <li>Install Ubuntu in WSL</li> <li>Install Java in WSL</li> <li>Install latest Clojure in WSL</li> <li>Install the Remote - WSL extension in VS Code</li> <li>Launch remote window</li> <li>Install Calva (gets installed into the WSL instance)</li> <li>Work away</li> </ol> <p>See also Remote Development.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-\\._]","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome!","text":"<p>Calva is an integrated, REPL powered, development environment for enjoyable and productive Clojure and ClojureScript programming in Visual Studio Code. It is feature rich and turnkey. A lot of effort has been put into making Calva a good choice if you are new to Clojure. Calva is open source and free to use.</p>"},{"location":"#getting-started","title":"Getting Started","text":"<p>Let's start a REPL!. \ud83d\ude80 Also see Get Started with Clojure</p>"},{"location":"#how-to-contribute-to-calva","title":"How to Contribute to Calva?","text":"<p>I'm glad you asked! Please see How to Contribute and The Tao of Calva</p>"},{"location":"#calva-patrons","title":"Calva Patrons","text":"The right kind of different"},{"location":"#calva-gold-sponsors","title":"Calva Gold Sponsors \u2665\ufe0f","text":"Scale your growth on mobile MAKE. DO. SHIP. <p>Please see this statement from Cognitect about the importance of supporting open source developers.</p> <p>See Sponsors for information about sponsoring Calva.</p> <p>If your Company benefits from Calva's existence and you see it as an important in the Clojure and ClojureScript ecosystem. please consider sponsoring!</p>"},{"location":"#features","title":"Features","text":"<p>Calva includes inline code evaluation, structural editing, code formatting, code navigation, a debugger, linting, syntax highlighting, Clojure aware rainbow brackets, a test runner, refactoring support, and more. </p>"},{"location":"#have-questions-and-feedback-need-help","title":"Have Questions and Feedback? Need Help?","text":"<p>Easiest way is to chat with us and other Calva users. Please join the #calva channel on the Clojurians Slack. If you haven't joined that slack workspace, you can get an invite here.</p> <p>If you're a beginner to Clojure(Script), the #beginners channel of the Clojurians Slack is very active and helpful.</p>"},{"location":"#please-star-the-calva-repo","title":"Please star the Calva repo!","text":"<p>Happy coding!</p>"},{"location":"api/","title":"The Calva Extension API","text":"<p>Calva exposes an API for use from other VS Code extensions (such as Joyride). The API is in an experimental state, while we are figuring out what is a good shape for this API. It is also rather small, and will grow to expose more of Calva's functionality.</p>","boost":7},{"location":"api/#accessing","title":"Accessing","text":"<p>To access the API the Calva extension needs to be activated. The API is exposed under the <code>v1</code> key on the extension's <code>exports</code>, and split up into submodules, like <code>repl</code>, and <code>ranges</code>.</p> <p>When using Joyride you can use its unique <code>require</code> API, for which one of the benefits is better lookup IDE support. When using the API from regular ClojureScript, you'll pick it up from the Calva extension instance. (Which you can do from Joyride as well, but why would you?). Here is how you access the API, with an example of usage as a bonus:</p> JoyrideClojureScriptJavaScript <pre><code>(ns ... (:require [\"ext://betterthantomorrow.calva$v1\" :as calva]))\n;; OR\n(require '[\"ext://betterthantomorrow.calva$v1\" :as calva])\n\n(calva/repl.currentSessionKey) =&gt; \"cljs\" ; or \"clj\", depending\n</code></pre> <pre><code>(def calvaExt (vscode/extensions.getExtension \"betterthantomorrow.calva\"))\n\n(def calva (-&gt; calvaExt\n             .-exports\n             .-v1\n             (js-&gt;clj :keywordize-keys true)))\n\n((get-in calva [:repl :currentSessionKey])) =&gt; \"cljs\" ; or \"clj\", depending\n</code></pre> <pre><code>const calvaExt = vscode.extensions.getExtension(\"betterthantomorrow.calva\");\n\nconst calva = calvaExt.exports.v1;\n\nconst sessionKey = calva.repl.currentSessionKey()\n</code></pre>","boost":7},{"location":"api/#repl","title":"<code>repl</code>","text":"<p>The <code>repl</code> module provides access to Calva's REPL connection.</p>","boost":7},{"location":"api/#replcurrentsessionkey","title":"<code>repl.currentSessionKey()</code>","text":"<p>Use <code>repl.currentSessionKey()</code> find out which REPL/session Calva's REPL is currently connected to (depends on the active file). Returns either <code>\"clj\"</code>, or <code>\"cljs\"</code>, or <code>nil</code> if no REPL is connected.</p> JoyrideClojureScriptJavaScript <pre><code>(def session-key (calva/repl.currentSessionKey))\n</code></pre> <pre><code>(def session-key ((get-in [:repl :currentSessionKey] calvaApi)))\n</code></pre> <pre><code>const sessionKey = calva.repl.currentSessionKey()\n</code></pre>","boost":7},{"location":"api/#replevaluatecode","title":"<code>repl.evaluateCode()</code>","text":"<p>This function lets you evaluate Clojure code through Calva's nREPL connection. Calling it returns a promise that resolves to a <code>Result</code> object. It's signature looks like so (TypeScript):</p> <pre><code>export async function evaluateCode(\n  sessionKey: 'clj' | 'cljs' | 'cljc' | undefined,\n  code: string,\n  ns = 'user',\n  output?: {\n    stdout: (m: string) =&gt; void;\n    stderr: (m: string) =&gt; void;\n  },\n  opts = {}\n): Promise&lt;Result&gt;;\n</code></pre> <p>Where <code>Result</code> is:</p> <pre><code>type Result = {\n  result: string;\n  ns: string;\n  output: string;\n  errorOutput: string;\n};\n</code></pre> <p>As you can see, the required arguments to the function are <code>sessionKey</code> and <code>code</code>. <code>sessionKey</code> should be <code>\"clj\"</code>, <code>\"cljs\"</code>, <code>\"cljc\"</code>, or <code>undefined</code> depending on which of Calva's REPL sessions/connections that should be used. It will depend on your project, and how you connect to it, which session keys are valid. Use <code>cljc</code> to request whatever REPL session <code>\"cljc\"</code> files are connected to. Use <code>undefined</code> to use the current REPL connection Calva would use (depends on which file is active).</p> <p>An example:</p> JoyrideClojureScriptJavaScript <pre><code>(-&gt; (p/let [evaluation (calva/repl.evaluateCode \"clj\" \"(+ 2 40)\")]\n      (println (.-result evaluation)))\n    (p/catch (fn [e]\n               (println \"Evaluation error:\" e))))\n</code></pre> <pre><code>(def evaluate (get-in [:repl :evaluateCode] calvaApi))\n(-&gt; (p/let [evaluation (evaluate \"clj\" \"(+ 2 40)\")]\n      (println (.-result evaluation)))\n    (p/catch (fn [e]\n               (println \"Evaluation error:\" e))))\n</code></pre> <pre><code>try {\n  const evaluation = await calvaApi.repl.evaluateCode(\"clj\", \"(+ 2 40)\");\n  console.log(evaluation.result);\n} catch (e) {\n  console.error(\"Evaluation error:\", e);\n}\n</code></pre>","boost":7},{"location":"api/#handling-output","title":"Handling Output","text":"<p>The <code>output</code> member on the <code>Result</code> object will have any output produced during evaluation. (The <code>errorOutput</code> member should contain error output produced, but currently some Calva bug makes this not work.) By default the stdout and stderr output is not printed anywhere.</p> <p>If you want to do something with either regular output or error output during, or after, evaluation, you'll need to provide the <code>output</code> argument to <code>evaluateCode()</code>. (The <code>stderr</code> callback function works, so this is the only way to get at any error output, until the above mentioned Calva bug is fixed.)</p> <p>An example:</p> JoyrideClojureScriptJavaScript <pre><code>(def oc (joyride.core/output-channel)) ;; Assuming Joyride is used\n(def evaluate (fn [code]\n                (calva/repl.evaluateCode\n                 \"clj\"\n                 code\n                 \"user\"\n                 #js {:stdout #(.append oc %)\n                      :stderr #(.append oc (str \"Error: \" %))})))\n\n(-&gt; (p/let [evaluation (evaluate \"(println :foo) (+ 2 40)\")]\n      (.appendLine oc (str \"=&gt; \" (.-result evaluation))))\n    (p/catch (fn [e]\n               (.appendLine oc (str \"Evaluation error: \" e)))))\n</code></pre> <pre><code>(def oc (joyride.core/output-channel)) ;; Assuming Joyride is used\n(def evaluate (fn [code]\n                ((get-in [:repl :evaluateCode] calvaApi)\n                 \"clj\"\n                 code\n                 \"user\"\n                 #js {:stdout #(.append oc %)\n                      :stderr #(.append oc (str \"Error: \" %))})))\n\n(-&gt; (p/let [evaluation (evaluate \"(println :foo) (+ 2 40)\")]\n      (.appendLine oc (str \"=&gt; \" (.-result evaluation))))\n    (p/catch (fn [e]\n               (.appendLine oc (str \"Evaluation error: \" e)))))\n</code></pre> <pre><code>const evaluate = (code) =&gt;\n  calvaApi.repl.evaluateCode(\"clj\", code, \"user\", {\n    stdout: (s) =&gt; {\n      console.log(s);\n    },\n    stderr: (s) =&gt; {\n      console.error(s);\n    },\n  });\n\ntry {\n  const evaluation = await evaluate(\"(println :foo) (+ 2 40)\");\n  console.log(\"=&gt;\", evaluation.result);\n} catch (e) {\n  console.error(\"Evaluation error:\", e);\n}\n</code></pre>","boost":7},{"location":"api/#ranges","title":"<code>ranges</code>","text":"<p>The <code>ranges</code> module contains functions for retreiving vscode.Ranges and text for pieces of interest in a Clojure document.</p> <p>All functions in this module have the following TypeScript signature:</p> <pre><code>(editor = vscode.window.activeTextEditor, position = editor?.selection?.active) =&gt; [vscode.Range, string];\n</code></pre> <p>I.e. they expect a vscode.TextEditor \u2013 defaulting to the currently active editor \u2013 and a vscode.Position \u2013 defaulting to the current active position in the editor (or the first active position if multiple selections/positions exist, and will return a tuple with the range, and the text for the piece of interest requested.</p> <p>Custom REPL Commands</p> <p>The <code>ranges</code> function have corresponding REPL Snippets/Commands substitution variables. It is the same implementation functions used in both cases.</p> <p>The functions available are:</p>","boost":7},{"location":"api/#rangescurrentform","title":"<code>ranges.currentForm()</code>","text":"<p>Retrieves information about the current form, as determined from the editor and position.</p> <p>Corresponding REPL Snippet variable: <code>$current-form</code>.</p> <p>See also about Calva's Current Form on YouTube.</p>","boost":7},{"location":"api/#rangescurrentenclosingform","title":"<code>ranges.currentEnclosingForm()</code>","text":"<p>The list/vector/etcetera form comtaining the current form.</p> <p>Corresponding REPL Snippet variable: <code>$enclosing-form</code>.</p>","boost":7},{"location":"api/#rangescurrenttoplevelform","title":"<code>ranges.currentTopLevelForm()</code>","text":"<p>The current top level form. Outside <code>(comment ...)</code> (Rich comments) forms this is most often (<code>(def ...), (defgn ...)</code>, etcetera. Inside Rich comments it will be the current immediate child to the <code>(comment ...)</code> form.</p> <p>Corresponding REPL Snippet variable: <code>$top-level-form</code>.</p>","boost":7},{"location":"api/#rangescurrentfunction","title":"<code>ranges.currentFunction()</code>","text":"<p>The current function, i.e. the form in \u201dcall position\u201d of the closest enclosing list.</p> <p>Corresponding REPL Snippet variable: <code>$current-fn</code>.</p>","boost":7},{"location":"api/#rangescurrenttopleveldef","title":"<code>ranges.currentTopLevelDef()</code>","text":"<p>The symbol being defined by the current top level form. NB: Will stupidly assume it is the second form. I.e. it does not check that it is an actual definition, and will often return nonsense if used in Rich comments.</p> <p>Corresponding REPL Snippet variable: <code>$top-level-defined-symbol</code>.</p>","boost":7},{"location":"api/#example-rangescurrenttoplevelform","title":"Example: <code>ranges.currentTopLevelForm()</code>","text":"JoyrideClojureScriptJavaScript <pre><code>(let [[range text] (calva/ranges.currentTopLevelForm)]\n  ...)\n</code></pre> <pre><code>(let [[range text] ((get-in [:ranges :currentTopLevelForm]))]\n  ...)\n</code></pre> <pre><code>const [range, text] = ranges.currentTopLevelForm();\n</code></pre>","boost":7},{"location":"api/#editor","title":"<code>editor</code>","text":"<p>The <code>editor</code> module has facilites (well, a facility, so far) for editing Clojure documents.</p>","boost":7},{"location":"api/#editorreplace","title":"<code>editor.replace()</code>","text":"<p>With <code>editor.replace()</code> you can replace a range in a Clojure editor with new text. The arguments are:</p> <ul> <li><code>editor</code>, a <code>vscode.TextEditor</code></li> <li><code>range</code>, a <code>vscode.Range</code></li> <li><code>newText</code>, a string</li> </ul> JoyrideJavaScript <pre><code>(-&gt; (p/let [top-level-form-range (first (calva/ranges.currentTopLevelForm))\n            _ (calva/editor.replace vscode/window.activeTextEditor top-level-form-range \"Some new text\")]\n      (println \"Text replaced!\"))\n    (p/catch (fn [e]\n               (println \"Error replacing text:\" e))))\n</code></pre> <pre><code>const topLevelRange = calvaApi.ranges.currentTopLevelForm();\ncalva.editor.replace(topLevelRange, \"Some new text\")\n  .then((_) =&gt; console.log(\"Text replaced!\"))\n  .catch((e) =&gt; console.log(\"Error replacing text:\", e));\n</code></pre>","boost":7},{"location":"api/#document","title":"<code>document</code>","text":"<p>The <code>document</code> module provides access to the Clojure/Calva aspects of VS Code <code>TextDocument</code>s.</p>","boost":7},{"location":"api/#documentgetnamespacedocument-vscodetextdocument-string","title":"<code>document.getNamespace(document?: vscode.TextDocument): string</code>","text":"<p><code>document.getNamespace()</code> returns the namespace of a document.</p> <ul> <li><code>document</code>, a <code>vscode.TextDocument</code> (defaults to the current active document)</li> </ul> <p>Example usage. To evaluate some code in the namespace of the current document:</p> JoyrideJavaScript <pre><code>(calva/repl.evaluateCode \"clj\" \"(+ 1 2 39)\" (calva/document.getNamespace))\n</code></pre> <pre><code>calva.repl.evaluateCode(\"clj\",  \"(+ 1 2 39)\", calva.document.getNamespace());\n</code></pre>","boost":7},{"location":"api/#documentgetnamespaceandnsformdocument-vscodetextdocument-ns-string-nsform-string","title":"<code>document.getNamespaceAndNsForm(document?: vscode.TextDocument): [ns: string, nsForm: string]</code>","text":"<p><code>document.getNamespaceAndNsForm()</code> returns the namespace and the <code>ns</code> form of a document as a tuple.</p> <ul> <li><code>document</code>, a <code>vscode.TextDocument</code> (defaults to the current active document)</li> </ul> <p>Example usage. To evaluate the <code>ns</code> form of the current document:</p> JoyrideJavaScript <pre><code>(calva/repl.evaluateCode \"clj\" (second (calva/document.getNamespaceAndNsForm)))\n</code></pre> <pre><code>calva.repl.evaluateCode(\"clj\", calva.document.getNamespaceAndNsForm()[1]);\n</code></pre>","boost":7},{"location":"api/#pprint","title":"<code>pprint</code>","text":"<p>The <code>pprint</code> module lets you pretty print Clojure code/data using Calva's pretty printing engine (which in turn uses zprint).</p>","boost":7},{"location":"api/#pprintprettyprint","title":"<code>pprint.prettyPrint()</code>","text":"<p>Use <code>pprint.prettyPrint()</code> to pretty print some Clojure data using your Calva pretty printing options. It accepts these arguments:</p> <ul> <li><code>text</code>, a <code>string</code> with the text to pretty print</li> <li><code>options</code>, a JavaScript object with pretty printing options, this is optional and will default to the current settings.</li> </ul> <p>The function is synchronous and returns the prettified text.</p> JoyrideJavaScript <pre><code>(println (calva/pprint.prettyPrint \"Some text\")))\n</code></pre> <pre><code>console.log(calvaApi.pprint.prettyPrint();\n</code></pre>","boost":7},{"location":"api/#pprintprettyprintingoptions","title":"<code>pprint.prettyPrintingOptions()</code>","text":"<p>Use to get the current pretty printint options:</p>","boost":7},{"location":"api/#vscode","title":"<code>vscode</code>","text":"<p>In the its <code>vscode</code> submodule, Calva exposes access to things from its own <code>vscode</code> module instance. It gets important in some situations.</p>","boost":7},{"location":"api/#vscoderegisterdocumentsymbolprovider","title":"<code>vscode.registerDocumentSymbolProvider()</code>","text":"<p>This is the <code>[vscode.languages](https://code.visualstudio.com/api/references/vscode-api#languages).registerDocumentSymbolProvider()</code> function from the Calva extension. Use it if you want to provide symbols for Clojure files together with the ones that Calva provides. (If you use the <code>vscode.languages.registerDocumentSymbolProvider()</code> function from your extension (or Joyride) you will provide a separate group.)</p> JoyrideClojureScriptJavaScript <pre><code>(-&gt; (joyride/extension-context)\n  .-subscriptions\n  (.push (calva/vscode.registerDocumentSymbolProvider ...)))\n</code></pre> <pre><code>(-&gt; yourExtensionContext\n  .-subscriptions\n  (.push ((get-in calva [:vscode :registerDocumentSymbolProvider]) ...)))\n</code></pre> <pre><code>yourExtensionContext.subscriptions.push(calva.vscode.registerDocumentSymbolProvider(...));\n</code></pre> <p>Deprecation candidate</p> <p>VS Code is still creating a separate group, just with the same name as Calva's, so this API is not good for anything, and we will probably remove it.</p>","boost":7},{"location":"api/#feedback-welcome","title":"Feedback Welcome","text":"<p>Please let us know how you fare using this API. Either in the #calva or #joyride channels on Slack or via the issues/discussions sections on the repositories. (Whichever seems to apply best.)</p>","boost":7},{"location":"async-out/","title":"Viewing Async Output While Working On Node Projects with <code>shadow-cljs</code>","text":"<p>When working on NodeJS projects with <code>shadow-cljs</code> and Calva, async output does not always appear in the Calva output window. To work around this problem, follow these steps:</p> <ol> <li>Run the command \"Calva: Copy Jack-in Command Line to Clipboard\", then paste the command in a terminal and run it.</li> <li>Wait for the message <code>shadow-cljs - nREPL server started on port &lt;some-port&gt;</code></li> <li>Issue the command Calva: Connect to a running REPL server in your project, <code>ctrl+alt+c ctrl+alt+c</code>. For project type select <code>shadow-cljs</code>, accept the proposed <code>localhost:&lt;some-port&gt;</code>, and for <code>build</code> select <code>node-repl</code>.</li> <li>Load a file from your project with the command <code>ctrl+alt+c Enter.</code> Evaluating forms in Calva will show results in the output window. Synchronous <code>stdout</code> output will be printed in both the output window and in the terminal where you started the repl. Some asynchronous output may show up in the output window, but all will appear in the terminal.</li> </ol> <p>If you use an integrated VSCode terminal to start shadow-cljs, all <code>stdout</code> will appear in the Calva window with your code. Alternatively, you can use an external terminal, which is especially nice when using a second monitor.</p> <p>For a discussion of this problem and other connection options, see issue #1468.</p>"},{"location":"babashka/","title":"Using Calva with Babashka","text":"<p>Since Babashka can be started such that it is an nREPL server, Calva can connect to it and a lot of the features will work.</p> <p>Calva can also start Babashka and connect its REPL for you, using the Jack-in command.</p> <p>Don't expect complete support</p> <p>Babashka's nREPL server is still a bit limited compared to a full cider-nrepl enhanced \"regular\" Clojure nREPL server. Things like function signatures, and more do not work.</p> <p>This might of course improve in the future, especially if you provide some PRs towards the Babashka nREPL.</p>","boost":5},{"location":"clj-java-decompiler/","title":"Decompiling and disassembly made easy","text":"<p>If you need some piece of Clojure code to execute as fast as possible you will often benefit from examining the code generated by the Clojure compiler from your code. There is a really easy to use tool for that: clj-java-decompiler. You can make the use of this tool super convenient with Calva custom command snippets.</p>"},{"location":"clj-java-decompiler/#prerequisites","title":"Prerequisites","text":"<p>Add <code>com.clojure-goes-fast/clj-java-decompiler</code> as a dependency to the project.</p>"},{"location":"clj-java-decompiler/#the-custom-snippets","title":"The custom snippets","text":"<p>You can add some Calva custom commands configuration to be able to decompile or disassemble any Clojure code in your editor with a keyboard shortcut. Here's an example configuration:</p> <pre><code>    \"calva.customREPLCommandSnippets\": [\n        {\n            \"name\": \"Decompile current top level form\",\n            \"key\": \"d\",\n            \"snippet\": \"(require '[clj-java-decompiler.core :refer [decompile]]) (spit \\\"decompiled-$top-level-defined-symbol.java\\\" (with-out-str (decompile $top-level-form)))\"\n        },\n        {\n            \"name\": \"Decompile current form\",\n            \"snippet\": \"(require '[clj-java-decompiler.core :refer [decompile]]) (spit \\\"decompiled.java\\\" (with-out-str (decompile $current-form)))\"\n        },\n        {\n            \"name\": \"Disassemble current top level form\",\n            \"key\": \"b\",\n            \"snippet\": \"(require '[clj-java-decompiler.core :refer [disassemble]]) (spit \\\"bytecode-$top-level-defined-symbol.class\\\" (with-out-str (disassemble $top-level-form)))\"\n        },\n        {\n            \"name\": \"Disassemble current current form\",\n            \"snippet\": \"(require '[clj-java-decompiler.core :refer [disassemble]]) (spit \\\"bytecode.class\\\" (with-out-str (disassemble $current-form)))\"\n        }\n    ],\n</code></pre> <p>Now, with the cursor anywhere in a top level defined function, you can spit out a file with the Java code generated for that function by pressing <code>ctrl+alt+space d</code>. For the byte code, press <code>ctrl+alt+space b</code>. The files will be generated in the same folder as the Clojure file and be named <code>decompiled-&lt;function name&gt;.java</code> and <code>bytecode-&lt;function name&gt;.class</code>, respectively. </p> <p>To decompile or disassemble the current form (or selection) press <code>ctrl+alt+space space</code> and pick the desired command from the quick pick menu that pops up. You can add <code>key</code> to these too if you want even quicker access, of course. The filenames for the results will here be named without any function name suffix, because there is often no function name that can be used.</p> <p>See this video for a demo.</p>"},{"location":"clojure-lsp/","title":"Clojure-lsp","text":"<p>Calva uses a mix of static and dynamic analysis to power the experience. A lot of the static abilities come from clojure-lsp. This enables you to check something up in a project, with a lot of navigational and contextual support, without starting a REPL for it. (And once you do start a REPL you'll get even more capabilities, enabled by the dynamic analysis.)</p> <p>Which clojure-lsp does Calva use?</p> <p>Calva defaults to using the <code>latest</code> clojure-lsp released. To use a different version of clojure-lsp, see the configuration section. Calva does not use the clojure-lsp installed on your system, unless you set the path for clojure-lsp to the installed binary in your settings. You can see what version is being used by running the <code>Clojure-lsp Server Info</code> command, which will also show the version of clj-kondo that's being used as well as other info.</p>"},{"location":"clojure-lsp/#the-lsp-server-lifecycle","title":"The LSP server lifecycle","text":"<p>By default you won't need to install/setup anything as Calva handles that for you by automatically downloading the latest clojure-lsp binary. It can take a while for clojure-lsp to start, especially the first time opening a new project, as clojure-lsp (via <code>clj-kondo</code>) indexes the project files.</p> <p>Calva is able to automatically start the clojure-lsp server for you and can be configured to start the server under various different conditions. These behaviours can be configured through the <code>calva.enableClojureLspOnStart</code> setting, which takes the following options:</p> <ul> <li>\"always-use-first-workspace-root\"</li> <li>\"when-workspace-opened-use-workspace-root\"</li> <li>\"when-file-opened-use-furthest-project\"</li> <li>\"never\"</li> </ul>"},{"location":"clojure-lsp/#always-use-first-workspace-root-default","title":"\"always-use-first-workspace-root\" [default]","text":"<p>When set to <code>\"always-use-first-workspace-root\"</code> Calva will attempt to start the clojure-lsp in the root of the first workspace folder if it is a valid clojure project. If it is not a valid clojure project it will fall back to starting the fallback server.</p> <p>This is the default auto-start behaviour.</p>"},{"location":"clojure-lsp/#when-workspace-opened-use-workspace-root","title":"\"when-workspace-opened-use-workspace-root\"","text":"<p>When set to <code>\"when-workspace-opened-use-workspace-root\"</code> Calva will start the clojure-lsp in the root of all opened vscode workspaces. All Clojure files in a workspace will be serviced by the clojure-lsp server running in that workspace. This behavior requires that you are opening workspaces with a valid Clojure project in the root (the directory must contain a <code>deps.edn</code>, <code>project.clj</code> or <code>shadow-cljs.edn</code> file).</p>"},{"location":"clojure-lsp/#when-file-opened-use-furthest-project","title":"\"when-file-opened-use-furthest-project\"","text":"<p>When set to <code>\"when-file-opened-use-furthest-project\"</code> Calva will attempt to start the clojure-lsp server whenever a Clojure file is opened. The LSP server will be started in the outermost valid Clojure project or will fall back to starting in the workspace root if no valid Clojure project can be found. A directory is considered a Clojure project if it contains typical Clojure project files such as a <code>deps.edn</code>, <code>project.clj</code>, or <code>shadow-cljs.edn</code> file. When working in a mono-repo style project or in a multi-workspace VS Code configuration you may have multiple LSP servers running, one for each independent Clojure project opened.</p> <p>Opening files that do not belong to a workspace folder</p> <p>When opening files that do not belong to any of the workspace folders currently open then Calva will fallback to starting the fallback clojure-lsp server</p>"},{"location":"clojure-lsp/#never","title":"\"never\"","text":"<p>When set to <code>\"never\"</code> Calva will never attempt to automatically start the clojure-lsp server. In this case you are responsible for manually starting the server. More advanced users might want to do this in order to have more control over which projects have a clojure-lsp server running for them. To manually start the clojure-lsp server you can run the <code>calva.clojureLsp.start</code> or the <code>calva.clojureLsp.manage</code> command and pick the project root. You can also click the <code>clojure-lsp</code> status bar icon to open the Management Menu.</p> <p>Additionally Calva has commands for:</p> <ul> <li>Inspecting the clojure-lsp server information</li> <li>Read the clojure-lsp server log</li> <li>Stopping any running clojure-lsp processes</li> <li>Starting clojure-lsp</li> <li>Restarting any running clojure-lsp processes</li> <li>Downloading the configured clojure-lsp version</li> </ul> <p>Note that the download command will download the configured clojure-lsp version regardless if it is already installed or not. This can be useful when some earlier download has failed resulting in that clojure-lsp can't be started. NB: It will not download anything if <code>calva.clojureLspPath</code> is set to something non-blank.</p>"},{"location":"clojure-lsp/#fallback-server","title":"Fallback Server","text":"<p>As a fallback behaviour Calva may start a clojure-lsp server in a temporary directory and use this to service lsp requests for clojure files that do not belong to a valid clojure project. This will show up in the management menu looking something like:</p> <p></p> <p>Any files that are handled by this server will have limited classpath analysis and lsp features. It is therefore recommended to setup your project as a clojure project (by creating a <code>deps.edn</code> file in the root, for example).</p>"},{"location":"clojure-lsp/#status-bar","title":"Status bar","text":"<p>In the status bar Calva will show an indicator with the clojure-lsp status. This status will track the currently open project, showing the status (<code>stopped</code>, <code>starting</code> or <code>active</code>) for the relevant clojure-lsp server.</p> <p>You can click on the status-bar item to open the clojure-lsp management menu which will look as follows:</p> <p></p> <p>The menu shows which clojure-lsp servers are active and which are stopped. Selecting a project will allow you to start/stop/restart the server for that project.</p>"},{"location":"clojure-lsp/#ignoring-lsp-cache-files","title":"Ignoring LSP cache files","text":"<p>Clojure-lsp stores its project analysis information in your project. Git users can add these lines to their project root directory <code>.gitignore</code>:</p> <pre><code>.lsp/.cache/\n.lsp/sqlite.*.db\n</code></pre>"},{"location":"clojure-lsp/#configuration","title":"Configuration","text":"<p>For information about how to configure clojure-lsp, see the settings page of the clojure-lsp docs.</p>"},{"location":"clojure-lsp/#changing-the-version-of-clojure-lsp-used-by-calva","title":"Changing the Version of Clojure-lsp Used by Calva","text":"<p>By default, Calva will use the latest released clojure-lsp. You can change the version of clojure-lsp used by Calva by setting the <code>calva.clojureLspVersion</code> property to a version of clojure-lsp found in its GitHub releases. This can be helpful if you're debugging an issue with clojure-lsp or you want to try out a feature of a new release that Calva does not yet use. However, you must remember to reset this setting in order for Calva to automatically use newer versions of clojure-lsp that are released with new versions of Calva.</p> <p>Example:</p> <pre><code>\"calva.clojureLspVersion\": \"2021.04.07-16.34.10\"\n</code></pre> <p>Special \u201dversion\u201d values</p> <p>Apart from the actual versions you can use two special values for this setting:</p> <ul> <li><code>latest</code>: Will download and use the latest stable build of clojure-lsp, when one becomes available. This is the default</li> <li><code>nightly</code>: Will always download and use the latest nightly build, whether there is a new version available or not.</li> </ul>"},{"location":"clojure-lsp/#using-a-custom-clojure-lsp","title":"Using a Custom Clojure-lsp","text":"<p>You can set a path to a custom clojure-lsp to be used by Calva by configuring the <code>calva.clojureLspPath</code> setting. This should be an absolute path to a native binary or JAR file.</p> <p>Example:</p> <pre><code>\"calva.clojureLspPath\": \"/usr/local/bin/clojure-lsp\"\n</code></pre> <p>Will override any <code>calva.clojureLspVersion</code> setting</p> <p>When <code>calva.clojureLspPath</code> is set, the binary at the path will be used uncoditionally, and the <code>calva.clojureLspVersion</code> setting will be ignored.</p>"},{"location":"clojure-lsp/#extra-commands","title":"Extra commands","text":"<p>clojure-lsp provides many useful [commands], and Calva has configuration for most of them. The clojure-lsp team works fast and sometimes Calva might miss some command. And Calva's configuration only really work for clojure-lsp commands that take no argument, or where it makes sense to prompt for the argument. Therefore Calva provides a generic command id, <code>clojure-lsp.command</code> which can be used with keyboard shortcuts and that allow for providing arguments that way. (The command can be used from Joyride too, of course.)</p> <p>When using the command, provide the args as an tuple of <code>[command-name, arguments]</code>, where <code>arguments</code> is an array of any arguments after <code>file-uri, row, col</code> which are common for all clojure-lsp extra commands and are provided automatically by Calva, based on active text editor and where the cursor is. It can look like so when binding a shortcut for <code>extract-function</code>:</p> <pre><code>    {\n        \"key\": \"ctrl+alt+r f\",\n        \"command\": \"clojure-lsp.command\",\n        \"args\": [\"extract-function\", [\"new-function\"]]\n    },\n</code></pre> <p>Note that even though <code>extract-function</code> takes only one argument, you should still provide it via an array.</p>"},{"location":"clojure-lsp/#troubleshooting","title":"Troubleshooting","text":""},{"location":"clojure-lsp/#viewing-the-logs-between-the-client-and-server","title":"Viewing the Logs Between the Client and Server","text":"<p>If something doesn't seem to be working correctly, and you suspect the issue is related to clojure-lsp, a good place to start investigating is the request and response logs between the LSP client and server. In your settings, set <code>clojure.trace.server</code> to <code>verbose</code>, then in the VS Code output tab, select the <code>Clojure Language Client</code> output channel.</p> <p></p> <p>It may be helpful to clear the output channel, then perform the action with which you're experiencing a problem, then read through the log for clues or paste the logs into a related issue in the Calva repo.</p>"},{"location":"clojure-lsp/#server-info-command","title":"Server Info Command","text":"<p>You can run the <code>Clojure-lsp Server Info</code> command to get information about the running clojure-lsp server, such as the version the server being used, the version of clj-kondo it's using, and more. This info is printed to the \"Calva says\" output channel.</p>"},{"location":"clojure-lsp/#opening-the-server-log-file","title":"Opening the Server Log File","text":"<p>You can open the clojure-lsp log file by running the command <code>Calva Diagnostics: Open Clojure-lsp Log File</code>. The log file will only be opened with this command if the clojure-lsp server is running and has finished initializing. If you need to open the file when the server is failing to run or initialize, see the clojure-lsp docs for information on the file location.</p>"},{"location":"clojure-lsp/#server-initialization-failed","title":"Server initialization failed","text":"<p>If clojure-lsp fails to start with \u201cServer initialization failed\u201d messages, it could be because the path to your project contains non-ASCII characters, or that the system PATH variable has been corrupted. (Or something else, of course.)</p> <p>See this issue for some findings about it: Issue #2251: Server initialization failed error</p>"},{"location":"clojure-lsp/#related","title":"Related","text":"<p>See also:</p> <ul> <li>Connecting the REPL</li> <li>Refactoring</li> </ul>"},{"location":"clojuredart/","title":"Using Calva with ClojureDart","text":"<p>Since ClojureDart is Clojure, Calva just works with it. Calva is also automatically configured to make VS COde treat <code>.cljd</code> files as a Clojure code.</p>","boost":4},{"location":"clojuredart/#dart-clojure-conversion","title":"Dart-&gt;Clojure Conversion","text":"<p>Similar to when using ClojureScript you will often find examples for Dart and Flutter written in, you guessed it, Dart. And then you will often wish there was a converter, because manually transpiling can be a bit tedious and error prone. Luckily you are in the Clojure community, and such a converter is provided: </p> <ul> <li>DartClojure</li> </ul> <p>There are several ways you can leverage this converter, and since you are using Calva, a very convenient way is available. There is a command Calva: Convert Dart code to Clojure/ClojureDart. This command takes whatever text is selected and uses DartClojure to convert it. Lacking a selection, the command will use the whole file.</p> <p>The workflow demoed in the video is something like so:</p> <ol> <li>Open a new untitled file/tab</li> <li>Paste your Dart/Flutter code in this file (VS Code will probably automatically figure out that it is Dart code, even if that doesn't matter for the converter.)</li> <li>Run Calva: Convert Dart code to Clojure/ClojureDart</li> <li>An, untitled, Clojure tab will open with the converted code in it.</li> </ol> <p>NB: The conversion will not always work. DartCLojure is work in progress. See the project repo for limitations and scope. Often when conversion, the error message will give you a clue to what is problematic. Try adjust your code selection and you will probably be able to get at least some help from the converter.</p> <p>Speaking of WIP...</p>","boost":4},{"location":"clojuredart/#work-in-progress","title":"Work in Progress","text":"<p>ClojureDart is very new and being super actively developed. Some feature are still missing. Like a REPL. Once that is added we will also add ClojureDart jack-in and connect support to Calva.</p>","boost":4},{"location":"clojuredart/#happy-clojuredart-hacking","title":"Happy ClojureDart Hacking!","text":"<p>Please feel welcome to the #clojuredart and #calva channel at the Clojurians Slack for questions, suggestions and support.</p>","boost":4},{"location":"clojuredocs/","title":"ClojureDocs integration","text":"<p>clojuredocs.org is the goto place #1 for finding out more about Clojure core(-ish) functions, macros, etcetera. It contains the doc strings from the functions and adds crowd sourced examples of usage and see alsos. You can surf for quite long on that site without getting bored. \ud83d\ude04</p> You can surf ClojureDocs in Calva <p>Calva integrates this information in two ways:</p> <ol> <li>Commands for requesting the ClojureDocs information for a symbol under the cursor:<ul> <li>Print clojuredocs.org examples to Rich Comment, default keybinding: <code>ctrl+alt+r d</code></li> <li>Print clojuredocs.org examples to OutputWindow, <code>ctrl+alt+o d</code></li> </ul> </li> <li>ClojureDocs information is included in the symbol lookup hovers, where each example has two buttons:<ul> <li>To Rich Comment</li> <li>To Output Window </li> </ul> </li> </ol> <p>That means that if you just want to glance at the examples, you look in the hover. And when you want to bring the examples to the REPL to play with them, you can do so very easily.</p> <p>ClojureScript support</p> <p>ClojureDocs information is available both for Clojure and ClojureScript files. However, clojuredocs.org only keeps info for Clojure. Thus: All information Calva shows about a symbol will be about the Clojure respresentation of that symbol. (The symbol might not even exist in ClojureScript.)</p>","boost":4},{"location":"clojuredocs/#clojuredocs-repl-surfing","title":"ClojureDocs REPL Surfing","text":"<p>Since the ClojureDocs information includes see-alsos, you can go for super interactive ClojureDocs surfing right in the file you are editing. Say you have this function:</p> <pre><code>(defn trim-text\n  \"Returns text without surrounding whitespace if not empty, otherwise nil\"\n  [text]\n  (let [trimmed-text (clojure.string/trim text)]\n    (when-not (empty? trimmed-text)\n      trimmed-text)))\n</code></pre> <p>Then you hover on <code>when-not</code> and scroll down a bit in the hover:</p> <p></p> <p>That first example would be interesting to play with, right? Click To Rich Comment and you will get:</p> <pre><code>(defn trim-text\n  \"Returns text without surrounding whitespace if not empty, otherwise nil\"\n  [text]\n  (let [trimmed-text (clojure.string/trim text)]\n    (when-not (empty? trimmed-text)\n      trimmed-text)))\n\n(comment\n  ;; = when-not - Example 1 = \n\n  ;; build tuples over sets with the same cardinality \n  (map\n   #(when-not (= %2 %3) [%1 %2 %3])\n   (iterate inc 0)   ; a lazy list of indices\n   [:a :b :c]\n   [:a :a :a])\n  ;;=&gt; (nil [1 :b :a] [2 :c :a])\n\n  ;; See also:\n  when\n  when-let\n  if\n  )\n</code></pre> <p>There you can evaluate the <code>(map ...)</code> form using <code>alt+enter</code>, modify it and evaluate again. You can also hover over <code>map</code>, <code>iterate</code>, or any of the \u201dSee also:\u201d symbols to find more fun examples to play with. And so on and so forth.</p> <p>See these two tweets for some videos of early versions of this functionality:</p> <ul> <li>Rich Comments surfing ClojureDocs Examples</li> <li>Clojuredocs in #Calva WIP 2: Hover examples -&gt; RFC</li> </ul> <p>Please retweet!</p>","boost":4},{"location":"clojuredocs/#quirks","title":"Quirks","text":"<p>Some of the ClojureDocs entries have text that is not really Clojure code, and sometimes even structural errors. This can break the structural integrity of your Clojure file. If you run into trouble trying to heal things, you can always use Undo until the Rich Comment is gone.</p>","boost":4},{"location":"commands-top10/","title":"The Top 10 Calva Commands","text":"<p>There are not all that many Calva commands. You can learn them all if you like, but here are the most important ones to know about for effective Clojure/ClojureScript coding:</p> <ul> <li>Grow/expand selection: <code>ctrl+w</code> (<code>shift+alt+right</code> on Windows and Linux)</li> <li>Load/Evaluate Current File and its Requires/Dependencies: <code>alt+ctrl+c enter</code>, evaluates the namespace code in the active editor tab. This also loads any required namespaces, and generally gives Calva what it needs to work.</li> <li>Evaluate current form:  <code>ctrl+enter</code> finds the form from the cursor position, evaluates it and displays the result inline. Hit <code>esc</code> to dismiss the results display.</li> <li>Evaluate current top-level form: <code>alt+enter</code>: inline evaluate the current top-level form. This also works inside <code>(comment)</code> forms. Use it to (re)define vars and then inside comment forms you can verify that they do what you want them to do.</li> <li>Dismiss the display of results: <code>escape</code>: (VIM Extension users should read Using Calva with the VIM Extension).</li> </ul> <p>There are also two commands for bringing over the current form and the current top level form over to the repl window:</p> <ul> <li><code>ctrl+alt+c ctrl+alt+e</code> (<code>ctrl+alt+c ctrl+alt+v</code> on Windows): to paste the current form in the REPL window.</li> <li><code>ctrl+alt+c ctrl+alt+space</code>: to paste the current top-level form in this window</li> </ul> <p>You can also switch the name space of the output/repl window to that of the current file: <code>alt+ctrl+c alt+n</code></p> <ul> <li>Toggle pretty printing of results on and off: <code>ctrl+alt+c p</code>. It's on by default. There is a status bar button showing the status and that also can be used to toggle the setting.</li> </ul>"},{"location":"commands-top10/#some-more-commands-to-try","title":"Some More Commands to Try","text":"<ul> <li>Code evaluation<ul> <li>Evaluate code and add as comment: <code>ctrl+alt+c c</code> (current form), <code>ctrl+alt+c ctrl+space</code> (current top level form)</li> <li>Evaluate code and replace it in the editor, inline: <code>ctrl+alt+c r</code></li> </ul> </li> <li>Integrated REPLs<ul> <li>Send current editor form to the REPL window: <code>ctrl+alt+c ctrl+alt+e</code> (<code>ctrl+alt+c ctrl+alt+v</code> on Windows)</li> <li>Send current editor top level form to the REPL window: <code>ctrl+alt+c ctrl+alt+space</code></li> </ul> </li> <li>Run tests and mark failures and errors in the Problems pane<ul> <li>Run namespace tests: <code>ctrl+alt+c t</code></li> <li>Run all tests: <code>ctrl+alt+c shift+t</code></li> <li>Run current test: <code>ctrl+alt+c ctrl+alt+t</code></li> <li>Rerun previously failing tests: <code>ctrl+alt+c ctrl+t</code></li> <li>Caveat: Right now the tests are reported only when all are run, making it painful to run all tests in larger projects. I'll fix it. Promise!</li> </ul> </li> <li>Select current form: <code>ctrl+alt+c s</code>.</li> <li>Run custom commands, i.e. code snippets, at will: <code>ctrl+alt+c .</code></li> </ul> <p>See also:</p> <ul> <li>Code Evaluation Tips</li> <li>Finding Calva Commands and Shortcuts</li> </ul>"},{"location":"connect-sequences/","title":"REPL Jack-in and Connect Sequences","text":"<p>Many projects grow out of the template phase and call for custom developer workflows involving application start commands, customized REPLs, and what have you. Even some templates add this kind of complexity. To make Jack-in usable for a broader set of projects, Calva has a setting keyed <code>calva.replConnectSequences</code> which lets you configure one ore more connect sequences.</p> <p>NB: Connect sequence configuration affects Calva's Jack-in menu in the following ways:</p> <ol> <li>With no sequence configured, Calva will prompt for the built-in sequences it has that seems to match your project.</li> <li>When any number of connection sequences are configured, Calva will prompt for your custom sequences, as well as the built-in sequences. Whether built-in or custom, only sequences relevant to your project will be included in the prompt.</li> </ol>","boost":6},{"location":"connect-sequences/#settings-for-adding-custom-sequences","title":"Settings for adding Custom Sequences","text":"<p>A connect sequence configures the following:</p> <ul> <li><code>name</code>: (required) This will show up in the Jack-in quick-pick menu when you start Jack-in (see above).</li> <li><code>projectType</code>: (required) This is either \"Leiningen\u201d, \"deps.edn\", \"shadow-cljs\", \"lein-shadow\", \"Gradle\", \u201dgeneric\u201d, or  \"custom\".</li> <li><code>autoSelectForJackIn</code>: A boolean. If true, this sequence will be automatically selected at Jack-in, suppressing the Project Type. Use together with <code>projectRootPath</code> to also suppress the Project Root menu. Add usage of <code>menuSelections</code> to go for a prompt-less REPL Jack-in. If you have more than one sequence with <code>autoSelectForJackIn</code> set to true, the first one will be used.</li> <li><code>autoSelectForConnect</code>: A boolean. If true, this sequence will be automatically selected at Connect, suppressing the Project Type menu. Use together with <code>projectRootPath</code> to also suppress the Project Root menu. If you have more than one sequence with <code>autoSelectForConnect</code> set to true, the first one will be used.</li> <li><code>projectRootPath</code>: An array of path segments leading to the root of the project to which this connect sequence corresponds. Use together with <code>autoSelectForJackIn</code>/<code>autoSelectForConnect</code> to suppress the Project Root menu. The path can be absolute or relative to the workspace root. If there are several Workspace Folders, the workspace root is the path of the first folder, so relative paths will only work for this first folder.</li> <li><code>nReplPortFile</code>: An array of path segments with the project root-relative path to the nREPL port file for this connect sequence. E.g. For shadow-cljs this would be <code>[\".shadow-cljs\", \"nrepl.port\"]</code>.</li> <li><code>afterCLJReplJackInCode</code>: Code to evaluate in the CLJ REPL once it has been created. You can use either a string or an array of strings. If you use an array, the strings will be joined with a newline character to form the resulting code.</li> <li><code>customJackInCommandLine</code>: A string with a command line that should be used to launch the REPL. See Custom Command Line, below.</li> <li><code>cljsType</code>: This can be either \"Figwheel Main\", \"shadow-cljs\", \"ClojureScript built-in for browser\", \"ClojureScript built-in for node\", \"lein-figwheel\", \"none\", or a dictionary configuring a custom type. If set to \"none\", Calva will skip connecting a ClojureScript repl. A custom type has the following fields:<ul> <li><code>dependsOn</code>: (required) Calva will use this to determine which dependencies it will add when starting the project (Jacking in). This can be either \"Figwheel Main\", \"shadow-cljs\", \"ClojureScript built-in for browser\", \"ClojureScript built-in for node\", \"lein-figwheel\", or \u201dUser provided\u201d. If it is \"User provided\", then you need to provide the dependencies in the project or launch with an alias (deps.edn), profile (Leiningen), or build (shadow-cljs) that provides the dependencies needed.</li> <li><code>isStarted</code>: Boolean. For CLJS REPLs that Calva does not need to start, set this to true. (If you base your custom cljs repl on a shadow-cljs workflow, for instance.)</li> <li><code>startCode</code>: Clojure code to be evaluated to create and/or start your custom CLJS REPL.</li> <li><code>isReadyToStartRegExp</code>: A regular expression which, when matched in the stdout from the startCode evaluation, will make Calva continue with connecting the REPL, and to prompt the user to start the application. If omitted and there is startCode Calva will continue when that code is evaluated.</li> <li><code>openUrlRegExp</code>: A regular expression, matched against the stdout of cljsType evaluations, for extracting the URL with which the app can be started. The expression should have a capturing group named <code>url</code>. E.g. \"Open URL: (?\\&lt;url&gt;S+)\"</li> <li><code>shouldOpenUrl</code>: Choose if Calva should automatically open the URL for you or not.</li> <li><code>connectCode</code>: (required) Clojure code to be evaluated to convert the REPL to a CLJS REPL that Calva can use to connect to the application. (For some setups this could also conditionally start the CLJS REPL. If so: <code>startCode</code> should be omitted.)</li> <li><code>isConnectedRegExp</code>: (required) A regular expression which, when matched in the <code>stdout</code> from the <code>connectCode</code> evaluation, will tell Calva that the application is connected. The default is <code>To quit, type: :cljs/quit</code> and you should leave it at that unless you know it won't work.</li> <li><code>printThisLineRegExp</code>: regular expression which, when matched in the <code>stdout</code> from any code evaluations in the <code>cljsType</code>, will make the matched text be printed to the Output window.</li> <li><code>buildsRequired</code>: Boolean. If the repl type requires that builds are started in order to connect to them, set this to true.</li> </ul> </li> <li><code>menuSelections</code>: a dictionary with pre-filled-in selections for the Jack-in and Connect prompts, making Calva not prompt for that particular selection:<ul> <li><code>leinProfiles</code>: At Jack-in to a Leiningen project, use these profiles to launch the repl.</li> <li><code>leinAlias</code>: At Jack-in to a Leiningen project, launch with this alias. Set to <code>null</code> to launch with Calva's default task (a headless repl), w/o prompting.</li> <li><code>cljAliases</code>: At Jack-in to a deps.edn project, use these aliases to launch the repl.</li> <li><code>cljsLaunchBuilds</code>: The cljs builds to start/watch at Jack-in/connect.</li> <li><code>cljsDefaultBuild</code>: Which cljs build to attach to at the initial connect.</li> </ul> </li> <li><code>jackInEnv</code>: An object with environment variables that will be merged with the global <code>calva.jackInEnv</code> and then applied to the Jack-in process. The merge is very similar to how Clojure's <code>merge</code> works. So for any common keys between the global setting and this one, the ones from this setting will win.</li> </ul> <p>The Calva built-in sequences also use this format, check them out to get a clearer picture of how these settings work.</p> <p>Force the project type menu to show</p> <p>The convenience of <code>autoSelectForJackIn/Connect</code> can be an inconvenience when you want to use another project type/sequence for a project. For this reason, the <code>calva.connect</code> and <code>calva.jackIn</code> can be provided with an option <code>disableAutoSelect</code>, which forces the project root and project type menus to show. See Options for the Connect Command and Options for the Jack-in Command for more on this.</p> <p>Path segments</p> <p><code>projectRootPath</code> and <code>nReplPortFile</code> both take an array of path segments. This is to make the paths work cross-platform. If you can't be bothered splitting up the path in segments, put the whole path in the first segment, though please note that if you use Windows path separators, these will not work for users with Linux or macOS.</p>","boost":6},{"location":"connect-sequences/#custom-command-line","title":"Custom Command Line","text":"<p>Custom command lines are there to bridge the gap to those situations where standard Jack-in command lines don't reach. Like:</p> <ol> <li>You want to provide command line options to a supported tool, which Jack-in does not provide</li> <li>Your project has some script through which it is started</li> <li>The REPL is provided by some tool that Calva does not know of</li> <li>Any other reason...</li> </ol> <p>A custom command line is executed from same directory as the REPL project root (See <code>projectRootPath</code>, above), and can be as simple as <code>my-repl-jack-in-command</code>. You  can use a relative or absolute path to your command line.</p> <p>If your custom command line starts a REPL of a project type that is not \u201dknown\u201d/built-in to Calva, use <code>custom</code> as the <code>projectType</code> for the connect sequence.</p>","boost":6},{"location":"connect-sequences/#custom-command-line-substitutionsplaceholdersenvironment-variables","title":"Custom Command Line Substitutions/Placeholders/Environment variables","text":"<p>You can use placeholders in your command line, and Calva will substitute them before executing the command. All these placeholders will also be provided to your script via environment variables with the same names (except dashes will be underscores in the env variable names):</p> <p>nREPL dependency versions:</p> <ul> <li><code>JACK-IN-NREPL-VERSION</code></li> <li><code>JACK-IN-CIDER-NREPL-VERSION</code></li> <li><code>JACK-IN-CIDER-PIGGIEBACK-VERSION</code></li> </ul> <p>Paths:</p> <ul> <li><code>JACK-IN-PROJECT-ROOT-PATH</code>: (See <code>projectRootPath</code>, above)</li> <li><code>JACK-IN-NREPL-PORT-FILE</code>: The path of the nREPL port file (see <code>nReplPortFile</code> above)</li> </ul> <p>Depending on the project type Calva will also look for these placeholders:</p> <ul> <li><code>JACK-IN-CLJ-MIDDLEWARE</code>: The nREPL middleware to be used for the Clojure REPL</li> <li><code>JACK-IN-CLJS-MIDDLEWARE</code>: The nREPL middleware to be used for the ClojureScript REPL</li> <li><code>JACK-IN-LEIN-PROFILES</code>: For Leiningen projects, the profiles selected by the user</li> <li><code>JACK-IN-LEIN-LAUNCH-ALIAS</code>: For Leiningen projects, the launch alias selected by the user</li> <li><code>JACK-IN-CLI-ALIASES</code>: For deps.edn projects, the aliases selected by the user</li> <li><code>JACK-IN-CLJS-LAUNCH-BUILDS</code>: For ClojureScript REPLs that configures builds, the builds selected by the user</li> <li><code>JACK-IN-NREPL-PORT</code>: For some project types (currently <code>nbb</code> and <code>Babashka</code>) Calva provided the TCP port they should use.</li> </ul>","boost":6},{"location":"connect-sequences/#example-custom-jack-in-command-lines","title":"Example Custom Jack-in Command lines","text":"","boost":6},{"location":"connect-sequences/#start-a-babashka-repl-via-wsl","title":"Start a Babashka REPL via WSL","text":"<p>Calva has a built-in jack-in sequence for starting a Babashka REPL and connect to it. It works as long as the <code>bb</code> process is on the same host as VS Code/Calva is running. So if you want it to run in WSL, but VS Code is running on your computer you need to start <code>bb</code> slightly differently. These settings in your VS Code settings file will give you a jack-in option that works for this:</p> <pre><code>  \"calva.replConnectSequences\": [\n    {\n        \"name\": \"Bashbabka (WSL)\",\n        \"projectType\": \"custom\",\n        \"customJackInCommandLine\": \"bash -c 'bb --nrepl-server JACK-IN-NREPL-PORT'\",\n    },\n  ],\n</code></pre> <p>If you place it in your user settings you will have access to it from any workspace.</p>","boost":6},{"location":"connect-sequences/#an-exampleskeleton-script","title":"An example/skeleton script","text":"<p>This script doesn't actually start a REPL, it's provided more for giving you an idea about what it could look like, and as a starting point for your real scripts:</p> <pre><code>#!/usr/bin/env bb\n\n(require '[clojure.string :as str])\n\n(defn parse-args [args]\n  (loop [args args\n         parsed {}]\n    (if (empty? args)\n      parsed\n      (let [[flag value &amp; rest-args] args]\n        (case flag\n          \"--aliases\" (recur rest-args (assoc parsed :aliases value))\n          \"--cider-nrepl-version\" (recur rest-args (assoc parsed :cider-nrepl-version value))\n          (do (println \"Unknown parameter:\" flag) (System/exit 1)))))))\n\n(defn process-args [args]\n  (let [aliases (str/split (:aliases args) #\",\")\n        cider-nrepl-version (:cider-nrepl-version args)\n        project-root-path (System/getenv \"JACK_IN_PROJECT_ROOT_PATH\")]\n    (println \"Aliases:\")\n    (doseq [alias aliases]\n      (println alias))\n    (println \"CIDER nREPL version:\" cider-nrepl-version)\n    (println \"JACK_IN_PROJECT_ROOT_PATH:\" project-root-path)))\n\n(def parsed-args (parse-args *command-line-args*))\n\n(when (= *file* (System/getProperty \"babashka.file\"))\n  (process-args parsed-args))\n</code></pre> <p>It's written in Babashka to encourage you to write your shell scripts in a civilized language. \ud83d\ude00 See the article Changing my mind: Converting a script from bash to Babashka for a small success-story about this mindset. See also bash2bb.</p> <p>The script reads <code>JACK-IN-CLJS-LAUNCH-BUILDS</code> and <code>JACK-IN-CIDER-NREPL-VERSION</code> from the command line, and <code>JACK_IN_PROJECT_ROOT_PATH</code> from the environment. It could be configured for use in a custom connect sequence like this:</p> <pre><code>    \"customJackInCommandLine\": \"../../custom-jack-in.bb --aliases JACK-IN-CLJS-LAUNCH-BUILDS --cider-nrepl-version JACK-IN-CIDER-NREPL-VERSION\",\n</code></pre> <p>Note how in this case the REPL is started two directories \u201ddown\u201d from the workspace root where the script resides.</p>","boost":6},{"location":"connect-sequences/#example-sequences","title":"Example Sequences","text":"<p>Whether you just want to speed up your workflow or encode some workflow/mechanics into it, it's often the case that you can create a custom sequence that helps.</p>","boost":6},{"location":"connect-sequences/#minimal-menus-with-full-stack-shadow-cljs-repls","title":"Minimal menus with full stack shadow-cljs REPLs","text":"<p>Minimize the amount of selecting from the Jack-in/Connect menu when working with a full-stack shadow-cljs + deps/lein project:</p> <pre><code>    {\n      \"name\": \"backend + frontend\",\n      \"projectType\": \"shadow-cljs\",\n      \"cljsType\": \"shadow-cljs\",\n      \"menuSelections\": {\n        \"cljsLaunchBuilds\": [\n          \":app\",\n          \":test\",\n        ],\n        \"cljsDefaultBuild\": \":app\"\n      }\n    }\n</code></pre> <p>See shadow-cljs + Clojure with Calva: The basics for how Calva and nREPL work with ClojureScript.</p>","boost":6},{"location":"connect-sequences/#polylith","title":"Polylith","text":"<p>This is the connect sequences used in the Polylith Real World App. The <code>(start)</code> sequence lets you jack-in to the project, and starts the Real World App without any prompts. The <code>(connect)</code> sequence can be used if you prefer to start the REPL manually, and want to connect without prompts.</p> <pre><code>    \"calva.replConnectSequences\": [\n        {\n            \"projectType\": \"deps.edn\",\n            \"afterCLJReplJackInCode\": \"(require '[dev.server] :reload) (in-ns 'dev.server) (start! 6003)\",\n            \"name\": \"Polylith RealWorld Server REPL (start)\",\n            \"autoSelectForJackIn\": true,\n            \"projectRootPath\": [\".\"],\n            \"cljsType\": \"none\",\n            \"menuSelections\": {\n                \"cljAliases\": [\"dev\", \"test\"]\n            }\n        },\n        {\n            \"projectType\": \"deps.edn\",\n            \"name\": \"Polylith RealWorld Server REPL (connect)\",\n            \"autoSelectForConnect\": true,\n            \"projectRootPath\": [\".\"],\n            \"cljsType\": \"none\",\n        }\n    ],\n    \"calva.autoConnectRepl\": true,\n</code></pre> <p>The <code>calva.autoConnectRepl</code>, when set to <code>true</code>, makes Calva, at project open, look for the nRepl port file and automatically connect the repl if the file exists. Therefore, you can leave the app running when you close the project in VS Code, and Calva will reconnect when you open the project again. (Alternatively, maybe you just need to reload the VS Code window and not lose the REPL state.)</p>","boost":6},{"location":"connect-sequences/#minimal-menus-with-full-stack-depsedn-and-figwheel-main-repls","title":"Minimal menus with full stack deps.edn and Figwheel Main REPLs","text":"<p>Setting for a full-stack application. It starts the backend server when the CLJ REPL has started. Then proceeds to create a custom CLJS REPL (calling in to the application code for this). And then connects to it.</p> <pre><code>{\n    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"Example Sequence\",\n            \"projectType\": \"Clojure-CLI\",\n            \"afterCLJReplJackInCode\": \"(go)\",\n            \"cljsType\": {\n                \"startCode\": \"(do (require '[cljs-test.main :refer :all])(start-nrepl+fig))\",\n                \"isReadyToStartRegExp\": \"Prompt will show\",\n                \"connectCode\": \"(do (use 'cljs-test.main) (cljs-repl))\",\n                \"isConnectedRegExp\": \"To quit, type: :cljs/quit\",\n                \"printThisLineRegExp\": \"\\\\[Figwheel\\\\] Starting Server at.*\"\n            }\n        }\n    ]\n}\n</code></pre>","boost":6},{"location":"connect-sequences/#juxt-edge","title":"JUXT Edge","text":"<p>Here is an example from the JUXT Edge project template. It adds two sequences, one for when only the Clojure REPL should be launched and one for when the customized Edge cljs repl should also be connected. The Edge backend + frontend sequence specifies that the web app should be opened by Calva, making cljs repl connection more stable, and also adds <code>menuSelections</code> to skip the launch aliases prompt.</p> <pre><code>{\n    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"Edge backend only\",\n            \"projectType\": \"deps.edn\"\n        },\n        {\n            \"name\": \"Edge backend + frontend\",\n            \"projectType\": \"deps.edn\",\n            \"cljsType\": {\n                \"dependsOn\": \"Figwheel Main\",\n                \"startCode\": \"(do (require 'dev-extras) (dev-extras/go) (println \\\"Edge Figwheel Main started\\\") ((resolve 'dev-extras/cljs-repl)))\",\n                \"isReadyToStartRegExp\": \"Edge Figwheel Main started\",\n                \"openUrlRegExp\": \"Website listening on: (?&lt;url&gt;\\\\S+)\",\n                \"printThisLineRegExp\": \"\\\\[Edge\\\\]\",\n                \"shouldOpenUrl\": true,\n                \"connectCode\": \"(do (require 'dev-extras) ((resolve 'dev-extras/cljs-repl)))\",\n                \"isConnectedRegExp\": \"To quit, type: :cljs/quit\",\n                \"buildsRequired\": false\n            },\n            \"menuSelections\": {\n                \"cljAliases\": [\n                    \"dev\",\n                    \"build\",\n                    \"dev/build\"\n                ],\n            }\n        }\n    ]\n}\n</code></pre>","boost":6},{"location":"connect-sequences/#plain-depsedn","title":"Plain deps.edn","text":"<p>A deps.edn sequence that does not promote the ClojureScript repl at all (leaving it a Clojure REPL), and leaves that up to you to do interactively. (Could be useful while you are developing a custom cljs repl.) The example is for when adapting a Figwheel Main repl.</p> <pre><code>{\n    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"Do not promote to cljs\",\n            \"projectType\": \"deps.edn\",\n            \"cljsType\": {\n                \"dependsOn\": \"Figwheel Main\",\n                \"connectCode\": \"\\\"Don't promote me bro!\\\"\",\n                \"isConnectedRegExp\": \"Don't promote me bro!\"\n            }\n        }\n    ]\n}\n</code></pre>","boost":6},{"location":"connect/","title":"Connect Calva to Your Project","text":"<p>When connected to your project's REPL Calva lets you evaluate code, supporting Interactive Programming. The REPL connection is also used to provide IDE functionality through the dynamic knowledge about the project that the REPL enables. The REPL communication depends on that your project has an nREPL server running, and that the cider-nrepl middleware is enabled.</p> <p>For the easiest way to provide your project with these dependencies, the recommended way to connect is to use the so called Jack-in command.</p>","boost":7},{"location":"connect/#jack-in-let-calva-start-the-repl-for-you","title":"Jack-in: Let Calva Start the REPL For You","text":"<p>This way Calva can make sure it is started with the dependencies needed for a working Clojure and/or ClojureScript session. This is often referred to as Jack in (because that is what it is called in CIDER).</p> <p>Jack-in supports both CLJ and for CLJS, and has built-in configurations for Leiningen, deps.edn, shadow-cljs, Gradle projects, as well as for the CLJS repl types: Figwheel Main, lein-figwheel (legacy Figwheel), shadow-cljs, and ClojureScript built-ins for both browser and node.js. Using jack-in provides your development environment with all the dependencies you need for Calva to work.</p> <p>It works like so:</p> <ol> <li>Open your project in VS Code.</li> <li>Issue the command Start a Project REPL and Connect: <code>ctrl+alt+c ctrl+alt+j</code>.</li> <li>Answer the quick-pick prompts telling Calva about project types and what profiles to start. (See the Jack-in Project Types and Profiles wiki page for more info if needed.)</li> </ol> <p>See also: Workspace Layouts</p> <p>About project roots</p> <p>You must have a project file, such as <code>project.clj</code> for Leiningen, or <code>deps.edn</code> for deps.edn, or <code>shadow-cljs.edn</code> for shadow-cljs, or <code>settings.gradle</code>/<code>settings.gradle.kts</code> for Gradle in the directory opened in VS Code in order for jack-in to work. If, after adding the project file, you experience an error during jack-in that says something could not be located, make sure you have the correct dependencies in your project file. For example, when using the Figwheel Main project type, you should have <code>com.bhauman/figwheel-main</code> in your project dependencies.</p> <p>See also below, regarding multiple projects in a workspace</p>","boost":7},{"location":"connect/#aliases-profiles-builds","title":"Aliases, Profiles, Builds","text":"<p>When Jack-in starts it will depend on the project type, and whether ClojureScript is involved or not, and if it is, what kind of ClojureScript project, what will happen next. Calva will analyze the project files and will then give you prompts with selections based on what is found there.</p> <p>You will need some basic knowledge about the project and the project type terminologies to answer the prompts.</p> <p>There are ways to tell Calva the answers to these prompts beforehand, so that Jack-in can be a zero-prompting command. Read on.</p>","boost":7},{"location":"connect/#customizing-jack-in","title":"Customizing Jack-in","text":"<p>The main mechanism for customizing your Jack-in, including automating menu selections, and custom CLJS REPL types is Custom Connect Sequences. See also Customizing Jack-in and Connect</p>","boost":7},{"location":"connect/#connecting-without-jack-in","title":"Connecting Without Jack-in","text":"<p>If, for whatever reasons, you can't use Jack-in with your project (possibly because the REPL is started as part of some other job) all is not lost. Old fashioned Connect to a running REPL is still there for you. For all features to work in Calva while connecting to a running REPL, your environment needs to have REPL related dependencies set up.</p> <p>However, just as before it can be tricky to get the dependencies right. Consider using Jack in to inform yourself on how to start your REPL to Calva's satisfaction. When you use Jack in, Calva starts a VS Code task for it and the command line used is displayed in the terminal pane used to handle the task. Reading that command line tells you what dependencies are needed for your project.</p> <p>Even better: Copying that command line gives you the command to start the REPL with the correct dependencies.</p> <p>All this said, I still recommend you challenge the conclusion that you can't use Jack-in.</p> <p>Copy the Jack-in command line</p> <p>There is a Calva command for copying the Jack-in command line to the clipboard. It will copy the command line including commands to change to the current REPL project root, avoiding hard-to-detect errors when starting the REPL in the wrong directory.</p> <p>The Generic Project Type</p> <p>A reason to use the connect to a running REPL way, can be that Calva does not have a built in connect sequence/project type for the particular REPL you want to connect to. Maybe it is something like Lingy which doesn't yet have a built in Calva connect sequence. As long as there is an nREPL server to connect to, you can Connect with Calva, using the Generic connect sequence/project type. (You can also create a connect sequence with a custom command line, and use Jack-in anyway.)</p> <p>See also Customizing Jack-in and Connect</p>","boost":7},{"location":"connect/#starting-the-repl-from-application-code","title":"Starting the REPL from application code?","text":"<p>If your project is setup so that the REPL server is started by the application code, you will need to get the cider-nrepl middleware in place. See the cider-nrepl docs about embedding nREPL in your application.</p>","boost":7},{"location":"connect/#auto-select-project-type-and-project-root","title":"Auto-select Project Type and Project Root","text":"<p>You can make both Jack-in and Connect stop prompting you for project type and project root path in projects where you always want to use the same. See Connect Sequences.</p>","boost":7},{"location":"connect/#monorepos-multiple-clojure-projects-in-one-workspace","title":"Monorepos / multiple Clojure projects in one workspace","text":"<p>If the workspace is a monorepo, Polylith repo or just a repository with more than one Clojure project, Calva will start the connect sequence with prompting for which project to start/connect to.</p> <p></p>","boost":7},{"location":"connect/#shadow-cljs","title":"shadow-cljs","text":"<p>Please see the shadow-cljs page.</p>","boost":7},{"location":"connect/#troubleshooting","title":"Troubleshooting","text":"","boost":7},{"location":"connect/#jack-in-and-main-opts","title":"Jack-in and <code>:main-opts</code>","text":"<p>When Calva starts the project REPL and connects to it (a.k.a. Jack-in), this is done by starting an nREPL server. For deps.edn projects this by default means that Calva will add <code>-m ...</code> with options that starts the server.</p> <p>However: If you choose an alias at Jack-in that specifies <code>:main-opts</code>, it will make the Clojure CLI to add main opts and Calva will then not override these by adding <code>-m ...</code> to the command line. This means that an alias that specify <code>:main-opts</code> must result in an nREPL server being started, or else Calva won't have a server to connect to. Calva won't further analyze this, but will just warn you at Jack-in.</p> <p>If you don't know if an alias starts an nREPL server or not, by all means, try it, if you have reasons for using that alias. You will notice if Jack-in works or not. If it doesn't work, you will need to run without that alias, or fix what happens when that alias is used so that an nREPL server is started. See https://nrepl.org/nrepl/usage/server.html about ways to do this.</p>","boost":7},{"location":"connect/#command-not-found-errors-when-jacking-in","title":"Command Not Found Errors When Jacking In","text":"<p>If you get <code>command not found</code> error when Calva tries to start your project, and you know you have the command installed, it's probably because VS Code starts from an environment where the command is not on the <code>$PATH</code>. It can look like so:</p> <pre><code>lein update-in :dependencies conj '[nrepl,\"0.8.3\"]' -- update-in :plugins conj '[cider/cider-nrepl,\"0.25.8\"]' -- update-in '[:repl-options,:nrepl-middleware]' conj '[\"cider.nrepl/cider-middleware\"]' -- repl :headless\n/bin/sh: lein: command not found\nJack-in process exited. Status: 127\n</code></pre> <p>The fix is to always start VS Code from the command line:</p> <pre><code>$ code\n</code></pre> <p>You might need to first run the Shell Command: Install <code>code</code> command in PATH.</p> <p>This will also make sure your REPL has access to the environment you probably expect it to have access to. See below.</p>","boost":7},{"location":"connect/#go-to-definition-not-working-for-java-definitions","title":"Go to Definition Not Working for Java Definitions","text":"<p>On some systems, the Java source may not be installed along with the JDK. The source must be present on your system in order to navigate to Java definitions. See this comment for more details.</p>","boost":7},{"location":"connect/#environment-variables-are-not-readable-from-repl","title":"Environment Variables Are Not Readable From REPL","text":"<p>If you've added environment variables in your OS, such as in your <code>~/.bashrc</code> file (Linux), in order for them to be read in a REPL created by Calva's jackin command, VS Code must be started from a shell where the environment variables are defined. For example, if you can open a bash terminal and run <code>echo $SOME_VAR</code> and see the value there, then open VS Code from that terminal with <code>code &lt;project path&gt;</code>.</p>","boost":7},{"location":"connect/#viewing-the-communication-between-nrepl-and-calva","title":"Viewing the Communication Between nREPL and Calva","text":"<p>It may be helpful to view the messages sent between nREPL and Calva when troubleshooting an issue related to the REPL. See how to do that here.</p>","boost":7},{"location":"contribute/","title":"Contribute to Calva","text":"<p>There are many ways to contribute:</p> <ul> <li>Become a sponsor</li> <li>Give us feedback:</li> <li>File issues</li> <li>Talk to us via the #calva channel at the Clojurians Slack (use the latter link to grab an invite)</li> <li>Provide PRs, see the Calva wiki about How to Hack on Calva</li> <li>Give us feedback, preferably via that <code>#calva</code> channel</li> <li>Cheer us on. (Same channel)</li> <li>Help us test things like reported issues, new features, etcetera. See Testing VSIX Packages and Smoke Testing</li> <li>Make tutorials, write blog articles, spread the word</li> <li>Star the Calva repository</li> <li>Help us help beginners with Calva and Clojure, on Slack as well as IRL and wherever.</li> </ul> <p>Be creative!</p>"},{"location":"contribute/#please-star-the-calva-repo","title":"Please star the Calva repo!","text":"<p>Happy Coding! \u2764\ufe0f</p>"},{"location":"custom-commands/","title":"Custom REPL Commands","text":"<p>Calva supports configuration of custom command snippets that you can evaluate in the REPL at will. This is useful if your workflow has you repeatedly evaluating a particular piece of code. There are two ways to use these:</p> <ol> <li>You can use the setting <code>calva.customREPLCommandSnippets</code> to configure it. Then either bind keyboard shortcuts to them or use the command Run Custom REPL Command to access it. The command will give you a menu with the snippets you have configured.</li> <li>You can bind a keyboard shortcut directly to a custom command snippet by inlining it in the shortcut definition. See Binding Keyboard Shortcuts</li> </ol> <p>Joyride</p> <p>For some use cases you might be better served by/want to combine these with using the VS Code Extension API, and that of Calva, or any other extension, through Joyride.</p> <p>The <code>calva.customREPLCommandSnippets</code> is an array of objects with the following fields (required fields in bold):</p> <ul> <li><code>name</code>: The name of the snippet as it will appear in the picker menu</li> <li><code>snippet</code>: The code that will be evaluated</li> <li><code>key</code>: A key can be used to reference the snippet from Run Custom REPL Command keyboard shortcut arguments. It will also be used in the quick-pick menu.</li> <li><code>ns</code>: A namespace to evaluate the command in. If omitted the command will be executed in the namespace of the current editor.</li> <li><code>repl</code>: Which repl session to use for the evaluation. Either <code>\"clj\"</code> or <code>\"cljs\"</code>. Omit if you want to use the session of the current editor.</li> <li><code>evaluationSendCodeToOutputWindow</code>: (default <code>true</code>) Whether the evaluated code should be echoed to the Output/REPL window.</li> </ul> <p>There are also substitutions available, which will take elements from the current state of Calva and splice them in to the text of your command before executing it. They are</p> <ul> <li><code>$line</code>: Current line number in editor</li> <li><code>$column</code>: Current column number in editor</li> <li><code>$file</code>: Full name of the current file edited</li> <li><code>$file-text</code>: The text of the current file edited</li> <li><code>$ns</code>: The namespace used for evaluating the command</li> <li><code>$editor-ns</code>: The namespace of the editor from which the command was run</li> <li><code>$selection</code>: The currently selected text</li> <li><code>$current-form</code>: The text of the current form</li> <li><code>$current-pair</code>: The text of the current pair if in a binding, otherwise empty string</li> <li><code>$enclosing-form</code>: The text of the current enclosing form</li> <li><code>$top-level-form</code> The text of the current top level form</li> <li><code>$current-fn</code>: The sexpr/form at call position in the current list, e.g. <code>str</code> with <code>(defn foo [] (str \"foo\" \"bar|\"))</code></li> <li><code>$top-level-defined-symbol</code>: The second symbol of the top level form, e.g. <code>foo</code> with <code>(defn foo [] (str \"foo\" \"bar|\"))</code></li> <li><code>$head</code>: The text between the start of the current list to the cursor</li> <li><code>$tail</code>: The text between the cursor and the end of the current list</li> </ul>","boost":4},{"location":"custom-commands/#user-and-workspace-settings","title":"User and Workspace Settings","text":"<p>Settings from your User (global) level and the workspace are merged.</p> <p>With these User settings:</p> <pre><code>    \"calva.customREPLCommandSnippets\": [\n        {\n            \"name\": \"Call Current Form\",\n            \"key\": \"c\",\n            \"snippet\": \"($current-form)\"\n        },\n        {\n            \"name\": \"Call Current Top Level Form\",\n            \"key\": \"t\",\n            \"snippet\": \"($top-level-form)\"\n        },\n        {\n            \"name\": \"CLJ Test Top Level Defined Symbol\",\n            \"repl\": \"clj\",\n            \"snippet\": \"(clojure.test/test-var #'$top-level-defined-symbol)\"\n        },\n        {\n            \"name\": \"CLJS Test Top Level Defined Symbol\",\n            \"repl\": \"cljs\",\n            \"snippet\": \"(cljs.test/test-var #'$top-level-defined-symbol)\",\n            \"key\": \"tab\"\n        }\n    ],\n</code></pre> <p>And these Workspace settings:</p> <pre><code>    \"calva.customREPLCommandSnippets\": [\n        {\n            \"name\": \"Remount CLJS App\",\n            \"key\": \"r\",\n            \"repl\": \"cljs\",\n            \"ns\": \"example.app\",\n            \"snippet\": \"(start)\"\n        }\n    ],\n</code></pre> <p>Issuing Run Custom REPL Command will then render this VS Code menu:</p> <p></p> <p>The default keyboard shortcut for the command is <code>ctrl+alt+space space</code>. (Beware: on MacOS it may conflict with the default shortuct for Input Sources - Select next source in Input menu.)</p>","boost":4},{"location":"custom-commands/#binding-keyboard-shortcuts","title":"Binding Keyboard Shortcuts","text":"<p>There are four ways to bind shortcuts to custom commands:</p> <ol> <li>Use a predefined <code>key</code> shortcut. These are predefined as <code>ctrl+alt+space &lt;something&gt;</code>, where <code>&lt;something&gt;</code> is one of:<ul> <li>The digits <code>0</code> through <code>9</code></li> <li>The English letters <code>a</code> through <code>z</code></li> <li>Arrow keys <code>right</code>, <code>left</code>, <code>up</code>, or <code>down</code></li> <li>One of <code>tab</code>, <code>backspace</code>, <code>,</code>, <code>.</code>, or <code>-</code> </li> </ul> </li> <li>Bind <code>calva.runCustomREPLCommand</code> to a shortcut with whatever code you want to evaluate in the <code>args</code> slot. You have access to the substitution variables here as well.</li> <li>Bind <code>calva.runCustomREPLCommand</code> to a keyboard shortcut referencing the <code>key</code> of one of your <code>calva.customREPLCommandSnippets</code>. (If not using any of the <code>key</code>s mentioned in 1.)</li> <li>Bind <code>calva.runCustomREPLCommand</code> to a shortcut with a <code>customREPLCommandSnippets</code> in the <code>args</code> slot. You have access to the substitution variables here as well.</li> </ol> <p>Here's an example shortcut entry for the 4th option:</p> <pre><code>    {\n        \"key\": \"ctrl+cmd+u alt+enter\",\n        \"command\": \"calva.runCustomREPLCommand\",\n        \"args\": {\n            \"ns\": \"user\",\n            \"snippet\": \"$current-form\",\n        }\n    },\n</code></pre> <p>This would evaluate the current form in the <code>user</code> namespace. Please note that this Custom REPL Command will not show up in the custom commands menu mentioned above.</p>","boost":4},{"location":"custom-commands/#custom-repl-hover-snippets","title":"Custom REPL Hover Snippets","text":"<p>Calva supports custom snippets that will display their result inside the tooltip. They will only work when connected to a repl, since they eval code in it. This is mostly useful for tooling authors that want to integrate with calva. Be careful with these, since they will be executed anytime Calva displays a tooltip. So they should be fast and probably not have any side effects.</p> <p>The hover snippets accept the same inputs as the Custom REPL Commands, except for the hotkey:</p> <pre><code>    \"calva.customREPLHoverSnippets\": [\n        {\n            \"name\": \"eval text on hover\",\n            \"repl\": \"clj\",\n            \"ns\": \"example.app\",\n            \"snippet\": \"(str \\\"$hover-text\\\")\"\n        }\n    ]\n</code></pre> <p>With this setting anything the mouse is over will also be shown inside its tooltip. There are now also <code>hover-</code> versions of most substitutions. Those currently only work inside the hover snippets.</p>","boost":4},{"location":"custom-commands/#configedn","title":"config.edn","text":"<p><code>:customREPLCommandSnippets</code> and <code>:customREPLHoverSnippets</code> can be also be configured in your user config at <code>.config/calva/config.edn</code> realative to your system home directory, or <code>.calva/config.edn</code> relative to the workspace root. Three things to note about this:</p> <ol> <li>None of these two configs get synced through VS Code Settings Sync.</li> <li>Changes to workspace <code>.calva/config.edn</code> will be automatically noticed by Calva, and refresh the config. This will not happen with the user config file.</li> <li>Internally in Calva, the settings are keyed on the snippet <code>:name</code> entry, and if you change the name, the old entry won't be removed until the VS Code window is reloaded.</li> </ol> <p>As for 2.: There is a command Calva: Refresh REPL snippets from User config.edn.</p> <p>There is also a command to open the User config.edn, for convenience: Calva: Open REPL snippets User config.edn. This command creates the file if it doesn't previously exist.</p>","boost":4},{"location":"custom-commands/#snippets-inside-deps","title":"Snippets Inside Deps","text":"<p>A new experimental feature lets library authors ship snippets inside their jar files. These accept the same options as above but should be placed in \"resources/calva.exports/config.edn\" inside the jar.</p> <pre><code>{:customREPLCommandSnippets\n [{:name \"edn test\"\n   :key \"a\"\n   :snippet ($current-form)}]\n :customREPLHoverSnippets\n [{:name \"edn hover\"\n   :snippet (str \"$hover-tex\")}\n  {:name \"edn hover show val\"\n   :snippet (str \"### EDN show val\\n```clojure\\n\" (pr-str (eval (symbol (str \"$ns\" \"/\" \"$hover-top-level-defined-symbol\")))) \"\\n```\")}]}\n</code></pre>","boost":4},{"location":"customizing-jack-in-and-connect/","title":"Customize Jack-in and Connect","text":"<p>Since Jack-in and connect both are about connecting the REPL, and only differ in how the REPL is started, many settings and configuration points are shared between the two concepts. A major customization point is Custom Connect Sequences, which are relevant for both Jack-in and Standalone Connect scenarios.</p> <p>This page lists some more Jack-in and Connect configuration options.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#auto-evaluate-code-on-connect","title":"Auto-evaluate Code on Connect","text":"<p>You can have Calva evaluate code whenever a REPL has been connected via the <code>calva.autoEvaluateCode.onConnect</code> setting. It has two entries <code>clj</code> and <code>cljs</code>:</p> <ul> <li><code>clj</code>: \"Code to evaluate when the Clojure REPL has been connected.<ul> <li>The default is code that refer in the <code>repl-requires</code>/REPL utilities (like <code>source</code>, <code>doc</code>, etcetera). (Note that there is also a command to do this on demand.).</li> <li>Overriding the default replaces it. If you want to add code to be evaluated on connect this way, and keep the behaviour of auto-refering REPL utilities, you need to provide code for the latter (copy/pasting the default code will do). See also note below about concatenation of configurations.</li> <li>The code will be evaluated before the <code>afterCLJReplJackInCode</code> in any connect sequence used.</li> </ul> </li> <li><code>cljs</code>: Code to evaluate when the ClojureScript REPL has been connected.<ul> <li>The default is code that refer in the <code>repl-requires</code>/REPL utilities (like <code>source</code>, <code>doc</code>, etcetera). (Note that there is also a command to do this on demand.).</li> <li>Same deal with overriding the default as with <code>clj</code>.</li> </ul> </li> </ul> <p>Set either of these to <code>null</code> to disable the feature for that REPL type. (The Settings linter will complain, but it works.)</p> <p>For Clojure this is in addition to <code>afterCLJReplJackInCode</code></p> <p>There are two mechanisms for evaluating code when a Clojure REPL is connected. The <code>afterCLJReplJackInCode</code> setting of custom connect sequences, and this <code>calva.autoEvaluateCode.onConnect.clj</code> setting. There is no fundamental difference between them. This one has a default function of auto-refering in the Clojure REPL utilities. And it will be run before the connect sequence after-Jack-in code.</p> <p>All configured code is concatenated</p> <p>If you configure this both in User/global settings and in a Workspace, the workspace configured code will be concatenated on the user level code. Meaning both code snippets will be evaluated, first the User level code, then the Workspace level code. Also <code>null</code> disables the feature:</p> <ul> <li>If you use <code>null</code> in the User level code, you will disable the onConnect code evaluation for all workspaces that do not configure code for this.</li> <li>If you configure code on the User level it will be evaluated in all workspaces, except those that disable the feature by configuring <code>null</code>.</li> </ul>","boost":7},{"location":"customizing-jack-in-and-connect/#auto-evaluate-code-at-filenamespace-loadevaluation","title":"Auto-evaluate Code at file/namespace load/evaluation","text":"<p>You can also make Calva auto-evaluate code when a file has been loaded in the REPL (via the Calva command for loading files). You add code for this via the <code>calva.autoEvaluateCode.onFileLoaded</code> setting. Like with <code>onConnect</code> you provide code for <code>clj</code> and <code>cljs</code> separately.</p> <ul> <li>Note that custom commands substitutions are in play here as well.</li> <li>Calva's does not provide defaults for this setting.</li> <li>Merging works the same as with <code>onConnect</code>.</li> </ul>","boost":7},{"location":"customizing-jack-in-and-connect/#customizing-connect","title":"Customizing Connect","text":"<p>If there is an nRepl port file, Calva will use it and not prompt for <code>host:port</code> when connecting. You can make Calva prompt for this by setting the boolean config <code>calva.autoSelectNReplPortFromPortFile</code> to <code>false</code>.</p> <p>With the setting <code>calva.autoConnectRepl</code> you can make Calva automatically connect the REPL if there is an nRepl port file present when the project is opened.</p> <p>With this and the below mentioned auto-select options you can make connect a prompt-less experience. See: Connect Sequences.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#options-for-the-connect-command","title":"Options for the Connect Command","text":"<p>The <code>calva.connect</code> command takes an optional options argument defined like so:</p> <pre><code>  options?: {\n    host?: string;\n    port?: string;\n    connectSequence?: string | ReplConnectSequence;\n    disableAutoSelect?: boolean;\n  }\n</code></pre> <p>Where <code>ReplConnectSequence</code> is a Connect Sequences. If you provide a string it needs to match against a built-in or custom connect sequence. With <code>disableAutoSelect</code> you can force the connect menus to be provided even if a custom connect sequence is set to be autoSelected.</p> <p>You can provide these options from keyboard shortcuts or from Joyride scripts.</p> <p>Here's a keyboard shortcut for connecting to a running REPL bypassing any connect sequence with <code>autoSelectForConnect</code>.</p> <pre><code>    {\n        \"command\": \"calva.connect\",\n        \"args\": {\"disableAutoSelect\": true},\n        \"key\": \"ctrl+alt+c shift+c\",\n    },\n</code></pre> <p>A Joyride command for connecting to a REPL on port 55555, without being asked for project type:</p> <pre><code>(vscode/commands.executeCommand \"calva.connect\" (clj-&gt;js {:port \"55555\" :connectSequence \"Generic\"}))\n</code></pre>","boost":7},{"location":"customizing-jack-in-and-connect/#customizing-jack-in","title":"Customizing Jack-in","text":"<p>The main mechanism for customizing your Jack-in, including automating menu selections, and custom CLJS REPL types is Custom Connect Sequences.</p> <p>There are also these settings:</p> <ul> <li><code>calva.jackInEnv</code>: An object with environment variables that will be added to the environment of the Jack-in process.</li> <li><code>calva.myCljAliases</code>: An array of <code>deps.edn</code> aliases not found in the project file. Use this to tell Calva Jack-in to launch your REPL using your user defined aliases.</li> <li><code>calva.myLeinProfiles</code>: An array of Leiningen profiles not found in <code>project.clj</code>. Use this to tell Calva Jack-in to launch your REPL using your user defined profiles.</li> <li><code>calva.openBrowserWhenFigwheelStarted</code>: For Legacy Figwheel only. A boolean controlling if Calva should automatically launch your ClojureScript app, once it is compiled by Figwheel. Defaults to <code>true</code>.</li> <li><code>calva.depsEdnJackInExecutable</code>: A string which should either be <code>clojure</code> or <code>deps.clj</code>, or <code>clojure or deps.clj</code> (default). It determines which executable Calva Jack-in should use for starting a <code>deps.edn</code> project. With this setting at its default, <code>clojure or deps.clj</code>, Calva will test if the <code>clojure</code> executable works, and use it if it does, otherwise <code>deps.clj</code> will be used, which is bundled with Calva.</li> <li><code>calva.jackInDependencyVersions</code>: See below</li> </ul> <p>Note</p> <p>When processing the <code>calva.jackInEnv</code> setting you can refer to existing ENV variables with <code>${env:VARIABLE}</code>.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#jack-in-dependency-versions","title":"Jack-in Dependency Versions","text":"<p>Calva Jack-in injects the following dependencies in order for the REPL session to support IDE features</p> <ul> <li>nrepl: nREPL is the wonderful piece of software that gives Calva a structured and extensible connection to the REPL in your Clojure and ClojureScript projects.</li> <li>cider-nrepl: cider-nrepl is middleware that extends the nREPL connection with all sorts of nice stuff that Calva uses to give you a delightful IDE experience.</li> <li>cider/piggieback: Piggieback is used to create nREPL sessions in ClojureScript projects. (Not with shadow-cljs projects though, which provides its own middleware for this.)</li> </ul> <p>The versions used are configurable via the VS Code settings <code>calva.jackInDependencyVersions</code>.</p> <p>Java 1.8 compatible versions</p> <p>The default dependency versions are not compatible with Java 1.8. If your project needs that version of Java you can use these settings in your Workspace <code>.vscode/settings.json</code>:</p> <pre><code>\"calva.jackInDependencyVersions\": {\n  \"nrepl\": \"1.0.0\",\n  \"cider-nrepl\": \"0.28.5\",\n  \"cider/piggieback\": \"0.5.3\"\n}\n</code></pre>","boost":7},{"location":"customizing-jack-in-and-connect/#options-for-the-jack-in-command","title":"Options for the Jack-in Command","text":"<p>The <code>calva.jackIn</code> command takes an optional options argument defined like so:</p> <pre><code>  options?: {\n    connectSequence?: string | ReplConnectSequence;\n    disableAutoSelect?: boolean;\n  }\n</code></pre> <p>Where <code>ReplConnectSequence</code> is a Connect Sequences. If you provide a string it needs to match against a built-in or custom connect sequence. With <code>disableAutoSelect</code> you can force the jack-in menus to be provided even if a custom connect sequence is set to be autoSelected.</p> <p>You can provide these options from keyboard shortcuts or from Joyride scripts.</p> <p>Here's a keyboard shortcut for connecting to a running REPL bypassing any connect sequence with <code>autoSelectForConnect</code>.</p> <pre><code>    {\n        \"command\": \"calva.jackIn\",\n        \"args\": {\"disableAutoSelect\": true},\n        \"key\": \"ctrl+alt+c shift+j\",\n    },\n</code></pre> <p>A Joyride command for starting a <code>deps.edn</code> REPL for a project in the root of the workspace.</p> <pre><code>(vscode/commands.executeCommand\n \"calva.jackIn\"\n (clj-&gt;js {:connectSequence {:projectType \"deps.edn\"\n                             :projectRootPath [\".\"]}}))\n</code></pre> <p>It will prompt for any aliases it finds in the <code>deps.edn</code> file.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#starting-the-repl-from-application-code","title":"Starting the REPL from application code?","text":"<p>If your project is setup so that the REPL server is started by the application code, you will need to get the cider-nrepl middleware in place. See the cider-nrepl docs about embedding nREPL in your application.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#auto-select-project-type-and-project-root","title":"Auto-select Project Type and Project Root","text":"<p>You can make both Jack-in and Connect stop prompting you for project type and project root path in projects where you always want to use the same. See Connect Sequences.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#project-roots-search-globing","title":"Project roots search globing","text":"<p>When searching for project roots in your workspace, Calva will glob for all files matching <code>project.clj</code>, <code>deps.edn</code>, or <code>shadow-cljs.edn</code>. This is done using VS Code's workspace search engine, and is very efficient. However, in a large monorepo, it is still a substantial task. In order to not waste resources Calva will exclude any directories in the setting <code>calva.projectRootsSearchExclude</code>.</p> <p></p> <p>Exclude entry globs</p> <p>Each entry is a partial glob and will be part of a resulting glob of the form <code>**/{glob1,glob2,...,globN}</code>. This means that all directories in the workspace matching an entry will be excluded, regardless of where in the workspace they reside.</p>","boost":7},{"location":"customizing-jack-in-and-connect/#viewing-the-communication-between-nrepl-and-calva","title":"Viewing the Communication Between nREPL and Calva","text":"<p>It may be helpful to view the messages sent between nREPL and Calva when troubleshooting an issue related to the REPL. See how to do that here.</p>","boost":7},{"location":"customizing/","title":"Customizing Calva","text":"<p>Don't like the defaults? On this page we can collect some of the customizations that people have done, and maybe write a thing or two about it some day.</p> <p>Tip for VS Code newcomers: The search box in Settings is your friend. Also, some Calva settings are more complex than the Settings UI can handle. VS Code will then show you a link to <code>settings.json</code>. And VS Code's built-in <code>json</code> extension is awesome. To add settings for Calva's Pretty Printing, for example, search for \u201dprettyprint\u201d in VS Code Settings and follow the link to <code>settings.json</code>. Start typing \u201dcalvapretty\u201d until auto-complete suggests <code>calva.prettyPrintingOptions</code>. Press ENTER and VS Code will fill in these defaults:</p> <pre><code>    \"calva.prettyPrintingOptions\": {\n        \"enabled\": true,\n        \"printEngine\": \"pprint\",\n        \"width\": 40\n    },\n</code></pre>"},{"location":"customizing/#clojure-defaults","title":"Clojure Defaults","text":"<p>Calva sets some VS Code settings for all Clojure files. Some of these are needed for Calva to function correctly, which should not be tampered with unless you really know what you are doing, and some of them are convenient defaults. If you add a setting to your <code>settings.json</code> and accept the snippet help you get when you type <code>\"[clojure]\"</code>, you will get the Calva defaults pasted:</p> <pre><code>    \"[clojure]\": {\n        \"editor.wordSeparators\": \"\\t ()\\\"':,;~@#$%^&amp;{}[]`\",\n        \"editor.autoClosingBrackets\": \"always\",\n        \"editor.autoClosingQuotes\": \"always\",\n        \"editor.autoClosingQuotes\": \"always\",\n        \"editor.formatOnType\": true,\n        \"editor.autoIndent\": \"full\",\n        \"editor.formatOnPaste\": true,\n        \"editor.matchBrackets\": \"never\",\n        \"editor.renderIndentGuides\": false,\n        \"editor.parameterHints.enabled\": false\n    }\n</code></pre> <p>Note</p> <p>The above <code>editor.wordSeparators</code> setting establish Clojure word boundaries. E.g <code>-</code> is considered to be part of words. This affects what happens when double-clicking symbols and other things. If you want to include <code>-</code> or something else as a word boundary, just add it to the setting.</p>"},{"location":"customizing/#pretty-printing","title":"Pretty Printing","text":"<p>Calva's pretty printing mode can be configured a bit. See Pretty Printing.</p>"},{"location":"customizing/#calva-highlight","title":"Calva Highlight","text":"<p>This is highly customizable. See Syntax highlighting</p>"},{"location":"customizing/#color-customizations","title":"Color customizations","text":"<p>Calva defines a set of themable colors which can be provided by the user using workbench.colorCustomizations.</p> <pre><code>    \"workbench.colorCustomizations\": {\n        \"calva.inlineErrorForegroundColor\": \"#ff0000\",\n        \"calva.inlineForegroundColor\": \"#ff9000\"\n    }\n</code></pre> <p></p>"},{"location":"customizing/#automatic-parameter-hints-poppup","title":"Automatic Parameter Hints Poppup","text":"<p>Calva has helpful parameter hints to aid when typing function calls. They look like so:</p> <p></p> <p>To have the hints automatically pop up when you are typing, set <code>editor.parameterHints.enabled</code> to <code>true</code> in the above <code>[clojure]</code> scoped setting. (To call them up on demand the default VS Code keybindings are <code>cmd+shift+space</code> on Mac and <code>ctrl+shift+space</code> on Linux/Windows.)</p>"},{"location":"customizing/#code-formatting","title":"Code Formatting","text":"<p>See Formatting for information on how to configure this.</p>"},{"location":"customizing/#jack-in-and-connect","title":"Jack-in and Connect","text":"<p>Jack-in and Connect are very customizable through Custom Connect Sequences.</p> <p>See also Customizing Jack-in and Connect</p>"},{"location":"customizing/#key-bindings","title":"Key bindings","text":"<p>Most of Calva's commands have default keybindings. They are only defaults, though, and you can change keybindings as you wish. To facilitate precision in binding keys Calva keeps some when clause contexts updated.</p>"},{"location":"customizing/#when-clause-contexts","title":"When Clause Contexts","text":"<p>The following contexts are available with Calva:</p> <ul> <li><code>calva:keybindingsEnabled</code>: a master switch that you find in the settings</li> <li><code>paredit:keyMap</code>: <code>strict</code>, <code>original</code>, or <code>none</code> from the corresponding Calva setting (see Paredit)</li> <li><code>calva:connected</code>: <code>true</code> when Calva is connected to a REPL (there is also <code>calva:connecting</code> || <code>calva:launching</code>)</li> <li><code>calva:outputWindowActive</code>: <code>true</code> when the Output/REPL window has input focus</li> <li><code>calva:replHistoryCommandsActive</code>: <code>true</code> when the cursor is in the Output/REPL window at the top level after the last prompt</li> <li><code>calva:replWindowSubmitOnEnter</code>: <code>true</code> when the cursor is adjacent after the last top level form in the Output/REPL window</li> <li><code>calva:cursorInString</code>: <code>true</code> when the cursor/caret is in a string or a regexp</li> <li><code>calva:cursorInComment</code>: <code>true</code> when the cursor is in, or adjacent to a line comment</li> <li><code>calva:cursorBeforeComment</code>: <code>true</code> when the cursor is adjacent before a line comment</li> <li><code>calva:cursorAfterComment</code>: <code>true</code> when the cursor is adjacent after a line comment</li> <li><code>calva:cursorAtStartOfLine</code>: <code>true</code> when the cursor is at the start of a line including any leading whitespace</li> <li><code>calva:cursorAtEndOfLine</code>: <code>true</code> when the cursor is at the end of a line including any trailing whitespace</li> </ul>"},{"location":"customizing/#some-custom-bindings","title":"Some Custom Bindings","text":"<p>Here is a collection of custom keybindings from here and there.</p> <ul> <li>Replace all Calva <code>ctrl+alt+...</code> key bindings with <code>ctrl+shift+...</code>, for keyboards lacking <code>alt</code> key: this gist</li> <li>Replace the default Calva \u201dprefix\u201d, <code>ctrl+alt+c</code> to just <code>alt+v</code>: WebWItch's keybindings.json (Please note, that <code>alt+v</code> does not work for some locales, but for when it works it is much less clunky than the default prefix).</li> <li>Here the Calva key is switched for <code>ctrl+,</code>: manas_marthi's keybindings</li> <li>Keybindings for Emacs users</li> <li>Use modifiers and WASD keys for movement and manipulation: isaksky's keybindings</li> </ul> <p>Are you a vim extension user? See: Using with VIM extension.</p>"},{"location":"customizing/#move-by-word","title":"Move by word","text":"<p>By default Calva changes the move-by-word key bindings to move by sexpr/form when the cursor is in structural Clojure code. Within line comments the editor default word movement is active.</p> <p>If you want the VS Code default word movement shortcuts, use these settings:</p> <pre><code>    {\n        \"key\": \"ctrl+right\",\n        \"win\": \"ctrl+right\",\n        \"mac\": \"alt+right\",\n        \"command\": \"cursorWordRight\"\n    },\n    {\n        \"key\": \"ctrl+left\",\n        \"win\": \"ctrl+left\",\n        \"mac\": \"alt+left\",\n        \"command\": \"cursorWordLeft\"\n    },\n    {\n        \"key\": \"ctrl+right\",\n        \"mac\": \"ctrl+right\",\n        \"win\": \"alt+right\",\n        \"command\": \"paredit.forwardSexp\",\n        \"when\": \"calva:keybindingsEnabled &amp;&amp; editorTextFocus &amp;&amp; editorLangId == 'clojure' &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+left\",\n        \"mac\": \"ctrl+left\",\n        \"win\": \"alt+left\",\n        \"command\": \"paredit.backwardSexp\",\n        \"when\": \"calva:keybindingsEnabled &amp;&amp; editorTextFocus &amp;&amp; editorLangId == 'clojure' &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    }\n</code></pre> <p>Use it as an inspiration for customizing things to your own liking. \ud83d\ude04</p>"},{"location":"customizing/#wrap-using-like-cursive","title":"Wrap using <code>(</code>, <code>[</code>, <code>{</code> (like Cursive)","text":"<p>Something I use in IntelliJ/Cursive is the ability to select an expression and hit one of <code>(</code>, <code>[</code>, <code>{</code> to wrap it. And after wrapping the expression I don't want the selection anymore, so if I were wrapping <code>(foo)</code> then I would want to get <code>( | (foo))</code> where <code>|</code> would be my cursor.</p> <p>Here's how you can make this work with Calva Paredit: Update all of the <code>Paredit: Wrap Around ...</code> commands so that their respective shortcuts are the wrappers themselves and update the <code>when</code> clause to include <code>editorHasSelection</code> (otherwise when you open a paren the next expression would get slurped in).</p> <p>The change would look like this in your <code>keybindings.json</code>:</p> <pre><code>    {\n        \"key\": \"shift+9\",\n        \"command\": \"paredit.wrapAroundParens\",\n        \"when\": \"editorTextFocus &amp;&amp; editorHasSelection &amp;&amp; !editorReadOnly &amp;&amp; editorLangId =~ /clojure|scheme|lisp/ &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"[\",\n        \"command\": \"paredit.wrapAroundSquare\",\n        \"when\": \"editorHasSelection &amp;&amp; editorTextFocus &amp;&amp; !editorReadOnly &amp;&amp; editorLangId =~ /clojure|scheme|lisp/ &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"shift+[\",\n        \"command\": \"paredit.wrapAroundCurly\",\n        \"when\": \"editorHasSelection &amp;&amp; editorTextFocus &amp;&amp; !editorReadOnly &amp;&amp; editorLangId =~ /clojure|scheme|lisp/ &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    }\n</code></pre>"},{"location":"debugger/","title":"Debugger","text":"<p>Calva comes with a powerful expression-based debugger, inspired by Cider's debugger, and using the same underlying library, cider-nrepl. We hope you love it!</p> <p></p> <p>Note</p> <p>The debugger currently does not support ClojureScript. Calva's debugger utilizes cider-nrepl for debugging. See this Cider issue for more information.</p>"},{"location":"debugger/#features","title":"Features","text":""},{"location":"debugger/#current","title":"Current","text":"<ul> <li>Instrument functions for debugging with <code>ctrl+alt+c i</code></li> <li>Instrument a function manually with <code>#dbg</code> (as opposed to the above command)</li> <li>Set individual breakpoints with <code>#break</code></li> <li>Continue to next breakpoint</li> <li>Step over form</li> <li>Step into form</li> <li>Step out of form</li> <li>Evaluate code in the debug context</li> <li>See variable values in the debugger side pane</li> <li>See variable values on hover in the editor</li> </ul>"},{"location":"debugger/#future-goals","title":"Future goals","text":"<ul> <li>See structured variables in the debugger side pane (currently maps and collections are just shown as strings)</li> <li>Inject values into the debug context</li> <li>Trace: continue, printing expressions and their values</li> </ul>"},{"location":"debugger/#dependencies","title":"Dependencies","text":"<p>The debugger itself relies pretty heavily on cider-nrepl, as do other parts of Calva. This library is loaded as a dependency when you use Calva Jack-in. If you are not using Calva Jack-in, you can add these dependencies in your project definition or user profile. See the Calva Jack-in guide for more information.</p>"},{"location":"debugger/#using-the-debugger","title":"Using the Debugger","text":"<p>If you're new to Clojure or expression-based debuggers, this debugger may function differently than what you're used to. Instead of placing breakpoints in the side margin and then hitting F5 to start debugging, you instead use Clojure reader tags, <code>#break</code> and <code>#dbg</code>, to denote breakpoints anywhere in a Clojure form. When you evaluate a call to a function that has been evaluated with that reader tag, the debugger will start when execution reaches the first breakpoint. There's also a convenience command to instrument functions. Read below about both options.</p> <p>Note</p> <p>The debugger is not configured via a <code>launch.json</code> file, and is not started in the same way as you may be used to when working with other languages in VS Code. The debugger is used by way of the REPL. If you are new to Clojure, please visit the Getting Started section of the documentation and get familiar with evaluating code using the REPL before using the debugger.</p>"},{"location":"debugger/#instrumenting-a-function","title":"Instrumenting a Function","text":"<p>You can instrument a top level function for debugging with <code>ctrl+alt+c i</code>. This places invisible breakpoints throughout the function where pausing makes sense. When you evaluate a call to this function, the debugger will start and execution will pause at the first breakpoint. Annotations show the value of the form at the cursor.</p> <p>A border is placed around the definition of the instrumented function and its references to show that it's instrumented. You can remove instrumentation by evaluating the function again normally, such as with <code>alt+enter</code>.</p> <p></p>"},{"location":"debugger/#setting-breakpoints-with-break","title":"Setting Breakpoints with <code>#break</code>","text":"<p>You can insert a breakpoint manually into any code by placing a <code>#break</code> in front of the form where you want execution to pause, and then evaluating the top level form with <code>alt+enter</code>. When you evaluate a call to this code the VS Code debugger will start, the cursor will move to right after the form that's preceded by <code>#break</code>, and the line will be highlighted to show execution is paused there.</p> <p></p> <p>Note</p> <p>Code will be executed up to and including the form after the breakpoint.</p>"},{"location":"debugger/#conditional-breakpoints","title":"Conditional Breakpoints","text":"<p>You can set conditional breakpoints by adding metadata before the form that the <code>#break</code> applies to.</p> <pre><code>(defn print-nums [n]\n  (dotimes [i n]\n    #break ^{:break/when (= i 7)} ;; This breakpoint will only be hit when i equals 7\n    (prn i)))\n</code></pre>"},{"location":"debugger/#instrumenting-a-form-with-dbg","title":"Instrumenting a Form with <code>#dbg</code>","text":"<p>Adding <code>#dbg</code> before a form then evaluating the form with <code>alt+enter</code> will instrument the form. This has the same effect as using the instrument command.</p> <p></p> <p></p>"},{"location":"debugger/#evaluating-code-in-the-paused-context","title":"Evaluating Code in the Paused Context","text":"<p>When execution is paused at a breakpoint, you can evaluate code in that context. This can be done in the editor or in the REPL window, as usual.</p> <p></p>"},{"location":"debugger/#viewing-variable-values","title":"Viewing Variable Values","text":"<p>While debugging, you can view the values of variables in VS Code's debugger side pane. You can also view values by hovering over the variables in the editor.</p> <p></p> <p>Metadata not available</p> <p>The variable viewer does not have access to any metadata attached to the variable values.</p>"},{"location":"debugger/#viewing-the-call-stack","title":"Viewing the Call Stack","text":"<p>While debugging, you can view the call stack in VS Code's call stack side pane. Clicking the stack frames will show the related line of code in an editor.</p> <p>Note</p> <p>You may only see one stack frame in the call stack side pane, as the change for adding additional frames was rolled back due to an issue. You can follow the change for this at #1150.</p> <p></p>"},{"location":"debugger/#stepping-commands","title":"Stepping Commands","text":"<p>You can use VS Code's debugger UI to advance execution while debugging.</p> <p></p> <p>Note</p> <p>Clicking restart does nothing, since this functionality does not make sense for our debugger.</p> <ul> <li>Continue - Continues without stopping for the current breakpoint</li> <li>Step over - Continues to the next breakpoint</li> <li>Step in - Steps in to the function about to be called. If the next breakpoint is not around a function call, does the same as next. Note that not all functions can be stepped in to - only normal functions stored in vars, for which cider-nrepl can find the source. You cannot currently step in to multimethods, protocol functions, or functions in clojure.core (although multimethods and protocols can be instrumented manually).</li> <li>Step out - Steps to the next breakpoint that is outside of the current sexp</li> <li>Restart - Does nothing. To restart debugging, you can hit disconnect or continue execution through the final result, then re-evaluate the expression that started the debugger.</li> <li>Disconnect - Disconnects the debugger</li> </ul>"},{"location":"debugger/#caveats","title":"Caveats","text":""},{"location":"debugger/#breakpoints-in-looprecur","title":"Breakpoints in loop/recur","text":"<p>One construct where the debugger is limited is <code>loop</code>/<code>recur</code>. As recur always has to appear in a tail-position inside a <code>loop</code> or a <code>fn</code> and the debugger uses macros to interleave breakpoints in the forms, it might happen that a <code>recur</code> no longer appears in a tail position. In that case we have to avoid setting up the breakpoint. An example of such a case is:</p> <pre><code>(loop [i 0]\n  #break\n  (when (&lt; i 10)\n    (println i)\n    (recur (inc i))))\n</code></pre> <p>Here the breakpoint is exactly in front of a form that contains as its last expression a <code>recur</code> which is wrapped in a loop. This breakpoint has no effect. This does not mean you cannot use the debugger with <code>loop</code>, it just means you have to set your debug statements more carefully.</p>"},{"location":"debugger/#loading-the-file-and-eval-on-save","title":"Loading the File and \"Eval On Save\"","text":"<p>When you load a file, any breakpoints that were previously set in functions will be unset. If you have the \"Eval On Save\" setting enabled, your file is also loaded with each save, therefore saving the file will remove breakpoints previously set.</p>"},{"location":"debugger/#troubleshooting","title":"Troubleshooting","text":""},{"location":"debugger/#debugger-hangs-when-stepping-over-infinite-seqs","title":"Debugger hangs when stepping over infinite seqs","text":"<p>This is because the debugger tries to evaluate the form when it's stepped over, and if <code>clojure.core/*print-length*</code> is set to <code>nil</code> as it is by default, evaluation will never complete. If you want to debug a form with an infinite seq, make sure to set <code>*print-length*</code> beforehand. For example:</p> <pre><code>(set! *print-length* 3)\n;; Or, to be more precise\n(set! clojure.core/*print-length* 3)\n</code></pre> <p>Calva does not set this for you during debug mode, instead leaving it up to you to decide the value.</p>"},{"location":"debugger/#my-breakpoint-isnt-being-hit","title":"My breakpoint isn't being hit","text":"<p>It's likely that your breakpoint is in a place that cider-nrepl does not see as an appropriate place to break execution. For example, if you put a breakpoint before a literal number, it will not be hit, because there's no need to show the value of a literal.</p> <pre><code>(defn simple [x]\n  (+ 1 #break 1)) ;; This breakpoint will not be hit\n</code></pre> <p>Another possible issue is that you're loading the file again after setting breakpoints, which unsets them. See Loading the File and \"Eval On Save\" under Caveats.</p>"},{"location":"debugger/#my-breakpoint-in-a-test-isnt-being-hit","title":"My breakpoint in a test isn't being hit","text":"<p>If you're using the test commands like \"Run current test\" to run your tests, breakpoints will not be hit. This is because Calva loads the file before running the tests to make sure the latest version of test code is being run, and when the file is loaded, breakpoints are unset.</p> <p>If you want a breakpoint to work within the test, evaluate the test form with a breakpoint tag in it, then call the test directly.</p> <p></p>"},{"location":"debugger/#no-reader-function-for-tag-error","title":"\"No reader function for tag\" error","text":"<p>If you get an error like this, it's likely that you connected to a REPL instead of jacking in, and you don't have the proper dependencies loaded in your REPL. You can run the command \"Copy Jack-in Command Line to Clipboard\" to see what command would be run if you jacked in.</p> <p>Most importantly, make sure you have <code>cider/cider-nrepl</code> as a dependency, and <code>cider.nrepl/cider-middleware</code> as middleware loaded in your REPL. For example, this is a jack-in command line for a deps.edn project:</p> <pre><code>clojure -Sdeps '{:deps {nrepl/nrepl {:mvn/version,\"0.8.3\"},cider/cider-nrepl {:mvn/version,\"0.25.8\"}}}' -m nrepl.cmdline --middleware \"[cider.nrepl/cider-middleware]\"\n</code></pre>"},{"location":"debugger/#passing-options-to-the-repl-jvm","title":"Passing options to the REPL JVM","text":"<p>There are times when Clojure debugging tools are not enough or not right for the job. This is usually true when use an (open source) Java library and you want to set some breakpoints in Java code. For those cases and others, you need to start the JVM in debug mode.</p> <p>Typical use cases:</p> <ul> <li>Change Java logger configuration for the REPL via java system properties: e.g <code>-Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE</code></li> <li>Enable JVM debugger, change VM memory size, etc.</li> </ul> <p>Calva supports passing environment variables via <code>jackInEnv</code>. You can set that option inside VSCode <code>settings.json</code> file.</p> <p>You can configure global <code>settings.json</code> file or a project wide version, inside <code>&lt;project-root&gt;/.vscode/settings.json</code>.</p> <p>Configuring the global option will impact all projects you work on using Calva, so be aware. See the documentation for <code>settings.json</code> for more information.</p> <p>The bellow snippet configures <code>JAVA_TOOL_OPTIONS</code> environment variable. We configure slf4j-simple logging level via a Java system property (<code>-D</code>) and JVM specific options (<code>-X</code>).</p> <p>NOTE: You can of course pass other env variables here.</p> <p>.vscode/settings.json</p> <pre><code>{\n    \"calva.jackInEnv\": {\n        \"JAVA_TOOL_OPTIONS\": \"${env:JAVA_TOOL_OPTIONS} -Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7896\"\n    }\n}\n</code></pre> <p>Once you saved the file, the next time you <code>Jack in</code> the project, this variable is read by the JVM and the configuration is applied accordingly.</p> <p>You should see something like the message below in the Calva terminal output window:</p> <pre><code>clojure -Sdeps '{:deps {nrepl/nrepl {:mvn/version,\"0.8.3\"},cider/cider-nrepl {:mvn/version,\"0.26.0\"}}}' -A:debug -m nrepl.cmdline --middleware \"[cider.nrepl/cider-middleware]\"\nPicked up JAVA_TOOL_OPTIONS:  -Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7896\nListening for transport dt_socket at address: 7896\nnREPL server started on port 46691 on host localhost - nrepl://localhost:46691\n</code></pre>"},{"location":"emacs-keybindings/","title":"Emacs Keybindings","text":"<p>Some keybindings to make it easier for Emacs users <pre><code>[\n    {\n        \"key\": \"ctrl+cmd+b\",\n        \"command\": \"paredit.backwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+alt+left\",\n        \"command\": \"-paredit.backwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"shift+cmd+]\",\n        \"command\": \"-workbench.action.nextEditor\"\n    },\n    {\n        \"key\": \"ctrl+shift+]\",\n        \"command\": \"paredit.barfSexpBackward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+right\",\n        \"command\": \"-paredit.barfSexpBackward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+[\",\n        \"command\": \"paredit.barfSexpForward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+left\",\n        \"command\": \"-paredit.barfSexpForward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+cmd+f\",\n        \"command\": \"paredit.forwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+alt+right\",\n        \"command\": \"-paredit.forwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+cmd+f\",\n        \"command\": \"-workbench.action.toggleFullScreen\"\n    },\n    {\n        \"key\": \"ctrl+shift+backspace\",\n        \"command\": \"-paredit.killSexpForward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"shift+cmd+k\",\n        \"command\": \"-editor.action.deleteLines\",\n        \"when\": \"textInputFocus &amp;&amp; !editorReadonly\"\n    },\n    {\n        \"key\": \"ctrl+shift+0\",\n        \"command\": \"paredit.slurpSexpForward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+right\",\n        \"command\": \"-paredit.slurpSexpForward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+9\",\n        \"command\": \"paredit.slurpSexpBackward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+left\",\n        \"command\": \"-paredit.slurpSexpBackward\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+c ctrl+c\",\n        \"command\": \"calva.evaluateCurrentTopLevelForm\",\n        \"when\": \"calva:activated\"\n    },\n    {\n        \"key\": \"ctrl+alt+c space\",\n        \"command\": \"-calva.evaluateCurrentTopLevelForm\",\n        \"when\": \"calva:activated\"\n    },\n    {\n        \"key\": \"ctrl+x ctrl+e\",\n        \"command\": \"calva.evalCurrentTopLevelFormInREPLWindow\",\n        \"when\": \"calva:activated\"\n    },\n    {\n        \"key\": \"ctrl+alt+c ctrl+alt+space\",\n        \"command\": \"-calva.evalCurrentTopLevelFormInREPLWindow\",\n        \"when\": \"calva:activated\"\n    },\n    {\n        \"key\": \"ctrl+x ctrl+s\",\n        \"command\": \"workbench.action.files.save\"\n    },\n    {\n        \"key\": \"cmd+s\",\n        \"command\": \"-workbench.action.files.save\"\n    },\n    {\n        \"key\": \"cmd+s\",\n        \"command\": \"paredit.spliceSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+alt+s\",\n        \"command\": \"-paredit.spliceSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+cmd+k\",\n        \"command\": \"paredit.cutForwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+x right\",\n        \"command\": \"-paredit.cutForwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+cmd+backspace\",\n        \"command\": \"paredit.cutBackwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+shift+x left\",\n        \"command\": \"-paredit.cutBackwardSexp\",\n        \"when\": \"calva:activated &amp;&amp; calva:pareditValid &amp;&amp; paredit:keyMap =~ /original|strict/\"\n    },\n    {\n        \"key\": \"ctrl+1\",\n        \"command\": \"-workbench.action.openEditorAtIndex1\"\n    },\n    {\n        \"key\": \"ctrl+1\",\n        \"command\": \"editor.action.quickFix\",\n        \"when\": \"editorHasCodeActionsProvider &amp;&amp; editorTextFocus &amp;&amp; !editorReadonly\"\n    },\n    {\n        \"key\": \"cmd+.\",\n        \"command\": \"-editor.action.quickFix\",\n        \"when\": \"editorHasCodeActionsProvider &amp;&amp; editorTextFocus &amp;&amp; !editorReadonly\"\n    },\n    {\n        \"key\": \"cmd+.\",\n        \"command\": \"editor.action.revealDefinition\",\n        \"when\": \"editorHasDefinitionProvider &amp;&amp; editorTextFocus &amp;&amp; !isInEmbeddedEditor\"\n    },\n    {\n        \"key\": \"f12\",\n        \"command\": \"-editor.action.revealDefinition\",\n        \"when\": \"editorHasDefinitionProvider &amp;&amp; editorTextFocus &amp;&amp; !isInEmbeddedEditor\"\n    }\n]\n</code></pre></p>"},{"location":"eval-tips/","title":"Code Evaluation","text":"<p>Calva tries to make it easy to evaluate code, supporting interactive development. The fastest path to learning about it is to use the Fire up the Getting Started REPL command, which you can learn more about in the Getting Started section.</p> <p>NB: The below assumes you have read about Finding Calva Commands and Shortcuts.</p>","boost":7},{"location":"eval-tips/#interruptingstopping-running-evaluations","title":"Interrupting/stopping running evaluations","text":"<p>Sometimes you evaluate things that take a very long time to complete, or might not even ever complete (infinite loops, lazy sequences, things like that). Calva has a command for interrupting running evaluations. You find it in the VS Code command palette, as well as in the REPL status bar item menu, when the REPL is connected.</p>","boost":7},{"location":"eval-tips/#evaluation-in-a-file-editor","title":"Evaluation in a File Editor","text":"<p>Calva has many commands for evaluating forms, including the current form and the current top-level form.</p> <p>Some of the commands also let you choose what should happen with the results:</p> <ol> <li>Inline. This will display the results (or some of it, if it is long) inline in the editor.</li> <li>This also creates a hover pane including the full results and a button which will copy the results to the clipboard.</li> <li>There is also a command for copying the last result to the clipboard.</li> <li>The full results are always available in the output window.<ul> <li>There is a command for showing the output window, allowing for a workflow where you either generally have it closed, or have it as one of the tabs in the same editor group as the files you are working with.</li> </ul> </li> <li>To comments. This will add the results as line comments below the current line.</li> <li>Replace the evaluated code. This will do what it says, the evaluated code will be replaced with its results.</li> </ol>","boost":7},{"location":"eval-tips/#wait-current-form-top-level-form","title":"Wait, Current Form? Top-level Form?","text":"<p>These are important concepts in Calva in order for you to create your most effective workflow. This video explains it a bit:</p>","boost":7},{"location":"eval-tips/#current-form","title":"Current Form","text":"<p>Default shortcut for evaluating the current form: <code>ctrl+enter</code>.</p> <p>The current form either means the current selection, or otherwise is based on the cursor position. Play some with the command Calva: Select current form, <code>ctrl+alt+c s</code>, to figure out what Calva thinks is the current form for some different situations. Try it inside a symbol, adjacent to a symbol (both sides) and adjacent to an opening or closing bracket (again, both sides). Generally the current form is determined like so:</p> <ol> <li>If text is selected, then that text</li> <li>If the cursor is \u201din\u201d a symbol, then that symbol    <pre><code>foob|ar ; foobar\n</code></pre></li> <li>If the cursor is adjacent to a form (a symbol or a list of some kind), then that form    <pre><code>(foo bar |(baz)) ; (baz)\n</code></pre></li> <li>If the cursor is between to forms, then the left side form    <pre><code>(foo bar | (baz)) ; bar\n</code></pre></li> <li>If the cursor is before the first form of a line, then that form    <pre><code>(foo\n| bar (baz)) ; bar\n</code></pre></li> </ol>","boost":7},{"location":"eval-tips/#current-top-level-form","title":"Current Top-level Form","text":"<p>Default shortcut for evaluating the current top level form: <code>alt+enter</code>.</p> <p>The current top-level form means top-level in a structural sense. It is not the topmost form in the file. Typically in a Clojure file you will find <code>def</code> and <code>defn</code> (and <code>defwhatever</code>) forms at the top level, which also is one major intended use for evaluating top level form: to define and redefine variables. However, Calva does not check the contents of the form in order to determine it as a top-level forms: all forms not enclosed in any other form are top level forms.</p> <p>An \u201dexception\u201d is introduced by the <code>comment</code> form. It will create a new top level context, so that any forms immediately inside a <code>(comment ...)</code> form will be considered top-level by Calva. This is to support a workflow with what is often referred to the Rich Comments.</p> <p>At the top level the selection of which form is the current top level form follows the same rules as those for the current form.</p>","boost":7},{"location":"eval-tips/#evaluate-enclosing-form","title":"Evaluate Enclosing Form","text":"<p>The default keyboard shortcut for evaluating the current enclosing form (the list the cursor is in) is <code>ctrl+shift+enter</code>.</p> <pre><code>(let [foo :bar]\n  (when false (str| foo))) ; =&gt; \":bar\"\n</code></pre>","boost":7},{"location":"eval-tips/#evaluate-to-cursor","title":"Evaluate to Cursor","text":"<p>There are several commands for evaluating a piece of code, closing brackets. It's good, especially in threads, but can also come in handy in other situations, for instance when you want to evaluate something that depends on bindings, such as in a <code>let</code> form.</p>","boost":7},{"location":"eval-tips/#evaluate-from-start-of-list-to-cursor-closing-brackets","title":"Evaluate From Start of List to Cursor, Closing Brackets","text":"<p>This command evaluates the text from the start of the current enclosing list to where the cursor is, and it adds the missing closing bracket for you. Convenient for checking intermediate results in thread or <code>doto</code>, or similar pipelines. The cursor is right behind <code>:d</code> in this form:</p> <pre><code>  (-&gt;&gt; [1 1 2 3 5 8 13 21]\n       (partition 2)\n       (zipmap [:a :b :c :d])\n       :d| ; =&gt; (13 21)\n       (apply -)\n       (Math/abs))\n</code></pre> <p>The default shortcut for this command is ctrl+alt+enter.</p>","boost":7},{"location":"eval-tips/#evaluate-selection-closing-brackets","title":"Evaluate Selection, Closing Brackets","text":"<p>This is the most versatile of the \u201devaluation, closing brackets\u201d commands. It will do what it says. \ud83d\ude04 It's extra handy in combination with the command Paredit: Select Backward Up Sexp/Form (shift+ctrl+up). Consider this contrieved form (buggy code, because it was supposed to result in <code>42</code>, not <code>-42</code>):</p> <pre><code>(defn fortytwo-from-thirty\n  []\n  (let [thirty 30]\n    (-&gt; thirty\n        inc            ;1\n        (send-off)\n        (+ 1 2 3)\n        (-&gt;&gt;\n         (+ 2 2)       ;2\n         (+))\n        list\n        (-&gt;&gt;\n         (into [1])\n         (reduce + 1))\n        (- 1)          ;3\n        (* -1))))\n</code></pre> <p>At <code>;1</code>, you can do backward up sexp (shift+ctrl+up) twice to select up to the <code>(let ..)</code>, then issue Evaluate Selection, Closing Brackets. It has the same default keybinding as the command for evaluating the current list up to the cursor: ctrl+alt+enter.</p> <p>At <code>;2</code> you need select backwards up three times.</p> <p><code>;3</code> is included because it is close to the bug. (Which was introduced when the thread-last, <code>-&gt;&gt;</code> was added to make this example.) Please practice the Evaluate Selection, Closing Brackets command to fix the bug.</p>","boost":7},{"location":"eval-tips/#evaluate-from-start-of-top-level-form-to-cursor-closing-brackets","title":"Evaluate From Start of Top Level Form to Cursor, Closing Brackets","text":"<p>This command has a default shortcut keybinding of <code>shift+alt+enter</code>. It will create a form from the start of the current top level form, up to the cursor, close all brackets, and this will then be evaluated. Good for examining code blocks up to a certain point. Often comes in handy in Rich comments (<code>(comment ...)</code>).</p> <p>Take this example and paste it in a file loaded into the REPL, then place the cursor in front of each line comment and try the command.</p> <pre><code>(comment\n (do\n   (def colt-express\n     {:name \"Colt Express\"\n      :categories [\"Family\"\n                   \"Strategy\"]\n      :play-time 40\n      :ratings {:pez 5.0\n                :kat 5.0\n                :wiw 5.0   ; 1, then eval `colt-express`\n                :vig 3.0\n                :rex 5.0\n                :lun 4.0}})\n\n   (defn average [coll]\n     (/ (apply + coll) (count coll)))\n\n   (let [foo-express (-&gt; colt-express\n                         (assoc :name \"Foo Express\")\n                         (assoc-in [:ratings :lyr] 5.0)\n                         (update-in [:ratings :vig] inc))]\n     (-&gt;&gt; foo-express   ; 2\n          :ratings      ; 3\n          vals          ; 4\n          average       ; 5\n          ))))\n</code></pre>","boost":7},{"location":"eval-tips/#evaluate-from-start-of-file-to-cursor-closing-brackets","title":"Evaluate From Start of File to Cursor, Closing Brackets","text":"<p>Yup, that command also exists. \ud83d\ude04</p>","boost":7},{"location":"eval-tips/#copying-the-inline-results","title":"Copying the inline results","text":"<p>There is a command called Copy last evaluation results, <code>ctrl+alt+c ctrl+c</code>.</p> <p>This works regardless if you have evaluated in a file editor or in a REPL window.</p>","boost":7},{"location":"eval-tips/#evaluating-in-a-repl-window","title":"Evaluating in a REPL window","text":"<p>Since the REPL Window is mostly just a regular file, things work pretty similar at the REPL prompt. You use <code>alt+enter</code> to evaluate. Selecting the current form (default key binding <code>ctrl+w</code> on Mac and <code>shift+alt+right</code> on Windows and Linux) after evaluating will select the result.</p>","boost":7},{"location":"evaluation/","title":"Code Evaluation","text":"<p>Calva tries to make it easy to evaluate code, supporting interactive development. The fastest path to learning about it is to use the Fire up the Getting Started REPL command, which you can learn more about in the Getting Started section.</p> <p>NB: The below assumes you have read about Finding Calva Commands and Shortcuts.</p>","boost":7},{"location":"evaluation/#interruptingstopping-running-evaluations","title":"Interrupting/stopping running evaluations","text":"<p>Sometimes you evaluate things that take a very long time to complete, or might not even ever complete (infinite loops, lazy sequences, things like that). Calva has a command for interrupting running evaluations. You find it in the VS Code command palette, as well as in the REPL status bar item menu, when the REPL is connected.</p>","boost":7},{"location":"evaluation/#evaluation-in-a-file-editor","title":"Evaluation in a File Editor","text":"<p>Calva has many commands for evaluating forms, including the current form and the current top-level form.</p> <p>Some of the commands also let you choose what should happen with the results:</p> <ol> <li>Inline. This will display the results (or some of it, if it is long) inline in the editor.</li> <li>This also creates a hover pane including the full results and a button which will copy the results to the clipboard.</li> <li>There is also a command for copying the last result to the clipboard.</li> <li>The full results are always available in the output window.<ul> <li>There is a command for showing the output window, allowing for a workflow where you either generally have it closed, or have it as one of the tabs in the same editor group as the files you are working with.</li> </ul> </li> <li>To comments. This will add the results as line comments below the current line.</li> <li>Replace the evaluated code. This will do what it says, the evaluated code will be replaced with its results.</li> </ol>","boost":7},{"location":"evaluation/#wait-current-form-top-level-form","title":"Wait, Current Form? Top-level Form?","text":"<p>These are important concepts in Calva in order for you to create your most effective workflow. This video explains it a bit:</p>","boost":7},{"location":"evaluation/#current-form","title":"Current Form","text":"<p>Default shortcut for evaluating the current form: <code>ctrl+enter</code>.</p> <p>The current form either means the current selection, or otherwise is based on the cursor position. Play some with the command Calva: Select current form, <code>ctrl+alt+c s</code>, to figure out what Calva thinks is the current form for some different situations. Try it inside a symbol, adjacent to a symbol (both sides) and adjacent to an opening or closing bracket (again, both sides). Generally the current form is determined like so:</p> <ol> <li>If text is selected, then that text</li> <li>If the cursor is \u201din\u201d a symbol, then that symbol    <pre><code>foob|ar ; foobar\n</code></pre></li> <li>If the cursor is adjacent to a form (a symbol or a list of some kind), then that form    <pre><code>(foo bar |(baz)) ; (baz)\n</code></pre></li> <li>If the cursor is between to forms, then the left side form    <pre><code>(foo bar | (baz)) ; bar\n</code></pre></li> <li>If the cursor is before the first form of a line, then that form    <pre><code>(foo\n| bar (baz)) ; bar\n</code></pre></li> </ol>","boost":7},{"location":"evaluation/#current-top-level-form","title":"Current Top-level Form","text":"<p>Default shortcut for evaluating the current top level form: <code>alt+enter</code>.</p> <p>The current top-level form means top-level in a structural sense. It is not the topmost form in the file. Typically in a Clojure file you will find <code>def</code> and <code>defn</code> (and <code>defwhatever</code>) forms at the top level, which also is one major intended use for evaluating top level form: to define and redefine variables. However, Calva does not check the contents of the form in order to determine it as a top-level forms: all forms not enclosed in any other form are top level forms.</p> <p>An \u201dexception\u201d is introduced by the <code>comment</code> form. It will create a new top level context, so that any forms immediately inside a <code>(comment ...)</code> form will be considered top-level by Calva. This is to support a workflow with what is often referred to the Rich Comments.</p> <p>At the top level the selection of which form is the current top level form follows the same rules as those for the current form.</p>","boost":7},{"location":"evaluation/#evaluate-enclosing-form","title":"Evaluate Enclosing Form","text":"<p>The default keyboard shortcut for evaluating the current enclosing form (the list the cursor is in) is <code>ctrl+shift+enter</code>.</p> <pre><code>(let [foo :bar]\n  (when false (str| foo))) ; =&gt; \":bar\"\n</code></pre>","boost":7},{"location":"evaluation/#evaluate-to-cursor","title":"Evaluate to Cursor","text":"<p>There are several commands for evaluating a piece of code, closing brackets. It's good, especially in threads, but can also come in handy in other situations, for instance when you want to evaluate something that depends on bindings, such as in a <code>let</code> form.</p>","boost":7},{"location":"evaluation/#evaluate-from-start-of-list-to-cursor-closing-brackets","title":"Evaluate From Start of List to Cursor, Closing Brackets","text":"<p>This command evaluates the text from the start of the current enclosing list to where the cursor is, and it adds the missing closing bracket for you. Convenient for checking intermediate results in thread or <code>doto</code>, or similar pipelines. The cursor is right behind <code>:d</code> in this form:</p> <pre><code>  (-&gt;&gt; [1 1 2 3 5 8 13 21]\n       (partition 2)\n       (zipmap [:a :b :c :d])\n       :d| ; =&gt; (13 21)\n       (apply -)\n       (Math/abs))\n</code></pre> <p>The default shortcut for this command is ctrl+alt+enter.</p>","boost":7},{"location":"evaluation/#evaluate-selection-closing-brackets","title":"Evaluate Selection, Closing Brackets","text":"<p>This is the most versatile of the \u201devaluation, closing brackets\u201d commands. It will do what it says. \ud83d\ude04 It's extra handy in combination with the command Paredit: Select Backward Up Sexp/Form (shift+ctrl+up). Consider this contrieved form (buggy code, because it was supposed to result in <code>42</code>, not <code>-42</code>):</p> <pre><code>(defn fortytwo-from-thirty\n  []\n  (let [thirty 30]\n    (-&gt; thirty\n        inc            ;1\n        (send-off)\n        (+ 1 2 3)\n        (-&gt;&gt;\n         (+ 2 2)       ;2\n         (+))\n        list\n        (-&gt;&gt;\n         (into [1])\n         (reduce + 1))\n        (- 1)          ;3\n        (* -1))))\n</code></pre> <p>At <code>;1</code>, you can do backward up sexp (shift+ctrl+up) twice to select up to the <code>(let ..)</code>, then issue Evaluate Selection, Closing Brackets. It has the same default keybinding as the command for evaluating the current list up to the cursor: ctrl+alt+enter.</p> <p>At <code>;2</code> you need select backwards up three times.</p> <p><code>;3</code> is included because it is close to the bug. (Which was introduced when the thread-last, <code>-&gt;&gt;</code> was added to make this example.) Please practice the Evaluate Selection, Closing Brackets command to fix the bug.</p>","boost":7},{"location":"evaluation/#evaluate-from-start-of-top-level-form-to-cursor-closing-brackets","title":"Evaluate From Start of Top Level Form to Cursor, Closing Brackets","text":"<p>This command has a default shortcut keybinding of <code>shift+alt+enter</code>. It will create a form from the start of the current top level form, up to the cursor, close all brackets, and this will then be evaluated. Good for examining code blocks up to a certain point. Often comes in handy in Rich comments (<code>(comment ...)</code>).</p> <p>Take this example and paste it in a file loaded into the REPL, then place the cursor in front of each line comment and try the command.</p> <pre><code>(comment\n (do\n   (def colt-express\n     {:name \"Colt Express\"\n      :categories [\"Family\"\n                   \"Strategy\"]\n      :play-time 40\n      :ratings {:pez 5.0\n                :kat 5.0\n                :wiw 5.0   ; 1, then eval `colt-express`\n                :vig 3.0\n                :rex 5.0\n                :lun 4.0}})\n\n   (defn average [coll]\n     (/ (apply + coll) (count coll)))\n\n   (let [foo-express (-&gt; colt-express\n                         (assoc :name \"Foo Express\")\n                         (assoc-in [:ratings :lyr] 5.0)\n                         (update-in [:ratings :vig] inc))]\n     (-&gt;&gt; foo-express   ; 2\n          :ratings      ; 3\n          vals          ; 4\n          average       ; 5\n          ))))\n</code></pre>","boost":7},{"location":"evaluation/#evaluate-from-start-of-file-to-cursor-closing-brackets","title":"Evaluate From Start of File to Cursor, Closing Brackets","text":"<p>Yup, that command also exists. \ud83d\ude04</p>","boost":7},{"location":"evaluation/#copying-the-inline-results","title":"Copying the inline results","text":"<p>There is a command called Copy last evaluation results, <code>ctrl+alt+c ctrl+c</code>.</p> <p>This works regardless if you have evaluated in a file editor or in a REPL window.</p>","boost":7},{"location":"evaluation/#evaluating-in-a-repl-window","title":"Evaluating in a REPL window","text":"<p>Since the REPL Window is mostly just a regular file, things work pretty similar at the REPL prompt. You use <code>alt+enter</code> to evaluate. Selecting the current form (default key binding <code>ctrl+w</code> on Mac and <code>shift+alt+right</code> on Windows and Linux) after evaluating will select the result.</p>","boost":7},{"location":"fiddle-files/","title":"Fiddle Files Support","text":"<p>In the podcast Functional Design in Clojure, Episode 014: Fiddle with the REPL, they discuss a workflow in which you keep some of your exploratory code in separate files, which they call Fiddle Files. It's like Rich Comments, 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 your project. Some developers keep personal fiddle files. In some projects they are meant to be shared, and in other projects it's a combination.</p> <p>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 a little configuration.</p>","boost":5},{"location":"fiddle-files/#the-three-fiddle-file-commands","title":"The Three Fiddle File Commands","text":"<p>The commands let you quickly navigate between your implementation code (called Source here) and your Fiddle file, and to evaluate the Fiddle file without leaving the Source file.</p> Command Action Shortcut Active Calva: Open Fiddle File for Current File Opens the Fiddle file corresponding to the current Clojure Source file. ctrl+alt+cf 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. ctrl+alt+cf 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. ctrl+alt+cctrl+alt+f When the currently active file is not a Fiddle file. <p>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 command will not offer to create the target file.</p> <p>What does corresponding mean here? Without any configuration Calva will look for \u201csibling\u201d files, where files with Clojure file extensions (E.g. <code>.clj</code>, <code>.cljs</code>, <code>.bb</code>) will be treated as Source files, and files with the <code>.fiddle</code> 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.</p>","boost":5},{"location":"fiddle-files/#the-fiddle-file-configuration","title":"The Fiddle File Configuration","text":"<p>To know how to map between Fiddle &lt;-&gt; Source files, Calva has three different modes of operation:</p> <ol> <li>The sibling files, as described above. This is the default. Example:<ul> <li><code>src</code><code>/a/b/c.cljc</code> corresponding to:</li> <li><code>src</code><code>/a/b/c.fiddle</code></li> </ul> </li> <li>Parallel directory structures. Mapping a Source directory tree to a Fiddle directory tree. Example:<ul> <li><code>src</code><code>/a/b/c.cljc</code> corresponding to:</li> <li><code>env/dev/fiddles</code><code>/a/b/c.cljc</code></li> </ul> </li> <li>A dedicated Fiddle file for a Source directory tree. E.g. both:<ul> <li><code>src</code><code>/a/b/c.cljc</code> and:</li> <li><code>src</code><code>/d/e/f.cljc</code> corresponding to:</li> <li><code>env/dev/fiddles</code><code>/x.cljc</code></li> </ul> </li> </ol> <p>The setting is named <code>calva.fiddleFilePaths</code> and is an array of <code>source</code> and <code>fiddle</code> root paths, relative to the project root.</p> <p>The Project Root</p> <p>It is important to note that the project root depends on whether you are connected to a REPL or not, and to which project you are connected, in case the workspace contains several projects.</p> <p>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.</p> <p>With a REPL connection, the project root will be the root of the project, i.e. where the project file (<code>deps.edn</code>, <code>project.clj</code>, <code>shadow-cljs.edn</code>) is.</p>","boost":5},{"location":"fiddle-files/#example-configurations","title":"Example Configurations","text":"","boost":5},{"location":"fiddle-files/#single-parallel-directory-structure","title":"Single Parallel Directory Structure","text":"<pre><code>\"calva.fiddleFilePaths\": [\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddles\"]\n  }\n]\n</code></pre> <p>This will make any file in the <code>src</code> directory tree correspond to a matching file with the same relative path. E.g.:</p> <ul> <li><code>src/a/b/c.clj</code> -&gt; <code>env/dev/fiddles/a/b/c.clj</code>, for both the open and evaluate commands</li> <li><code>env/dev/fiddles/a/b/c.clj</code> -&gt; <code>src/a/b/c.clj</code></li> </ul>","boost":5},{"location":"fiddle-files/#single-dedicated-fiddle-file","title":"Single Dedicated Fiddle File","text":"<p>If you generally work with one Fiddle file at a time, you can configure a mapping to a Dedicated Fiddle file. E.g.:</p> <pre><code>\"calva.fiddleFilePaths\": [\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddle.clj\"]\n  },\n]\n</code></pre> <p>This will make any file in the <code>src</code> directory tree correspond to the same Fiddle file. E.g.:</p> <ul> <li><code>src/a/b/c.clj</code> -&gt; <code>env/dev/fiddle.clj</code>, for both the open and evaluate commands</li> <li><code>src/d/e/f.clj</code> -&gt; <code>env/dev/fiddle.clj</code>, ditto</li> <li><code>env/dev/fiddle.clj</code> -&gt; Won't correspond to a Source file in this case</li> </ul> <p>Jumping from a dedicated fiddle to a source file</p> <p>Calva's command for opening the corresponding source file won't work in this case because it is a one-&gt;many situation. If you want to open the last file you worked with before using Open Fiddle File for Current File, consider using the VS Code command: Go Previous.</p>","boost":5},{"location":"fiddle-files/#multiple-mappings","title":"Multiple Mappings","text":"<p>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.</p> <pre><code>\"calva.fiddleFilePaths\": [\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddles\"]\n  },\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddle.clj\"]\n  },\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddle.cljs\"]\n  },\n  {\n    \"source\": [\"src\"],\n    \"fiddle\": [\"env\", \"dev\", \"fiddle.bb\"]\n  },\n  {\n    \"source\": [\"src\", \"b\"],\n    \"fiddle\": [\"env\", \"dev\", \"b-fiddles\"]\n  },\n]\n</code></pre> <p>With this configuration we would get a behaviour like so:</p> <ul> <li><code>src/a/b/c.clj</code> -&gt; <code>env/dev/fiddle.clj</code>, because all four first <code>[\"src\"]</code> mappings match, but the second one is a dedicated fiddle file, and matches the <code>.clj</code> extension.</li> <li><code>src/a/b/c/d.bb</code> -&gt; <code>env/dev/fiddle.bb</code>, because all four first <code>[\"src\"]</code> mappings match, but the second one is a dedicated fiddle file, and matches the <code>.bb</code> extension.</li> <li><code>src/a/b/c/d.cljc</code> -&gt; <code>env/dev/fiddle.clj</code>, because all four first <code>[\"src\"]</code> mappings match, but the second one is a dedicated fiddle file, without a matching  file extension, (so the first dedicated fiddle file is picked).</li> <li><code>src/b/c/d.clj</code> -&gt; <code>env/dev/b-fiddles/c/d.clj</code>, because the <code>[\"src\", \"b\"]</code> mapping is longer than the also matching <code>[\"src\"]</code> mappings.</li> </ul>","boost":5},{"location":"fiddle-files/#tips","title":"Tips","text":"<p>Organize your Fiddle files such that they do not get automatically loaded as part of your application. This can lead to strange errors and hard-to-detect bugs. Most often it should only be you manually loading the fiddle file, not clj/clojure or Leiningen or any such system which loads your application.</p> <p>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 happily comply.</p> <p>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.</p> <p>The linter and fiddle files</p> <p>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. You might find yourself wanting to silence some linters for some fiddle files. E.g. like this:</p> <pre><code>(ns main.core\n  {:clj-kondo/config\n   '{:linters {:unresolved-symbol {:level :off}}}})\n</code></pre> <p>See clj-kondo Configuration for more on what options you have for this.</p>","boost":5},{"location":"fiddle-files/#see-also","title":"See Also","text":"<ul> <li>Rich Comments</li> <li>Functional Design in Clojure Episode 014: Fiddle with the REPL</li> <li>The Polylith Development page mentions good practice for where to put your fiddle files (not called fiddle files there, but it is the same concept).</li> </ul>","boost":5},{"location":"finding-commands/","title":"Finding Calva Commands","text":"<p>Calva relies a lot on that VS Code makes it really easy to find commands by opening the command palette: <code>ctrl+shift+p</code> (Windows/Linux), <code>cmd+shift+p</code> (Mac), and then start typing some words (or parts of words) that you think might be in the command.</p> <p>To leverage this, all Calva commands are prefixed with <code>Calva</code>. As an example, say you want to find commands related to evaluating the top level form. Then you can do this:</p> <ol> <li>Open the command palette</li> <li>Type <code>calevtop</code></li> </ol> <p>VS Code will match <code>cal</code> to \u201dCalva\u201d, <code>ev</code> to \u201dEvaluate\u201d, and <code>top</code> to \u201dTop\u201d. It looks like so:</p> <p></p> <p>As you can see on the screenshot, VS Code will also reveal the keyboard shortcut for each command. My advice is to make it a habit to try to remember those shortcuts and use them for a more effective workflow.</p> <p>Now might be a good time to see Calva Top 10 Commands</p>"},{"location":"finding-commands/#all-the-settings-and-commands","title":"All the Settings and Commands","text":"<p>Did you know? There is a complete list of Calva settings and commands in the Contributions tab of the Calva entry in the Extensions pane in VS Code.</p> <p></p>"},{"location":"finding-commands/#toggling-keyboard-shortcuts-onoff","title":"Toggling Keyboard Shortcuts On/Off","text":"<p>The command <code>calva.toggleKeybindingsEnabled</code> can be used to quickly enable and disable (almost) all keyboard shortcuts. This allows you to quickly toggle between Calva keybindings and other keybindings which would otherwise not be available when Calva is enabled. This is particularly useful with the Paredit keyboard shortcuts, whose default shortcuts conflict with the default VS Code shortcuts for textual (non-structural) editing.</p> <p>By default it is not bound to a shortcut so as not to cause confusion by users unwittingly pressing it, but if this is something you'd like to use often, you may want to bind it to a shortcut.</p>"},{"location":"formatting/","title":"Formatting","text":"<p>We have tried to make Calva's formatter so that it just works. It is enabled by default for Clojure files, and with the default configuration it mostly follows Bozhidar Batsov's Clojure Style Guide. Calva uses cljfmt for the formatting.</p> <p>Tab formats the current surrounding form</p> <p>Calva's code formatter sets the default keybinding of its Format Current Form command to <code>tab</code>. Meaning that most often when things look a bit untidy, you can press <code>tab</code> to make things look pretty. Good to know, right? For performance reasons it only formats the current enclosing form, so sometimes you want to move the cursor up/out a form (<code>ctrl+up</code>) first. See The Paredit Guide for more on moving the cursor structurally through your code.</p> <p>With the default settings, Calva's formatting behaves like so:</p> <ul> <li>indents as you type (when entering new lines)</li> <li>formats the current enclosing form when you hit <code>tab</code></li> <li>formats pasted code</li> <li>formats according to community standards</li> <li>formats the current form, aligning map keys and values, when you press <code>ctrl+alt+l</code></li> <li>formats <code>(comment ...)</code> forms special, see rich comments</li> </ul> <p>Infer parens at will</p> <p>Calva has a command that will \u201dheal\u201d the bracket structure if it is correctly indented using Parinfer Infer parens. This command is default bound to <code>ctrl+alt+p i</code>.</p> <p>Also: If you have Format on Save enabled in VS Code, it will be Calva doing the formatting for Clojure files.</p> <p>Calva's formatting is mostly about indenting, but it also (again, defaults):</p> <ul> <li>trims whitespace at the end of the line</li> <li>trims whitespace inside brackets<ul> <li>this also folds trailing brackets (a k a the paren trail) up on the same line</li> </ul> </li> <li>inserts whitespace between forms</li> </ul> <p>Not a fan of some default setting? The formatter is quite configurable.</p>"},{"location":"formatting/#format-current-form-command-variants","title":"Format current form command variants","text":"<p>There are three special commands for formatting the current form:</p>"},{"location":"formatting/#1-format-and-align-current-form","title":"1. Format and Align Current Form","text":"<p>Aligns associative structures and bindings in two columns. See more below.</p>"},{"location":"formatting/#2-format-current-form-and-trim-space-between-forms","title":"2. Format Current Form and trim space between forms","text":"<p>This formats the text, and trims consecutive, non-indent, whitespace on a line to just one space. Something like:</p> <pre><code>(let [a    :b]\n(str \"foo\"     \"bar\" \"baz\"\n\"a\"    a))\n</code></pre> <p>Becomes:</p> <pre><code>(let [a :b]\n  (str \"foo\" \"bar\" \"baz\"\n       \"a\" a))\n</code></pre> <p>Basically, it behaves like if <code>:remove-multiple-non-indenting-spaces? true</code> was added to the <code>cljfmt</code> config. Which, in fact, is what happens. Calva merges that onto your cljfmt config when this command is used.</p>"},{"location":"formatting/#3-replace-current-form-or-selection-with-pretty-printed-form","title":"3. Replace Current Form (or Selection) with Pretty Printed Form","text":"<p>This command will run the code of the Current Form through Calva's pretty printer (the engine named <code>calva</code>, which is using zprint) and replace the current form inline in the editor with the pretty printed results.</p> <p>Unlike with the \u201dreal\u201d Calva Formatter, which never breaks up lines, this one will follow your pretty printing options and break up lines if you have set <code>maxWidth</code> to something that calls for breaking up lines.</p> <p>Applies to the other Current Form</p> <p>Unlike the other Format commands, which applies to the current enclosing form, this one applies to the Current Form, same as with evaluations. That is because this is not really part of the Calva formatter, but rather is a convenience command for tidying up code or data.</p>"},{"location":"formatting/#configuration","title":"Configuration","text":"<p>You can adjust the above mentioned defaults, and the default indents, by configuring the formatting using cljfmt's configuration EDN.</p> <p>This configuration can either be provided via a file or via clojure-lsp. See Providing configuration via clojure-lsp below.</p>"},{"location":"formatting/#providing-configuration-via-a-config-file","title":"Providing configuration via a config file","text":"<p>Calva will look for the configuration in one  of the default cljfmt paths ('.cljfmt.edn', '.cljfmt.clj', 'cljfmt.edn', or 'cljfmt.clj' in the workspace root). If your file is somewhere else use the <code>calva.fmt.configPath</code> to tell Calva where to find it. The path should either be absolute, or relative to the workspace root directory. If your config file is somewhere in the workspace root, Calva will hot reload it when you update it.</p> <p>Wherever the config file is, a suggested path for providing your configuration is to start changing the Calva formatting defaults by pasting the following map into a file and save it.</p> <pre><code>{:remove-surrounding-whitespace? true\n :remove-trailing-whitespace? true\n :remove-consecutive-blank-lines? false\n :insert-missing-whitespace? true\n :remove-multiple-non-indenting-spaces? false}\n</code></pre> <p>If the file is in the workspace, you can quickly test how different settings affect the formatting. Try:</p> <ol> <li>Adding <code>:align-associative? true</code> to the config</li> <li>then save</li> <li>then hit <code>tab</code>, and see what happens.</li> </ol> <code>:align-associative?</code> is experimental <p>This particular setting is experimental and known to cause trouble together with namespaced keywords. Consider using <code>ctrl+alt+l</code> instead of <code>tab</code> as your formatting command, instead of enabling this setting. See below for more info about this. See more below about this.</p> No Leiningen config support <p>The cljfmt docs mention the <code>:cljfmt</code> config key of Leiningen projects. Calva does not yet read the config from there, so if your Leiningen project has such a configuration, you will need to copy it out into a file.</p>"},{"location":"formatting/#providing-configuration-via-clojure-lsp","title":"Providing configuration via clojure-lsp","text":"<p>If you work in a team where some members use clojure-lsp for formatting, you can make Calva format using the same configuration by telling setting <code>calva.fmt.configPath</code> to <code>CLOJURE-LSP</code> (case sensitive). See Clojure LSP Settings) for how to provide the configuration. (It might not be provided from where you think it is, specifically check clojure-lsp's global config in you user home directory.) Use the command Calva Diagnostics: Clojure-lsp Server Info to see what cljfmt configuration is being used (under the <code>cljfmt-raw</code> key).</p> <p>Note that doing this you will not have hot reload of the formatting configuration, and of course you will be depending on that clojure-lsp is running and functioning.</p>"},{"location":"formatting/#indentation-rules","title":"Indentation rules","text":"<p>The <code>cljfmt</code> indents are highly configurable. They, and the rest of the configuration options, are masterly detailed here.</p> <p><code>:extra-indents</code> vs <code>:indents</code></p> <p>Since Calva <code>v2.0.383</code> we are using cljfmt <code>0.11.x</code> which has a breaking configuration change. From the cljfmt README:</p> <p>The <code>:indents</code> key has been split into <code>:indents</code> and :extra-indents. The <code>:indents</code> key replaces all default indents, while the <code>:extra-indents</code> key will append to the default indents.</p> <p>If something prevents you from using a config with <code>:extra-indents</code>, there's an escape hatch to keep using the <code>:indents</code> key as before, by adding <code>:legacy/merge-indents? true</code> to the config map.</p> <p>Calva is an extra good tool for experimenting with these settings. <code>cljfmt</code> doesn't care about keys in the map that it doesn't know about so you can sneak in test code there to quickly see how it will get formatted by certain rules. Try this, for instance:</p> <pre><code>{:remove-surrounding-whitespace? true\n :remove-trailing-whitespace? true\n :remove-consecutive-blank-lines? false\n :insert-missing-whitespace? false\n :indents {#re \"^\\w\" [[:inner 0]]}\n :test-code\n (concat [2]\n         (map #(inc (* % 2))\n              (filter #(aget sieved %)\n                      (range 1 hn))))}\n</code></pre> <p>Save, then hit <code>tab</code>, and the code should get formatted like so:</p> <pre><code> :test-code\n (concat [2]\n    (map #(inc (* % 2))\n      (filter #(aget sieved %)\n        (range 1 hn))))\n</code></pre> <p>That's somewhat similar to Nikita Prokopov's Better Clojure Formatting suggestion. (Please be aware that this setting might not be sufficient to get complete Tonsky Formatting, please share any settings you use to get full compliance.)</p>"},{"location":"formatting/#rich-comments","title":"Rich Comments","text":"<p>To encourage use of <code>(comment ...)</code> forms for development, the default settings give these forms get a special treatment when formatting. Use the <code>calva.fmt.keepCommentTrailParenOnOwnLine</code> setting to control this behaviour. See Rich Comments first.</p>"},{"location":"formatting/#etecetera","title":"Etecetera","text":""},{"location":"formatting/#about-aligning-associative-forms","title":"About aligning associative forms","text":"<p>Calva loooks in the config map for the key <code>:align-associative?</code> and if it is <code>true</code> it will use an old version of cljfmt which is patched with functionality for doing this alignment. Note, though:</p> <ul> <li>The implementation is a bit buggy and can do a bit crazy formatting on certain forms.</li> <li>The older version of cljfmt lacks updates for some new Clojure features and also some bugs fixed since the fork are not applied.</li> </ul> <p>You are hereby warned, and let us also remind you about the Format and Align Current Form command which lets you apply this formatting a bit more surgically, and on demand.</p> <p>This old version of cljfmt is inlined in the Calva repository along with the discontinued <code>rewrite-cljs</code> project. Regard it as frozen code. If you want Calva's formatter to have full support for newer Clojure constructs and the bugs in the alignment code fixed, contribute to cljfmt. See this issue for starting to collect context.</p>"},{"location":"get-started-with-clojure/","title":"Get Started with Clojure","text":"<p>Welcome to a zero-install, interactive, guide to get you started with Clojure using:</p> <ul> <li>Clojure</li> <li>Gitpod (A development environment delivered via the web browser)</li> <li>VS Code (Or Gitpod Code, actually. In your web browser.)</li> <li>Calva (A Clojure extension to VS Code. The thing this site is about.)</li> <li>Calva's Getting Started REPL</li> </ul> I have VS Code and Java <p>Clojure runs on the JVM. How to install it is a big topic. Since you have already done that, you can, if you want, choose to install Calva in your local VS Code and fire up the Getting Started REPL. By all means read this page anyway, you can just skip the Gitpod parts.</p> <p>Also: If you are using Windows your Java might have a bug that prevents things from working. Then you might want to defer fixing that and use the zero-install option first.</p> Is Gitpod Code exactly as VS Code? <p>Almost! But, yeah, there are some difference between regular VS Code and Gitpod's ditto. Most of it doesn't matter, but finding the main menu can be a bit tricky: </p>","boost":10},{"location":"get-started-with-clojure/#what-youll-learn","title":"What you'll learn","text":"<ul> <li>The basics of the Clojure language (at least the start of the basics)</li> <li>The basics of the ClojureScript language (we won't be using ClojureScript, but it is same language \ud83d\ude00)</li> <li>The basics of Calva (It's a bit as a side effect. You need it to learn Clojure this way, and by learning Clojure this way, Calva knowledge trickles in.)</li> <li>What is meant by, and some ways to perform, Interactive Programming (aka REPL Driven Development)</li> <li>Where to find Clojurians, i.e. folks who use Clojure and care about it (you will thus find help, the friendliest help you have ever seen a community provide)</li> </ul> I am not convinced I should spend time on learning Clojure <p>Fair enough. We can recommend watching any or all of these videos to get excited about Clojure and the rather unique mood of development it offers:</p> <p></p> <ul> <li>Solving Problems the Clojure Way - with Rafal Dittwald (using JavaScript, so no new syntax to grasp to get the message)</li> <li>Developer Ergonomics with VS Code, Clojure, and ClojureScript - with Peter Str\u00f6mberg</li> <li>Clojure in VS Code Workflow using FizzBuzz - with Peter Str\u00f6mberg</li> </ul>","boost":10},{"location":"get-started-with-clojure/#what-you-wont-learn","title":"What you won't learn","text":"<ul> <li>How to install Clojure for your operating system of choice</li> <li>About various old and new build and dependency tools</li> <li>How to create projects and do real stuff</li> </ul> Why won't I learn about this? <p>All in due time. \ud83d\ude04 It can be a bit confusing with all the things you find out about installing Clojure and creating projects when searching for information about it. We want you to relax about all that and just enjoy learning a bit about this fantastic programming language and the wonderful mode of development it offers.</p> <p>There is a lot of info about this out there already. And since you will learn where to find Clojurians, you will also find guidance. But we suggest do these things later. First, let's focus on having fun with Interactive Programming!</p>","boost":10},{"location":"get-started-with-clojure/#what-you-need","title":"What you need","text":"<ul> <li>Curiosity about Clojure</li> <li>A web browser</li> </ul> The browser ate my keyboard shortcuts! <p>There is always a competition for which system gets to catch keyboard shortcuts first. This worsens a bit when an application like VS Code runs in the web browser. Remember this if some shortcut/command doesn't work.</p> <p>On some machines, with some web browsers, some shortcuts are caught by the web browser and instead re-opening a closed tab or whatever. These have been observed:</p> <ul> <li>Undo (undoing something web browser related)</li> <li>Select the line (focusing the browser URL input)</li> <li>Open the command palette (opening a private browsing window. Looking at you Firefox.)</li> <li>Escape key shortcuts (are you using VIM bindings in your browser?)</li> </ul> <p>Sometimes the workaround is to redefine the shortcuts in VS Code, sometimes making your web browser stop catching the shortcut.</p> I am new to VS Code <p>You might want to have a look at this Getting Started with VS Code video. (You can of course ignore the parts about installing for now.) Also, have this overview of the VS Code interface handy.</p>","boost":10},{"location":"get-started-with-clojure/#how-it-works","title":"How it works","text":"<ol> <li>You will open an instance of VS Code in a development environment running in the browser. The environment will have Java, Clojure tools, and Calva installed.<ul> <li> Gitpod Sign-in    You will be asked to sign in to Gitpod, if you aren't already. You need to use the \u201dSign in with GitHub\u201d option. </li> </ul> </li> <li>Instructions will be automatically displayed (very brief such, because it is mainly about firing up the Getting Started REPL)</li> <li>The guides are a mix of prose (in Clojure line comments), Clojure code, and exercises. What's extra poetic is that you will use Calva and Clojure to learn Calva and Clojure.</li> </ol> <p>Use a desktop/laptop computer. Even if it actually works on the phone, it is far from convenient.</p> <p>It sometimes takes a while (several minutes) for the environment to initialize. Take some deep breaths and be patient. \ud83d\ude0e</p>","boost":10},{"location":"get-started-with-clojure/#lets-go","title":"Let's go!","text":"<p>Ready? Awesome. Click this button to start the guide in a new browser tab.</p> https://gitpod.io/#https://github.com/PEZ/get-started-with-clojure Stuck? Something not working? Or just unclear? <p>Please don't hesitate to reach out for help, should you get stuck. See below for where to find Clojurians. As for the Calva team, we are almost always (true story) to be found at the Clojurians Slack, especially in the <code>#calva</code> Channel. We are <code>@pez</code> and <code>@bringe</code> there.</p> <p>Happy Interactive Programming! \u2764\ufe0f</p>","boost":10},{"location":"get-started-with-clojure/#and-where-do-i-find-those-clojurians","title":"And where do I find those Clojurians?","text":"<p>We Clojurians inhabit a lot of community platforms. I'll list some of the more popular ones here in some order of popularity.</p> <ul> <li>The Clojurians Slack - by far the largest and most active Clojure community, the <code>#beginners</code> channel is spectacularly fantastic</li> <li>ClojureVerse - a web forum. Lots of Clojurians, lots of Clojure knowledge collected, easy to search, easy to join</li> <li>/r/Clojure - Reddit when Reddit is at its best, lots of Clojurians here</li> <li>Clojurians on Zulip - An other web forum using the Zulip platform</li> <li>On Discord there are two active servers: Clojurians and Discord</li> </ul> <p>You can also ask questions, and find answers, about Clojure at ask.clojure.org</p>","boost":10},{"location":"get-started-with-clojure/#learn-and-practice-clojure-using-rich-4clojure","title":"Learn and Practice Clojure using Rich 4Clojure","text":"<p>If you like the style of interactive learning that this guide provides, you should definitely check Rich 4Clojure out. It also can be used in the zero-installed way.</p> <p>You can regard it as a companion to this guide. It is aimed at practicing Clojure, starting at the elementary levels, bringing you to advanced stuff.</p> Can I use Rich 4Clojure instead of this guide? <p>We suggest you start by opening up this guide and do the Calva part of the excerises. Then use the <code>welcome_to_clojure.clj</code> guide in combination with Rich 4Clojure..</p>","boost":10},{"location":"get-started-with-clojure/#run-the-clojure-exercism-track-in-your-browser","title":"Run the Clojure Exercism Track in your browser","text":"<p>In a similar manner to the Get Started with Clojure project, you can run the Clojure Exercism Track in your browser without installing anything and with full Interactive Programming enabled using this Template project.</p>","boost":10},{"location":"get-started-with-clojure/#clojuredocs","title":"ClojureDocs","text":"<p>Clojurians draw tremendous value from ClojureDocs. At ClojureDocs the concise documentation for Clojure core functions, etcetera, are amended with examples and advice from fellow Clojurians. Crowdsourcing at its very best! It is a big part of the reason why you won't find an abundance of Clojure information at StackOverflow.</p>","boost":10},{"location":"get-started-with-clojure/#other-learning-resources","title":"Other learning resources","text":"<ul> <li>CalvaTV - Calva's YouTube channel often focuses on beginning with Clojure and ClojureScript. Subscribe, please!</li> <li>Clojure Beginner Resources - a much more comprehensive list than this one</li> <li>clojure.org Getting Started - the source of truth, includes installing and stuff</li> <li>The Exercism Clojure track - Learn solving carefully crafted Clojure exercises, get mentor feedback if you like.</li> <li>Clojure for the Brave and True - helping you from beginner to pretty advanced stuff, very popular among Clojurians</li> <li>on the code again - often features Clojure concepts, with snappy, well communicated, and entertaining videos</li> <li>Clojure Koans with VS Code/Calva instructions</li> </ul>","boost":10},{"location":"get-started-with-clojure/#help-us-help-beginners","title":"Help us help beginners","text":"<p>Give us feedback. Spread the word. Please consider:</p> <ul> <li>Join the <code>#improve-getting-started</code> channel at the Clojurian Slack</li> <li>Linking to this page from your blog</li> <li>Tweeting about this guide</li> <li>Contributing to the Calva project</li> <li>Wearing Calva and RFC T-shirts</li> <li>Starring these repositories:<ul> <li>Get Started with Clojure - (the repository powering this guide)</li> <li>Rich 4Clojure</li> <li>Clojure Exercism Track Template</li> <li>Calva</li> <li>Dram - Where this guide (the Getting Started REPL) is authored</li> </ul> </li> <li>What do beginners struggle with? - a ClojureVerse thread, where you can tell us about what you have found hard in picking up Clojure. It's what spawned the creation of this guide.</li> </ul> <p>Please also consider other ways to contribute.</p> <p>Thanks! \ud83d\ude4f</p>","boost":10},{"location":"getting-started/","title":"Getting Started","text":"<p>Depending on wether you want to just start a Clojure REPL or you have a project you want to work with, getting started looks similar but a bit different. Regardless, you need to first:</p>","boost":10},{"location":"getting-started/#install-vs-code-and-calva","title":"Install VS Code and Calva","text":"<ol> <li>Downloading VS Code and run the installer.<ul> <li>Also get aquainted to the basics of VS Code, if you aren't already. Here's an excellent intro: Getting Started with VS Code</li> </ul> </li> <li>Install Calva. The easiest way to do that is to start VS Code and search for <code>Calva</code> in the VS Code Extension pane, then click Install.</li> </ol>","boost":10},{"location":"getting-started/#say-hello-to-calva","title":"Say hello to Calva","text":"<p>If you have a Clojure or ClojureScript project, you will be interested in how to get Calva connected to the REPL of your project. But before you run over there, you might want to familiarize yourself with Calva a bit, which you can do without a project.</p> <p>The demo tells you about the command (and some about the Clojure Beginner's material that it makes available).</p> I am completely new to Clojure <p>The \u201dGetting Started\u201d REPL below introduces you to Clojure as well as to Calva. You might however, not want to start with installing the right version of Java and such to run the guide. If so you should definitely check the Get Started with Clojure guide on this site.</p> <p>Three clicks will have you running Calva in your browser with the REPL ready to serve.</p> I don't have Java installed <p>If you like, you can defer installing anything at all and still get started with Calva (not kidding).</p> <p>See Get Started with Clojure.</p>","boost":10},{"location":"getting-started/#theres-a-getting-started-repl","title":"There's a \u201dGetting Started\u201d REPL","text":"<p>If you are new to Calva, a good place to start is using the command Fire up the \u201dGetting Started\u201d REPL. (You can open the command palette using the VS Code top menu by going to <code>View -&gt; Command Palette...</code> or by running the associated keyboard shortcut for your OS.) Demo:</p> <p></p> <p>It will open up a three files in a temporary directory, and start and connect a REPL. The files are:</p> <ul> <li><code>hello_repl.clj</code> \u2013 The basics of how to evaluate code in Calva</li> <li><code>hello_paredit.clj</code> - A super brief intro to Calva structural editing</li> <li><code>welcome_to_clojure.clj</code> - The very basics of the Clojure language</li> </ul> <p></p> <p>The only prerequisite here is that you have Java installed. No pre-installed clojure tools required. (You will want to install these tools later, of course.)</p> <p>Note</p> <p>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 <code>PATH</code> of its environment for this feature to work. See this issue on the Calva repo for more on this, including any progress.</p>","boost":10},{"location":"getting-started/#there-are-standalone-clojurescript-quick-start-repls","title":"There are standalone \u201dClojureScript Quick Start\u201d REPLs","text":"<p>Without creating a project structure or installing anything but Calva, you can start standalone ClojureScript REPLs both in a browser and for node:</p> <ul> <li>Fire up the ClojureScript Quick Start Browser REPL<ul> <li>Opens the files <code>core.cljs</code> and <code>index.html</code> and starts the ClojureScript app, opening it in the browser.</li> </ul> </li> <li>Fire up the ClojureScript Quick Start Node REPL<ul> <li>Opens a file, <code>core.cljs</code>, and starts a nodejs REPL where it loads the file.</li> </ul> </li> </ul> <p>The browser REPL app looks like so:</p> <p></p>","boost":10},{"location":"getting-started/#you-have-a-project","title":"You have a Project?","text":"<p>If you are new to Calva, please consider the above option first. Then when it will be time to get Calva connected to the REPL of your project.</p>","boost":10},{"location":"getting-started/#clojure-resources","title":"Clojure Resources","text":"<p>If you are new to Clojure or ClojureScript altogether, please check out the guide material on the respective official sites:</p> <ul> <li>Getting Started with Clojure</li> <li>ClojureScript Quick Start</li> </ul> <p>There are also many great books on Clojure. Clojure for the Brave and True can be read for free online. It is a great resource for beginners.</p>","boost":10},{"location":"getting-started/#there-is-also-standalone-repl","title":"There is also Standalone REPL","text":"<p>When you are more familiar with Calva, and want a standalone REPL, there is a separate command: Start a standalone REPL (not in project). It will open up a <code>user.clj</code> in a temporary directory, containing only an <code>(ns user)</code> form, and start and connect the REPL.</p>","boost":10},{"location":"getting-started/#dram-where-the-guides-live","title":"Dram - Where the Guides Live","text":"<p>The command for starting the Getting Started REPL will download the files from this repository. It is very much work in progress, and there is not even a finished Clojure Beginner's Guide there yet. When you run the command again, and from then on, you will get the option to download new files or keep using your existing. Downloading new ones will not overwrite your existing ones, because they will be downloaded to a new temp directory. You can find the directory easily using VS Codes context menu command for revealing a file in the Explorer/Finder.</p>","boost":10},{"location":"getting-started/#one-last-thing","title":"One Last Thing","text":"<p>Happy coding! \u2665\ufe0f</p>","boost":10},{"location":"hiccup/","title":"Converting HTML to Hiccup","text":"<p>Calva can help you convert HTML to Hiccup.</p>","boost":7},{"location":"hiccup/#features","title":"Features","text":"","boost":7},{"location":"hiccup/#three-commands","title":"Three commands","text":"<ul> <li>Convert HTML to Hiccup, will convert the selected text, or the entire file, to Hiccup and open up an Untitled Clojure file with the result.</li> <li>Copy HTML as Hiccup, will convert the selected text, or the entire file, to Hiccup and copy it to the clipboard.</li> <li>Paste HTML as Hiccup, will convert the contents of the clipboard to Hiccup and paste it. (The clipboard will then be restored to the original content.)</li> </ul> <p>The resulting data structure is formatted with zprint using it's <code>:style :hiccup</code> configuration.</p>","boost":7},{"location":"hiccup/#conversion-capabilities","title":"Conversion capabilities","text":"<p>In addition to, optionally, being able to convert style attributes to maps and kebab-case attributes, the conversion: </p> <ul> <li>Opts for producing compact Hiccup:<ul> <li>The <code>id</code> attribute and classes are made part of the tag, CSS selector style<ul> <li><code>&lt;foo id=\"bar\"&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo#bar]</code></li> <li><code>&lt;foo class=\"c1 c2\"&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo.c1.c2]</code></li> <li><code>&lt;foo id=\"bar\" class=\"c1 c2\"&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo#bar.c1.c2]</code></li> </ul> </li> <li>Though, if the id or any class is not valid as part of a keyword, they remain in the props/attributes map)<ul> <li><code>&lt;foo id='foo-[id]'&gt;&lt;/foo&gt;</code> =&gt;  <code>[:foo {:id \"foo-[id]\"}]</code></li> <li><code>&lt;foo class='clz1 clz[2]'&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo.clz1 {:class [\"clz[2]\"]}]</code></li> </ul> </li> <li>Whitespace is trimmed<ul> <li><code>&lt;foo&gt; \\nbar\\n &lt;/foo&gt;</code> =&gt; <code>[:foo \"bar\"]</code></li> <li><code>&lt;foo&gt; \\n &lt;/foo&gt;</code> =&gt; <code>[:foo]</code></li> </ul> </li> </ul> </li> <li>Handles boolean attributes<ul> <li><code>&lt;foo disabled&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo {:disabled true}]</code></li> <li><code>&lt;foo disabled=disabled&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo {:disabled \"disabled\"}]</code></li> </ul> </li> <li>Special case for camelCasing attributes <code>viewBox</code> and <code>baseProfile</code> (SVG is picky about it)<ul> <li><code>&lt;foo bAsePROFilE=bar viewbox=\"0 0 1 1\"&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo {:baseProfile \"bar\" :viewBox \"0 0 1 1\"}]</code></li> </ul> </li> <li>Comments are retained<ul> <li><code>&lt;foo&gt;&lt;!-- ... --&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo (comment \"...\")]</code></li> </ul> </li> <li>You can have several top level tags<ul> <li><code>&lt;foo&gt;&lt;/foo&gt;&lt;foo&gt;&lt;/foo&gt;</code> =&gt; <code>[:foo]\\n[:foo]</code></li> </ul> </li> </ul>","boost":7},{"location":"hiccup/#it-is-somewhat-configurable","title":"It is somewhat configurable","text":"<p>The Hiccup converstion can be tweaked with two options using the setting <code>calva.html2HiccupOptions</code>, which is a map/object:</p> <ul> <li><code>mapify-style</code>: boolean, default <code>false</code>. When <code>true</code> any <code>style</code> attribute will be converted to a map (Reagent supports this)</li> <li><code>kebab-attrs?</code>: boolean, default <code>false</code>. When <code>true</code> attribute names will be converted from camelCase, or snake_case/SNAKE_CASE to kebab-case. (Reagent wants most attribute names like this.)</li> <li><code>add-classes-to-tag-keyword?</code>: boolean, default <code>true</code>. When <code>true</code> all class names will be added CSS-style to the tag keyword (<code>[:tag.clz1.clz2]</code>), as opposed to being kept in the class attribute. Keeping the class names in the attribute may be preferable with elements having a lot of class names, such as when using Tailwind CSS.</li> </ul>","boost":7},{"location":"hiccup/#copy-as-menus-copy-html-as-hiccup","title":"Copy as menus: Copy HTML as Hiccup","text":"<p>The Copy HTML as Hiccup command is available from VS Code's Edit menu, as well as the editor context menu, in both cases under the Copy as sub menu.</p> <p></p>","boost":7},{"location":"hiccup/#the-commands-take-arguments","title":"The commands take arguments","text":"<p>This options map can also be provided as an argument to the commands, so you can bind keyboard shortcuts to a particular configuration for the conversion. </p> <p>The command <code>calva.convertHtml2Hiccup</code> takes a map as an argument:</p> <ul> <li><code>toUntitled</code>: <code>boolean</code>, default <code>false</code>. When <code>false</code> the result of the conversion will be returned to the caller (This is intended for Joyride, or some other VS Code extension). When <code>true</code> it will behave like the default command does, placing the result of the conversion in an Untitled Clojure file.</li> <li><code>options</code>: Same as those <code>calva.html2HiccupOptions</code> mentioned above.</li> </ul> <p>The <code>calva.pasteHtmlAsHiccup</code> and <code>calva.copyHtmlAsHiccup</code> commands takes only a <code>calva.html2HiccupOptions</code> map.</p>","boost":7},{"location":"hiccup/#example-keyboard-shortcuts","title":"Example keyboard shortcuts","text":"<p>The commands have no default keyboard shortcuts, you use the Command Palette to execute them, or you bind your own shortcuts. Here are some examples:</p> <pre><code>    // calva.convertHtml2Hiccup\n    {\n        // With args, `\"toUntitled\": true` is necessary for keyboard shortcuts\n        // without it, the command just returns the result to the caller\n        \"key\": \"ctrl+alt+c ctrl+h\",\n        \"command\": \"calva.convertHtml2Hiccup\",\n        \"args\": {\"toUntitled\": true, \"options\": {\"mapify-style?\": false}}\n    },\n    {\n        // Only for completeness, providing the HTML is only useful from e.g. Joyride \n        \"key\": \"ctrl+alt+c shift+h\",\n        \"command\": \"calva.convertHtml2Hiccup\",\n        \"args\": {\"html\": \"&lt;foo style='a: b' bar='baz'&gt;gaz&lt;foo&gt;\", \"toUntitled\": true}\n    },\n    {\n        // Without args, the command uses the `calva.html2HiccupOptions` configuration\n        // And writes the results to an Untitled document\n        \"key\": \"ctrl+alt+c h\",\n        \"command\": \"calva.convertHtml2Hiccup\",\n    },\n\n    // calva.pasteHtmlAsHiccup\n    {\n        // Override the `calva.html2HiccupOptions` configuration\n        \"key\": \"ctrl+alt+h ctrl+v\",\n        \"command\": \"calva.pasteHtmlAsHiccup\",\n        \"args\": {\"mapify-style?\": true, \"kebab-attrs?\": true}\n    },\n    {\n        // Without args, the command uses the `calva.html2HiccupOptions` configuration\n        \"key\": \"ctrl+alt+h v\",\n        \"command\": \"calva.pasteHtmlAsHiccup\"\n    },\n\n    // calva.copyHtmlAsHiccup\n    {\n        // Override the `calva.html2HiccupOptions` configuration\n        \"key\": \"ctrl+alt+h ctrl+c\",\n        \"command\": \"calva.copyHtmlAsHiccup\",\n        \"args\": {\"mapify-style?\": false, \"kebab-attrs?\": true}\n    },\n    {\n        // Without args, the command uses the `calva.html2HiccupOptions` configuration\n        \"key\": \"ctrl+alt+h c\",\n        \"command\": \"calva.copyHtmlAsHiccup\"\n    },\n</code></pre> <p>The default/args-less bindings are placed last because reasons.</p>","boost":7},{"location":"hiccup/#using-from-joyride-or-some-other-vs-code-extension","title":"Using from Joyride (or some other VS Code extension)","text":"<p>As with any VS Code command using these from Joyride is a matter of calling <code>executeCommand</code>.</p>","boost":7},{"location":"hiccup/#calvapastehtmlashiccup-and-calvapastehtmlashiccup","title":"<code>calva.pasteHtmlAsHiccup</code> and <code>calva.pasteHtmlAsHiccup</code>","text":"<pre><code>(-&gt; (vscode/commands.executeCommand \"calva.pasteHtmlAsHiccup\"\n                                    #js {:mapify-style? true})\n    (.then ...))\n\n(-&gt; (vscode/commands.executeCommand \"calva.copyHtmlAsHiccup\"\n                                    #js {:mapify-style? true})\n    (.then ...))\n</code></pre>","boost":7},{"location":"hiccup/#calvaconverthtml2hiccup","title":"<code>calva.convertHtml2Hiccup</code>","text":"<p>Without options the command behaves just like selecting the command from the command palette. If there is a selection it will be converted, otherwise the whole file. The result will be opened in a new Untitled document.</p> <pre><code>(-&gt; (vscode/commands.executeCommand \"calva.convertHtml2Hiccup\")\n    (.then ...))\n</code></pre> <p>Called with arguments it will by default return an object with a <code>.-result</code> member which is a string with the Hiccup.</p> <pre><code>(-&gt; (vscode/commands.executeCommand \"calva.convertHtml2Hiccup\" \n                                    #js {:html \"&lt;foo class='clz1 clz2&gt;bar&lt;/foo&gt;\"})\n    (.then #(println (.-result %))))\n\n(-&gt; (vscode/commands.executeCommand \"calva.convertHtml2Hiccup\" \n                                    #js {:options #js {:mapify-style? false}})\n    (.then #(println (.-result %))))\n</code></pre> <p>To make it put the text in a new Untitled document instead, provide the argument option <code>:toUntitled true</code></p> <pre><code>(-&gt; (vscode/commands.executeCommand \"calva.convertHtml2Hiccup\" \n                                    #js {:toUntitled true\n                                         :html \"&lt;foo class='clz1 clz2&gt;bar&lt;/foo&gt;\"\n                                         :options #js {:mapify-style? true\n                                                       :kebab-attrs? true}})\n    (.then ...))\n</code></pre>","boost":7},{"location":"jack-in-guide/","title":"Learn about Calva Jack-in","text":"<p>The Calva Jack-In Academy, by @pez</p> <p>Like with CIDER Jack-in, Calva's let-me-help-you-start-your-project-and-connect feature might seem a bit mysterious. It really is helpful, but also really isn't mysterious. Here are a few things about it that is good to know about.</p> <p>Note</p> <p>If you came here to find out how to configure the versions of the dependencies that Calva Jack-in injects, see Customizing Calva - Jack-in Dependency Versions.</p>","boost":6},{"location":"jack-in-guide/#what-it-solves","title":"What it Solves","text":"<p>At first it might seem that something like <code>lein repl</code> in a terminal and then connecting Calva is enough. It sometimes might be, but only if you are in luck. To provide many of its IDE features, Calva relies on nREPL middleware, mainly cider-nrepl and, for ClojureScript, piggieback. When starting your Clojure(Script) app and its REPL, it needs to be started with these dependencies satisfied. There are mainly three ways this can be achieved.</p> <ol> <li>In the project definition (files like <code>project.clj</code>, <code>deps.edn</code>, <code>shadow-cljs.edn</code>, and combination of these).</li> <li>In your user profile (files like <code>~/.lein/profiles.clj</code> and <code>~/.clojure/deps.edn</code>).</li> <li>On the command line.</li> </ol> <p>Because 1 and 2 are hard to keep in sync with the various editor environments people in your project might be using, Calva Jack-In is about 3.</p> <p>Ideally, you will be able to rid your project files completely of editor dependencies when people working on the project can rely on the Jack-In features of their Clojure editor.</p>","boost":6},{"location":"jack-in-guide/#a-controlled-shell-command","title":"A Controlled Shell Command","text":"<p>At its core Calva Jack-In is just a glorified, REPL-starting, command-line. No, it is more than that, but anyway. The command line can look like so for a Leiningen project using legacy Figwheel for its ClojureScript assistance:</p> <pre><code>lein update-in :dependencies conj '[nrepl\"0.6.0\"]' -- update-in :dependencies conj '[cider/piggieback\"0.4.1\"]' -- update-in :dependencies conj '[figwheel-sidecar\"0.5.18\"]' -- update-in :plugins conj '[cider/cider-nrepl\"0.22.4\"]' -- update-in '[:repl-options :nrepl-middleware]' conj '[\"cider.nrepl/cider-middleware\"]' -- update-in '[:repl-options :nrepl-middleware]' conj '[\"cider.piggieback/wrap-cljs-repl\"]' -- with-profile +dev repl :headless\n</code></pre> <p>Even if a bit long, it might look simple enough. But actually it has taken quite some effort to make Calva craft it. Shell quoting can be really tricky. Look at how <code>'[nrepl\"0.6.0\"]'</code> doesn't have a space between <code>nrepl</code> and the version. That was the only way I could find that was cross platform enough to make all supported shells parse the command line. (The trick relies on that the string is read by the super reliable Clojure Reader, which does not need that space to tokenize it.)</p> <p>It is awesome that Clojure is used on so many platforms, but for a tool smith this also means more work. (I think Windows and its shell hell ate up about 95% of the many hours spent on getting the quoting good enough.)</p> <p>The command-line crafted is then used to start a shell command that Calva controls, but we are getting ahead of ourselves...</p>","boost":6},{"location":"jack-in-guide/#project-types-builds-aliases-profiles-etcetera","title":"Project Types, Builds, Aliases, Profiles, etcetera","text":"<p>In order to cook the right command for your project, Calva looks for project files, reads them, and figures out what possible project types and ClojureScript tools could be involved. Then Calva presents you with a menu with the options it has found. You need to know enough about your project to answer this question. It looks like this in a shadow-cljs project that uses a <code>deps.edn</code> file for setting up its classpath.</p> <p></p> <p>(I know enough about this particular project to know that I should choose the <code>shadow-cljs</code> project type.)</p> <p>But Calva isn't ready to cook the command-line just yet. Depending on the project type, and contents of your project files, more info is needed. E.g. in the case of shadow-cljs projects, Calva needs to know what builds to start.</p> <p></p> <p>Here you can select any combination of builds defined in the project, and Calva will cook a command line that starts them.</p> <p>You might get more prompts from Calva before it issues the command, but for this example project, Calva goes ahead, cooks the command line, and issues it. On my Mac, it looks like so:</p> <pre><code>npx shadow-cljs -d cider/piggieback:0.4.1 -d cider/cider-nrepl:0.22.4 watch :app\n</code></pre> <p>(Much shorter than the one with lein-figwheel, right? It is because shadow-cljs is aware of CIDER dependencies, so it doesn't need as many dependencies specified as some other project types do.)</p>","boost":6},{"location":"jack-in-guide/#connecting","title":"Connecting","text":"<p>When the command is issued Calva needs to wait until the REPL Server is started, before connecting to it and possibly continuing with starting a ClojureScript REPL and connecting to that as well. It also needs to know which port to connect to.</p> <p>Because reasons, Calva can't yet read the <code>stdout</code> of the shell command it has issued, so to know when the REPL server is started, and on which port, Calva monitors the filesystem for the <code>.nrepl-port</code> file. (This file is not always named like that. shadow-cljs, for instance, creates the file <code>.shadow-cljs/nrepl.port</code>.)</p> <p>When the port file is created, Calva picks up the port number from it and connects to the nREPL server. At this point you have a Clojure REPL backing your Calva session, providing all sorts of nice IDE help for you.</p>","boost":6},{"location":"jack-in-guide/#starting-your-clojure-app","title":"Starting Your Clojure App","text":"<p>Once you have the Clojure REPL connected you can start your Clojure app/server. See Custom Connect Sequences for how to let Calva do this for you automatically. See the same article for ways to automate more of the Jack-In process. It can be brought down to a single Jack-In command/action, even for a full stack Clojure and ClojureScript application.</p>","boost":6},{"location":"jack-in-guide/#clojurescript","title":"ClojureScript","text":"<p>For ClojureScript, things are not done yet, though, far from it. It turns out that cooking the command line was the easy part.</p> <p>In order for Calva to provide REPL power for ClojureScript projects, several things need to happen:</p> <ol> <li>A Clojure nREPL connection needs to be established. We've covered that above. Calva makes an nREPL session clone to use for the ClojureScript REPL and then:</li> <li>Your ClojureScript app needs to be compiled.</li> <li>Your ClojureScript app needs to be started.</li> <li>The Clojure nREPL session needs to be promoted to a ClojureScript nREPL session. (This is what piggieback helps with.)</li> </ol>","boost":6},{"location":"jack-in-guide/#compiling-the-app-and-watchers","title":"Compiling the App and Watchers","text":"<p>Depending on ClojureScript project type, Calva uses different methods to start the compilation and the watcher:</p> <ul> <li>Figwheel: The compilation and the watchers are started in the Clojure REPL session. (This is both for Figwheel Main and for lein-figwheel.)</li> <li>shadow-cljs: The compilation and the watchers are started with the Jack-In command line.</li> </ul> <p>This results in a bit of difference in the user interaction. Mainly that for shadow-cljs, the user needs to check the Jack-In Terminal tab to follow what's going on.</p>","boost":6},{"location":"jack-in-guide/#starting-the-app","title":"Starting the App","text":"<p>Number 3 above, the app needs to be started, might seem obvious, but it actually trips many people up. Because of this, Calva goes to quite some lengths to provide assistance. Many projects are configured not to spawn a browser session automatically, requesting the app once it has been compiled, so we can't rely on that.</p> <p>What Calva does instead is to monitor the output of the commands it uses for starting the compilation, looking for information that the app is ready to be requested/started. It then tells the user this, providing a URL, in case it is a browser app. (There are also settings that tell Calva to open the URL automatically for you, regardless what the project settings are.)</p>","boost":6},{"location":"jack-in-guide/#connecting_1","title":"Connecting","text":"<p>Meanwhile, Calva is monitoring the output and when it sees that the app is started, it continues to hook up the REPL connection to the editor.</p> <p>This whole connection sequence is quite configurable, using Custom Connect Sequences. In fact, Calva's built in ClojureScript sequences (Figwheel Main, lein-figwheel, shadow-cljs, and ClojureScript built-ins for both Browser and Node) are all built using those same settings mechanisms.</p>","boost":6},{"location":"jack-in-guide/#shadow-cljs-is-less-managed-by-calva","title":"shadow-cljs is Less Managed by Calva","text":"<p>NB: The managed way in which Calva creates and connects the ClojureScript REPL breaks apart a bit for shadow-cljs, which works a bit differently and also outputs most of the information Calva is looking for on the <code>stdout</code> of the REPL start command (where Calva can't see it, remember?). We'll figure out a better way to support shadow-cljs, but for now, the user needs to do more of this figuring out than is needed with Figwheel projects.</p>","boost":6},{"location":"jack-in-guide/#hack-away","title":"Hack Away","text":"<p>So, there are things going on when you start Jack-In, and even more things for ClojureScript projects, but Calva tries to keep it together, so as a user it is a matter of paying attention and responding to a few prompts/menus with pre-populated options (prompts which can be configured away, even).</p>","boost":6},{"location":"jack-in-guide/#switch-clojurescript-builds","title":"Switch ClojureScript Builds","text":"<p>Once the REPL is connected you might want to change which ClojureScript build you have Calva connected to. For this Calva has the Select CLJS Build Connection command. Please note that you can only switch between builds that you have started.</p>","boost":6},{"location":"jack-in-guide/#play-with-starting-the-cljs-repl-yourself","title":"Play With Starting the <code>cljs-repl</code> Yourself","text":"<p>To get a good grip on what is going on when creating and connecting the ClojureScript REPL, I can recommend making a custom connect sequence which leaves the REPL unpromoted (e.g. give it <code>nil</code> as <code>connectCode</code>), and then evaluate the <code>cljs-repl</code> start commands yourself. So for instance, promoting it to a ClojureScript Node.js REPL looks something like so:</p> <pre><code>user=&gt; (require 'cljs.repl.node)\nuser=&gt; (cider.piggieback/cljs-repl (cljs.repl.node/repl-env))\nClojureScript 1.10.844\nTo quit, type: :cljs/quit\nnil\ncljs.user=&gt; |\n</code></pre> <p>It is the piggieback middleware there telling you that you can unpromote the REPL by \u201devaluating\u201d <code>:cljs/quit</code>.</p>","boost":6},{"location":"jack-in-guide/#about-full-stack-applications","title":"About Full Stack Applications","text":"<p>Because Calva uses the Clojure REPL connection to spawn the ClojureScript REPL, and because Calva only handles one Clojure REPL per VS Code window, some projects need special handling by the user.</p> <p>If your full stack project is using shadow-cljs for the frontend, like this Fulcro template project does, maybe you first try to Jack-In to your backend Clojure REPL, and then to your shadow-cljs frontend. This works if you do it in separate VS Code windows, but if you do it in the same window, the second Jack-In will kill the backend session! See also connect shadow-cljs in fullstack projects.</p> <p>See Workspace Layouts for tips about how to open the same project folder in two separate VS Code windows.</p> <p>Please also consider to play around with starting the REPL and ClojureScript wiring entirely from the terminal, see this example project for some instructions on that. You can also use that project together with the <code>nil</code> for <code>connectCode</code> sequence mentioned above.</p>","boost":6},{"location":"jack-in-guide/#please-grab-your-calva-jack-in-certificate","title":"Please Grab your Calva Jack-In Certificate","text":"<p>There, you now know all there is to know about Calva Jack-In.</p> <p>Just kidding, there are a few more details to it, some of which might find their way into this article at a later time.</p> <p>To really get to know it all, you will need to spend some time with the Calva Jack-In code. Head over to the Calva Development Wiki to learn how to hack on Calva.</p>","boost":6},{"location":"joyride/","title":"Using Calva With Joyride","text":"<p>Joyride is a VS Code extension for user space scripting of VS Code itself. You find the extension here. The scripting language for Joyride is the best you language imaginable: Clojure. And, as is proper for a Clojure implementation, it has a REPL, even an nREPL server.</p> <p>This means you can connect Calva to Joyride and interactively develop your VS Code scripts.</p> <p>This video shows Joyride in action, using Calva as the nREPL client.</p>"},{"location":"joyride/#how-to-connect","title":"How to connect","text":"<p>Once you have the Joyride extension installed you can start its REPL and connect Calva to it (a.k.a Jack-in).</p> <p>Start the Joyride REPL and Connect</p> <p>This 1 minute video shows the following steps:</p> <ol> <li>Installing the Joyride Extension</li> <li>Isssuing the command Calva: Start a REPL in your Project and (a.k.a Jack-in)</li> <li>Selecting <code>joyride</code> project type</li> <li>Isssuing the command Calva: Load/Evaluate Current File and its Requires/Dependencies</li> <li>Evaluating some non-vscode code</li> <li>Evaluating code exercising something from the VS Code API</li> </ol> <p>(Right-click the video and choose Full Screeen if it is too tiny embedded.)</p>"},{"location":"joyride/#how-to-get-started-with-joyride","title":"How to Get Started with Joyride","text":"<p>The Joyride README has some Quick Start pointers for you. Please feel invited to the <code>#joyride</code> channel on the Clojurians Slack and chat with us and other Joyride users.</p> <p>Come on, Join the Joyride! \u2764\ufe0f</p>"},{"location":"krell/","title":"Using Calva With Krell","text":"<p>Krell is \u00e0 la carte ClojureScript tooling for React Native.</p> <p>Even if Calva does not yet have built-in support, all is not lost. You can add support yourself by way of a Custom REPL Connect Sequence. Here's how;</p>"},{"location":"krell/#starting-the-krell-clojurescript-repl","title":"Starting the Krell ClojureScript REPL","text":"<p>Add this REPL Connect Sequence to your workspace <code>settings.json</code>:</p> <pre><code>    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"deps.edn + Krell\",\n            \"projectType\": \"deps.edn\",\n            \"cljsType\": {\n                \"connectCode\": \"(require '[clojure.edn :as edn] \\n    '[clojure.java.io :as io]\\n    '[cider.piggieback] \\n    '[krell.api :as krell]\\n    '[krell.repl])\\n\\n(def config (edn/read-string (slurp (io/file \\\"build.edn\\\"))))\\n(apply cider.piggieback/cljs-repl (krell.repl/repl-env) (mapcat identity config))\",\n                \"dependsOn\": \"User provided\"\n            }\n        }\n    ]\n</code></pre> <p>Then issue the command Start a Project REPL and Connect (aka Jack-In). It start the project and connect to the Krell REPL once the app is running on a device (wether real or virtual/emulated).</p>"},{"location":"krell/#additional-vs-code-tips","title":"Additional VS Code Tips","text":"<p>For a smooth workflow you can also:</p> <ul> <li>Install the React Native Tools extension</li> <li>Install the Debugger for Chrome extension, and add this Launch Configuration <pre><code>        {\n            \"type\": \"chrome\",\n            \"request\": \"launch\",\n            \"name\": \"Launch Debugger\",\n            \"url\": \"http://localhost:8081/debugger-ui/\",\n            \"webRoot\": \"${workspaceFolder}\"\n        }\n</code></pre></li> </ul> <p>Together with the connect sequence this will make for a start of a Krell session like this:</p> <ol> <li>Open the project root in VS Code</li> <li>Issue the Jack-in command</li> <li>Issue the React Native; Run Android on Emulator (or Run iOS on Simulator) command. (Disable Fast Refresh from the *React Native dev menu, if it is enabled.)</li> <li>Issue the React Native: Run Element Inspector command     (You might need to install the React Native inspector globally):     ```sh     yarn global add react-devtools     ````</li> <li>Launch Debugger (<code>F5</code>)</li> <li>Hack away, with hot reload and interactive REPL</li> </ol> <p>Once the debugger (a Chrome session) is running, you probably will want to enable Custom Formatters in order for clojure structures to be logged conveniently.</p>"},{"location":"linting/","title":"Linting","text":"<p>Calva does no linting, yet with Calva you get excellent linting. That is because Calva uses clojure-lsp, which provides linting powered by clj-kondo.</p> <p>clj-kondo comes with great default rules, and the configuration can be customized. One of your options for the configuration file is to  placed a <code>config.edn</code> file in <code>.clj-kondo/</code> at the root of your project. This folder may or may not already exist. It is safe to create it manually if it doesn't.</p> <p>The configuration will be merged with the default set of rules, you can only specify the rules you want to override. The full list of available options can be found on clj-kondo's github</p> <p>clojure-lsp is customizable, see Clojure LSP Settings for your options. It is safe to manually create the <code>.lsp</code> folder if it doesn't exist.</p> <p>You might want to read about how to configure clj-kondo. These two sections might be of extra interest:</p> <ul> <li>Unrecognized macros</li> <li>Lint a custom macro like a built-in macro</li> </ul> <p>If you see a linting squiggle under the first character of the file with an error you don't quite understand, it is probably something wrong with your clj-kondo configuration.</p> <p>Files are linted as they're being edited. If you want to lint the whole project, use the clj-kondo cli command. See https://github.com/borkdude/clj-kondo for more info on that. Windows users might like to know that they too can get a clj-kondo cli command now, via <code>npm install -g clj-kondo</code>. It'll be a bit slower to start than the native build, but for sure it's better than not having a clj-kondo command! See https://github.com/borkdude/clj-kondo/blob/master/doc/install.md#npm-linux-macos-windows for more on this.</p>"},{"location":"linting/#resolve-macro-as","title":"Resolve Macro As","text":"<p>When your cursor is on a macro form in the editor, you may notice a code action (click the light bulb that appears) called Resolve Macro As. Running this code action will ask you what macro you'd like to resolve the current macro as, and then what clj-kondo config file you want the macro to be saved to. This code action is also available as a command.</p>"},{"location":"live-share/","title":"Using Calva with Live Share","text":"<p>Live Share is a Microsoft provided VS Code extension.  It allows you to share the workspace that you have open in your computer with somebody else. Everybody is then working on the same source code files, namely those on your computer. You can edit files at the same time, everyone has their own caret. You can follow each other (i.e. when someone switches to a different file, you will as well). This is great for remote pair programming, for example.</p> <p>An extra nice thing is that each participant is using their own VSCode configuration, including fonts, colors, keyboard shortcuts, etc.</p> <p>Disable Calva Spritz to get rid of Notebooks interference</p> <p>The headline below Calva Supports Live Share is true. However, due to a bug in LiveShare, guest participants always get their Clojure files opened in the Calva Clojure Notebooks editor. To workaround this issue Calva uses a \u201dside-car\u201d extension named Calva Spritz for the Notebooks associations of Clojure files. You can disable that extension when participating in LiveShare sessions.</p>"},{"location":"live-share/#calva-supports-live-share","title":"Calva Supports Live Share","text":"<p>When using Calva, you can use Live Share as well. Editing works exactly the same as for any other programming language. What makes Calva a bit special, is the REPL. When using Live Share, Calva allows the host to share the REPL with guests as well. If you use any of the supported configuration, this will be pretty much automatic.</p> <p>You need to enable the LiveShare support</p> <p>Due to an issue in the LiveShare API, for some users, this feature stops Calva from connecting the REPL. Therefore the support is disabled by default. The setting is <code>calva.useLiveShare</code>.</p> <p>This is what a typical scenario looks like:</p> <ol> <li>The host jacks-in.</li> <li>The host shares its workspace using Live Share. Calva will detect that    the workspace is being shared, so it will offer to share the REPL port that    was opened when jacking in. The host clicks \"Allow\" to start sharing the    port. (Note: steps 1 and two can also be done in the reverse order.)    </li> <li>The host sends the Live Share URL to the guest(s).</li> <li>The guest joins the Live Share session using the URL it received.</li> <li>The guest connects to the host's REPL using the command \"Connect to a    running REPL server in the project\". If needed, the guest chooses the same    build configuration as the host.</li> </ol> <p>Voila! Both the guest and the host can now use the REPL that is running on the host. Things like documentation lookup now also work on the guest's machine.</p>"},{"location":"live-share/#control-visibility-of-calva-folder","title":"Control Visibility of <code>.calva</code> Folder","text":"<p>Calva depends on the <code>output.calva-repl</code> file to be available. If you have the <code>.calva</code> folder listed in your <code>.gitignore</code>, this also causes the folder to be hidden from guests in Live Share by default. In order to make the folder visible, you can put a file called <code>.vsls.json</code> in your project. In its simplest form, the contents can be this:</p> <pre><code>{\n  \"$schema\": \"http://json.schemastore.org/vsls\",\n  \"hideFiles\": [\n    \"!.calva\"\n  ]\n}\n</code></pre> <p>Now the <code>.calva</code> folder is shared as well. But also any other file and folder that you may have in your <code>.gitignore</code>. If you want to have more fine-grained control, please refer to the section Controlling file access and visibility of the Live Share documentation.</p>"},{"location":"live-share/#some-things-to-keep-in-mind","title":"Some Things To Keep In Mind","text":"<ul> <li>As a guest, you're connected to a REPL running on the host's machine. With   power comes responsibility; be nice, and be careful!</li> <li>There is only one <code>output.calva-repl</code> file, which all participants are   sharing. It may work better to evaluate things in the source code editors   instead of from the REPL window. Otherwise you will end up in a situation   where one person is typing something in the <code>output.calva-repl</code> window, and   somebody else is evaluating something (hence sending the output there) at the   same time. That gets confusing quickly.</li> <li>When you're working on a CLJS-based web development project, things may   get extra confusing. By default, Live Share will share any HTTP ports on the   host automatically, and also offer to open the URL on the guest. (You can   disable using the setting \"Liveshare: Open Shared Servers\".) As a guest, you   do not want to open that browser window normally. Think about it: where is   the REPL running? Yes: in the browser! But Calva connects to the REPL running   in the browser on the host's machine, so if you open a browser as a guest, you   will also get a REPL there, but you won't be connected to it in Calva.</li> <li>Currently Live Share does not allow Calva to know whether the workspace is   shared read-only or read-write. If you share read-only, and you don't want the   guests to have access to your REPL, don't click \"Allow\" when VSCode asks you   to share the REPL port.</li> </ul>"},{"location":"live-share/#calva-spritz","title":"Calva Spritz","text":"<p>Together with Calva there is an extension called Calva Spritz installed. All it does is to provide the association of Clojure file types to Clojure Notebooks. We do it this way because of the LiveShare issues mentioned above. So that you can disable the Notebook association when participating as a guest in LiveShare sessions. The issue is tracked here:</p> <ul> <li>Calva issue: LiveShare participants incorrectly opening every Clojure file as if via \"Open with Notebook\"</li> <li>LiveShare issue: Guest opens Clojure file as a notebook (incorrectly)</li> </ul> <p>Calva Spritz can be disabled and enabled at will, and it will take immediate effect, without any reload of VS Code needed.</p>"},{"location":"luminus/","title":"How to Use Calva with Luminus","text":"<p>Luminus is a powerful and versatile Leiningen template for creating web development projects. It comes with built in configuration which makes it easy to use Calva as your Clojure(Script) editor.</p>"},{"location":"luminus/#server-shadow-cljs","title":"Server + shadow-cljs","text":"<p>Basically this is the same wokflow as with Server only. Behind the scenes there is more happening, though. Such as the ClojureScript app being built and the CLJS REPL connected once the web app is running.</p> <ol> <li>If you haven't created the project yet, create a new shadow-cljs Luminus project. E.g.:     <pre><code>$ lein new luminus my-luminus-shadow +reagent +re-frame +shadow-cljs\n</code></pre></li> <li>Install npm dependencies     <pre><code>$ npm i\n</code></pre>     (Or <code>yarn</code> if you prefer.)</li> <li>This creates the folder <code>my-luminus-shadow</code>. Open it in VS Code:     <pre><code>$ code my-luminus-shadow\n</code></pre></li> <li>Use the Calva command Start a Project REPL and Connect (aka Jack-in): <code>ctrl+alt+c ctrl+alt+j</code></li> <li>Select to start my-luminus-shadow Server + Client, and wait for the Terminal Calva Jack-in output to say <code>[:app] Build completed.</code></li> <li>Open 127.0.0.1:3000 in your web browser and start hacking.</li> </ol> <p>Note</p> <p>Currently Calva has troubles following the app-start with shadow-cljs, so Calva will report <code>Jack-in done.</code> in the output window before shadow-cljs is actually done building the app. If you open the app page at that stage, you will see a message to \u201cPlease run <code>lein shadow watch app</code>\u201d. Rest assured that this is already underway. Follow the Jack-in process in the Terminal tab in VS Code for the message that the app is built, then reload the app page in the web browser.</p>"},{"location":"luminus/#server-only","title":"Server Only","text":"<p>The workflow here is really just: Jack-in and start hacking. However, the first time it will involve these steps:</p> <ol> <li>If you haven't created the project yet, create a new server only Luminus project. For a all-defaults setup it is like so:     <pre><code>$ lein new luminus my-luminus-server\n</code></pre></li> <li>This creates the folder <code>my-luminus-server</code>. Open it in VS Code:     <pre><code>$ code my-luminus-server\n</code></pre></li> <li>Use the Calva command Start a Project REPL and Connect (aka Jack-in): <code>ctrl+alt+c ctrl+alt+j</code><ul> <li>Select to start my-luminus-shadow Server and wait until you see <code>Jack-in done.</code> in the output window.</li> </ul> </li> <li>Open 127.0.0.1:3000 in your web browser and start hacking.</li> </ol>"},{"location":"luminus/#server-figwheel","title":"Server + Figwheel","text":"<p>This is Legacy Figwheel (lein-figwheel), so the recommendation is to use the shadow-cljs setup instead. As with the server only, the workflow here is really just: Jack-in and start hacking. The first time it involves these steps:</p> <ol> <li>If you haven't created the project yet, create a new server only Luminus project. E.g.:     <pre><code>$ lein new luminus my-fw +reagent\n</code></pre></li> <li>This creates the folder <code>my-fw</code>. Open it in VS Code:     <pre><code>$ code my-fw\n</code></pre></li> <li>Use the Calva command Start a Project REPL and Connect (aka Jack-in): <code>ctrl+alt+c ctrl+alt+j</code>, select Server + Client - my-fw in the Project type picker menu, and wait for the web app to pop open in your web browser.</li> <li>Start hacking.</li> </ol> <p>If you prefer to open the web app yourself, open <code>.vscode/settings.json</code> and change <code>\"shouldOpenUrl\"</code> to <code>false</code> in the pre-configured Calva connect sequence. Calva will then print the URL 127.0.0.1:3000 in the output, so that you can click it open.</p>"},{"location":"luminus/#etcetera","title":"Etcetera","text":"<p>You will have three Calva Custom Command Snippets configured. Invoke them by issuing the Run Custom REPL Command, <code>ctrl+alt+c .</code> (that's a dot). These commands control the Luminus server:</p> <ol> <li><code>Start &lt;project&gt; Server</code></li> <li><code>Stop &lt;project&gt; Server</code></li> <li><code>Restart &lt;project&gt; Server</code></li> </ol> <p>When used, Calva will open its REPL window and execute the command, if it is not already opened. You can close this window if you prefer to use the REPL directly from the Clojure files.</p> <p>Calva also opens the REPL window, and starts the Luminus server, as part of the Jack-in process.</p>"},{"location":"merch/","title":"Calva Merch","text":"<p>In this video, there is a question about where you can buy the Calva T-shirt:</p> <p>You couldn't, then. But now you can! On Amazon.</p> <p>Zero profit</p> <p>To keep the admin of this shop to a minimum the merch is sold at production prize (or as close to production prize as the respective store allows). There is no royalty going to anyone in the Calva team when you buy one of these t-shirts. You will represent, which is certainly a way to support the project. You are of course encouraged to support us via sponsoring as well:</p> <ul> <li>Sponsor Peter Str\u00f6mberg</li> <li>Sponsor Brandon Ringe</li> </ul> <p>Calva Merch is available on Zazzle and on Amazon</p>","boost":10},{"location":"merch/#zazzle","title":"Zazzle","text":"","boost":10},{"location":"merch/#calva-symbol-sticker","title":"Calva Symbol Sticker","text":"Calva Symbol Sticker by BetterThanTomorrow","boost":10},{"location":"merch/#joyride-symbol-sticker","title":"Joyride Symbol Sticker","text":"Joyride Symbol Sticker by BetterThanTomorrow","boost":10},{"location":"merch/#amazon-merch","title":"Amazon Merch","text":"","boost":10},{"location":"merch/#the-designs","title":"The designs","text":"<p>There are four design, all featuring the Calva symbol (the Calva glass), which are all available for a Standard T-shirt, in men's, women's and kid's cut, and in some different colors. In the <code>.com</code> store there are also Premium T-shirts**.</p>","boost":10},{"location":"merch/#symbol-logo","title":"Symbol + Logo","text":"<p>Available at:</p> <ul> <li>https://www.amazon.com/dp/B09BCVH9SC (Premium T-shirt)</li> <li>https://www.amazon.com/dp/B097TB5QFW</li> <li>https://www.amazon.de/dp/B098GWQC6M</li> <li>https://www.amazon.co.uk/dp/B098KM9XMF</li> <li>https://www.amazon.fr/dp/B0994TYXTN</li> <li>https://www.amazon.it/dp/B099KLJJV1</li> <li>https://www.amazon.es/dp/B099NXR71Y</li> <li>https://www.amazon.co.jp/dp/B097YZVMC4</li> </ul>","boost":10},{"location":"merch/#symbol-logo-we-do-it-with-rich-comments","title":"Symbol + Logo + We do it with Rich Comments","text":"<p>The Calva symbol and Logo front, Rich Comments back.</p> <p></p> <p>Available at:</p> <ul> <li>https://www.amazon.com/dp/B09C4PBH5N (Premium T-shirt)</li> <li>https://www.amazon.com/dp/B09BFMRCHL</li> <li>https://www.amazon.de/dp/B09C3VYZH8</li> <li>https://www.amazon.co.uk/dp/B09BLD2BVJ</li> <li>https://www.amazon.fr/dp/B09C3X1H7K</li> <li>https://www.amazon.it/dp/B09C3WV2JQ</li> <li>https://www.amazon.es/dp/B09C4P1GD1</li> <li>https://www.amazon.co.jp/dp/B09C4P45MR</li> </ul>","boost":10},{"location":"merch/#symbol-only","title":"Symbol Only","text":"<p>Available at:</p> <ul> <li>https://www.amazon.com/dp/B09B83481D (Premium T-shirt)</li> <li>https://www.amazon.com/dp/B097TB5QFW</li> <li>https://www.amazon.de/dp/B098434W9M</li> <li>https://www.amazon.co.uk/dp/B098KNGPBB</li> <li>https://www.amazon.fr/dp/B099RZGNN7</li> <li>https://www.amazon.it/dp/B099WYH94Z</li> <li>https://www.amazon.es/dp/B09B2TFCSR</li> <li>https://www.amazon.co.jp/dp/B09B4XN3HY</li> </ul>","boost":10},{"location":"merch/#symbol-we-do-it-with-rich-comments","title":"Symbol + We do it with Rich Comments","text":"<p>The Calva symbol front, Rich Comments Back.</p> <p></p> <p>Available at:</p> <ul> <li>https://www.amazon.com/dp/B098M34FKJ (Premium T-shirt)</li> <li>https://www.amazon.com/dp/B0993VCG7P</li> <li>https://www.amazon.de/dp/B098MF14PV</li> <li>https://www.amazon.co.uk/dp/B098P1MV44</li> <li>https://www.amazon.fr/dp/B098TPQFCJ</li> <li>https://www.amazon.it/dp/B098YP33ZL</li> <li>https://www.amazon.es/dp/B098RDPK55</li> <li>https://www.amazon.co.jp/dp/B0992MQYG6</li> </ul> <p>Note</p> <p>What's available on this or that Amazon site will vary a bit and it is a bit slow to add a particular design to a particular market. Eventually I hope to have both designs up on these markets: <code>.com</code>, <code>.co.uk</code>, <code>.de</code>, <code>.fr</code>, <code>.it</code>, <code>.es</code>, and <code>.co.jp</code></p>","boost":10},{"location":"namespace-form-auto-creation/","title":"Namespace Form Auto-creation","text":"<p>When you create a new clojure file, a file with <code>.clj</code>, <code>.cljc</code> or <code>.cljs</code> extension, an appropriate namespace form will be added to the file. This feature is provided by clojure-lsp.</p> <p></p>"},{"location":"nbb/","title":"Using Calva with nbb","text":"<p>Since nbb can be started such that it is an nREPL server, Calva can connect to it and a lot of the features will work.</p> <p>Calva can also start nbb and connect its REPL for you, using the Jack-in command. This will start an nbb nREPL server on a random port and connect Calva to it. Check out this video where they use Calva and nbb to create a CLI tool as an executable npm module:</p> <p>In that video they ask for a JavaScript to ClojureScript converter. And there is one: https://mauricioszabo.gitlab.io/js2cljs/</p> <p>Though if you are using Calva, this converter is easier to use directly via the command Calva: Convert JavaScript to ClojureScript:</p> <p>Errors jacking in to nbb on Windows?</p> <p>On some machines it seems necessary to first run <code>npx nbb</code> from the <code>CMD</code> prompt to make jack-in work. Or try first install it <code>npm i -g nbb</code>. (You probabl want nbb installed globally anyway.)</p> <p>Don't expect complete support</p> <p>nbb's nREPL server is completely new and and WIP. It will be a bit limited compared to a full cider-nrepl enhanced \"regular\" Clojure nREPL server. Things like function signatures, and more do not work.</p> <p>It's a bit hacky</p> <p>The nbb nREPL server is the first ClojureScript nREPL server around and throws Calva's assumption that an nREPL server is always started in a Clojure process out the window. The nbb Jack-in/connect option \u201dpretends\u201d it is connecting to a Clojure nREPL and then the code fro promoting the nREPL session to a ClojureScript one is just dummy code.</p> <p>This means that if you open a Clojure (<code>.clj</code>) file while connected to an nbb nREPL server, it will still be a ClojureScript session serving even though Calva will indicate that it is a Clojure one. Bare with us until we can fix this properly in Calva.</p>","boost":4},{"location":"notebooks/","title":"Clojure Notebooks","text":"<p>WIP: Notebook support is very basic and experimental</p> <ul> <li>You might experience loss of file contents when saving a Clojure Notebook. Have backups of any files you open as notebooks.</li> <li>Tooling around autocomplete, go to def, linting and such does not work at all yet.</li> <li>There is no Markdown support.</li> <li>Etcetera. As if this was not enough, notebooks can also interfere with LiveShare support.</li> </ul> <p>Please help test the feature. We're looking forward to your feedback!</p> <p>You can open any Clojure file as a notebook by right clicking the file -&gt; <code>Open with...</code> -&gt; <code>Clojure Notebook</code>.</p> <p>Running cells sends them to the REPL and pretty prints the results. If the return is a string that starts with <code>&lt;html</code> it will be displayed in an html webview.</p> <p>Forms inside <code>(comment)</code> blocks get shown as their own cells. When adding code blocks in between those cells they get saved with the same indentation as the first form.</p>","boost":1},{"location":"notebooks/#calva-spritz","title":"Calva Spritz","text":"<p>Together with Calva there is an extension called Calva Spritz installed. It only provides the association of Clojure file types to Clojure Notebooks. This is due to the LiveShare issues mentioned above. So that you can disable the Notebook association when participating as a guest in LiveShare sessions. The issue is tracked here:</p> <ul> <li>Calva issue: LiveShare participants incorrectly opening every Clojure file as if via \"Open with Notebook\"</li> <li>LiveShare issue: Guest opens Clojure file as a notebook (incorrectly)</li> </ul>","boost":1},{"location":"nrepl_and_cider-nrepl/","title":"nREPL and cider-nrepl","text":"<p>nREPL and cider-nrepl middleware enable Calva to support full Interactive Programming.</p>","boost":2},{"location":"nrepl_and_cider-nrepl/#about-nrepl","title":"About nREPL","text":"<p>The REPL is a Clojurists quintessential tool, it\u2019s what we use to do Interactive Development, the hallmark of the LISP style of development.</p> <p>In Interactive Development (more commonly but somewhat imprecisely referred to as REPL-driven development), the programmer\u2019s editor has a direct connection with the running application process. This allows evaluating pieces of code in the context of a running program, directly from where the code is written (and so not in some separate \u201cREPL place\u201d), inspecting and manipulating the innards of the process. This is helped along by the dynamic nature of Clojure in which any var can be redefined at any point, allowing for quick incremental and iterative experimentation and development.</p> <p>This is why it\u2019s essential to the Clojure development experience to have proper editor support, a plugin which bridges the gap between where the code is written and where the code is run. So we have CIDER for Emacs, Calva for VS Code, Cursive for IntelliJ, Conjure or Iced for Vim, and so forth. Often these will also leverage the same (or a parallel) connection into the process for other editor affordances, like navigation and completion.</p> <p>But for these editor plugins to connect to the Clojure process something needs to be listening on the other side, accepting connections, allowing the initiation of a program-to-program dialogue. The most common way to achieve this is by leveraging the nREPL protocol, an asynchronous message-based network protocol for driving interactive development. The application process is started with an embedded nREPL server, so that the editor can connect as an nREPL client.</p> <p>From: Lambda Island</p>","boost":2},{"location":"nrepl_and_cider-nrepl/#about-the-nrepl-server-and-middleware","title":"About the nREPL Server and Middleware","text":"<p>nREPL is an extensible protocol, the reference server implementation understands certain core operation types like \"eval\". More operations can be supported, or existing operations can be modified or augmented, through nREPL middleware. For example: the Piggieback middleware can intercept \"eval\" messages, and forward them to a ClojureScript environment, rather than evaluating them in the Clojure process itself.</p> <p>Which middleware to use will mostly depend on the editor you are using. You\u2019ll typically find that the Clojure-specific functionality for a given editor is partly implemented as a typical editor extension, for instance CIDER written in Emacs LISP, or Calva written in Typescript, and partly as nREPL middleware, providing the functionality the editor extension relies on. For instance, both CIDER and Calva rely on functionality provided by cider-nrepl.</p> <p>Also from: Lambda Island</p>","boost":2},{"location":"nrepl_and_cider-nrepl/#viewing-the-communication-between-calva-and-nrepl","title":"Viewing the Communication Between Calva and nREPL","text":"<p>You can view the messages sent between Calva and nREPL by running the command <code>Toggle nREPL Logging Enabled</code>. Enabling nREPL message logging triggers the creation of a VS Code output channel called <code>nREPL Messages</code> where the messages will be logged. Messages sent to nREPL from Calva will have <code>-&gt; sent</code> above them, and messages sent from nREPL to Calva will have <code>&lt;- received</code> above them. Disabling nREPL message logging causes the <code>nREPL Messages</code> channel to be removed and messages will no longer be logged.</p> <p>Each message is logged as JSON. If you find a need for the messages to be logged as EDN (for example, to transform and analyze them with Clojure) please open a GitHub issue for this change. A PR would be welcome too!</p> <p>The example below shows two messages logged when the cursor hovers over <code>println</code> in a Clojure file while a REPL is connected.</p> <pre><code>-&gt; sent\n{\n  op: 'info',\n  ns: 'test-lein.core',\n  symbol: 'println',\n  id: '7',\n  session: '1a080b66-b1b6-4b8c-8206-c4af2cc02747'\n}\n\n&lt;- received\n{\n  added: '1.0',\n  'arglists-str': '[&amp; more]',\n  column: 1,\n  doc: 'Same as print followed by (newline)',\n  file: 'jar:file:/Users/brandon/.m2/repository/org/clojure/clojure/1.10.1/clojure-1.10.1.jar!/clojure/core.clj',\n  id: '7',\n  line: 3733,\n  name: 'println',\n  ns: 'clojure.core',\n  resource: 'clojure/core.clj',\n  'see-also': [\n    'clojure.core/prn',\n    'clojure.core/print',\n    'clojure.core/println-str',\n    'clojure.pprint/pprint'\n  ],\n  session: '1a080b66-b1b6-4b8c-8206-c4af2cc02747',\n  static: 'true',\n  status: [ 'done' ]\n}\n</code></pre>","boost":2},{"location":"output/","title":"Output Destinations","text":"<p>Calva categorizes output into three types:</p> <ul> <li>evaluation results: Clojure data returned from an evaluation.</li> <li>evaluation output: stdout/stderr from an evaluation</li> <li>other output: Other messages, logs, etc</li> </ul> <p>With the setting <code>calva.outputDestinations</code>, you can configure where each category of output should go to:</p> <ul> <li>the REPL Window</li> <li>the Calva Says Output Channel</li> <li>the Calva Output (pseudo) Terminal</li> </ul> <p>The reason there are several options for this is partly legacy and partly because VS Code restricts the placement of different views in different ways. We hope you will find a combination of output destinations that suits you.</p>"},{"location":"output/#commands-for-showing-output-destinations","title":"Commands for showing output destinations","text":"<p>These are the commands and their default keyboard shortcuts for revealing output destinations</p> <ul> <li>Calva: Show/Open the result output destination - <code>ctrl+alt+o o</code></li> <li>Calva: Show/Open the Calva says Output Channel - <code>ctrl+alt+o c</code></li> <li>Calva: Show/Open the Calva Output Terminal - <code>ctrl+alt+o t</code></li> <li>Calva: Show/Open REPL Window - <code>ctrl+alt+o r</code></li> </ul>"},{"location":"output/#about-stdout-in-the-repl-window","title":"About stdout in the REPL Window","text":"<p>Since Calva v2.0.423 the REPL Window prints <code>stdout</code> prepended with <code>;</code> to make it into line comments. This is because stdout output easily breaks the Clojure structure of the REPL Window, making it misbehave in various ways. We made this change because as maintainers of Calva we have seen all too often how this hits users, and it is also taking too much of our Calva time to try mitigate the problem, which is fundamentally not fixable.</p> <p>There are now other output destinations that do not have this limitation.</p> <p>All that said. If you want to keep using the REPL Window for stdout output, and need the old behavior, you can enable the setting: <code>calva.legacyPrintBareReplWindowOutput</code>. Please note that at some point after we have created a dedicated Output Window, the REPL Window will be retired as a destination for output.</p>"},{"location":"output/#repl-process-output-stdout-and-stderr","title":"REPL process output (stdout and stderr)","text":"<p>When Calva is connected to the REPL, the Output window will by default print not only results of evaluations, but also:</p> <ol> <li>Things printed to <code>stdout</code> and <code>stderr</code> in the main thread of the evaluations</li> <li>Things printed to <code>stdout</code> and <code>stderr</code> from child threads of the evaluations</li> <li>Anything printed to <code>stdout</code> and <code>stderr</code> by the REPL process</li> </ol> <p>You can control the default via the <code>calva.redirectServerOutputToRepl</code> setting. It defaults to <code>true</code>. Setting it to <code>false</code> before connecting the REPL will result in that 2. and 3. will not get printed in the Output window. It will then instead be printed wherever the REPL process is printing its messages, usually the terminal from where it was started (the Jack-in terminal if Calva started the REPL).</p>"},{"location":"paredit/","title":"Paredit \u2013 a Visual Guide","text":"<p>Structural editing and navigation for Clojure.</p>","boost":7},{"location":"paredit/#what-is-paredit","title":"What is Paredit?","text":"<p>Calva Paredit helps you navigate, select and edit Clojure code in a structural way. LISP isn't line or character oriented, it is based around S-expressions, a.k.a forms. We strongly recommend that you take advantage of the structural nature of Clojure, and have therefore put a lot of work into making Calva Paredit extra awesome.</p> <p>If you are new to Paredit, consider starting with learning the Slurp Forward (pull in the next form into this form) and Barf Forward (push the last form out of this form). It will take you quite far.</p>","boost":7},{"location":"paredit/#strict-mode","title":"Strict Mode","text":"<p>To protect the integrity of your code, Strict mode is enabled by default.</p> Strict mode keybinding Action Description <code>backspace</code> Delete Backward Deletes one character backwards, unless it will unbalance a form. Otherwise moves past the character instead of deleting it. If the list is empty, it will remove both open and close brackets.  <code>delete</code> Delete Forward Deletes one character forwards, unless it will unbalance a form. Otherwise moves past the character instead of deleting it. If the list is empty, it is removed.  <code>alt+backspace</code> Force Delete Backward Deletes one character backwards, even if it will unbalance a form.  <code>alt+delete</code> Force Delete Forward Deletes one character forwards, even if it will unbalance a form.  <p>Disable at your own peril. Strict mode can be toggled on/off using the Toggle Paredit Mode command, and there is a status bar indicator telling you:</p> Indicator Paredit Mode <code>[\u03bb]</code> Strict <code>(\u03bb)</code> Cave Man (strict mode off) <code>\u03bb</code> No default key bindings <p>Toggle between Strict and Cave Man using: <code>ctrl+alt+p ctrl+alt+m</code></p>","boost":7},{"location":"paredit/#a-keybinding-for-protecting-the-structure-from-semi-colon","title":"A keybinding for protecting the structure from semi-colon","text":"<p>Semi-colons (<code>;</code>) in Clojure are non-structural because they comment out the rest of the line regardless of brackets. In a way they can delete brackets. There is a somewhat secret command in Paredit that can be used to insert <code>;</code> in a safe way:</p> <p><code>paredit.insertSemiColon</code></p> <p>Bind it to the <code>;</code> key with a <code>when</code> clause that activates it together with the other Strict mode commands:</p> <pre><code>{\n    \"command\": \"paredit.insertSemiColon\",\n    \"key\": \";\",\n    \"when\": \"calva:keybindingsEnabled &amp;&amp; editorLangId == clojure &amp;&amp; editorTextFocus &amp;&amp; paredit:keyMap == strict &amp;&amp; !editorReadOnly &amp;&amp; !editorHasMultipleSelections &amp;&amp; !calva:cursorInComment\"\n },\n</code></pre>","boost":7},{"location":"paredit/#commands","title":"Commands","text":"<p>The Paredit commands are sorted into Navigation, Selection, and Edit. As mentioned, Slurp and Barf are power commands, which go into the editing category. Learning to navigate structurally, using shortcuts, also saves time and adds precision to your editing. It has the double effect that you at the same time learn how to select structurally, because that is the same, just adding the shift key.</p> <p>To make the command descriptions a bit clearer, each entry is animated. When you try to figure out what is going on in the GIFs, focus on where the cursor is at the start of the animation loop.</p>","boost":7},{"location":"paredit/#strings-are-not-lists-but-anyway","title":"Strings are not Lists, but Anyway...","text":"<p>In Calva Paredit, strings are treated in much the same way as lists are. Here's an example showing Slurp and Barf, Forward/Backward List, and Expand Selection.</p> <p></p>","boost":7},{"location":"paredit/#navigating","title":"Navigating","text":"<p>(Modify these with <code>shift</code> to select rather than move, see below.)</p> Default keybinding Action Description <code>ctrl+right</code> (win/linux)<code>alt+right</code> (mac) Forward Sexp Moves the cursor forward, to the end of the current form. If at the end, moves to the end of the next form. Will not move out of lists. <code>ctrl+left</code> (win/linux)<code>alt+left</code> (mac) Backward Sexp Moves the cursor backward, to the start of the current form. If at the start, moves to the start of the previous form. Will not move out of lists. <code>ctrl+down</code> Forward Down Sexp Moves the cursor into the following list. <code>ctrl+alt+up</code> Backward Down Sexp Moves the cursor into the preceding list. <code>ctrl+alt+down</code> Forward Up Sexp Moves the cursor forwards, out of the current list. <code>ctrl+up</code> Backward Up Sexp Moves the cursor backwards, out of the current list. Unbound Forward Sexp Or Up Moves the cursor forward, to the end of the current form. If at the end, moves to the end of the next form. Moves out of the lists if at the end of it.  Unbound Backward Sexp Or Up Moves the cursor backward, to the start of the current form. If at the start, moves to the start of the previous form. Moves out of the list if at the start of it.  <code>ctrl+end</code> Forward to List End/Close Moves the cursor forwards, staying within the current list. <code>ctrl+home</code> Backward to List Start/Open Moves the cursor backwards, staying within the current list.","boost":7},{"location":"paredit/#selecting","title":"Selecting","text":"<p>Most of these commands are selecting \u201dversions\u201d of the navigation commands above. Repeated use will grow the current selection step by step.</p> Default keybinding Action Description <code>shift+alt+right</code> (win/linux)<code>ctrl+w</code> (mac) Expand Selection Starts from the cursor and selects the current form. Then will keep expanding to enclosing forms. <code>shift+alt+left</code> (win/linux)<code>ctrl+shift+w</code> (mac) Shrink Selection Contracts back from an expanded selection performed by any Paredit selection command. (In the animation the selection is first grown using a combination of Expand Selection and some lateral selection commands, then shrunk all the way back down to no selection.) <code>ctrl+alt+w space</code> Select Top Level Form Top level in a structural sense. Typically where your<code>(def ...)</code>/<code>(defn ...)</code> type forms. Please note that<code>(comment ...)</code> forms create a new top level.  <code>shift+ctrl+right</code> (win/linux)<code>shift+alt+right</code> (mac) Select Forward Sexp <code>ctrl+shift+k</code> Select Right Select forward to the end of the current form or the first newline. See Kill right below. (The animation also shows Shrink Selection). <code>shift+ctrl+left</code> (win/linux)<code>shift+alt+left</code>(mac) Select Backward Sexp <code>ctrl+shift+down</code> Select Forward Down Sexp (You probably do not need to select like this, but you can!) <code>ctrl+shift+alt+up</code> Select Backward Down Sexp (You probably do not need to select like this, but you can!) <code>ctrl+shift+alt+down</code> Select Forward Up Sexp (You probably do not need to select like this, but you can!) <code>ctrl+shift+up</code> Select Backward Up Sexp (You probably do not need to select like this, but you can!) Unbound Select Forward Sexp Or Up (You probably do not need to select like this, but you can!) Unbound Select Backward Sexp Or Up (You probably do not need to select like this, but you can!) <code>ctrl+shift+end</code> Select Forward to List End/Close <code>ctrl+shift+home</code> Select Backward to List Start/Open","boost":7},{"location":"paredit/#editing","title":"Editing","text":"Default keybinding Action Description <code>ctrl+alt+right</code> (mac/win)<code>ctrl+alt+.</code> (linux) Slurp Forward Moves the closing bracket forward, away from the cursor, past the following form, if any.  <code>ctrl+alt+left</code> (mac/win)<code>ctrl+alt+,</code> (linux) Barf Forward Moves the closing bracket backward, towards the cursor, past the preceding form.  <code>ctrl+alt+shift+left</code> Slurp Backward Moves the opening bracket backward, away from the cursor, past the preceding form, if any.  <code>ctrl+alt+shift+right</code> Barf Backward Moves the opening bracket forward, towards the cursor, past the following form.  <code>ctrl+alt+s</code> Splice Sexp Remove enclosing brackets.  <code>ctrl+shift+s</code> Split Sexp Splits a string, or a list, into two strings, or lists of the same type as the current.  <code>ctrl+shift+j</code> Join Sexps/Forms Joins two strings, or two lists of the same type, into one form (string/list).  <code>ctrl+alt+p ctrl+alt+r</code> Raise Sexp Replaces the enclosing list with the current form.  <code>ctrl+alt+t</code> Transpose Sexps/Forms Swaps place of the two forms surrounding the cursor.  <code>alt+up</code><code>alt+down</code> Drag Sexp Backward/Forward Moves the current form to the behind/in front of the previous/next one. (See below about behavior in maps and binding boxes.)  <code>ctrl+alt+shift</code> <code>u</code><code>ctrl+alt+shift</code> <code>d</code> Drag Sexp Backward UpDrag Sexp Forward Down Moves the current form up/out of the current list, backwards, and down/in to the following list, forwards, keeping the cursor within the sexpr being dragged. <code>ctrl+alt+shift</code> <code>k</code><code>ctrl+alt+shift</code> <code>j</code> Drag Sexp Forward UpDrag Sexp Backward Down Moves the current form up/out of the current list, forwards, and down/in to the preceding list, backwards, keeping the cursor within the sexpr being dragged. <code>ctrl+shift+c</code> Convolute \u00af\\_(\u30c4)_/\u00af  <code>ctrl+shift+delete</code> Kill Sexp Forward Deletes the next form in the same enclosing form as the cursor. <code>ctrl+k ctrl+k</code> (win/linux)<code>ctrl+k</code> (mac) Kill Right Delete forward to the end of the current form or the first newline. <code>ctrl+k ctrl+h</code> (win/linux)<code>cmd+backspace</code> (mac) Kill Left Delete backward to the start of the current form or the start of the line. <code>ctrl+alt+backspace</code> Kill Sexp Backward Deletes the previous form in the same enclosing form as the cursor. <code>ctrl+delete</code> Kill List Forward Deletes everything from the cursor to the closing of the current enclosing form. <code>ctrl+backspace</code> Kill List Backward Deletes everything from the cursor to the opening of the current enclosing form. <code>ctrl+alt+shift+delete</code> Splice Killing Forward Delete forward to end of the list, then Splice.  <code>ctrl+alt+shift+backspace</code> Splice Killing Backwards Delete backward to the start of the list, then Splice.  <code>ctrl+alt+shift+p</code> Wrap Around () Wraps the current form, or selection, with parens.  <code>ctrl+alt+shift+s</code> Wrap Around [] Wraps the current form, or selection, with square brackets.  <code>ctrl+alt+shift+c</code> Wrap Around {} Wraps the current form, or selection, with curlies.  <code>ctrl+alt+shift+q</code> Wrap Around \"\" Wraps the current form, or selection, with double quotes. Inside strings it will quote the quotes.  <code>ctrl+alt+r</code><code>ctrl+alt+p</code>/<code>s</code>/<code>c</code>/<code>q</code>/<code>h</code> Rewrap Changes enclosing brackets of the current form to parens/square brackets/curlies/double quotes and set (<code>#{}</code>)  <p>Copy to Clipboard when killing text</p> <p>You can have the kill commands always copy the deleted code to the clipboard by setting <code>calva.paredit.killAlsoCutsToClipboard</code> to <code>true</code>.  If you want to do this more on-demand, you can kill text by using the selection commands and then Cut once you have the selection.</p> <p>clojure-lsp drag fwd/back overlap</p> <p>As an experimental feature, the two commands for dragging forms forward and backward have clojure-lsp alternatives. See the clojure-lsp page.</p>","boost":7},{"location":"paredit/#drag-bindings-forwardbackward","title":"Drag bindings forward/backward","text":"<p>When dragging forms inside maps and binding boxes, such as with <code>let</code>, <code>for</code>, <code>binding</code>, etcetera, it often makes most sense to drag each binding as a pair. And this is what Calva will do. Like so:</p> <p></p> <p>And like so (wait for it):</p> <p></p>","boost":7},{"location":"paredit/#about-the-keyboard-shortcuts","title":"About the Keyboard Shortcuts","text":"<p>Care has been put in to making the default keybindings somewhat logical, easy to use, and work with most keyboard layouts. Slurp and barf forward are extra accessible to go with the recommendation to learn using these two super handy editing commands.</p> <p>You can relax how Paredit's shortcuts replace VS Code built in shortcuts a bit by setting <code>calva.paredit.hijackVSCodeDefaults</code> to <code>false</code>.</p> <p>There are some context keys you can utilize to configure keyboard shortcuts with precision. See Customizing Keyboard Shortcuts.</p> <p>The Nuclear Option: You can choose to disable all default key bindings by configuring <code>calva.paredit.defaultKeyMap</code> to <code>none</code>. (Then you probably also want to register your own shortcuts for the commands you often use.)</p> <p>In some instances built-in command defaults are the same as Paredit's defaults, and Paredit's functionality in a particular case is less than what the default is. This is true of Expand Selection and Shrink Selection for Windows/Linux when multiple lines are selected. In this particular case adding <code>!editorHasMultipleSelections</code> to the <code>when</code> clause of the binding makes for a better workflow. The point is that when the bindings overlap and default functionality is desired peaceful integration can be achieved with the right <code>when</code> clause. This is left out of Paredit's defaults to respect user preference, and ease of maintenance.</p> <p>Happy Editing! \u2764\ufe0f</p>","boost":7},{"location":"paredit/#experimental-feature-multicursor-support","title":"Experimental Feature: Multicursor support","text":"<p>There is an ongoing effort to support simultaneous multicursor editing with Paredit. This is an experimental feature and is not enabled by default. To enable it, set <code>calva.paredit.multicursor</code> to <code>true</code>. This feature is still in development and may not work as expected in all cases. Currently, this supports the following categories:</p> <ul> <li>Movement</li> <li>Selection (except for <code>Select Current Form</code> - coming soon!)</li> <li>Rewrap</li> </ul>","boost":7},{"location":"parinfer/","title":"Calva Parinfer Mode is Reverted","text":"<p>Reverted in Calva v2.0.228</p> <p>The changes in v2.0.227 seemed to cause problems for some users. Unclear yet if and why. But to not risk causing problems for more users these changes where reverted and Calva v2.0.228 does not contain them. Please consider using v2.0.227 and help find what the problems are about! Please note: Even in v2.0.227 this feature is currently disabled by default.</p> <p>Parinfer is a system for editing the structure of LISP text without explicit commands. The structure can be regarded as already being expressed through indentation. With Parinfer you can use your intuition about the structure inferred from the indentation to perform surprisingly many structural edits.</p>"},{"location":"parinfer/#quirks","title":"Quirks","text":"<p>There are some known quirks, of varying severity, with this feature. Some of them will need to be fixed before we move this feature out of Experimental status.</p> <p>For the most times you can always Undo to get back to where the document was fine. You just need to pay some attention and be aware when undo is needed.</p>"},{"location":"parinfer/#no-multi-cursor-support","title":"No multi-cursor support","text":"<p>The bracket inference will remove all cursors but the first one. So for instance if you edit with multiple cursors and it causes brackets to move, you'll end up with just one cursor and the subsequent edits will not be what you intended. This is particularly important to note when you have cursors that are not in the viewport. In such cases it might be better to turn Parinfer off while you do the edits, fix formatting and such manually and then switch Parinfer on again.</p>"},{"location":"parinfer/#wrong-inferences","title":"Wrong inferences","text":"<p>For yet unknown reasons an edit such as the following does the wrong thing (the cursor indicated by the vertical bar):</p> <pre><code>(foo| (bar)\n      (baz))\n</code></pre> <p>backspace =&gt; </p> <pre><code>(fo| (bar\n      (baz)))\n</code></pre> <p>That is <code>(baz)</code> is slurped. When what should happen is:</p> <pre><code>(fo| (bar)\n     (baz))\n</code></pre>"},{"location":"parinfer/#lag-causing-errors-when-fast-typing","title":"Lag causing errors when fast typing","text":"<p>The way that Calva Parinfer works is that for any edit of the document it first reformats the code around the cursor, then infer brackets. Currently these two steps are not atomic to VS Code, so if you type fast bracket inference might happen on the yet unformatted code, and thus not be correct. You might also see the cursor end up at the wrong position at times.</p>"},{"location":"parinfer/#infer-parens","title":"Infer Parens","text":"<p>This is no longer available in Calva</p> <p>See above about how to try this build anyway, warts and all.</p> <p>When you enable Calva's Parinfer it is all about infering brackets from indentation. There are no further Parinfer modes. Calva's auto-formatter will take care of keeping the code correctly indented.</p> <p>Enable it with from this setting: <code>calva.fmt.experimental.inferParensAsYouType</code> or from the status bar item.</p>"},{"location":"parinfer/#parinfer-status-bar-items","title":"Parinfer Status bar items","text":"<p>To the right on the status bar, right before the Paredit status bar item, you will have two items, Parinfer toggle ON/OFF and a health indicator.</p> <ol> <li>Parinfer ON/OFF indicator/button. \u2022() (The dot/circle indicates ON/OFF)</li> <li>Structure and indentation health indicator. \u2714\ufe0f/\u26a0/\u2298</li> </ol> <p>When Parinfer is ON, the health indicator will have three states:</p> <ol> <li>\u2714\ufe0f Healthy - meaning both structure and indentation is OK</li> <li>\u2298 Structure broken - you need to fix the the structure of the code</li> <li>\u26a0 Bad indentation - meaning that to Parinfer the structure and indentation do not match, _the item is now also a button with which you can fix the indentation.</li> </ol> <p>Parinfer will be disabled in both the unhealthy states.</p> <p>When Parinfer is OFF, only the first two states above are used.</p>"},{"location":"parinfer/#some-vs-code-settings-automatically-changed","title":"Some VS Code Settings automatically changed","text":"<p>In order for some automatic VS Code behaviour not to interfere with Parinfer the following settings are automatically configured when you toggle Parinfer ON:</p> <pre><code>    \"[clojure]\": {\n        \"editor.autoClosingBrackets\": \"never\",\n        \"editor.autoClosingOvertype\": \"never\",\n        \"editor.formatOnPaste\": false\n    },\n</code></pre> <p>And when you toggle Parinfer OFF:</p> <pre><code>    \"[clojure]\": {\n        \"editor.autoClosingBrackets\": \"always\",\n        \"editor.autoClosingOvertype\": \"always\",\n        \"editor.formatOnPaste\": true\n    },\n</code></pre> <p>It is recommended that you let Calva handle these settings to avoid weird behaviour.</p>"},{"location":"parinfer/#no-tab-indenting","title":"No Tab indenting","text":"<p>As the <code>tab</code> key is used for formatting the current form in Calva, it is \u201dtaken\u201d. The closest equivalents you have are <code>space</code> and <code>backspace</code>. At least for now. We'll see if we can find out a good way for supporting <code>tab</code> and <code>shift+tab</code> for indent and dedent.</p> <p><code>tab</code> for formatting is of course just a default key binding and you can assign it to something else to get it to do indenting. However, it will not be a very smart indent anyway, there is no Clojure awareness about it. You are hereby adviced to instead use some more spaces.</p>"},{"location":"parinfer/#paredit-is-still-there","title":"Paredit is still there","text":"<p>In Calva, Parinfer and Paredit are designed to coexist and both be there to let you edit the structure easily and efficiently. Since Paredit commands are always formatted, they leave the code in a state where Parinfer has what it needs to infer bracket placement as you either edit the indentation, or remove/add brackets.</p>"},{"location":"parinfer/#disable-the-parinfer-extension","title":"Disable the Parinfer Extension","text":"<p>If you want to have Parinfer you are probably best served by Calva's built-in version. It is designed, and will continue to be improved to function well together with Calva's other structural editing and formatting features. It will also probably conflict with the Parinfer Extension.</p>"},{"location":"parinfer/#see-also","title":"See also","text":"<ul> <li>Paredit</li> <li>Formatting</li> </ul>"},{"location":"polylith/","title":"How to Use Calva with Polylith","text":"<p>Polylith is an architecture for backend projects that maximizes development ergonomics and code reuse.</p> <p></p> <p>When developing a Polylith application you use one REPL for everything. And as such it is a rather vanilla <code>deps.edn</code> project, so there is really not much more to using Calva with Polylith than:</p> <ol> <li>Jack in, selecting the <code>deps.edn</code> project type</li> <li>Select aliases, most often <code>:dev</code> and <code>:test</code></li> <li>Hack away!</li> </ol>"},{"location":"polylith/#the-realworld-example","title":"The RealWorld Example","text":"<p>To make it easy to try Polylith out with Calva, the Polylith RealWorld example implementation has some Calva config to get the server started and Calva connected to its REPL quickly:</p> <ol> <li>Fork the project and open it in VS Code</li> <li>Jack-in, selecting the <code>Polylith RealWorld Server REPL</code> project type</li> <li>Wait for the REPL prompt to read <code>clj\ua789dev.server\ua789&gt;</code></li> <li>Evaluate <code>(start! 6003)</code></li> <li>Hack away!</li> </ol>"},{"location":"polylith/#try-it-with-a-frontend","title":"Try it with a Frontend","text":"<p>A ClojureScript frontend, of course:</p> <ol> <li>Fork the jacekschae/conduit project and open it in VS Code</li> <li>Edit the <code>api-url</code> definition in <code>events.cljs</code> file to be     <pre><code>(def api-url \"http://localhost:6003/api\")\n</code></pre></li> <li>Jack-in, selecting to start and connect to the <code>:app</code> build</li> <li>Wait for it to compile and then open http://localhost:3000</li> <li>Hack away!</li> </ol>"},{"location":"pprint/","title":"Pretty Printing","text":"<p>In Calva, pretty printing is a mode. Prettiness is on by default and all your evaluation results will get that treatment.</p> <p>You can also pretty print code on demand</p> <p>There is a command Replace Current Form (or Selection) with Pretty Printed Form. See Clojure Formmatting for more on this.</p>"},{"location":"pprint/#toggle-it","title":"Toggle it","text":"<p>There is a <code>pprint</code> indicator to the right in the status bar which shows the status of the mode. Click the indicator to toggle prettification on and off. There is also a Calva: Toggle Pretty Printing for All Evaluations command.</p> <p>Tip: If you have evaluated something time consuming, or that is not idempotent, with pretty printing mistakenly off: toggle it on and evaluate <code>*1</code>.</p>"},{"location":"pprint/#configuration","title":"Configuration","text":"<p>For most people the defaults will probably work, but Calva pretty printing comes a few knobs you can turn, and they are all available through the <code>calva.prettyPrintingOptions</code> settings. Things you can set are:</p> Setting Type Effect <code>enabled</code> boolean So this is a third way you can change this mode \ud83d\ude04 <code>printEngine</code> enum Which printer function that will be used. Default is <code>pprint</code>, more about this setting below <code>printFn</code> object You can configure Calva to use a custom <code>nREPL</code> compatible <code>print</code> function, more below. <code>width</code> number The maximum line length of printed output (or at least the printers will try) <code>maxLength</code> number The maximum number of elements printed in nested nodes, good for evaluating something like <code>(iterate inc 0)</code>, which you shouldn't do without setting <code>maxLength</code>. Most printers will indicate truncated lists with <code>...</code> at the end. <code>maxDepth</code> number The maximum number of levels deep that will get printed. Different printers mark a stop different ways. <code>puget</code> doesn't support it at all. <p>See Customizing Calva for some tips on adding settings like these.</p> <p>Here's an example of how <code>zprint</code> handles <code>maxDepth</code> (from the Calva implementation of it's client side pretty printing.).</p> <pre><code>  (pretty-print [[[[[[[[:deeper]]]]]]]] {:max-depth 4})\n  ;; =&gt; {:value \"[[[[##]]]]\"}\n</code></pre>"},{"location":"pprint/#your-selection-of-prettifiers","title":"Your Selection of Prettifiers","text":"<p>Pretty printing can happen on the server (i.e. in the JVM, via nREPL), or on the client (i.e. in node, via VS Code/Calva). Client side always uses <code>zprint</code>. Server side you can choose from these printers:</p> Print Engine Client or Server Side Comments <code>calva</code> client The nREPL server will plain print the results, and then Calva will pretty it (using <code>zprint</code>). <code>pprint</code> server Current Calva default. <code>clojure.core/pprint</code> is a bit basic, but it's tried and tested, and doesn't suffer from the issues with the other server side printing options, mentioned below. <code>fipp</code> server <code>puget</code> server Lacks <code>maxDepth</code> option. <code>zprint</code> server A very good option. However, it will need to be configured before Jack-in if you want Calva's help to inject its dependencies. (If you are not using Jack-in, you'll need to supply this dependency yourself.) <p>These particular server side functions were chosen because they have pre-configured print-functions in <code>cider-nrepl</code>.</p>"},{"location":"pprint/#or-configure-printfn","title":"Or configure <code>printFn</code>","text":"<p>If the selection of built-in <code>printEngine</code> support doesn't cut it, you can configure a custom function. This function will need to conform to the requirements of nREPL print functions. The VS Code settings editor will help you configure this one. (This is also a bit experimental, please consider giving feedback about how it works for you if you try it.)</p>"},{"location":"pprint/#why-does-server-or-client-side-matter","title":"Why does Server or Client Side Matter?","text":"<p>This matters because on the server all pretty printers, except <code>pprint</code> does more than just pretty print the result that would be printed with plain printing. Pretty printing results on the server causes some results to get expanded. This can have huge implications depending on the results and which printer is used. E.g. for Datomic transaction results, you will get the whole database printed. Twice. Depending on the database, you could be so unlucky that nothing gets printed, and instead you will soon have a very hot computer.</p> <p>Note: With the help of zprint creator, Kim Kinnear, we have found ways to compensate for this problem. Ways that are not yet implemented, but please stay tuned.</p> <p>Then why not always do it client side? It turns out that on the client side there are also things going on. Calva gets the results back as a string and therefore it needs to first be parsed back to EDN, before it can be pretty printed by <code>zprint</code>. And \u2013 here's the catch \u2013 all results are not valid EDN and therefore can't be pretty printed by <code>zprint</code>. Datomic transaction results are one example.</p>"},{"location":"pprint/#need-more-configurability","title":"Need More Configurability?","text":"<p>The current options are limited, because our time developing Calva is limited. But <code>cider-nrepl</code> really allows for fully configurable pretty printing, so it is within reach. Please feel invited to give us feedback on what you would want to configure for the printing of results. File issues and/or chat us up in #calva in the Clojurians slack.</p>"},{"location":"pprint/#troubleshooting","title":"Troubleshooting","text":""},{"location":"pprint/#pprint-is-not-working","title":"pprint is not working","text":"<p>If pprint is not working, try a different pprint engine or use Calva's jack-in to make sure the necessary dependencies are loaded in your REPL. If you are starting your REPL without jack-in and want to continue doing so, you can use the command <code>Copy Jack-in Command Line to Clipboard</code> then paste the command somewhere to see what dependencies it injects. You can then add these dependencies to your REPL in whatever way suits your needs.</p> <p>Enjoy Prettiful Printing! \u2764\ufe0f</p>"},{"location":"quirks/","title":"Quirks","text":"<p>Here's a shocker for ya': Calva isn't perfect. \ud83d\ude04</p> <p>There are quirks and things that flat out do not work. We'll try to collect info about such things here, providing workarounds when available (or, rather, known to us).</p>"},{"location":"quirks/#test-features-not-available-with-clojurescript","title":"Test features not available with ClojureScript","text":"<p>Currently <code>cider-nrepl</code> does not provide its test functionality for ClojureScript code. Please consider contributing to fixing that.</p>"},{"location":"quirks/#using-with-parinfer","title":"Using with Parinfer","text":"<p>See Using with Parinfer</p>"},{"location":"quirks/#calva-and-the-vim-extension","title":"Calva and the VIM Extension","text":"<p>See Using Calva with the VIM Extension.</p>"},{"location":"quirks/#command-not-found-errors-on-jack-in","title":"\u201dCommand not found\u201d Errors on Jack-in","text":"<p>Jack-in starts by running a command in a new terminal. You will need the commands used installed on your computer:</p> <ul> <li><code>clojure</code> for tools.deps/deps.edn</li> <li><code>lein</code> for Leiningen</li> <li><code>npx</code> for shadow-cljs</li> <li><code>gradlew</code> for Gradle (in your project)</li> </ul> <p>Also, in some circumstances VS Code is not spawned from a shell with the environment variables, especially <code>$PATH</code>, which might mean that even though you have the tools installed, they are not found when VS Code/Calva tries to execute them. To fix this you will need to do one of these two things:</p> <ol> <li>Figure out from where VS Code is spawned, and make sure the <code>$PATH</code> there includes the directory with the needed binary.</li> <li>Start VS Code from a terminal where the <code>$PATH</code> is correctly configured. (Using the <code>code</code> command.)</li> </ol> <p>See this issue for more clues on this problem.</p>"},{"location":"quirks/#strange-linting-errors","title":"Strange linting errors?","text":"<p>This is not really a quirk, and most linting errors are not strange when you learn about why they are there. Calva does not do any linting, btw, see also linting.</p>"},{"location":"quirks/#consider-uninstalling-these-extensions","title":"Consider uninstalling these extensions","text":"<p>Without Calva, many users install other nifty extensions (some of which are old pieces of Calva) that help with this or that problem. It might sometimes work together with Calva, sometimes not. Here's a list of some common extensions you should consider to at least disable:</p> <ul> <li>Strict Paredit - Calva Paredit has evolved a lot since that version</li> <li>Calva-fmt/Calva Formatter - Same here, evolution</li> <li>Clojure Warrior - Calva includes it, in a much evolved way</li> <li>Parinfer - This one you can actually keep, at some cost, see Using Calva with Parinfer.</li> </ul>"},{"location":"re-frame-template/","title":"How to use Calva with the re-frame template","text":"<p>The re-frame template creates a <code>shadow-cljs</code> project, making it easy to use with Calva.</p> <ol> <li><code>npm install</code></li> <li>From VS Code, issue the command Calva: Start a Project REPL and Connect (a.k.a Jack-in), <code>ctrl+alt+c ctrl+alt+j</code>.</li> <li>Calva will auto-detect that this is a <code>shadow-cljs</code> project and ask for which build to compile.</li> <li>Calva's output window will open and log some progress information.</li> <li>When prompted for which build to start, select <code>:app</code>.</li> <li><code>:app</code> is the only configured build, but the VS Code menu for this is a bit strange so make sure the <code>:app</code> checkbox is really ticked before proceeding.</li> <li>This will start the app, so in this workflow you don't do the Run application steps outlined below.</li> <li>When prompted for which build to connect to, select <code>:app</code>.<ul> <li>In the View menu of VS Code, you can tell it to show the Terminal view, where you see which command the jack-in process is started with, and it's output. <code>Ctrl+C</code> in this pane will kill your app and free up all resources it has allocated.</li> </ul> </li> <li>When the app is compiled<ol> <li>Open http://localhost:8280 in your browser.</li> <li>Confirm that it says Hello from re-frame. (Depending on how long the app takes to compile, you might need to reload the page a few times.)</li> </ol> </li> <li>Open the <code>views.cljs</code> file from <code>src/&lt;your-project-name&gt;</code> and issue Calva: Load/Evaluate Current File and its Requires/Dependencies. <code>ctrl+alt+c enter</code>.<ol> <li>Confirm that you are connected by adding evaluating <code>(js/alert \"Hello from Calva\")</code> (<code>alt+enter</code> and <code>ctrl+enter</code> are your friends).</li> <li>Confirm that Shadow is hot reloading by changing the greeting message.</li> </ol> </li> </ol>"},{"location":"rebl/","title":"How to Use Calva and REBL Together","text":"<p>REBL is a graphical, interactive tool for browsing Clojure data.</p>"},{"location":"rebl/#depsedn","title":"deps.edn","text":"<p>Add the following aliases to your deps.edn file. Use the deps.edn file in the <code>~/.clojure</code> directory to enable alias reuse across multiple projects. This is the configuration for REBL on openjdk 12. Check out the REBL github page for more info.</p> <pre><code>;; REBL Base\n:rebl\n{:extra-deps {org.clojure/core.async {:mvn/version \"0.4.490\"}\n                ;; deps for file datafication (0.9.149 or later)\n                org.clojure/data.csv {:mvn/version \"0.1.4\"}\n                org.clojure/data.json {:mvn/version \"0.2.3\"}\n                org.yaml/snakeyaml {:mvn/version \"1.23\"}\n                com.cognitect/rebl\n                ;; adjust to match your install location\n                {:local/root \"/Users/ozimos/REBL/latest/REBL.jar\"}}}\n\n;; REBL 12\n:rebl-12\n{:extra-deps {org.openjfx/javafx-fxml     {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-controls {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-graphics {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-media    {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-swing    {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-base     {:mvn/version \"12.0.1\"}\n                org.openjfx/javafx-web      {:mvn/version \"12.0.1\"}}}\n\n;; nREBL\n:nrebl {:extra-deps {rickmoynihan/nrebl.middleware {:mvn/version \"0.2.0\"}}\n            :main-opts [\"-e\" \"((requiring-resolve,'cognitect.rebl/ui))\" \"-m\" \"nrepl.cmdline\" \"--middleware\" \"[nrebl.middleware/wrap-nrebl]\" \"-I\"]}\n</code></pre> <p>Create a Calva custom connect sequence for your VSCode editor. (Read Custom REPL Connect Sequences if you haven't.) Add the following to your vscode settings.json:</p> <pre><code>{\n    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"Rebl Connect\",\n            \"projectType\": \"deps.edn\",\n            \"menuSelections\": {\n                \"cljAliases\": [\n                    \"rebl\",\n                    \"rebl-12\",\n                    \"nrebl\"\n                ]\n            }\n        }\n    ]\n}\n</code></pre>"},{"location":"rebl/#leiningen","title":"Leiningen","text":"<p>Add rebl profiles to your user-wide profiles so that they will be available for all your projects. Here's a sample user profile (located at <code>~/.lein/profiles.clj</code> on mac):</p> <p><pre><code>{:user {:plugins [[lein-ancient \"0.6.15\"]]}\n\n ;; REBL Base\n :rebl {:resource-paths [\"/Users/ozimos/REBL/latest/REBL.jar\"]\n        :dependencies [[org.clojure/core.async \"0.4.490\"]\n                       [org.clojure/data.csv \"0.1.4\"]\n                       [org.clojure/data.json \"0.2.3\"]\n                       [cljfmt \"0.6.4\"]\n                       [org.yaml/snakeyaml \"1.23\"]]}\n\n ;; REBL 12 for JDK 12.0.1. Swap out for your JDK version\n :rebl-12 {:dependencies [[org.openjfx/javafx-fxml  \"12.0.1\"]\n                          [org.openjfx/javafx-controls \"12.0.1\"]\n                          [org.openjfx/javafx-graphics \"12.0.1\"]\n                          [org.openjfx/javafx-media \"12.0.1\"]\n                          [org.openjfx/javafx-swing \"12.0.1\"]\n                          [org.openjfx/javafx-base  \"12.0.1\"]\n                          [org.openjfx/javafx-web \"12.0.1\"]]}\n\n;; NREBL https://github.com/RickMoynihan/nrebl.middleware\n :nrebl {:repl-options {:nrepl-middleware [nrebl.middleware/wrap-nrebl]}\n        :dependencies [[rickmoynihan/nrebl.middleware \"0.3.1\"]]}}\n</code></pre> More info here</p> <p>Create a Calva custom connect sequence for your VSCode editor. (Read Custom REPL Connect Sequences if you haven't.) Add the following to your vscode settings.json:</p> <pre><code>{\n    \"calva.replConnectSequences\": [\n        {\n            \"name\": \"Lein REBL\",\n            \"projectType\": \"Leiningen\",\n            \"menuSelections\": {\n                \"leinProfiles\": [\"rebl\", \"rebl-12\", \":nrebl\"]\n            },\n            \"afterCLJReplJackInCode\": \"((requiring-resolve 'cognitect.rebl/ui))\"\n        }\n    ]\n}\n</code></pre>"},{"location":"rebl/#shadow-cljs-tbd","title":"shadow-cljs (TBD)","text":"<p>TBD. If you know how to do it, please update this page.</p>"},{"location":"refactoring/","title":"Refactoring","text":"<p>There are two \u201dflavours\u201d to refactoring support. Some (just a few) refactorings are made available as Quick Fix suggestions (the light bulb), the rest are regular commands in the clojure-lsp Refactoring category.</p> <p></p> <p>You can enable or disable the Quick Fix suggestion lightbulb using the VS Code setting <code>editor.lightbulb.enabled</code>.</p> <p>The refactoring commands do not have default keyboard shortcuts. You find them all by typing \u201dclojure-lsp Refactor\u201d in the Command Palette.</p>"},{"location":"refactoring/#commands","title":"Commands","text":"Command Title Command Key Description Clean NS Form <code>clojureLsp.refactor.cleanNs</code> Add Missing Require <code>clojureLsp.refactor.addMissingLibspec</code> Extract to New Function <code>clojureLsp.refactor.extractFunction</code> Cycle/Toggle Privacy <code>clojureLsp.refactor.cyclePrivacy</code> Inline Symbol <code>clojureLsp.refactor.inlineSymbol</code> Introduce let <code>clojureLsp.refactor.introduceLet</code> Creates a new let box with the binding. Follow up with \u201dExpand let\u201d to move it upwards. Expand Let <code>clojureLsp.refactor.expandLet</code> Move to Previous let Box <code>clojureLsp.refactor.moveToLet</code> Thread First <code>clojureLsp.refactor.threadFirst</code> Thread First All <code>clojureLsp.refactor.threadFirstAll</code> Thread Last <code>clojureLsp.refactor.threadLast</code> Thread Last All <code>clojureLsp.refactor.threadLastAll</code> Unwind All <code>clojureLsp.refactor.unwindAll</code> Unwind Thread <code>clojureLsp.refactor.unwindThread</code> <p>Formatting</p> <p>The way that some of the refactorings are applied to the document, makes it difficult for Calva to format the results. So, sometimes you'll need to navigate the cursor to the enclosing form and hit <code>tab</code> to tidy up the formatting after a refactoring. See also Formatting.</p>"},{"location":"refactoring/#thanks-to-clojure-lsp","title":"Thanks to clojure-lsp","text":"<p>Most of Calva's refactoring support is sourced directly from clojure-lsp. This also means that most often, if you find issues with refactoring, or have suggestions about it, the clojure-lsp repo is where to direct your reporting.</p>"},{"location":"remote-development/","title":"Using Calva with Remote Development","text":"<p>VS Code Remote Development is a new feature in version 1.35 of VS Code that allows a developer to use a container, remote machine, or the Windows Subsystem for Linux (WSL) as a full-featured development environment.</p> <p>I would recommend reading the introductory blog post and watching the videos. I find the feature extremely exciting and wish more IDEs would implement something like it.</p> <p>From a Clojure perspective it allows you to have VS Code installed on your Java-less, Clojure-less hardware and still use it to develop Clojure through it.</p>"},{"location":"remote-development/#a-use-case","title":"A use-case","text":"<ul> <li>For some reason your physical computer has to be running Windows (organizational rules etc.)</li> <li>Your deployment environment is Linux</li> <li>You want to edit files in an editor running on your physical computer</li> <li>Most Clojure tooling is made with *nix first in mind and there are incompatibilities with Windows</li> </ul>"},{"location":"remote-development/#how-to","title":"How to","text":"<p>Run Remote-Containers: Add Development Container Configuration Files... and pick a suitable Java base image. Then:</p>"},{"location":"remote-development/#modify-dockerfile-to-install-clojure-cli-and-optionally-lein","title":"Modify Dockerfile to install Clojure CLI (and optionally lein)","text":"<p>Add:</p> <pre><code># ...\n\n# Install Clojure - see https://github.com/Quantisan/docker-clojure/blob/master/target/openjdk-14-slim-buster/tools-deps/Dockerfile\nENV CLOJURE_VERSION=1.10.1.619\nWORKDIR /tmp\nRUN \\\napt-get update &amp;&amp; \\\napt-get install -y curl make rlwrap wget &amp;&amp; \\\nrm -rf /var/lib/apt/lists/* &amp;&amp; \\\nwget https://download.clojure.org/install/linux-install-$CLOJURE_VERSION.sh &amp;&amp; \\\nsha256sum linux-install-$CLOJURE_VERSION.sh &amp;&amp; \\\necho \"28b1652686426cdf856f83551b8ca01ff949b03bc9a533d270204d6511a8ca9d *linux-install-$CLOJURE_VERSION.sh\" | sha256sum -c - &amp;&amp; \\\nchmod +x linux-install-$CLOJURE_VERSION.sh &amp;&amp; \\\n./linux-install-$CLOJURE_VERSION.sh\nRUN \\\nsu vscode -c \"clojure -e '(clojure-version)'\" &amp;&amp; \\\nrm ./linux-install-$CLOJURE_VERSION.sh\n\n# Install Lein\nRUN \\\nwget https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein -O /bin/lein &amp;&amp; \\\nchmod uog+x /bin/lein\nRUN su vscode -c \"/bin/lein\"\n\n# Cleanup\nRUN apt-get purge -y --auto-remove curl wget\n\n# ...\n</code></pre>"},{"location":"remote-development/#modify-devcontainerjson","title":"Modify devcontainer.json","text":"<p>Add Calva and, optionally, forward some ports to the host::</p> <pre><code>\"extensions\": [\"betterthantomorrow.calva\"],\n\"forwardPorts\": [8088, 52162], // example: your webapp, your nREPL\n</code></pre>"},{"location":"remote-development/#build-and-start","title":"Build and start","text":"<p>Run Remote-Containers: Rebuild and Reopen in container</p>"},{"location":"remote-development/#wsl","title":"WSL","text":"<p>See Using Calva with WSL</p>"},{"location":"repl-window/","title":"The REPL Window/File","text":"<p>The Calva REPL Window is actually a regular file with some extra treatment from Calva, like displaying a prompt, offering evaluation history recall and generally \u201cfollowing\u201d the current namespace. This file is created and opened when Calva is connected to a REPL. You can use it for experimental code (though there are also Rich Comments and Fiddle Files for this). </p> <p>In ClojureScript projects, the window will be associated with the <code>cljs</code> REPL once it is connected. It will then look something like this:</p> <p></p> <p>The first prompt is from when the <code>clj</code> REPL is connected, and the second from <code>cljs</code>. The first part of the prompt tells you which REPL type the window is currently connected to.</p>"},{"location":"repl-window/#using-the-repl-window-for-output","title":"Using the REPL Window for output","text":"<p>By default the REPL Window doubles as the place where Calva sends output like stdout/stderr and other messages. See Calva Output for more about this and how to change this behaviour.</p>"},{"location":"repl-window/#finding-the-repl-window","title":"Finding the REPL Window","text":"<p>If you quickly want to open and/or switch to the REPL Window there is the command Calva: Show/Open REPL Window, <code>ctrl+alt+o r</code>.</p> <p>To sync the REPL window namespace with the current file before switching, use the Switch Namespace of the REPL Window to Current Namespace command, <code>ctrl+alt+c alt+n</code>.</p>"},{"location":"repl-window/#find-the-file-for-the-current-repl-window-namespace","title":"Find the File for the Current REPL Window Namespace","text":"<p>When you are editing things in the REPL window, and want to open the file that defines its current namespace, use the Show File for the Current REPL Window Namespace command, <code>ctrl+alt+o r</code>.</p> <p>Note</p> <p>This also works for Clojure core and library namespaces.</p>"},{"location":"repl-window/#evaluating-code","title":"Evaluating Code","text":"<p>The window will be automatically associated with the REPL and the namespace of any project Clojure/ClojureScript file you evaluate code in. So for instance if you evaluate this code in a <code>clj</code> file with the namespace <code>fresh-reagent.handler</code>:</p> <pre><code>(def mount-target\n  [:div#app\n   [:h2 \"Welcome to fresh-reagent\"]\n   [:p \"please wait while Figwheel is waking up ...\"]\n   [:p \"(Check the js console for hints if nothing exciting happens.)\"]])\n</code></pre> <p>If the REPL Window is the configured destination for evaluation results, the defined var will be printed there. Otherwise, it will be printed to the destination you've configured. In either case, the REPL window will print a new prompt reflecting the current REPL connection and namespace:</p> <p></p> <p>If you then switch to the output window (<code>ctrl+alt+o r</code>), and enter this at the prompt:</p> <pre><code>mount-target\n</code></pre> <p>then evaluate it using <code>alt+enter</code>, you'll get this:</p> <p></p> <p>... because the namespace \u201dfollowed\u201d the first evaluation in the REPL window.</p>"},{"location":"repl-window/#repl-history","title":"REPL History","text":"<p>Recently evaluated forms in the REPL file are persisted and can easily be shown again for modifying and re-evaluating.</p>"},{"location":"repl-window/#navigate-repl-history","title":"Navigate REPL History","text":"<p>You can navigate up and down the history of evaluated forms in the REPL file by pressing <code>alt+up</code> and <code>alt+down</code>, provided your cursor is at the end of the last form after the prompt. If the cursor is not at the end of the last form, then <code>alt+up</code> and <code>alt+down</code> will do whatever they are mapped to, which is by default \"Move Line Up\" and \"Move Line Down,\" respectively.</p> <p>If you have typed some text after the prompt before you start traversing up the history, this text will be preserved and will display when you traverse back down the history. If you modify some text in the history while traversing, the modification will be saved at that location in history.</p>"},{"location":"repl-window/#clear-repl-history","title":"Clear REPL History","text":"<p>You can clear the repl history by running the command \"Clear REPL History\" from the command palette.</p>"},{"location":"repl-window/#stack-traces","title":"Stack Traces","text":"<p>When an evaluation produces an error, it will automatically be printed in the REPL Window. If there is a stack trace associated with the error, it can now be printed on demand using the Calva: Print Last Stacktrace to the Output Window command. You can also print the stack trace for any error message printed to the REPL Window via the Codelens button below it.</p> <p></p> <p>For printed stacktraces, when source locations are available (Clojure files), you will be able to navigate to them by pressing <code>ctrl+click</code> (<code>cmd+click</code> on Mac) on the file name. You can also hover over symbols in the stack trace to see the symbol's documentation, and <code>ctrl+click</code> (<code>cmd+click</code> on Mac) the symbol to Peek Definition.</p> <p></p> <p>Output destinations</p> <p>If you have configured some other destination for stderr output, the error message will be printed there as well. But it will also be printed to the REPL Window, because the augmented stack traces need this (because reasons). </p>"},{"location":"repl-window/#load-current-namespace","title":"Load Current Namespace","text":"<p>When navigating namespaces it is easy to forget to first require them and that can be tricky to debug. To help with this, Calva's command Load/Evaluate Current File and its Requires/Dependencies also works in the REPL Window, but there, it acts like Load Current Namespace.</p> <p>Suppose you have two files, <code>pez/xxx.clj</code> and <code>pez/yyy.clj</code>, where <code>pez.yyy</code> requires <code>pez.xxx</code>.</p> <pre><code>(ns pez.xxx)\n\n(def a :xxx-a)\n\n(def b :xxx-b)\n</code></pre> <pre><code>(ns pez.yyy\n  (:require [pez.xxx]))\n\n(def a :yyy-a)\n\n(println \"Hello\" pez.xxx/a)\n</code></pre> <p>Then, with a freshly jacked-in REPL, you evaluate <code>(ns pez.yyy)</code> and want to work with the vars defined there, Clojure will complain. But if you Load/Evaluate Current File and its Requires/Dependencies, it will start working. Something like so:</p> <p></p> <p>Note</p> <p>This currently suffers from a limitation in Calva where it won't reload dependencies, so you will sometimes have to do this \u201dmanually\u201d anyways (by opening the files and loading them yourself). See Calva issue #907</p>"},{"location":"repl-window/#peek-current-namespace","title":"Peek Current Namespace","text":"<p>A somewhat hidden feature: You can peek, see documentation for, and navigate to a namespace by hovering on the namespace symbol in one of the REPL Window prompts (just like you would if it was not in the prompt \ud83d\ude04).</p>"},{"location":"repl-window/#paredit-enabled","title":"Paredit Enabled","text":"<p>The REPL Window is mostly a regular Calva Clojure/ClojureScript file, which makes everything that works in a regular file work in this file, including Paredit. This makes it easy to navigate the input and output there. For instance, to select the last evaluation results, you can press <code>ctrl+w</code> (<code>shift+alt+right</code> on Windows and Linux):</p> <p></p>"},{"location":"repl-window/#debugger-enabled","title":"Debugger Enabled","text":"<p>The output window is mostly a regular... (you get it), which means you also have the Calva debugger at your command at the REPL prompt (only for <code>clj</code> sessions, for now). So instead of evaluating a function definition using <code>alt+enter</code>, you can evaluate it and instrument it for debugging using <code>ctrl+alt+c i</code>, and then call the function.</p> <p></p>"},{"location":"repl-window/#it-is-ephemeral","title":"It is Ephemeral","text":"<p>The contents of the output/REPL window is written to a file named <code>output.repl</code> in the <code>.calva/output-window</code> directory of your project. The file is recreated every new session, so you should copy or save anything you want to preserve between sessions.</p> <p>You probably want to add <code>.calva/output-window/</code> to your <code>.&lt;something&gt;ignore</code> files. (There are some more files in that directory that you shouldn't keep under source control.)</p>"},{"location":"repl-window/#choose-clj-or-cljs-repl-connection","title":"Choose CLJ or CLJS REPL Connection","text":"<p>In full-stack projects, you will probably use the window as a REPL for both <code>clj</code> and <code>cljs</code>. You can toggle which REPL the window is connected to by using the command Calva: Toggle REPL Connection for CLJC files. There is also a button for this in the status bar:</p> <p></p>"},{"location":"repl-window/#known-quirks-and-caveats","title":"Known Quirks and Caveats","text":"<p>Due to limitations in the VS Code API it is hard for Calva to know if the REPL file is open, and if it was opened more than once. Therefore, we suggest you make it a habit to leave this window open, or even pinned. And if it is open in several tabs, expect evaluation printouts to be a bit unpredictable.</p> <p>If you save the REPL file (which most often does not make much sense, but anyway) you will sometimes be presented with a message about VS Code being confused about the file contents being out of sync. Just choose to Overwrite the currently saved version and you should be fine.</p>"},{"location":"reveal/","title":"How to use Calva and Reveal together","text":"<p>Reveal is a \"Read Eval Visualize Loop for Clojure\". This page describes how to use Reveal in your development setup based on Calva.</p> <p>Note</p> <p>See https://vlaaad.github.io/reveal for the latest version and use that wherever this page says <code>&lt;version&gt;</code>.</p>"},{"location":"reveal/#when-using-toolsdeps","title":"When using tools.deps","text":"<p>You can go for the nrepl middleware or just add the dependency. </p> <p>Please see the Calva test-data project minimal-reveal for an example.</p>"},{"location":"reveal/#middleware","title":"Middleware","text":"<p>This will make Reveal to start together with your project.</p> <p>Note</p> <p>This will make all Calva evaluations go to Reveal. Too chatty for you? Take the dependencies only approach.</p> <p>Add this alias <code>deps.edn</code>:</p> <pre><code>:aliases\n{:reveal-nrepl-middleware\n    {:extra-deps {vlaaad/reveal {:mvn/version \"&lt;version&gt;\"}}\n     :main-opts  [\"-m\" \"nrepl.cmdline\"\n                  \"--middleware\" \"[vlaaad.reveal.nrepl/middleware,cider.nrepl/cider-middleware]\"]}}\n</code></pre> <p>And then jack-in choosing the deps.edn option and then pick the <code>:reveal-nrepl-middleware</code> alias.</p>"},{"location":"reveal/#dependencies-only","title":"Dependencies only","text":"<p>If you don't want to use the nrepl-middleware you can configure just the dependency and then start Reveal yourself.</p> <p>The alias:</p> <pre><code>:reveal-dep-only\n  {:extra-deps {vlaaad/reveal {:mvn/version \"&lt;version&gt;\"}}}\n</code></pre> <p>A custom REPL command for starting Reveal in your project:</p> <pre><code>    \"calva.customREPLCommandSnippets\": [\n        ...\n        {\n            \"name\": \"Start Reveal Tapper\",\n            \"snippet\": \"(require '[vlaaad.reveal :as reveal])(add-tap (reveal/ui))\",\n            \"key\": \"sr\"\n        },\n        ...\n    ]\n</code></pre> <p>See Custom REPL Command for how to configure more commands, and bind shortcuts to them, to make Reveal integration nice for you.</p>"},{"location":"reveal/#when-using-leiningen","title":"When using Leiningen","text":"<p>In your <code>project.clj</code>, add a profile named \"reveal\":</p> <pre><code>:profiles {:reveal {:dependencies [[vlaaad/reveal \"&lt;version&gt;\"]]\n                    :repl-options {:nrepl-middleware [vlaaad.reveal.nrepl/middleware]}}}\n</code></pre> <p>Now when you jack-in using Calva, you enable this profile and Reveal will be started automatically. Please note that Reveal requires Java 8 or higher, and uses JavaFX. Depending on your setup, you may need to make sure it is available.</p>"},{"location":"reveal/#tips-about-font-size","title":"Tips about font size","text":"<p>If you find the font to small you can add a <code>:jvm-opts</code> key to make it a little bigger:</p> <pre><code>:aliases\n{:reveal\n    {:extra-deps {vlaaad/reveal {:mvn/version \"&lt;version&gt;\"}}\n     :jvm-opts   [\"-Dvlaaad.reveal.prefs={:font-size,17}\"]\n     :main-opts  [\"-m\" \"nrepl.cmdline\"\n                  \"--middleware\" \"[vlaaad.reveal.nrepl/middleware,cider.nrepl/cider-middleware]\"]}}\n</code></pre>"},{"location":"reveal/#using-java-11","title":"Using Java &gt; 11?","text":"<p>Reveal needs some reflective access to internal classes that has since Java 11 been restricted. You can relax this and get things working via JVM options. Tuck this into your reveal alias:</p> <pre><code>:jvm-opts [\"--add-opens\" \"javafx.graphics/com.sun.javafx.tk=ALL-UNNAMED\"]\n</code></pre> <p>(If you are using the font size tips, just add the options into the <code>:jvm-opts</code> vector.)</p> <p>See https://github.com/vlaaad/reveal/issues/1 for some more context around this issue.</p>"},{"location":"rich-comments/","title":"Rich Comments Support","text":"<p>Why bother with Rich comments? Read on. Consider watching this Youtube video for a demo of the workflow using the (in?)famous FizzBuzz problem as an example.</p>","boost":5},{"location":"rich-comments/#things-in-comment-are-not-evaluated","title":"Things in <code>comment</code> are not evaluated","text":"<p>The Clojure <code>comment</code> macro is defined like so:</p> <pre><code>(defmacro comment\n  \"Ignores body, yields nil\"\n  {:added \"1.0\"}\n  [&amp; body])\n</code></pre> <p>It has no forms in its body and will therefore always (as long as the Clojure Reader can read it) evaluate to <code>nil</code>. That is: nothing in the <code>(comment ...)</code> form will get evaluated when the file is loaded.</p> <p>This makes it a very good \u201dplace\u201d where you can develop code, experiment with code, and keep example code. Since you will be able to load/evaluate the current file without worrying that the code in the <code>comment</code> form will get evaluated. This also holds true when using tools that hot-reload the code on save, such as Figwheel, shadow-cljs and Krell.</p> <p>To develop or refine a function you might:</p> <ol> <li>Open up a <code>(comment ...)</code> form</li> <li>Inside this form, type a first, super simple, version (or refinement) of your function and evaluate it</li> <li>Inside the same <code>comment</code> form, type some code to test your function and evaluate that<ul> <li>Or type and evaluate some code you might need for your function</li> </ul> </li> <li>Repeat from 2., until the function does what you want it to do</li> <li>Move the function definition out of the <code>comment</code> form</li> <li>Clean up the <code>comment</code> form to keep some of the test code as example use, or \u201ddesign decision log\u201d for the function.</li> </ol> <p>Note</p> <p>Using <code>(comment ...)</code> forms for developing code is very common among Clojure coders. Rich Hickey is known for using it, which is why they are called Rich comments to begin with (even if it also is a very rich experience).</p>","boost":5},{"location":"rich-comments/#calva-encourages-rich-comments","title":"Calva encourages Rich comments","text":"<p>Calva has several features to facilitate the Rich comments workflow, e.g.</p> <ol> <li>A command that helps you create a new Rich comment form quickly: Calva: Add Rich Comment, ctrl+alt+r c</li> <li>A snippet for creating Rich comment form quickly. Typing <code>(rcf</code>, will make it appear.</li> <li>Special Syntax highlight. By default <code>comment</code> forms are rendered in italics</li> <li>Special top-level form context</li> <li>Special formatting</li> </ol> <p>Note that the command and snippet for creating Rich comments add the keyword <code>:rcf</code> right before the closing paren. This makes the closing paren stay and not fold when you format the code. The special formatting (see below) will treat this and also any ignored (with <code>#_</code>) form at the end of the form specially.</p>","boost":5},{"location":"rich-comments/#comment-is-top-level","title":"<code>comment</code> is top-level","text":"<p>To make it easy to evaluate forms in <code>(comment ...)</code> forms, they create a new top-level context. Instead of you having to place the cursor with precision before evaluating the current form, you can have the cursor anywhere within a <code>comment</code> enclosed form and Evaluate Top-Level Form.</p> <p>This carries over to all commands in Calva which deal with the top level form. Including custom command snippets.</p>","boost":5},{"location":"rich-comments/#special-formatting","title":"Special formatting","text":"<p>To invite a Rich comments workflow, the Calva command Format Current Form will not fold the closing bracket of the <code>(comment ...)</code> form. Instead it will place this bracket on a line of its own (or keep it there).</p> <pre><code>(comment\n  )\n</code></pre> <p>With the cursor somewhere directly inside the comment form (denoted with a <code>|</code>):</p> <pre><code>(comment\n  (def foo\n:foo)|)\n</code></pre> <p>tab</p> <pre><code>(comment\n  (def foo\n    :foo)\n  |)\n</code></pre> <p>!!! Note \"Only for the current comment form\u201d     The special formatting only applies in the current <code>comment</code> form. When outside it, formatting tucks the closing paren in again. That's why fold when done, below works like it does. This also applies to VS Code commands like Format Document, or when you have Format On Save enabled. There are several reasons for this, and one is that there is no <code>cljfmt</code> config for it and leaving the closing comment un-tucked might give you troubles with CI pipelines that enforce some cljfmt config be followed. (Another reason is that it would be pretty hard to do on the whole document.)</p>","boost":5},{"location":"rich-comments/#special-formatting-disabled-for-trailing-rcf","title":"Special formatting disabled for trailing <code>:rcf</code>","text":"<p>If the Rich comment ends with <code>:rcf</code> (or an ignored form), the special formatting doesn't happen. So if you have:</p> <pre><code>(comment\n  (def foo\n:foo)\n  |\n  :rcf)\n</code></pre> <p>And hit tab, you will get:</p> <pre><code>(comment\n  (def foo\n    :foo)\n  |\n  :rcf)\n</code></pre>","boost":5},{"location":"rich-comments/#thinking-space-is-kept","title":"Thinking space is kept","text":"<p>The formatter will not remove newlines between the cursor and the closing bracket. So if you have entered a few lines to get \u201dthinking\u201d room:</p> <pre><code>(comment\n  (def foo\n:foo)\n\n|\n\n)\n</code></pre> <p>tab</p> <pre><code>(comment\n  (def foo\n    :foo)\n\n  |\n\n  )\n</code></pre>","boost":5},{"location":"rich-comments/#fold-when-done","title":"Fold when done","text":"<p>To fold the trailing paren automatically, place the cursor immediately outside (before or after) the form:</p> <pre><code>(comment\n  (def foo\n:foo))|\n</code></pre> <p>tab</p> <pre><code>(comment\n  (def foo\n    :foo))|\n</code></pre>","boost":5},{"location":"rich-comments/#enabled-by-default","title":"Enabled by default","text":"<p>You can disable this behavior with the setting: <code>calva.fmt.keepCommentTrailParenOnOwnLine</code>.</p>","boost":5},{"location":"rich-comments/#only-for-the-current-form","title":"Only for the Current Form","text":"<p>Note</p> <p>This treatment only applies to formatting of the current form. With fold when done as an exception.</p>","boost":5},{"location":"shadow-cljs/","title":"shadow-cljs","text":"<p>Calva supports most any JVM hosted ClojureScript environment (and some others, including SCI based, too), but shadow-cljs gets some special treatment to try make it extra convenient to use.</p> <p>With many shadow-cljs projects, Calva's connect project type shadow-cljs, is the right choice. Projects that use Leiningen or deps.edn can be used both with the Leiningen/deps.edn and shadow-cljs type, depending on configuration see below for more on this.</p>","boost":7},{"location":"shadow-cljs/#shadow-cljs-browser-quickstart","title":"shadow-cljs - browser quickstart","text":"<p>Here's how you start a shadow-cljs ClojureScript REPL and connect Calva with the shadow-cljs - browser quickstart example project:</p> <p>Prep:</p> <ol> <li>Clone the project to your machine and open its root folder in VS Code.</li> <li>Open a terminal and run <code>npm install</code></li> </ol> <p>Connect Calva:</p> <ol> <li>Run the command Calva: Start a Project REPL and Connect (a.k.a. Jack-in)</li> <li>Select project type shadow-cljs</li> <li>Select to start the build :app</li> <li>Select to connect to the build :app</li> <li>Wait for the build to complete</li> <li>Open http://localhost:8020/ in the browser</li> <li>Open browser.cljs file and load it in the REPL: Calva: Load/Evaluate Current File and Dependencies</li> </ol> <p>Now you can should be able to evaluate forms, e.g.:</p> <ul> <li>The current form or selection with ctrl+enter, or</li> <li>Top-level forms with alt/option+enter.</li> </ul> <p>(See Code Evaluation)</p>","boost":7},{"location":"shadow-cljs/#shadow-cljs-in-full-stack-projects","title":"shadow-cljs in full stack projects","text":"<p>shadow-cljs is a bit special in regards to Calva REPL connection. Mainly because you can start shadow-cljs and it's nREPL server in two ways:</p> <ol> <li>Using the shadow-cljs npm executable</li> <li>Via the Clojure REPL in your Leiningen or deps.edn project</li> </ol> <p>These options show up as project types when connecting or jacking in:</p> <ol> <li>Project type: shadow-cljs</li> <li>Project type: deps.edn + shadow-cljs or Leiningen + shadow-cljs</li> </ol> <p>The technical difference here is wether you let shadow-cljs start clojure/Leiningen (the first option) or if you let Calva do it (the second option). If you let Calva do it, Calva will then start the shadow-cljs watcher from the Clojure process. From a usage perspective the two approaches will result in different channeling of shadow-cljs output, e.g. test runner results. With the first option (the shadow-cljs project type), shadow-cljs output will be channeled to the Jack-in terminal. With the deps.edn/Leiningen option, that output will be channeled to the Output/REPL window.</p> <p>See shadow-cljs + Clojure with Calva: The basics for some more discussion on how the REPL connection works.</p> <p>shadow-cljs and <code>clojure</code> aliases</p> <p>The shadow-cljs project type will not prompt you for any aliases found in the <code>deps.edn</code> file. Usually you should provide such aliases in <code>shadow-cljs.edn</code> like <code>:deps {:aliases [...]}</code>. If, for whatever reason you can't provide the aliases that way, you can configure a Custom REPL Connect Sequence and provide the aliases as <code>menuSelections</code> -&gt; <code>cljAliases</code>.</p> <p>Leiningen + shadow-cljs middleware issue</p> <p>Please note that for Leiningen, the command line dependency injection of the shadow-cljs nrepl middleware doesn't work. You need to add it to your <code>project.clj</code>:</p> <pre><code>:repl-options {:nrepl-middleware [shadow.cljs.devtools.server.nrepl/middleware]}\n</code></pre>","boost":7},{"location":"shadow-cljs/#see-also","title":"See also:","text":"<ul> <li>Connect the REPL</li> <li>Custom REPL Connect Sequences</li> <li>shadow-cljs + Clojure with Calva: The basics</li> </ul>","boost":7},{"location":"sponsors/","title":"Calva Sponsors","text":"<p>Calva is open source and free to use. It is actively maintained during our free time, and it keeps improving. You can contribute in many different ways, one of which is sponsoring. You can sponsor Calva by directly sponsoring any of us.</p> <p>If you are working at a company which benefits from Calva's existence and continued development, please consider sponsoring at the Calva Gold Sponsor tier.</p> <p>Please see this statement from Cognitect about the importance of supporting open source developers.</p>","boost":7},{"location":"sponsors/#patrons","title":"Patrons","text":"The right kind of different","boost":7},{"location":"sponsors/#gold-sponsors","title":"Gold Sponsors","text":"Scale your growth on mobile MAKE. DO. SHIP.","boost":7},{"location":"sponsors/#silver-sponsors","title":"Silver Sponsors","text":"","boost":7},{"location":"sponsors/#clojurists-together","title":"Clojurists Together","text":"<p>Significant additions to Calva have been made possible by funding from Clojurists Together. And this has often been transformational for the whole project. Calva would not be where it is today without Clojurists Together.</p>","boost":7},{"location":"sponsors/#our-sponsoring-profiles","title":"Our Sponsoring Profiles","text":"<p>These are the sponsoring profiles for the active maintainers of Calva (a.k.a. The Calva Team).</p> <ul> <li>Peter Str\u00f6mberg</li> <li>Brandon Ringe</li> <li>Cora Sutton</li> <li>Lukas Domagala</li> <li>Rayat Rahman</li> </ul>","boost":7},{"location":"sponsors/#readme-visibility","title":"README visibility","text":"<p>There is also a sponsors section in the README of the Calva project (which means it is also displayed in the VS Code Extension Marketlace).</p>","boost":7},{"location":"syntax-highlighting/","title":"Calva Highlight","text":"<p>Calva takes care of syntax highlighting, and also provides some features not available through VS Code's highlighting mechanism. These extras include rainbow parens, sane bracket matching, and comment form dimming/highlighting.</p>"},{"location":"syntax-highlighting/#syntax-highlighting","title":"Syntax Highlighting","text":"<p>When using Calva, you are also using its TMLanguage grammar (the core mechanism VS Code uses for syntax highlighting).</p> <p>Our grammar tokenizes Clojure keywords as <code>constant.keyword.clojure</code>. Since it is pretty uncommon with keyword constants in the programming languages out there, your theme might not have a highlight defined for this scope. Try find a grammar that highlights keywords! If you are very fond of some theme lacking this, you can help it with a setting:</p> <pre><code>\"editor.tokenColorCustomizations\": {\n    \"[Default Dark+]\": {\n        \"textMateRules\": [\n            {\n                \"scope\": [\n                    \"constant.keyword.clojure\"\n                ],\n                \"settings\": {\n                    \"foreground\": \"#6fbfff\"\n                }\n            }\n        ]\n    }\n},\n</code></pre> <p>Instead of <code>Default Dark+</code> you should use your theme's name/key. And choose a color you like, of course.</p>"},{"location":"syntax-highlighting/#extra-highlighting","title":"Extra Highlighting","text":"<p>You are in charge of how brackets and comments are highlighted via the <code>calva.highlight.&lt;setting&gt;</code> settings:</p> Setting Meaning Example <code>enableBracketColors</code> Enable rainbow colors <code>true</code> <code>rainbowIndentGuides</code> Enable rainbow indent guides <code>true</code> <code>highlightActiveIndent</code> Highlight the active indent guide <code>true</code> <code>bracketColors</code> Which colors to use <code>[\"#000\", \"#999\"]</code> <code>cycleBracketColors</code> Whether same colors should be  reused for deeply nested brackets <code>true</code> <code>misplacedBracketStyle</code> Style of misplaced bracket <code>{ \"border\": \"2px solid #c33\" }</code> <code>matchedBracketStyle</code> Style of bracket pair highlight <code>{\"backgroundColor\": \"#E0E0E0\"}</code> <code>ignoredFormStyle</code> Style of <code>#_...</code> form <code>{\"textDecoration\": \"none; opacity: 0.5\"}</code> <code>commentFormStyle</code> Style of <code>(comment ...)</code> form <code>{\"fontStyle\": \"italic\"}</code> <p>Calva disables the VS Code built-in indent guides</p> <p>The VS Code built-in settings <code>editor.renderIndentGuides</code> and <code>editor.highlightActiveIndent</code> do not have any effect, since the former is switched off by the Clojure Defaults, mentioned above. Use Calva Highlight's <code>rainbowIndentGuides</code> and <code>highlightActiveIndent</code> instead. They are different from the built in ones in that they are independent, meaning you can choose to have active indent highlighted while the guides generally are not rendered (this is the default, even).</p> <p>VS Code bracket coloring vs Calva's</p> <p>Calva's bracket coloring is more Clojure aware than VS Code's built-in coloring. And also will chime better with Calva's indent guides. If you like to have bracket coloring outside Clojure code, by all means enable it. Calva's bracket coloring will \u201dover paint\u201d in Clojure files, when enabled. These settings work nicely:</p> <pre><code>\"calva.highlight.highlightActiveIndent\": true,\n\"editor.bracketPairColorization.enabled\": true,\n</code></pre> <p>The <code>calva.highlight.bracketColors</code> setting can be used to harmonize the coloring between VS Code and Calva.</p>"},{"location":"tao/","title":"The Tao of Calva","text":"<p>Calva, the spirit, gains much of its taste and color from the Cider it is distilled from, and the oak it is matured in. I started to wonder what it is that shapes Calva, the VS Code Clojure Extension. I should know, being the master distiller, right?. Indeed. Poking some at the question, I do find that I have some answers.</p> <p>Please read the following to learn what Calva is, and, to some extent, is not, about. Read it to get an idea about which path Calva is following, where we are headed with the project, and how you can contribute to the journey.</p>"},{"location":"tao/#why-calva","title":"Why Calva?","text":"<p>Calva's raison d\u00b4\u00eatre is to provide Visual Studio Code users with an easy to use and productive environment for Clojure and ClojureScript development. See the Why Calva? page for some evidence that we are succeeding.</p> <p>While Calva draws a lot of inspiration from CIDER, Cursive, Fireplace, and other Clojure development environments, it does not try to compete with them. Reading r/Clojure and elsewhere, it is easy to get the impression that the most common question is \"Which editor should I use for Clojure development?\u201d. I think a much more common question is \u201dHow do I use my favorite editor for Clojure development?\u201d. For VS Code users, that is where Calva should be a good choice.</p> <p>I also have an ambition to leverage VS Code for easing the path to Clojure. Given that it is the favorite editor for so many developers, it is important to have a good development environment in place on this platform, and to make it as easy to use as we possibly can, while also being productive and something that you want to stick with, once you are hooked on Clojure.</p> <p>That said, and therefore: For people who want to start out with Clojure, and do ask about what development environment would make it the most enjoyable, I'd like for Calva to be a really good option, an option so good that Clojurians feel they can recommend it.</p>"},{"location":"tao/#design-goals","title":"Design Goals","text":"<p>Calva should be easy to start with and productive enough to stick with. It should support Clojure Best Practices, and be pleasant and enjoyable to use. It should also be easy to hack on, and to contribute to. The ClojureScript story keeps getting more important. Calva should contribute to making the development experience with ClojureScript delightful.</p>"},{"location":"tao/#easy-to-start-with","title":"Easy to Start With","text":"<p>There are reasons as to why VS Code is so popular. Among those, one stands out to me: It is the most approachable code editor out there. There is nothing you need to learn when you start using it. The editor makes it obvious that you can start typing, deleting, cutting, pasting and undoing, without having to figure anything out. Then you learn how to bring up the command palette and get a boost few other environments can provide with such immediacy.</p> <p>A language extension for VS Code can leverage this, by recognizing that what's old is old, and that what's new should be as easy as possible to pick up. Coming to a new language, people bring with them a lot of expectations from the languages they are used to. This is also true for the editor support. Syntax highlighting and formatting should just work, as should documentation lookup, linting and other IDE commodities.</p> <p>Clojure brings some new concepts to the table. Chief among these: The REPL. It does take some time to grasp it. Calva needs to remove any obstacles it can when it comes to helping the user to reach the REPL, in order to help getting it, and start loving it.</p> <p>To help the users to quickly focus on Clojure, we provide a package that is all-inclusive, with few knobs to turn, and with sane defaults for the knobs that still need to be there.</p>"},{"location":"tao/#productive-enough-to-stick-with","title":"Productive Enough to Stick With","text":"<p>I think VS Code brings inspiration also when it comes to following up its excellent Getting Started story. You do not have to dig very deep under its surface to find that there is a lot more power to be unleashed. VS Code makes it easy to pick up more features as you get ready for it, and each little piece makes you more productive. To me, only Vim beats VS Code in this game.</p> <p>Most often there should be no contradiction between Easy to Start With and Productive. Quite the contrary. This story is mainly about being feature complete with the most important tools. As beginners start to pick up the first few features, they should be rewarded with finding more productive tools when they go looking for them. The VS Code way is Calva's way.</p>"},{"location":"tao/#pleasant-and-enjoyable","title":"Pleasant and Enjoyable","text":"<p>Enjoyable starts with that Calva shouldn't be an experience full of pains. I think Calva is living up to this first bar of enjoyability. The next step is making it delightful!</p> <p>Calva has two main assets it can leverage for being delightful to use: Clojure and VS Code:</p> <p>Clojure is plain wonderful and also has this totally awesome REPL thing. Wherever we can, Calva should use the REPL to make the editor spark and bring joy to the developer.</p> <p>VS Code is a sweet development environment, offering its power in a consistent way across languages. Even if Clojure is very special, most of Calva's features are surfaced in the ways that VS Code encourages. It makes for less to learn for the user, and most often also makes it easier to implement functionality.</p>"},{"location":"tao/#support-clojure-best-practices","title":"Support Clojure Best Practices","text":"<p>Mainly, I think Stuart Halloway is right about the REPL being best used from inside the files you are editing rather than from the prompt. It doesn't mean that Calva's REPL window should be neglected, but efforts should be directed such that the file editor REPL is our first way to improve the experience. Expect the Calva REPL window to get much less \u201din your face\u201d, than it is today, as the editor REPL gets stronger.</p> <p>Halloway also gives me some peace of mind with his reasoning of keeping a spartan setup. Calva does not need to pack every feature imaginable. If we can get the right features in place, in the right way, the mission is accomplished.</p> <p>Clojure is data centric. Calva should make it easy to examine data and how our code affects it. Today, this is not good enough when it comes to data structures larger than a few elements.</p> <p>Clojure is a LISP. Thus Structural Editing is possible, and TBH, desirable. Calva should support this and encourage it. There is little we can do about Parinfer not playing well with VS Code, but there is Paredit, and Paredit rocks! Calva's Paredit plays in the top league of Paredits, for this reason.</p>"},{"location":"tao/#made-from-the-produce-of-the-orchard","title":"Made from the Produce of the Orchard","text":"<p>Calva is distilled from CIDER, which in turn is brewed from the products of The Orchard. This makes a lot of Calva's features thin wrappers around cider-nrepl and related middleware. It also should mean that we strive for adding features by thinking \u201dThe Orchard\u201d first. If it lacks what we need, we should assist in providing it there. We need to up this game a bit from where we are today, I think.</p>"},{"location":"tao/#leveraging-clojure-lsp","title":"Leveraging clojure-lsp","text":"<p>Today, Calva draws a lot of its static power from clojure-lsp. As does a lot of other Clojure tooling out there. The Calva and the clojure-lsp teams work very nicely together, which is something we cherish and should take care to maintain.</p>"},{"location":"tao/#project-stewardship","title":"Project Stewardship","text":"<p>Here Calva takes inspiration from many Clojure related projects, and perhaps most so from CIDER,shadow-cljs, and clojure-lsp. Bozhidar Batsov, Thomas Heller, and Eric Dallo all lead their projects with clarity and with gusto. You can feel how they really care about their products and their users. They are there. They listen. They respond. And they relentlessly keep improving their products.</p> <p>So we are there. We listen. We respond. And we keep trying to improve Calva.</p> <p>The Calva team cares deeply about the user experience. That is a major part of why we do this. When implementing a new feature, or changing a feature, Ux is always the first thing on our mind. Personally, to keep that direction I often start with the documentation of the feature. Reading the documentation before implementation reveals a lot about if the Ux design is within the ballpark or not.</p> <p>We have limited time on our hands, however, and we must cut some corners. We can't afford to spend very much time in Ux design. Rather we will use our Ux intuition, iterate the documentation quickly, and be fast to get things out. Then we are responsive in tweaking those things, based on user feedback. This also has impact on general quality at times. We only can do so much QA, and it happens that some releases of Calva cause disruptions in people's workflow because of things we haven't thought of, or not found during our testing. Again, we try to be attentive to feedback and quick to fix. Apologies in advance for any inconveniences caused!</p> <p>A super major part of our love for Ux is that Calva should be serving its users. That's why we treat feedback as a gift, listen intently, and use the feedback as a major ingredient in shaping Calva.</p> <p>Calva develops from user feedback in more direct ways as well. It is quite astonishing how many people have decided to improve on it by hacking it to do some small or big thing differently. That's great! We should make sure Calva is super easy to contribute to. </p> <p>There has been quite a lot of work put into improving the development process. Starting to hack on Calva is just a few steps, taking less than three minutes from cloning to running a dev version in the VS Code debugger. We encourage contributions, from the tiniest typo to whole new features. And we are ready to spend time helping people get their contributions integrated.</p> <p>However, Calva can't be what everyone wants it to be, that would make it useless. It needs direction and aim. And it is we, the Calva Team, who are the stewards. We need to be in charge of what Calva is about, and what it is not about.</p>"},{"location":"tao/#the-road-ahead","title":"The Road Ahead","text":"<p>Tying back to Stuart Halloway, I don't think he means that spartan needs to also mean poor. The products he helps to bring to the market tell another story. VS Code and Clojure brought together has the capacity to create something amazingly rich and luxurious. And I want Calva to tap into that potential.</p> <p>On the Calva journey we will allow ourselves to change our minds about how things work. Calva is not a library. Its an interface between Clojure and human beings. Human beings can adapt. And they will need to enjoy adapting in order to enjoy Calva. \ud83d\ude04</p> <p>By now it should be clear that you can expect Calva to keep evolving, keep being tended and maintained, and keep getting ever more enjoyable to use. Lately we have been improving Calva pretty rapidly. It would be great to keep it up like that, but I think it is good to expect a more humble and sustainable pace.</p> <p>Calva is still quite new. A bit like freshly distilled Calvados. It will need time in those oak barrels to develop its full bouquet of flavors. And time is what we will give it. Our time, our creativity, and our passion.</p>"},{"location":"test-runner/","title":"Test Runner","text":"<p>Calva provides commands that make running your Clojure tests easier.</p> <p>Note</p> <p>Since the test commands utilize cider-nrepl, they only work with Clojure, not ClojureScript. See this issue for more details.</p>"},{"location":"test-runner/#test-commands","title":"Test Commands","text":"Command Shortcut Description Run All Tests <code>ctrl+alt+c shift+t</code> Runs all tests Run Failing Tests <code>ctrl+alt+c ctrl+t</code> Runs the tests that failed Run Tests for Current Namespace <code>ctrl+alt+c t</code> Runs the tests for the current namespace. If not a <code>-test</code> namespace, tests for the current namespace plus its corresponding <code>&lt;current-namespace&gt;-test</code> namespace will be run. Run Current Test <code>ctrl+alt+c ctrl+alt+t</code> Runs the test at the cursor. This includes a <code>defn</code> with a <code>:test</code> in its metadata, a <code>defn</code> defined in a <code>with-test</code>, and a <code>deftest</code>. Toggle between implementation and test - Switches the file between implementation and test, prompts to create a new file if not found."},{"location":"test-runner/#test-on-save","title":"Test on Save","text":"<p>You can enable the Calva setting \"Test on Save\" to have tests for the current namespace run on file save.</p>"},{"location":"test-runner/#vs-code-test-ui","title":"VS Code Test UI","text":"<p>Calva has experimental support for showing test results in VS Code's Test UI. You can enable this support by setting <code>calva.useTestExplorer</code> to <code>true</code>. When you enable this setting, the Testing icon will appear in the Testing tab of VS Code's Activity Bar.</p> <p>With this feature enabled you will be able to browse and run tests directly from the Testing tab.</p> <p>Please join the #calva channel on the Clojurians Slack if you have any feedback on this new feature.</p>"},{"location":"test-runner/#troubleshooting","title":"Troubleshooting","text":""},{"location":"test-runner/#tests-are-not-found","title":"Tests Are Not Found","text":"<p>Calva will not load namespaces in the REPL that you haven't loaded. This is so that you can be in control of what is loaded in the REPL. However, it also means that commands like Run All tests actually mean Run All Tests That are Loaded in the REPL, since the test-runner only runs tests that it knows about, i.e. are loaded in the REPL. Some developers choose to make sure all test namespaces are loaded as part of starting their REPL. Others register a custom REPL command for loading test namepaces. (Yet others use test-runners such as Cognitect's test-runner, Kaocha, poly test, or some other that runner allows for tests being run automatically, separate from the REPL used for development.)</p> <p>If you have tests in a test directory separate from your source directory, and those tests are not being found by the test runner, make sure the test directory is included in your paths. This will not be the case by default with a tools.deps (deps.edn) project. If your project is a tools.deps project, you can create an alias in your deps.edn file with <code>:extra-paths</code> that includes <code>\"test\"</code> (or the name of your test directory).</p> <pre><code>{:aliases {:dev {:extra-paths [\"test\"]}}}\n</code></pre>"},{"location":"test-runner/#changes-arent-taking-effect-when-running-tests","title":"Changes Aren't Taking Effect When Running Tests","text":"<p>In order for changes in code to take effect, you need to load the file or evaluate the changed code before running a test command. Prior to version 2.0.301, Calva would load the file for you when running some test commands, but that behavior was removed in favor of leaving control to the user, and to avoid a potential issue.</p> <p>Having added the above to your deps.edn, when you jack-in, choose the <code>:dev</code> alias and the <code>test</code> directory will be added to your paths, which will allow tests located in the directory to be found by the test runner.</p>"},{"location":"test-runner/#toggle-between-implementation-and-test-command-not-working-as-intended","title":"Toggle between implementation and test command not working as intended","text":"<p>This feature mostly works with projects that has leiningen style folder structure and makes some assumption about your folder structure and test file names.</p> <ul> <li>It assumes that the test files ends with <code>_test</code> prefix.</li> <li>It assumes that your implementation files are in <code>src</code> folder and the test files are in <code>test</code> folder.</li> </ul> <p>If you are using any non leiningen style folder structure, you may have to add source paths inside <code>.lsp/config.edn</code>.</p>"},{"location":"try-first/","title":"Something to Try First (After Connecting)","text":"<p>You should start with loading the file you are working with. Do this with Load/Evaluate Current File and its Requires/Dependencies, <code>ctrl+alt+c enter</code>.</p> <p>To get a feeling for evaluating code in the editor and get immediate response from the REPL try this:</p> <ul> <li>On a new line, type a <code>comment</code> form and put some code inside it:</li> </ul> <pre><code>(comment\n  (+ (* 2 2)\n      2)\n  (Math/abs -1)\n  (hello \"Calva REPL\")\n  (defn hello [s]\n    (str \"Hello \" s))\n  (range 10)\n  \"I \u2665\ufe0f Clojure\")\n</code></pre> <p>Then:</p> <ol> <li>Place the cursor behind the form <code>(* 2 2)</code> and issue the command Calva: Evaluate Current Form, <code>ctrl+enter</code>.<ul> <li>You should see the result being displayed inline. Press <code>esc</code> to dismiss it.</li> </ul> </li> <li>Now issue the command Evaluate Current Top Level Form (defun), <code>alt+enter</code>.<ul> <li>You should see the whole form <code>(+ (* 2 2) 2)</code> getting highlighted and the result of that expression being displayed inline.</li> </ul> </li> <li>Evaluate each form inside the comment form using the Top Level command.<ul> <li>You should see each one of them evaluated.</li> <li>Evaluating the <code>(hello \"Calva REPL\")</code> form before the <code>(defn hello...</code> form should result in an error/exception. A stacktrace is then printed in the output window</li> <li>Try it again after having evaluated the <code>defn</code>form.</li> </ul> </li> </ol> <p>Demo:</p> <p></p>"},{"location":"try-first/#how-does-this-work","title":"How does this work?","text":"<p>Calva has this notion about the current form. Issue the Evaluate Current Form command, with the cursor placed in different locations to get a feeling for how the current form is determined.</p> <p>There is also a concept about the current top level form. Good for evaluating  various <code>def</code>s <code>defn</code>, <code>defthis</code>, <code>defthat</code>. With your cursor placed anywhere inside such a form.</p> <p>The Top Level command also works inside <code>(comment ...)</code> forms, treating the <code>comment</code> as creating a new top level context. It is good for in-file code experimentation.</p>"},{"location":"try-first/#see-also","title":"See also","text":"<ul> <li>Calva Top 10 Commands.</li> <li>Code Evaluation Tips</li> </ul>"},{"location":"vim/","title":"Calva and the VIM Extension","text":"<p>First thing first. The VIM Extension and Calva has a history of friction between them. Less so these days, but you might still encounter some rough edges. Please don't hesitate to reach out to the Calva team, as we might be able to fix things if only we are aware of them.</p>"},{"location":"vim/#key-bindings","title":"Key bindings","text":"<p>In general Calva's default key bindings are not very VI-ish.</p>"},{"location":"vim/#expand-selection-on-mac","title":"Expand selection on Mac","text":"<p>On Mac, Calva binds expand selection to <code>ctrl+w</code>. This conflicts with the VIM Extension's default mapping of window splitting shortcuts. You'll need to remap it either with Calva or with the VIM Extension.</p>"},{"location":"vim/#the-esc-key","title":"The <code>esc</code> key","text":"<p>While showing inline evaluation results, Calva binds the <code>esc</code> key to dismiss the display of inline results. If you want to be able to use the <code>esc</code> key to enter command mode while inline results are showing, you'll need to rebind Calva's command for dismissing the inline results.</p>"},{"location":"vim/#remap-calvas-clearinlineresults","title":"Remap Calva's <code>clearInlineResults</code>","text":"<ul> <li>Open the Keyboard Shortcuts JSON file from the Command Palette</li> <li>Disable <code>clearInlineResults</code> and remap the command e.g.</li> </ul> <pre><code>// Place your key bindings in this file to override the defaults\n[\n  {\n    \"key\": \"escape\",\n    \"command\": \"-calva.clearInlineResults\"\n  },\n  {\n    \"key\": \"shift+escape\",\n    \"command\": \"calva.clearInlineResults\",\n    \"when\": \"editorTextFocus &amp;&amp; !editorHasMultipleSelections &amp;&amp; !editorReadOnly &amp;&amp; !hasOtherSuggestions &amp;&amp; !suggestWidgetVisible &amp;&amp; editorLangId == 'clojure'\"\n  }\n]\n</code></pre> <p>If you run into issues, refer to the commands in the default Keyboard Shortcuts JSON file.</p>"},{"location":"vim/#remap-vims-insert-mode","title":"Remap Vim's Insert Mode","text":"<p>Remap vim's insert mode keybinding to go into command mode by adding the following to your user settings:</p> <pre><code>\"vim.insertModeKeyBindings\": [\n    {\n        \"before\": [\"j\", \"k\"],\n        \"after\": [\"&lt;esc&gt;\"]\n    }\n]\n</code></pre> <p>(Change <code>before</code> to whatever keybinding you are comfortable with!)</p>"},{"location":"vim/#vim-fireplace-ish-keybindings","title":"Vim Fireplace-ish keybindings","text":"<p>You can add these keybindings to your <code>init.vim</code> if you are using the VSCode Neovim extension. It is inspired by and tries to emulate the keybindings found in vim-fireplace which is the most popular vim plugin for Clojure.</p> <pre><code>nmap cqp :call VSCodeNotify('calva.jackIn')&lt;CR&gt;\nnmap cqq :call VSCodeNotify('calva.disconnect')&lt;CR&gt;\nnmap cpr :call VSCodeNotify('calva.loadFile')&lt;CR&gt;\nnmap cpR :call VSCodeNotify('calva.loadNamespace')&lt;CR&gt;\nnmap cpp :call VSCodeNotify('calva.evaluateSelection')&lt;CR&gt;\nnmap cqc :call VSCodeNotify('calva.evalCurrentFormInREPLWindow')&lt;CR&gt;\n</code></pre> <p>Unfortunately these key combinations will not work in the normal VIM extension as <code>c</code> is an operator key and cannot be remapped. This is a call for someone to share their VIM re-mappings.</p>"},{"location":"when-clauses/","title":"Calva When Clause Contexts","text":"<p>When clause contexts is a powerful customization mechanism in VS Code. The most common use for end users is with keyboard shortcut bindings. Extensions can provide their own. The following contexts are available with Calva:</p> <ul> <li><code>calva:keybindingsEnabled</code>: a master switch that you find in the settings</li> <li><code>paredit:keyMap</code>: <code>strict</code>, <code>original</code>, or <code>none</code> from the corresponding Calva setting (see Paredit)</li> <li><code>calva:connected</code>: <code>true</code> when Calva is connected to a REPL (there is also <code>calva:connecting</code> || <code>calva:launching</code>)</li> <li><code>calva:outputWindowActive</code>: <code>true</code> when the Output/REPL window has input focus</li> <li><code>calva:replHistoryCommandsActive</code>: <code>true</code> when the cursor is in the Output/REPL window at the top level after the last prompt</li> <li><code>calva:replWindowSubmitOnEnter</code>: <code>true</code> when the cursor is adjacent after the last top level form in the Output/REPL window</li> <li><code>calva:cursorInString</code>: <code>true</code> when the cursor/caret is in a string or a regexp</li> <li><code>calva:cursorInComment</code>: <code>true</code> when the cursor is in, or adjacent to a line comment</li> <li><code>calva:cursorBeforeComment</code>: <code>true</code> when the cursor is adjacent before a line comment</li> <li><code>calva:cursorAfterComment</code>: <code>true</code> when the cursor is adjacent after a line comment</li> <li><code>calva:cursorAtStartOfLine</code>: <code>true</code> when the cursor is at the start of a line including any leading whitespace</li> <li><code>calva:cursorAtEndOfLine</code>: <code>true</code> when the cursor is at the end of a line including any trailing whitespace</li> </ul>"},{"location":"why-calva/","title":"Why Calva?","text":"<p>The main reason you would choose Calva for your Clojure and/or ClojureScript coding is that you want to use Visual Studio Code. Calva provides VS Code users with a comprehensive set of features to keep you productive and make it easy to follow Clojure coding best practices. This also means that if your choice of editor is not made yet, we think you should give VS Code and Calva a try.</p> <p>While Calva is a good choice for professional and experienced Clojure developers, great care has been taken in making Calva a really good choice for beginners of Clojure as well.</p> <p>We who make Calva are actively stewarding, maintaining, documenting and supporting it. We are also very active Clojure (and Calva) users, participating in the community. Clojure is dear to us, a lot because it keeps programming fun and rewarding.</p> <p>Calva has very happy users! Check out the Programming Languages section on the Visual Studio Code Marketplace, sorted by rating:</p> <p></p> <p>Recently there was a thread over at ClojureVerse, asking about how Calva Compares to Emacs with CIDER. It is well worth reading. We would like to highlight the answer by Nick Cernis, which focuses on Calva. We'll even quote parts of it. \ud83d\ude0d</p>"},{"location":"why-calva/#nick-cernis-on-clojureverse","title":"Nick Cernis on ClojureVerse","text":"<p>My advice to anyone starting their Clojure journey who is unsure about what editor to use:</p> <ul> <li>Pick something today and start writing Clojure.</li> <li>Probably pick an editor you are familiar with already.</li> <li>If you\u2019re not familiar with any editor yet or you don\u2019t have a strong allegiance to one, choose VS Code and Calva.</li> <li>Switch to something else only if you encounter persistent annoyances that you can\u2019t remove with plugins, code/config changes, help from the community, or more sleep.</li> </ul> <p>I now use VS Code with Calva every day but went through a long journey trying almost every other editor and plugin combo first. I switched from Emacs to VS Code, which might make my perspective different to others here.</p> <p>\u2026</p> <p>I started with the jaded assumption that VS Code was probably bad because it's built by committee at Microsoft on a web-tech based Electron stack, only to find that it succeeds in embodying the spirit of a \u201chacker's editor\u201d more than even Emacs does in many ways: </p> <p>\u2026</p> <p>On the benefits of Calva:</p> <ul> <li> <p>Of all the amazing Clojure community projects, Calva seems most likely to encourage new users to try Clojure and ClojureScript. A lot of developers use VS Code. It\u2019s been tricky to convince frontend developer friends to try ClojureScript, but at least they don\u2019t have the excuse that they\u2019ll need to switch editors to even try it now. I think as a community we should try to support the projects that encourage Clojure\u2019s adoption and ease of use, including by using those products ourselves.</p> </li> <li> <p>Calva provides a better first-time experience than any other editor/plugin combo whether you\u2019re new to Clojure or not. You can install the plugin and be chatting with your REPL in under a minute without any knowledge of Elisp or VimScript/Lua or how to configure Run Configurations in IntelliJ.</p> </li> <li>The default key bindings are good and the commands are easily discoverable.</li> <li>For its age it\u2019s surprisingly feature rich.</li> </ul>"},{"location":"why-calva/#100-five-star-marketplace-reviews","title":"100% Five-star Marketplace Reviews","text":"<p>We are super proud of the Calva reviews on the Visual Studio Code Marketplace. Please read them all. \ud83d\ude04 Here's a selection that we think captures what we focus on in when developing Calva:</p> <p>\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f Calva has become an essential part of my Clojure workflow.</p> <p>It's an incredible piece of work by the team behind it.</p> <p>Sean Corfield</p> <p>\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f Calva hits the sweet spot of being both approachable for new users and powerful for seasoned ones.</p> <p>The creators/maintainers are fantastic individuals that care deeply about streamlining the user experience, and it shows.</p> <p>Good stuff, check it out.</p> <p>Clay Hopperdietzel</p> <p>\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f I switched from IntelliJ / Cursive to VS Code and Calva and it's been amazing.</p> <p>...</p> <p>That is the biggest thing I can say for Calva, it just works. I was never a fan of VS Code before, but VS Code + Calva for Clojure is now my favorite language / IDE experience.</p> <p>Plus, the #calva on the clojurians slack is brilliant, always someone there to help if you have issues (although any issue I've had has been squarely on me, and never Calva itself).</p> <p>I often feel we live in an age where so much software is badly written, without care, slow, buggy and just generally awful. Calva is the complete opposite. I think the maintainers want to, and have, made a wonderful piece of software for Clojure developers.</p> <p>Stuart Stein</p> <p>\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f This is great, and makes VS Code a truly viable IDE/editor for clojure development.</p> <p>It already has great REPL support (including inline evaluation), an extensive Paredit implementation, and excellent linting (care of the bundled clj-kondo). Calva is being improved on at an impressive clip by maintainers who appear solidly committed to its ongoing development. It's well-documented, and manages to be both approachable and capable.</p> <p>A no-brainer if you're already a VS Code user, and well worth a look if you're not.</p> <p>Crispin Bennett</p> <p>\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f\u2605\ufe0f\ufe0f\ufe0f\ufe0f\ufe0f I'm using Calva now for a few months and I'm loving it.</p> <p>I joined the Slack channel about 2 wks ago and I must say that I'm very impressed by how active and responsive this community is. Already 2 of my issues fixed and I really like Calva (and the extensions it uses!).</p> <p>These are professional people and they make me very happy!</p> <p>Uitbeijerse, E (Eric)</p>"},{"location":"workspace-layouts/","title":"Workspace Layouts","text":"<p>Project directory layouts can vary quite a lot. From the \u201dtemplate\u201d projects where the Clojure project files are at the root, to, well, let's just say that the project files are not always at the root. And sometimes there is more than one project (read here how to get clojure-lsp support with a Leiningen project in a subfolder).</p> <p>Calva only really supports working with one project at a time per VS Code window. Here's a short guide for some different setups:</p> <ol> <li>You have one project in the workspace, the project files are in there somewhere.<ul> <li>Use a regular VS Code \u201dfolder window\u201d or a Workspace proper, both will totally work.</li> </ul> </li> <li>You have more than one project in the repository, but only really work with one at a tine.<ul> <li>Use a Workspace proper and add the different project directories as separate Workspace Folders.</li> <li>You can only jack-in/connect to one project at a time.</li> </ul> </li> <li>You have more than one project in the repository, and need to work with them in parallell.<ul> <li>Open each project you want to work with in a separate VS Code window.</li> </ul> </li> </ol>"},{"location":"workspace-layouts/#one-folder-two-windows","title":"One Folder - Two Windows?","text":"<p>As is mentioned in the Calva Jack-In Guide, if you have a full stack project using a Clojure backend and a shadow-cljs frontend, you will need to open the same project in two separate VS Code windows, one for the backend and one for the frontend. This is how you can do that:</p> <ol> <li>Open a new VS Code window.</li> <li>Select File-&gt;Add Folder to Workspace.... Save the workspace as, say, <code>Server.code-workspace</code>.</li> <li>Open a new VS Code window.</li> <li>Select File-&gt;Add Folder to Workspace.... Save the workspace as, say, <code>Client.code-workspace</code>.</li> </ol> <p>Now, whenever you want to Jack-in to the backend and/or frontend, do it from the Server and/or Client workspace, respectively.</p>"},{"location":"wsl/","title":"Calva \u2764\ufe0f WSL","text":"<p>The use of Calva with WSL (Windows Subsystem for Linux) is fully supported through the Remote - WSL extension. Simply install the extension and open your project with one of the <code>Remote-WSL</code> commands. Calva will run directly in the WSL environment and no further configuration is required.</p>"},{"location":"wsl/#steps-involved","title":"Steps Involved","text":"<ol> <li>Enable WSL</li> <li>Install Ubuntu in WSL</li> <li>Install Java in WSL</li> <li>Install latest Clojure in WSL</li> <li>Install the Remote - WSL extension in VS Code</li> <li>Launch remote window</li> <li>Install Calva (gets installed into the WSL instance)</li> <li>Work away</li> </ol> <p>See also Remote Development.</p>"}]}
\ No newline at end of file
diff --git a/sitemap.xml b/sitemap.xml
index 552be4dcd..e2c709ed1 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,302 +2,302 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://calva.io/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/api/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/async-out/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/babashka/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/clj-java-decompiler/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/clojure-lsp/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/clojuredart/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/clojuredocs/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/commands-top10/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/connect-sequences/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/connect/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/contribute/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/custom-commands/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/customizing-jack-in-and-connect/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/customizing/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/debugger/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/emacs-keybindings/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/eval-tips/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/evaluation/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/fiddle-files/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/finding-commands/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/formatting/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/get-started-with-clojure/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/getting-started/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/hiccup/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/jack-in-guide/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/joyride/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/krell/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/linting/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/live-share/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/luminus/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/merch/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/namespace-form-auto-creation/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/nbb/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/notebooks/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/nrepl_and_cider-nrepl/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/output/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/paredit/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/parinfer/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/polylith/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/pprint/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/quirks/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/re-frame-template/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/rebl/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/refactoring/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/remote-development/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/repl-window/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/reveal/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/rich-comments/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/shadow-cljs/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/sponsors/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/syntax-highlighting/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/tao/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/test-runner/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/try-first/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/vim/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/when-clauses/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/why-calva/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/workspace-layouts/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://calva.io/wsl/</loc>
-         <lastmod>2024-04-11</lastmod>
+         <lastmod>2024-04-15</lastmod>
          <changefreq>daily</changefreq>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 0778f58b3..359ce371e 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ