vim-iced

vim-iced itself and vim-sexp are the minimal requirements.

In addition, if there is one of follows, you can use interactive UI for selecting one from multiple candidates (e.g. selecting a ns which you’d like to add)

If anything is okay, ctrlp.vim is easy to install and stable.

Let’s create a sample project for quick start. Here Leiningen is used to create a project template.

We use iced command to launch REPL instead of lein command. This allows iced command to take care of all the additional libraries and REPL settings you need.

Open vim and execute IcedConnect command.

You succeeded to connect REPL if you see "Connected" message, so let’s execute the next command.

Do you see 15 as a result? If so, your vim has started working with Clojure’s REPL finally!

There are 3 main ranges to evaluation in vim-iced.

See the following figure for the concrete ranges.

If you enable default key mappings, following key mappings are available.

See help file for other default key mappings.

The evaluation result is echoed on command-line and displayed in a popup at the end of line. However, the displayed result is only the returned value, so for example, the contents output by println are not displayed.

The contents output to standard output are displayed on the Stdout buffer.

The highlight setting for popup can be modified by g:iced#eval#popup_highlight.

vim-iced also provides ways to evaluate forms by Vim’s mark. This feature is implemented by Conjure originally.

For example, when you have a mark m on any position, <Leader>eam will evaluate the outer list on the mark m from any position.

The evaluated result is yanked to numbered registers. Like vim’s behavior, iced shifts the previous result of register 1 into register 2, 2 into 3, and so forth.

If you have values you don’t want to store, See g:iced#eval#values_to_skip_storing_register.

When you specify a register like yank, <Plug>(iced_eval) operator will yank the result.

E.g. "x<Leader>ee will yank a result to register x.

If you’d like to define a custom mapping, try below.

There are times when you want to evaluate the contents of a function for confirmation.

It is tired to bind arguments separately, or to write function calls in the comment form every time.

This is where evaluating codes in context help you. There is a default key bindings to evaluate code in a context.

With this mapping, the context input will be required.

The context is clojure.core/let style. For example, the context s "iced" will be expanded to the following code.

See <Plug>(iced_eval_in_context) for more information.

Unresolved directive in evaluation.adoc - include::evaluation/spinner.adoc[]

vim-iced provides only omni completion. It is set to omnifunc for clojure filetype automatically by default.

Vim has a <C-x><C-o> key mapping for omni completion.

vim-iced itself does not provide any auto completion methods.

However, the following completion plugins are supported as external plugins.

There are two ways (explicit and implicit) to refer to a var’s docstring.

The explicit way is to execute one of the following commands.

The implicit way is the Auto Document feature. This feature will automatically display a one-line documentation string on the right of cursor line. This will be done by CursorMoved / CursorMovedI auto command and timer.

ClojureDocs is a community-powered documentation and examples repository for the Clojure programming language. Vim-iced can display ClojureDocs reference information for a provided search term or the symbol under the cursor. It opens a temporary window split which can be closed with IcedDocumentClose.

IcedSourceShow or IcedSourcePopupShow is useful when you would like to refer to the source code itself. The keyboard shortcuts will show the source code for the symbol under the cursor, the commands can be used to search for the source code of any symbol that’s provided.

Sometimes, it is useful to know how a function is used elsewhere. IcedUseCaseOpen command is for that.

IcedUseCaseOpen will open a separated buffer, and show the first usecase if it is found. When there are several usecases, IcedNextUseCase and IcedPrevUseCase commands switch the shown usecase.

vim-iced provides following commands to integrate with clojure.spec.

vim-iced provides following commands to integrate with clojure.java.javadoc.

vim-iced provides IcedDefJump command for jumping to definition.

It supports jumping to

Can also specify using split window, tab, or other ways to open target location.

If you jumped to a definition with above command, vim-iced add the current cursor position to Vim’s tag stack. So you can go back easily with <C-t>.

See also:

As you know, IcedMacroExpand1OuterList will show the result of expanding once.

In the separated buffer for expanding macro, you can use IcedMacroExpand1OuterList command and its <Leader>em key mapping again. This means you can expand the expanded macro additionally.

When tests are failed, vim-iced show error messages in Test buffer, and IcedTestBufferOpen command open the buffer.

vim-iced also set error positions to quickfix, and :cwindow command enables you to show this information. This is useful to jump each failed tests.

IcedTestUnderCursor is not just running a test under cursor.

If the var under cursor does not contain :test metadata and current namespace doesn’t end with "-test", vim-iced searches test vars in corresponding test namespace (c.f. Source and test) and run them. Target test vars should include original var name in its name.

There is also checking spec as one of the tests.

IcedTestSpecCheck command is useful to run clojure.spec.test.alpha/check for the function under cursor.

You can specify the number of tests as a command argument, or g:iced#test#spec_num_tests variable.

