BetterThanTomorrow · PEZ · Nov 8, 2021 · Nov 8, 2021 · Nov 8, 2021 · Nov 8, 2021
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -49,6 +49,7 @@
         "docmirror",
         "Docstring",
         "eckstein",
+        "eduarddyckman",
         "eldoc",
         "enablement",
         "enablements",
@@ -131,6 +132,7 @@
         "Sexp",
         "Sexpr",
         "Sexps",
+        "shaunlebron",
         "sivertsen",
         "stacktraces",
         "stian",

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,9 @@
 Changes to Calva.
 
 ## [Unreleased]
+- Re-enable, Experimental: [Add Parinfer Mode](https://github.com/BetterThanTomorrow/calva/issues/253)
+- Re-enable, Experimental: [Add option to keep text more fully formatted as you type](https://github.com/BetterThanTomorrow/calva/issues/1406)
+- Re-enable, [Remove `calva.fmt.formatAsYouType` option](https://github.com/BetterThanTomorrow/calva/issues/1407)
 
 ## [2.0.231] - 2021-12-14
 - Fix: [Calva randomly edits file while in Live Share](https://github.com/BetterThanTomorrow/calva/issues/1434)

diff --git a/docs/site/customizing.md b/docs/site/customizing.md
@@ -25,18 +25,19 @@ Calva sets some VS Code settings for all Clojure files. Some of these are needed
     "[clojure]": {
         "editor.wordSeparators": "\t ()\"':,;~@#$%^&{}[]`",
         "editor.autoClosingBrackets": "always",
+        "editor.autoClosingOvertype": "always",
         "editor.autoClosingQuotes": "always",
         "editor.formatOnType": true,
         "editor.autoIndent": "full",
         "editor.formatOnPaste": true,
         "files.trimTrailingWhitespace": false,
         "editor.matchBrackets": "never",
-        "editor.renderIndentGuides": false,
+        "editor.guides.indentation": false,
         "editor.parameterHints.enabled": false
     }
 ```
 
-!!! Note
+!!! Note "`editor.wordSeparators`"
     The above `editor.wordSeparators` setting establish Clojure word boundaries. E.g `-` is considered to be part of words. This affects what happens when double-clicking symbols and other things. If you want to include `-` or something else as a word boundary, just add it to the setting.
 
 ## Pretty Printing
@@ -45,34 +46,7 @@ Calva's pretty printing mode can be configured a bit. See [Pretty Printing](ppri
 
 ## Calva Highlight
 
-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.
-
-You are in charge of how brackets and comments are highlighted via the `calva.highlight.<setting>` settings:
-
-| Setting | Meaning | Example |
-| --- | ------- | ------- |
-| `enableBracketColors` | Enable rainbow colors |  `true` |
-| `rainbowIndentGuides` | Enable rainbow indent guides |  `true` |
-| `highlightActiveIndent` | Highlight the active indent guide |  `true` |
-| `bracketColors` | Which colors to use |  `["#000", "#999"]` |
-| `cycleBracketColors` | Whether same colors should be <br> reused for deeply nested brackets | `true` |
-| `misplacedBracketStyle` | Style of misplaced bracket | `{ "border": "2px solid #c33" }` |
-| `matchedBracketStyle` | Style of bracket pair highlight | `{"backgroundColor": "#E0E0E0"}` |
-| `ignoredFormStyle` | Style of `#_...` form | `{"textDecoration": "none; opacity: 0.5"}` |
-| `commentFormStyle` | Style of `(comment ...)` form | `{"fontStyle": "italic"}` |
-
-!!! Note "Calva disables the VS Code built-in indent guides"
-    The VS Code built-in settings `editor.renderIndentGuides` and `editor.highlightActiveIndent` do not have any effect, since the former is switched off by the **Clojure Defaults**, mentioned above. Use Calva Highlight's `rainbowIndentGuides` and `highlightActiveIndent` 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).
-
-!!! Note "VS Code bracket coloring vs Calva's"
-    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 ”over paint” in Clojure files, when enabled. These settings work nicely:
-
-    ```clojure
-    "calva.highlight.highlightActiveIndent": true,
-    "editor.bracketPairColorization.enabled": true,
-    ```
-
-    The `calva.highlight.bracketColors` setting can be used to harmonize the coloring between VS Code and Calva.
+See [Clojure Syntax Highlighting](highlight.md) for customization options.
 
 ## Automatic Parameter Hints Poppup
 

diff --git a/docs/site/formatting.md b/docs/site/formatting.md
@@ -19,9 +19,6 @@ With the default settings, Calva's formatting behaves like so:
 * formats the current form, _aligning map keys and values_, when you press `ctrl+alt+l`
 * formats `(comment ..)` forms special, see [rich comments](#rich-comments)
 
-!!! Tips
-    Calva has a command that will ”heal” the bracket structure if it is correctly indented. Yes, it is Parinfer behind the scenes. This command is default bound to `shift+tab` to form a nicely balanced pair with the `tab` formatting.
-
 Also: If you have **Format on Save** enabled in VS Code, it will be Calva doing the formatting for Clojure files.
 
 Calva's formatting is mostly about indenting, but it also (again, defaults):
@@ -35,6 +32,19 @@ Not a fan of some default setting? The formatter is quite configurable.
 
 ## Configuration
 
+There are settings for the general behaviour of Calva formatting as well as for configuring `cljfmt`, which is the formatting engine used.
+
+| Setting | Description | Default
+| ------- | ----------- | -------
+| `calva.fmt.newIndentEngine` | Fast indentation. When disabled, a full formatting will be done on the current enclosing form. | **true**
+| `calva.fmt.experimental.fullFormatOnType` | Experimental: Formats forms starting on the same line, forwards from the cursor as you enter or delete text. Also enabled as part of [Parinfer](parinfer.md) mode (`inferParensAsYouType`) | **false**
+| `calva.fmt.experimental.inferParensAsYouType` | Experimental: [Parinfer](parinfer.md) mode | **false**
+| `calva.fmt.keepCommentTrailParenOnOwnLine` | See [Rich Comments](rich-comments.md) | **true**
+
+Calva's auto-formatter will reformat forms that are directly affected by your edits, and it will automatically indent new lines to match your `cljfmt` indentation settings. See below.
+
+### cljfmt
+
 You configure Calva's formatting using [cljfmt's configuration EDN](https://github.com/weavejester/cljfmt#configuration). This means that you can adjust the above mentioned defaults, including the indenting.
 
 !!! Note

diff --git a/docs/site/highlight.md b/docs/site/highlight.md
@@ -0,0 +1,47 @@
+---
+title: Syntax Highlighting
+description: Calva takes care of your Clojure syntax highlighting, and then some.
+---
+
+# Calva Highlight
+
+Calva takes care of syntax highlighting, and also provides some features not available through VS Code's highlighting mechanism. These extras include Clojure aware rainbow parens and vertical guides, sane bracket matching, and comment form dimming/highlighting.
+
+1. Dimming of ignored forms (or whatever style you customize it to)
+2. Italics for `(comment ...)` forms (or your preferred highlight style)
+3. Colorize the tags/dispatches of tagged lists the same as the bracket color.
+4. Highlight matched brackets at the tag for a tagged list
+5. Option to display colorized indent guide for the active indent only
+
+<figure markdown>
+  ![Calva Highlight](images/calva-highlight.png)
+  <figcaption>The cursor is that light-blue bar before the `#:g` namespace tag. The corresponding brackets highlight and the cursor is marked as being inside the blue `#:b` map (by the blue vertical guide).</figcaption>
+</figure>
+
+You are in charge of how brackets and comments are highlighted via the `calva.highlight.<setting>` settings:
+
+| Setting | Meaning | Example |
+| --- | ------- | ------- |
+| `enableBracketColors` | Enable rainbow colors |  `true` |
+| `rainbowIndentGuides` | Enable rainbow indent guides |  `true` |
+| `highlightActiveIndent` | Highlight the active indent guide |  `true` |
+| `bracketColors` | Which colors to use |  `["#000", "#999"]` |
+| `cycleBracketColors` | Whether same colors should be <br> reused for deeply nested brackets | `true` |
+| `misplacedBracketStyle` | Style of misplaced bracket | `{ "border": "2px solid #c33" }` |
+| `matchedBracketStyle` | Style of bracket pair highlight | `{"backgroundColor": "#E0E0E0"}` |
+| `ignoredFormStyle` | Style of `#_...` form | `{"textDecoration": "none; opacity: 0.5"}` |
+| `commentFormStyle` | Style of `(comment ...)` form | `{"fontStyle": "italic"}` |
+
+!!! Note "Calva disables the VS Code built-in indent guides"
+    The VS Code built-in settings `editor.renderIndentGuides` and `editor.highlightActiveIndent` do not have any effect, since the former is switched off by the **Clojure Defaults**, mentioned above. Use Calva Highlight's `rainbowIndentGuides` and `highlightActiveIndent` 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).
+
+!!! Note "VS Code bracket coloring vs Calva's"
+    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 ”over paint” in Clojure files, when enabled. These settings work nicely:
+
+    ```clojure
+    "calva.highlight.highlightActiveIndent": true,
+    "editor.bracketPairColorization.enabled": true,
+    ```
+
+    The `calva.highlight.bracketColors` setting can be used to harmonize the coloring between VS Code and Calva.
+
diff --git a/docs/site/images/calva-highlight.png b/docs/site/images/calva-highlight.png
diff --git a/docs/site/images/calva-parinfer-and-format-forward-big.gif b/docs/site/images/calva-parinfer-and-format-forward-big.gif
diff --git a/docs/site/images/calva-parinfer-and-format-forward.gif b/docs/site/images/calva-parinfer-and-format-forward.gif
diff --git a/docs/site/index.md b/docs/site/index.md
@@ -7,7 +7,7 @@ description: Learn how to use Calva, an IDE bringing full Clojure and ClojureScr
 
 ![Calva Logo](https://raw.githubusercontent.com/BetterThanTomorrow/calva/dev/assets/calva-64h.png)
 
-[Calva](https://marketplace.visualstudio.com/items?itemName=betterthantomorrow.calva) is an integrated REPL powered environment for enjoyable and productive [Clojure](https://clojure.org) and [ClojureScript](https://clojurescript.org) development in [Visual Studio Code](https://code.visualstudio.com). It includes inline code evaluation, Paredit, code formatting, a test runner, syntax highlighting, [linting](linting.md), and more. [Calva is open source](https://github.com/BetterThanTomorrow/calva) and free to use.
+[Calva](https://marketplace.visualstudio.com/items?itemName=betterthantomorrow.calva) is an integrated REPL powered environment for enjoyable and productive [Clojure](https://clojure.org) and [ClojureScript](https://clojurescript.org) development in [Visual Studio Code](https://code.visualstudio.com). It includes inline code evaluation, [Paredit](paredit.md), [Parinfer](parinfer.md), [code formatting](formatting.md), a [test runner](test-runner.md), syntax highlighting, [linting](linting.md), and more. [Calva is open source](https://github.com/BetterThanTomorrow/calva) and free to use.
 
 ## Getting Started
 

diff --git a/docs/site/paredit.md b/docs/site/paredit.md
@@ -7,7 +7,7 @@ search:
 
 # Paredit – a Visual Guide
 
-Structural editing and navigation for Clojure.
+Structural editing and navigation for Clojure. Works great together with [Parinfer](parinfer.md).
 
 ## What is Paredit?
 
@@ -34,11 +34,12 @@ Indicator | Paredit Mode
 `(λ)`     | Cave Man (strict mode off)
  `λ`      | No default key bindings
 
-Toggle between Strict and Cave Man using: `ctrl+alt+p ctrl+alt+m`
+Strict mode also inserts matching brackets when you type an open bracket.
 
-### Prevent Unbalanced Closing Brackets
+Toggle between Strict and Cave Man using: `ctrl+alt+p ctrl+alt+m`
 
-There is also a setting, `calva.paredit.strictPreventUnmatchedClosingBracket`, that will help you to not enter unbalanced closing brackets into the code.
+!!! Note "Parinfer is strict mode"
+    When you are using Calva's [Parinfer](parinfer.md) mode, then this strictness is handled by Parinfer. It is recommended that you leave this setting on regardless.
 
 ## Commands
 
@@ -145,5 +146,11 @@ There are some context keys you can utilize to configure keyboard shortcuts with
 
 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 `!editorHasMultipleSelections` to the `when` 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 `when` clause. This is left out of Paredit's defaults to respect user preference, and ease of maintenance.
 
+## See also
+
+* [Parinfer](parinfer.md)
+* [Formatting](formatting.md)
+
+## Cheering-ons
 
 Happy Editing! ❤️
diff --git a/docs/site/parinfer.md b/docs/site/parinfer.md
@@ -1,18 +1,114 @@
 ---
 title: Parinfer
-description: Yes, you can use Calva with with the Parinfer extension
+description: Learn how to leverage Calva Parinfer Mode for structural editing 
 ---
 
-# Using Calva with Parinfer
+# Calva Parinfer Mode
 
-Yes, you can use Calva with with the Parinfer extension. The only conflict here is that Calva's auto-formatting (that which happens as you type) is going to risk clash with Parinfer's.
+[Parinfer](https://shaunlebron.github.io/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.
 
-However, Calva's [Paredit](paredit.md) is carefully crafted. If you don't already have an established preference for parinfer, we suggest you give it a try. Even parinfer veterans may find they prefer the explicit nature of paredit. It takes only some few minutes to learn two or three basic Paredit commands:
+!!! Note "Experimental"
+    This feature is currently disabled by default and should be considered experimental. There are known [quirks](#quirks). Especially beginners should take note. Parinfer is not as beginner friendly as it might seem, and with the quirks it might be extra ”dangerous”.
 
-* **Select form**
-* **Slurp**
-* **Barf**
+## Infer Parens
 
-Also, if you find yourself having deleted or added a bracket out of structure, despite Calva Paredit's **Strict mode** (which you are using, right?) there is a command that might help you heal the structure: **Infer Parens from Indentation**. That command is actually implemented using the Parinfer library, so it will let you recover from quite many situations. This command is bound to `shift+tab` by default, making it a good companion to `tab` which indents based on bracket structure. 
+When you enable Calva's Parinfer it is all about infering brackets from indentation. There are no modes further Parinfer modes. Calva's auto-formatter will take care of keeping the code correctly indented.
 
-All that said, what was said first is true: if you want to use the Parinfer extension, you can. You'll probably want to disable Calva's auto-formatting. The setting for controlling this is named `calva.fmt.formatAsYouType`.
+Enable it with from this setting: `calva.fmt.experimental.inferParensAsYouType` or from the status bar item.
+
+### Parinfer Status bar items
+
+To the right on the status bar, right before the [Paredit](paredit.md) status bar item, you will have two items, Parinfer toggle ON/OFF and a health indicator.
+
+1. Parinfer **ON**/**OFF** indicator/button. <kbd>•()</kbd> (The dot/circle indicates **ON**/**OFF**)
+2. Structure and indentation health indicator. <kbd>✔️</kbd>/<kbd>⚠</kbd>/<kbd>⊘</kbd>
+
+When Parinfer is **ON**, the health indicator will have three states:
+
+1. <kbd>✔️</kbd> Healthy - meaning both structure and indentation is OK
+2. <kbd>⊘</kbd> Structure broken - you need to fix the the structure of the code
+3. <kbd>⚠</kbd> 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.
+
+Parinfer will be disabled in both the unhealthy states.
+
+When Parinfer is OFF, only the first two states above are used.
+
+## Some VS Code Settings automatically changed
+
+In order for some automatic VS Code behaviour not to interfere with Parinfer the following settings are automatically configured when you toggle Parinfer ON:
+
+```json
+    "[clojure]": {
+        "editor.autoClosingBrackets": "never",
+        "editor.autoClosingOvertype": "never",
+        "editor.formatOnPaste": false
+    },
+```
+
+And when you toggle Parinfer OFF:
+
+```json
+    "[clojure]": {
+        "editor.autoClosingBrackets": "always",
+        "editor.autoClosingOvertype": "always",
+        "editor.formatOnPaste": true
+    },
+```
+
+It is recommended that you let Calva handle these settings to avoid weird behaviour.
+
+## No Tab indenting
+
+As the `tab` key is used for formatting the current form in Calva, it is ”taken”. The closest equivalents you have are `space` and `backspace`. At least for now. We'll see if we can find out a good way for supporting `tab` and `shift+tab` for indent and dedent.
+
+`tab` 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.
+
+## Paredit is still there
+
+In Calva, Parinfer and [Paredit](paredit.md) 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.
+
+## Disable the Parinfer Extension
+
+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._
+
+## Quirks
+
+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.
+
+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.
+
+### No multi-cursor support
+
+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.
+
+### Wrong inferences
+
+For yet unknown reasons an edit such as the following does the wrong thing (the cursor indicated by the vertical bar):
+
+```clojure
+(foo| (bar)
+      (baz))
+```
+
+<kbd>backspace</kbd> => 
+
+```clojure
+(fo| (bar
+      (baz)))
+```
+
+That is `(baz)` is slurped. When what should happen is:
+
+```clojure
+(fo| (bar)
+     (baz))
+```
+
+### Lag causing errors when fast typing
+
+the way that Calva Parinfer works is that at eny edit of the document it first re-formats 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.
+
+## See also
+
+* [Paredit](paredit.md)
+* [Formatting](formatting.md)