Merge branch dev into published

CHANGELOG.md

@@ -4,6 +4,9 @@ Changes to Calva.
 
 ## [Unreleased]
 
+## [2.0.197] - 2021-05-12
+- [Add command for evaluating enclosing form](https://github.com/BetterThanTomorrow/calva/issues/1176)
+
 ## [2.0.196] - 2021-05-10
 - Fix: [Forward slurp with closing paren after newline, breaks the structure](https://github.com/BetterThanTomorrow/calva/issues/1171)
 - [Pre-bind some keyboard shortcuts to custom REPL commands](https://github.com/BetterThanTomorrow/calva/issues/1173)

docs/site/custom-commands.md

@@ -18,6 +18,7 @@ There are also substitutions available, which will take elements from the curren
 * `$ns`: The namespace used for evaluating the command
 * `$selection`: The currently selected text
 * `$current-form`: The text of the [current form](eval-tips.md#current-form)
+* `$enclosing-form`: The text of the [current enclosing form](eval-tips.md#evaluate-enclosing-form)
 * `$top-level-form` The text of the [current top level form](eval-tips.md#current-top-level-form)
 * `$current-fn`: The sexpr/form at call position in the current list, e.g. `str` with `(defn foo [] (str "foo" "bar|"))`
 * `$top-level-defined-symbol`: The second symbol of the top level form, e.g. `foo` with `(defn foo [] (str "foo" "bar|"))`

docs/site/eval-tips.md

@@ -1,6 +1,6 @@
 # Code Evaluation Tips
 
-Calva tries to make it easy to evaluate code, supporting interactive development.
+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](getting-started.md) section.
 
 NB: _The below assumes you have read about [Finding Calva Commands and Shortcuts](finding-commands.md)._
 
@@ -20,12 +20,37 @@ These are important concepts in Calva in order for you to create your most effec
 
 ### Current Form
 
-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**, `ctrl+alt+c s`, 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).
-
 Default shortcut for evaluating the current form: `ctrl+enter`.
 
+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**, `ctrl+alt+c s`, 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:
+
+If text is selected, then that text
+
+If the cursor is ”in” a symbol, then that symbol
+```clojure
+foob|ar ; foobar
+```
+
+If the cursor is adjacent to a form (a symbol or a list of some kind), then that form
+```clojure
+(foo bar |(baz)) ; (baz)
+```
+
+If the cursor is between to forms, then the left side form
+```clojure
+(foo bar | (baz)) ; bar
+```
+
+If the cursor is before the first form of a line, then that form
+```clojure
+(foo
+ | bar (baz)) ; bar
+```
+
 ### Current Top-level Form
 
+Default shortcut for evaluating the current top level form: `alt+enter`.
+
 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 `def` and `defn` (and `defwhatever`) forms at the top level, but it can be any form not enclosed in any other form.
 
 An exception is the `comment` form. It will create a new top level context, so that any forms immediately inside a `(commment ...)` form will be considered top-level by Calva. This is to support a workflow where you
@@ -35,27 +60,34 @@ An exception is the `comment` form. It will create a new top level context, so t
 3. Put them to test with expressions inside a `comment` form.
 4. Repeat from *1.*, until the function does what you want it to do.
 
-Default shortcut for evaluating the current top level form: `alt+enter`.
-
 Here's a demo of the last repetition of such a workflow, for a simple implementation of the `abs` function:
 
 ![top-level-eval](images/howto/top-level-eval.gif)
 
 ### Evaluate to Cursor
 
-There is also a command for evaluating the text from the start of the current list to where the cursor is. Convenient for checking intermediate results in thread or `doto`, or similar pipelines. Assuming the cursor is right behind `:d` in this form:
+There is also a command for evaluating the text from the start of the current list to where the cursor is. Convenient for checking intermediate results in thread or `doto`, or similar pipelines. The cursor is right behind `:d` in this form:
 
 ```clojure
   (->> [1 1 2 3 5 8 13 21]
        (partition 2)
        (zipmap [:a :b :c :d])
-       :d => (12 21)
+       :d| ; => (12 21)
        (apply -)
        (Math/abs))
 ```
 
 The default shortcut for this command is `ctrl+alt+enter`.
 
+### Evaluate Enclosing Form
+
+The default keyboard shortcut for evaluating the current enclosing form (the list the cursor is in) is `ctrl+shift+enter`.
+
+```clojure
+(let [foo :bar]
+  (when false (str| foo))) ; => ":bar"
+```
+
 ### Copying the inline results
 
 There is a command called **Copy last evaluation results**, `ctrl+alt+c ctrl+c`.

docs/site/getting-started.md

@@ -16,9 +16,9 @@ If you are new to Calva, a good place to start is using the command **Fire up th
 
 It will open up a three files in a temporary directory, and start and connect a REPL. The files are:
 
-- `hello-repl.clj` – The basics of how to evaluate code in Calva
-- `hello-paredit.clj` - A super brief intro to Calva structural editing
-- `hello-clojure.clj` - The very basics of the Clojure language
+- `hello_repl.clj` – The basics of how to evaluate code in Calva
+- `hello_paredit.clj` - A super brief intro to Calva structural editing
+- `welcome_to_clojure.clj` - The very basics of the Clojure language
 
 ![Hello REPL](images/howto/hello-repl.png "hello-repl.clj")
 

docs/site/krell.md

@@ -14,7 +14,7 @@ Add this *REPL Connect Sequence* to your workspace `settings.json`:
             "name": "deps.edn + Krell",
             "projectType": "deps.edn",
             "cljsType": {
-                "connectCode": "(require '[clojure.edn :as edn] '[clojure.java.io :as io] '[cider.piggieback] '[krell.api :as krell] '[krell.repl]) (def config(edn/read-string(slurp(io/file \"build.edn\")))) (krell/build config) (apply cider.piggieback/cljs-repl (krell.repl/repl-env)(mapcat identity config))",
+                "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))",
                 "dependsOn": "User provided"
             }
         }