vim-iced basically requires nREPL with some middlewares. But in some case, you may need to use plain nREPL such as babashka.nrepl.

In this case, vim-iced provides simple test integration which has less functionality than cider-nrepl’s one.

To use this simple test integration, you don’t need to recognize whether your nREPL is plain or not. Following commands are also support simple test integration, so you just execute these commands as usual.

vim-iced also provides following sync commands.

These commands are useful for formatting on writing files. For example, add this to your confirguration to format the current file on write.

Add this to your confirguration to format the current form on write.

vim-iced also supports following (GraalVM powered) code formatting tools.

If you change g:iced_formatter option, vim-iced will use the tool to format code and calculate indent level.

vim-iced provides auto indentation, enabled by default.

The indent level is calculated by the set formatter, so cljfmt formatter which is used by default may lead slow down vim/nvim.

If you don’t use vim-iced’s auto indentation, you can disable it through the g:iced_enable_auto_indent variable.

vim-iced provides 2 commands for tracing function calls.

Traced result will be displayed in Stdout buffer.

If you have a big data structure and want to dig into it, browsing tapped values is useful.

When you evaluate (tap> YOUR_DATA), IcedBrowseTapped shows tapped values. Select the value you want to dig into, then browsing value start.

All tapped values are stored in memory. So if you would like to delete them, execute IcedClearTapped command.

Following commands are available.

If you don’t want to place a newline after the :require and :import tokens with IcedCleanNs command, Please see g:iced#refactor#insert_newline_after_require option.

Following commands are available.

Following commands are available.

Following commands are available.

This feature is disabled by default. To enable, set v:true to g:iced_enable_clj_kondo_analysis.

Analysis process is run at BufWritePost autocmd. Analyzed data is cached at g:iced_cache_directory, and used in followings:

iced command currently supports following tools.

To start CLJS REPL with Figwheel main, you need to specify build-id.

To start CLJS REPL with shadow-cljs, you need following steps.

If you would like to start CLJS REPL by hand, you can do it as follows.

For example, the skeleton when you open src/foo/bar.clj is as follows.

A skeleton for test file depends on the file extension.

At first, build a simple docker image for vim-iced.

Second, launch nREPL with a fixed port number.

Finally just connect with IcedConnect as usual.

When evaluating a form the output from Clojure’s standard output is sent to a dedicated buffer. Vim-iced provides the following commands to control it’s stdout buffer.

Test results will be outputted to dedicated buffer.

vim-iced provides following commands to control test buffer.

Test buffer is opened automatically when tests are failed. On the other hand, test buffer is closed automatically when test are succeeded.

So you don’t need to use the above command basically.

Documents will be shown to popup window by default. But you can show them to dedicated buffer to keep them displayed.

vim-iced provides following commands to control document buffer.

Some events on vim-iced can be hooked, and you can execute any processing.

g:iced#hook is the definition. This is a dictionary with hook event as a key, and the value is a dictionary or a list of dictionaries.

Another way, you can also use iced#hook#add function to add definitions.

g:iced#nrepl#path_translation is a option to define path translation rules.

In actual use, it is recommended to define the option in the project-specific configuration file by vim-localrc like follows.

The g:iced#palette option allows you to customize the command palette.

In actual use, it is recommended to define the option in the project-specific configuration file by vim-localrc like follows.

vim-submode is useful to repeat some commands such as IcedSlurp or IcedBarf.

If you’d like to connect to REPL automatically, define autocmd for VimEnter event.

It is recommended to define autocmd like follows in ftplugin directory.

If you don’t want to connect to REPL for project.clj, *.edn, or etc, skip connecting as below.

vim-iced provides default key mappings. Since vim-iced will verify the mapping existence, if you would like to overwrite some key mappings, you could do as follows.

By default vim-sexp's paredit mode is enabled. If you want to be able to add parentheses individually, you can disable that behavior by adding the following line to one of your startup files:

If you also want to turn off other vim-sexp key mappings for clojure files (and scheme, lisp, and timl files), add the following line to one of your startup files instead of the preceding one:

Then specify any vim-sexp key mappings that you want to keep by following the the instructions at :help sexp-explicit-mappings. Place the resulting code (including the augroup block) into a startup file.

If you are managing lifecycle of components with Stuart Sierra’s component, integrant or etc, following configurations are useful.

kaocha is full featured next gen Clojure test runner.

vim-iced has a external plugin named vim-iced-kaocha to integrate with kaocha.

You can try socket REPL connection as follows.

Another way, you can launch socket REPL with random empty port internally.

If you’d like to use nREPL server instead of Socket REPL, you use g:iced#repl#babashka_repl_type option.

pREPL connection is based on socket REPL connection in vim-iced.

You can try pREPL connection as follows.

Minimal configuration is useful for debugging. If you find an unexpected behavior, please try this configuration.

vim-iced uses vim-themis as a test runner.