Skip to content

Customizing Calva#

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 settings.json. And VS Code's built-in json extension is awesome. To add settings for Calva's Pretty Printing, for example, search for ”prettyprint” in VS Code Settings and follow the link to settings.json. Start typing ”calvapretty” until auto-complete suggests calva.prettyPrintingOptions. Press ENTER and VS Code will fill in these defaults:

    "calva.prettyPrintingOptions": {
        "enabled": true,
        "printEngine": "pprint",
        "width": 40
    },

Refresh namespaces#

You can add before and after functions to the commands for refreshing the namespace. Goof for e.g. in the reloaded workflow. The settings are calva.refreshNssBeforeFn and calva.refreshNssAfterFn. Both are strings respresenting a fully qualified function. They correspond to the :before and :after parameters to the cider-nrepl refresh ops: https://docs.cider.mx/cider-nrepl/nrepl-api/ops.html#refresh

Clojure Defaults#

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 settings.json and accept the snippet help you get when you type "[clojure]", you will get the Calva defaults pasted:

      "[clojure]": {
        "editor.wordSeparators": "\t ()\"':,;~@#$%^&{}[]`",
        "editor.autoClosingBrackets": "always",
        "editor.autoClosingOvertype": "always",
        "editor.autoClosingQuotes": "always",
        "editor.formatOnType": true,
        "editor.autoIndent": "full",
        "editor.formatOnPaste": true,
        "editor.matchBrackets": "never",
        "editor.guides.indentation": false,
        "editor.parameterHints.enabled": false,
        "editor.unicodeHighlight.allowedCharacters": {
          " ": true,
          "꞉": true
        },
        "editor.foldingStrategy": "indentation"
      }

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.

editor.foldingStrategy

To use the folding levels provided by clojure-lsp, set this to auto. Though at the time of this writing there is a bug in clojure-lsp making folding stop working with this setting.

Pretty Printing#

Calva's pretty printing mode can be configured a bit. See Pretty Printing.

Calva Highlight#

This is highly customizable. See Syntax highlighting

Color customizations#

Calva defines a set of themable colors which can be provided by the user using workbench.colorCustomizations.

    "workbench.colorCustomizations": {
        "calva.inlineErrorForegroundColor": "#ff0000",
        "calva.inlineForegroundColor": "#ff9000"
    }

image

Automatic Parameter Hints Poppup#

Calva has helpful parameter hints to aid when typing function calls. They look like so:

image

To have the hints automatically pop up when you are typing, set editor.parameterHints.enabled to true in the above [clojure] scoped setting. (To call them up on demand the default VS Code keybindings are cmd+shift+space on Mac and ctrl+shift+space on Linux/Windows.)

Code Formatting#

See Formatting for information on how to configure this.

Jack-in and Connect#

Jack-in and Connect are very customizable through Custom Connect Sequences.

See also Customizing Jack-in and Connect

Key bindings#

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.

When Clause Contexts#

The following contexts are available with Calva:

  • calva:keybindingsEnabled: a master switch that you find in the settings
  • paredit:keyMap: strict, original, or none from the corresponding Calva setting (see Paredit)
  • calva:connected: true when Calva is connected to a REPL (there is also calva:connecting || calva:launching)
  • calva:outputWindowActive: true when the Output/REPL window has input focus
  • calva:replHistoryCommandsActive: true when the cursor is in the Output/REPL window at the top level after the last prompt
  • calva:replWindowSubmitOnEnter: true when the cursor is adjacent after the last top level form in the Output/REPL window
  • calva:cursorInString: true when the cursor/caret is in a string or a regexp
  • calva:cursorInComment: true when the cursor is in, or adjacent to a line comment
  • calva:cursorBeforeComment: true when the cursor is adjacent before a line comment
  • calva:cursorAfterComment: true when the cursor is adjacent after a line comment
  • calva:cursorInWhitespaceAfterComment: true when the cursor is in whitespace after a line comment
  • calva:cursorAtStartOfLine: true when the cursor is at the start of a line including any leading whitespace
  • calva:cursorAtEndOfLine: true when the cursor is at the end of a line including any trailing whitespace

Some Custom Bindings#

Here is a collection of custom keybindings from here and there.

Are you a vim extension user? See: Using with VIM extension.

Move by word#

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.

If you want the VS Code default word movement shortcuts, use these settings:

    {
        "key": "ctrl+right",
        "win": "ctrl+right",
        "mac": "alt+right",
        "command": "cursorWordRight"
    },
    {
        "key": "ctrl+left",
        "win": "ctrl+left",
        "mac": "alt+left",
        "command": "cursorWordLeft"
    },
    {
        "key": "ctrl+right",
        "mac": "ctrl+right",
        "win": "alt+right",
        "command": "paredit.forwardSexp",
        "when": "calva:keybindingsEnabled && editorTextFocus && editorLangId == 'clojure' && paredit:keyMap =~ /original|strict/"
    },
    {
        "key": "ctrl+left",
        "mac": "ctrl+left",
        "win": "alt+left",
        "command": "paredit.backwardSexp",
        "when": "calva:keybindingsEnabled && editorTextFocus && editorLangId == 'clojure' && paredit:keyMap =~ /original|strict/"
    }

Use it as an inspiration for customizing things to your own liking. 😄

Wrap using (, [, { (like Cursive)#

Something I use in IntelliJ/Cursive is the ability to select an expression and hit one of (, [, { to wrap it. And after wrapping the expression I don't want the selection anymore, so if I were wrapping (foo) then I would want to get ( | (foo)) where | would be my cursor.

Here's how you can make this work with Calva Paredit: Update all of the Paredit: Wrap Around ... commands so that their respective shortcuts are the wrappers themselves and update the when clause to include editorHasSelection (otherwise when you open a paren the next expression would get slurped in).

The change would look like this in your keybindings.json:

    {
        "key": "shift+9",
        "command": "paredit.wrapAroundParens",
        "when": "editorTextFocus && editorHasSelection && !editorReadOnly && editorLangId =~ /clojure|scheme|lisp/ && paredit:keyMap =~ /original|strict/"
    },
    {
        "key": "[",
        "command": "paredit.wrapAroundSquare",
        "when": "editorHasSelection && editorTextFocus && !editorReadOnly && editorLangId =~ /clojure|scheme|lisp/ && paredit:keyMap =~ /original|strict/"
    },
    {
        "key": "shift+[",
        "command": "paredit.wrapAroundCurly",
        "when": "editorHasSelection && editorTextFocus && !editorReadOnly && editorLangId =~ /clojure|scheme|lisp/ && paredit:keyMap =~ /original|strict/"
    }