Add evaluate enclosing form

CHANGELOG.md

@@ -3,6 +3,7 @@
 Changes to Calva.
 
 ## [Unreleased]
+- [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)

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`.