Fifteen years ago, writing Lisp code in Vim was an odd adventure. There were no good plugins for Vim that assisted in structured editing of Lisp s-expressions or allowed interactive programming by embedding a Lisp Read-Eval-Print-Loop (REPL) or a debugger within the editor. The situation has improved a lot since then. In the last ten years, we have seen active development of two Vim plugins named Slimv and Vlime. Slimv is over 10 years old now. Vlime is more recent and less than 3 years old right now. Both support interactive programming in Lisp.
I am going to discuss and compare both Slimv and Vlime in this article. I will show how to get started with both plugins and introduce some of their basic features. I will not cover everything though. This is not a tutorial. For tutorials, see the References section.
Before we get started with Slimv and Vlime, it would be nice to take a brief look at the heritage behind these plugins. These plugins provide Lisp development environments for Vim, so their story begins with Lisp.
Lisp
Lisp is a family of programming languages with a distinctive, fully parenthesised prefix notation. It is quite unlike most of the other popular programming languages today like C, Python, Ruby, etc. Its homoiconic nature and its powerful macro system that can transform arbitrary Lisp expressions make it such a flexible, versatile, extensible and introspective language that articles describing Lisp often have the word "enlightenment" in them. For example, see the following articles:
Lisp has been described in various ways by various eminent personalities in the history of computing. Alan Kay has famously described Lisp as:
The greatest single programming language ever designed.
John Foderaro has written this about Lisp:
Lisp is a programmable programming language.
Eric S. Raymond has expressed the enlightenment one experiences by learning Lisp in his famous article titled How To Become A Hacker:
Lisp is worth learning for the profound enlightenment experience you will have when you finally get it. That experience will make you a better programmer for the rest of your days, even if you never actually use Lisp itself a lot.
Randall Munroe, the creator of the XKCD webcomic has dedicated two comic strips to Lisp:
Developed in 1958 by John McCarthy, Lisp is the second oldest programming language in use today. Only Fortran is older, by one year. Some of the popular Lisp dialects today include Common Lisp, Scheme and Clojure. Most of this article would focus on Common Lisp. Scheme and Clojure would be discussed briefly towards the end of this article.
Emacs: SLIME
Many Lisp programmers immediately think of Emacs when they think of writing Lisp code. Emacs is a family of text editors. An Emacs editor itself is typically implemented in a dialect of Lisp. There is an Emacs mode named SLIME that provides excellent support for programming in Lisp. SLIME stands for Superior Lisp Interaction Mode for Emacs. First released in August 2003, SLIME was created by Eric Marsden and then later developed further by Luke Gorrie and Helmut Eller. It offers a Read-Eval-Print-Loop (REPL), integrated debugging and interactive evaluation of expressions, all available right within the editor. There are several nifty key bindings available to compile and evaluate parts or whole of the code in the current buffer.
SLIME works by launching a Swank TCP server. Swank is a backend server program written in Common Lisp that listens on a socket to receive SLIME commands from Emacs and execute them. SLIME is so useful that it is considered to be indispensible by many Lisp programmers who write Lisp code in Emacs.
Vim: Slimv/Vlime
Is there anything similar to SLIME for Vim? Yes, there are two popular options:
Slimv: It stands for Superior Lisp Interaction Mode for Vim. It is a Vim plugin created by Tamas Kovacs that was first released in January 2009.
Vlime: It is a Vim plugin created by Kay Z that was first released in May 2017. It is much more recent than Slimv. Vlime is younger than Slimv by eight years.
Both plugins use a client-server architecture like SLIME does in Emacs. Both plugins rely on Swank server to be started. In fact, Slimv bundles a slightly modified version of Swank with it, so that it can launch it and connect to it to send expressions to be evaluated. Vlime does not bundle Swank server with itself but it provides a wrapper that automatically downloads Swank server when needed.
Vim Plugin Management
When I started using Vim fifteen years ago, we used to just download a Vim plugin and copy/extract it to ~/.vim directory. These days, there are a few plugin management tools for Vim such as Pathogen, Vundle, vim-plug, etc. I am not going to use any of them because I don't know which one of them you use and I don't want to write down steps for each one of them.
In fact, I have never used any Vim plugin manager myself. Until Vim 7, I used to create a ~/.vim/bundle directory, then copy each plugin to its own directory within it and add the plugin's directory path to Vim's runtimepath option.
Vim 8 has native support for packages which makes installing plugins and loading them simpler. With Vim 8, we can copy each plugin to its own directory within ~/.vim/pack/plugins/start and they are loaded automatically when Vim starts. The directory name plugins in this path is only an example. It could be any arbitrary name and Vim would still load the plugins fine.
In this article, I will use Vim 8's native support for packages to set up Vim plugins. The only exception to this would be installing Vlime. The top-level directory of Vlime is not the plugin directory. The plugin directory is contained in a subdirectory named vim. This does not conform to the directory structure of plugins in a Vim package. Therefore, in this article, I will set up Vlime in the old fashioned way by copying it to ~/.vim/bundle and then adding the path to its plugin directory to Vim's runtimepath option.
Software Versions
Since this article involves several layers of software, some of what is written here may not hold good in future as these various pieces of software change and evolve over time. Therefore, in this section, I will note down the versions of various software tools I used while writing this article. Here they are:
Debian GNU/Linux 10.1 (buster)
Vim 8.1
Slimv (Git repo last updated on 30 Nov 2019 with commit 47a0070)
Vlime (Git repo last updated on 16 Oct 2017 with commit 065b95f)
Paredit (Git repo last updated on 30 Nov 2019 with commit d99905a)
Rainbow Parentheses (Git repo last updated on 29 Oct 2015 with commit 27e7cd7)
SBCL 1.4.16.debian
GNU CLISP 2.49.92
ECL 16.1.3
MIT/GNU Scheme 9.1.1 on Debian GNU/Linux 9.11 (stretch)
Clojure 1.10.1
Quicklisp beta (libraries last updated on 30 Nov 2019)
tmux 2.8
You will probably need only a tiny subset of the tools above depending on which sections in this article you would follow. Just pick the sections you want to try out and follow the steps written in them. They will walk you through the procedure to install the tools applicable to the sections you have picked. Regardless of which sections you pick, I recommend that you definitely go through the three "Get Started" subsections below. These subsections go into detail about some of the prerequisites such as support for tmux, Paredit, support for Python interface in Vim, etc. that are not covered in the other sections.
The choice of Debian may look like an odd one. I want the commands and steps discussed in this article to be easily reproducible in a free and open source operating system. Debian happens to be my favourite. What works on Debian is easily reproducible on Ubuntu and other derivatives, often without any changes to the steps. I believe, it will not be too difficult to translate the steps provided for Debian to the steps that would work on another operating system.
Note that Quicklisp (a prerequisite for Vlime) is still beta software at the time of writing this article. The actual steps to install Quicklisp may change in future. Check https://www.quicklisp.org/ for the most up-to-date instructions to install Quicklisp.
Get Started
Get Started with Slimv and SBCL
Here are the steps to set up Slimv and use it:
Install the tools required to set up a Common Lisp development environment with Slimv with this command:
sudo apt-get install vim-nox sbcl tmux git
The default Vim in Debian is vim.basic provided by the vim package which does not have support for Python interface. Slimv is written in Vim script, Lisp and Python 3, so it does need a Vim package that has support for Python interface. One such package is vim-nox that provides the vim.nox command. Installing it automatically updates the vim command to run vim.nox. Another such package is vim-gtk which additionally provides GUI support. The graphical Vim known as GVim can be launched with the gvim command. It runs in the desktop environment. For the purpose of this article, I will stick to vim-nox because it is lightweight. All steps meant for Slimv would run equally well on vim-gtk, MacVim and GVim.
Installing tmux is optional. Slimv can launch Swank server automatically if Vim is running within tmux, GNU Screen or a desktop environment, so if you are using GNU Screen already, you don't need to install tmux. Also, if you are running Slimv in a desktop environment, you don't really need to install either tmux or GNU Screen, although you could if you would like to see Swank running in a separate tmux or GNU Screen window rather than a separate terminal window. In this article, I am going to assume that Vim is running within tmux.
If you are going to run Slimv in a terminal without a desktop environment, tmux or GNU Screen, Swank server has to be run manually. Point 4 below explains how to do it.
Installing Slimv is pretty simple. Here is one way to do it:
git clone https://github.com/kovisoft/slimv.git ~/.vim/pack/plugins/start/slimv
vim +'helptags ~/.vim/pack/plugins/start/slimv/doc' +q
That is it! Slimv is set up. It's that straightforward. The commands above show how to set up Slimv with just two shell commands. You could also use a Vim plugin manager to install Slimv for you but I am not going to cover that here.
This is an optional step. Slimv supports starting Swank server automatically if you are running Vim in tmux, GNU Screen or a desktop environment. To start tmux, enter this command:
tmux
If you use GNU screen or a desktop environment, you don't have to run tmux.
If you do not use tmux, GNU Screen or a desktop environment, then you must start Swank server manually as explained in the next point.
This step is necessary only if you are not using tmux, GNU Screen or a desktop environment. The following command shows how to start Swank server manually:
If you are using tmux, GNU Screen or a desktop environment, Slimv can start Swank server automatically when needed and you don't need to perform this step.
Create a new Lisp source code file, say, foo.lisp with this command:
vim foo.lisp
To connect to Swank server, enter the following command in normal mode:
,c
If Vim is running within tmux, GNU Screen or desktop environment, Slimv would automatically launch Swank server and connect to it.
After Slimv connects to Swank successfully, Vim window should split into two and the following prompt should appear in the new split window:
CL-USER>
This is the integrated REPL. It is now alive and ready for interactive programming.
We assume here that Slimv is using the default Slimv leader key ,. If you have overridden the Vim leader key, then the Slimv leader key might be same as the Vim leader key. Enter the command :echo g:slimv_leader in Vim command-line mode to find the leader key being used by Slimv.
Type some code into the buffer for the new file. To do so, first type i to enter insert mode and type this code:
(format t "hello, world~%")
Type esc to return to normal mode.
To evaluate the current expression under the cursor, enter the following command in normal mode:
,e
Both the current expression and its result should appear in the REPL window.
The REPL is interactive. Type ctrl+ww to switch to the REPL window. Then type i to enter insert mode and type this code:
(+ 1 2)
Type enter to evaluate the expression just like you would do in a real REPL. The result should then appear in the REPL.
Type esc to return to normal mode again. Use the normal mode command ctrl + w w to switch between the split windows.
Now that you have got started with Slimv, here is a brief note on uninstallation, in case you ever need it. If Slimv is installed as described in point 2 above, enter the following command to uninstall it:
rm -rf ~/.vim/pack/plugins/start/slimv
In steps 7 and 9, you may have noticed that as soon as you type an opening parenthesis or double quotation mark, a matching closing one is automatically inserted. That is done by the Paredit plugin which is bundled along with Slimv. Paredit ensures structured editing of Lisp s-expressions and keeps all matched characters (parentheses, brackets, braces, quotes) balanced. It also provides many new keybindings to edit s-expressions conveniently. We will look into Paredit in a little more detail in the Get Started with Paredit subsection later.
Get Started with Vlime and SBCL
Here are the steps to set up Vlime and use it:
Install the tools required to set up a Common Lisp development environment with Vlime with this command:
sudo apt-get install vim sbcl git curl
Note that unlike Slimv, Vlime can work with the default Vim in Debian, i.e. vim.basic. Vlime does not require Vim with Python interface.
Unlike Slimv, Vlime does not bundle Paredit along with itself. As explained in the previous section, it helps us with structured editing of Lisp s-expressions.
I recommend that you install Paredit but in case you choose not to, ensure that loading of filetype plugins is enabled by entering the :filetype command in command-line mode. The output should contain plugin:ON. If it is off, add the command filetype plugin on to ~/.vimrc to ensure that this is always on. Vlime won't work without this being enabled. If you install Paredit, you don't have to bother about this because Paredit takes care of enabling this by default.
Create a new Lisp source code file, say, foo.lisp with this command:
vim foo.lisp
To start Vlime server (a wrapper around Swank server) and connect to it automatically, enter the following command in normal mode:
\rr
We assume here that Vim <LocalLeader> is left to its default, i.e. backslash. If it is mapped to some other key combination, then that must be used instead of backslash in the above command.
The first time this command is run after installing Vlime, it installs Swank server using Quicklisp. Therefore, it can take a while for Vlime server to start the first time this command is run. On subsequent use of these commands, it would start faster because it would be already installed.
The console output from Vlime server is displayed in a split window. After Vlime successfully connects to Swank, the following message is displayed at the bottom:
Vlime Connection 1 established.
After the above message appears, it is okay to close the split window for Vlime server by entering this command in Vim command-line mode:
:q
Vlime server would continue to run in background. The following command can be used in normal mode to view the console output of Vlime server anytime it is required:
\rv
Type some code into the buffer for the new file. To do so, first type i to enter insert mode and type this code:
(format t "hello, world~%")
Type esc to return to normal mode.
To evaluate, the current expression under the cursor, enter the following command in normal mode:
\ss
Both the current expression and its result should appear in the REPL window.
Unlike Slimv, the REPL window of Vlime is not interactive. Its nomodifiable option is set, so we cannot type code directly into the REPL window. This can be a bit of a problem if we want to type arbitrary expressions into the REPL and execute them. To mitigate this shortcoming to some extent, Vlime provides an alternative way to evaluate the current expression known as the interaction mode. This is explained in the next point.
Enable interaction mode by entering this command in normal mode:
\i
The same command disables interaction mode, i.e. this command toggles the state of interaction mode between on and off. When interaction mode is on, evaluate an expression under the cursor by simply pressing enter in normal mode.
Now that you have got started with Vlime, here is a brief note on uninstallation, in case you ever need it. If Quicklisp and Vlime are installed as described in the points 2 and 3 above, run these commands to uninstall them:
rm -rf ~/quicklisp ~/.vim/bundle/vlime ~/.vim/pack/plugins/start/paredit
sed -i.bkp '/runtimepath.*vlime/d' ~/.vimrc
Optionally, remove ~/.sblrc or edit it to remove the code pertaining to loading quicklisp/setup.lisp.
Get Started with Paredit
You have already got started with Paredit when you wrote Lisp code while following one of the previous two subsections. The moment you typed an opening parenthesis, Paredit inserted a closing one for you automatically. Paredit keeps all matched characters such as parentheses, double quotes, etc. balanced when you edit code. Here is a very brief exercise to quickly get started with some of the very basic features of Paredit:
Create a new Lisp source code file, say, foo.lisp with this command:
vim foo.lisp
Type i to enter insert mode and then type only this:
(defun square (x
At this point, Paredit should have inserted the two closing parentheses automatically. The code should look like this:
(defun square (x))
The cursor should be situated just after the parameter x. The block above shows where the cursor should be.
While you are still in insert mode, type the first closing parenthesis. Yes, type it even if the closing parenthesis is already present. The cursor should now skip over the first closing parenthesis like this:
(defun square (x))
Of course, there was no need to type the closing parenthesis because it was already present but typing it out to skip over it is more efficient than escaping to normal mode, then moving over it and then entering insert mode again. This is, in fact, a very nifty feature of Paredit. We can enter code with the same keystrokes as we would without Paredit.
You should still be in insert mode. Type enter to create a new line below. Now one of two things is going to happen. If electric return is disabled, then a newline is inserted as expected like this:
(defun square (x))
)
If electric return is enabled, two newlines are inserted to create an empty line in between:
(defun square (x)
)
In both cases, indentation of two spaces is inserted automatically. The new empty line inserted by electric return allows linewise editing of the code to be entered in this empty line.
The electric return feature is enabled by default in both Paredit and Slimv. It works by Paredit remapping the "enter" key (<CR>) in insert mode to a function that inserts electric return. Slimv needs to remap the "enter" key to present the argument list of the current function but it takes care of performing an electric return before showing the argument list. Vlime, however, forgets to perform electric return before showing the argument list, so this feature does not work in Vlime.
For now, we will continue with the assumption that electric return is enabled and working fine. If it is disabled or if it is not working for you, ignore the steps that discuss electric return.
Now, type only this:
(* x x
Again, Paredit would have inserted the closing parenthesis automatically. The code should look like this now:
(defun square (x)
(* x x)
)
Now, type one more closing parenthesis to advance past the automatically inserted closing parenthesis like this:
(defun square (x)
(* x x)
)
Then type another closing parenthesis. Paredit would now pick the lone closing parenthesis that is present in its own line and move it at the end of the current line like this:
(defun square (x)
(* x x))
This behaviour of consuming the extra newline inserted by an electric return on typing a closing parenthesis helps the code to conform to the popular Lisp coding convention of putting all the consecutive closing parentheses next to each other in the same line. In other words, typing closing parentheses re-gathers electric returns when applicable.
Let us see what happens if we try to delete the opening parenthesis around the product function (the * function). Type esc to return to normal mode. Then enter h in normal mode to move the cursor one place left so that the cursor is placed on the parenthesis just after the last x in the code like this:
(defun square (x)
(* x x))
Type x to delete the closing parenthesis the cursor is on. Nothing gets deleted! Instead the cursor just skips over the parenthesis like this:
(defun square (x)
(* x x))
Paredit refuses to delete the closing parenthesis because it encloses a non-empty list. It would have deleted the closing parenthesis along with the opening one if the list were empty. This is Paredit trying to ensure that the s-expressions remain valid while editing.
Note that in this step, h is a regular Vim motion command. In Vim, by default, x deletes the character under the cursor, but when Paredit is enabled, it remaps this command to behave the way it did in this step to ensure that the parentheses remain balanced.
Let us now try to delete the current line. Type dd to do so. The result looks like this:
(defun square (x)
)
Note how the closing parenthesis has been left intact to keep the parentheses balanced. Again, Paredit has remapped the dd command to produce this behaviour.
Now type da( to delete the entire defun expression. The buffer should look empty now.
Type i to enter insert mode and type out the following code:
(list (* 10 20) (+ 30 40))
Type esc to return to normal mode. Type h(hh to place the cursor on the closing parenthesis of the first expression.
(list (* 10 20) (+ 30 40))
Now type ,\>. The closing parenthesis of the first expression moves right to _slurp_ the next expression. The buffer looks like this:
(list (* 10 20 (+ 30 40)))
We assume here that Paredit is using the default Paredit leader key ,. If you have overridden the Vim leader key, then the Paredit leader key might be same as the Vim leader key. Enter the command `:echo g:paredit_leader` in Vim command-line mode to find the leader key being used by Paredit.
Now type ,<. The closing parenthesis of the outer expression moves left to barf the inner expression out. The buffer looks like this again:
(list (* 10 20) (+ 30 40))
While the cursor is on a parenthesis, the normal mode commands `,<` or `,>` can be used in this manner to move the parenthesis left or right respectively, thereby slurping or barfing expressions.
That was a very brief overview of what Paredit can do. There is a lot more to Paredit than what is described above. Paredit has a rich set of keybindings to make editing s-expressions very convenient. Enter :help paredit-keys in command-line mode to see the list of the keybindings.
I think it is a good idea to read the entire Paredit documentation. Enter :help paredit to do so. It is about 500 lines long and takes about 30 to 40 minutes to read. The time spent reading this documentation is worth it because it makes editing Lisp code very pleasant and productive.
Use Debugger and Inspector
After getting started with Slimv or Vlime, the very next thing you might want to know is how to work with the debugger. The debugger window comes up whenever an error or an unhandled condition occurs. It might look quite scary to a beginner, so it is a good idea to become comfortable with it as soon as possible. Fortunately, both Slimv and Vlime provide excellent key-bindings to inspect the error or dismiss it to return to the source code buffer quickly and easily.
Use Debugger and Inspector with Slimv
The following steps trigger an error and then show how to work with the debugger in Slimv:
Create a file with Vim, say foo.lisp and enter the following code into it:
(defun square (x)
(* x x))
(square "foo")
Enter ,b to evaluate the buffer.
As soon as the defective form (square "foo") gets evaluated, an error occurs. The error, possible restarts and the backtrace is displayed in a new split window for SLDB. SLDB stands for Slime Debugger. Here is an example of what may appear in the SLDB window:
The value
"foo"
is not of type
NUMBER
when binding SB-KERNEL::X
[Condition of type TYPE-ERROR]
The ellipsis in the end is added by me to denote that the actual output has been truncated in this article for the sake of brevity.
In the SLDB window, move the cursor to the second line of backtrace, i.e. on the following line:
1: (SQUARE "foo")
Then type enter. This line should now unfold to show the following details:
1: (SQUARE "foo")
in "(SB-INT:NAMED-LAMBDA SQUARE-----------------------------------
Locals:
X = "foo"
Move the cursor to the line that begins with in, i.e. on this line:
in "(SB-INT:NAMED-LAMBDA SQUARE-----------------------------------
Then type enter. Some information about its source code should appear like this:
1: (SQUARE "foo")
in "(SB-INT:NAMED-LAMBDA SQUARE
(X)
(BLOCK SQUARE (#:***HERE*** (* X X))))" byte 1
Locals:
X = "foo"
Move the cursor to the following line:
X = "foo"
Then type ,i to inspect this variable. A prompt would appear to confirm the variable name. Type enter to confirm. An inspector window should now appear with more details about this variable. This window should look like this:
Inspecting #<(SIMPLE-ARRAY CHARACTER (3)) {100478AFAF}>
Press for Help
Dimensions: (3)
Element type: CHARACTER
Total size: 3
Adjustable: NIL
Fill pointer: NIL
Contents:
0: #\f
1: #\o
2: #\o
[<<] Exit Inspector
Type enter to inspect any object under the cursor and drill down further.
Type backspace in normal mode to return to the previous object.
Enter ,q in normal mode to quit the inspector.
Finally, move the cursor to the following line in the SLDB window:
1: [*ABORT] Return to SLIME's top level.
Then type enter to execute this restart. Alternatively, enter ,a in normal mode to select the abort restart and quit to the previous level or ,q to quit to top level.
Most of the times when an error occurs, I quickly take a look at the stack trace to realise that I have made a silly mistake and enter the ,q command to abort and quit to top level. This can be quite convenient because it allows returning from debugging to coding very quickly with only two keystrokes.
Use Debugger and Inspector with Vlime
The following steps trigger an error and then show how to work with the debugger in Vlime:
Create a file with Vim, say foo.lisp and enter the following code into it:
(defun square (x)
(* x x))
(square "foo")
Save the file, connect to Vlime server and enter \of in normal mode to compile the entire buffer.
As soon as the defective form (square "foo") gets evaluated, an error occurs. The error, possible restarts and the backtrace is displayed in a new split window for SLDB. SLDB stands for Slime Debugger. Here is an example of what may appear in the SLDB window:
Thread: 1; Level: 1
The value
"foo"
is not of type
NUMBER
when binding SB-KERNEL::X
[Condition of type TYPE-ERROR]
The ellipsis in the end is added by me to denote that the actual output has been truncated in this article for the sake of brevity.
In the SLDB window, move the cursor to the second line of backtrace, i.e. on the following line:
(SQUARE "foo")
Then type d. A new split window should appear with the following details about this frame:
Frame: 1 (Restartable)
Locals:
X: "foo"
Location:
File: /home/susam/foo.lisp
Position: 20
Snippet:
(* x x))
(square "foo")
While the cursor is on the same line as mentioned in the previous point, type i to bring up the inspector window for this frame.
In the inspector window, type i to enter insert mode. Enter the following variable name in insert mode:
x
Then type esc to return to normal mode. Then type enter. The following details about the variable x should now appear in the inspector window:
#<(SIMPLE-ARRAY CHARACTER (3)) {1004617ABF}>
============================================
Dimensions: (3)
Element type: CHARACTER
Total size: 3
Adjustable: NIL
Fill pointer: NIL
Contents:
0: #\f
1: #\o
2: #\o
Type enter to inspect any object under the cursor and drill down further.
Type p to return to the previous object.
Enter the regular Vim command :q in command-line mode to quit the inspector window.
Finally, move the cursor to the following line in the SLDB window:
1: [*ABORT] Return to SLIME's top level.
Then type enter to execute this restart. Alternatively, we can enter a in normal mode to select the abort restart to return to the previous level. At this time, there is no command to return to SLIME's top level.
Trace Function
Trace Function in Slimv
The following steps show how to get started with tracing functions in Slimv:
Create a file with Vim, say foo.lisp and enter the following code into it:
(defun square (x)
(* x x))
(square (square 2))
Enter ,b in normal mode to evaluate the entire buffer.
Place the cursor on the function name, i.e. on square and enter ,t in normal mode to toggle tracing for this function. A prompt appears to confirm the function name. Type enter to confirm.
While the cursor is on the last expression, enter ,d in normal mode to evaluate the top-level form. The following output appears in the REPL buffer.
(square (square 2))
0: (SQUARE 2)
0: SQUARE returned 4
0: (SQUARE 4)
0: SQUARE returned 16
16
This output contains information about each call to the traced function, arguments passed to it and the return values.
Trace Function in Vlime
It takes a little more work to start tracing functions in Vlime. The following steps show how to do it:
The above variable defines the list of Swank contrib modules to load while initialising a Vlime connection. All modules mentioned above except the last one are loaded by default. The SWANK-TRACE-DIALOG module is not loaded by default but this module is necessary for tracing functions, so in order to load it, we define this variable to load this module in addition to all the other modules that are loaded by default.
Create a file with Vim, say foo.lisp and enter the following code into it:
(defun square (x)
(* x x))
(square (square 2))
Save the file, connect to Vlime server and enter \of in normal mode to compile the entire buffer.
Enter \TD in normal mode to show the trace dialog in a split window.
Enter ctrl + w w in normal mode to go back to the source code window.
Place the cursor on the function name, i.e. on square and enter \TT in normal mode to toggle tracing for this function.
While the cursor is on the last expression, enter \st in normal mode to evaluate the top-level form.
Enter ctrl + w w in normal mode twice to go to the trace window.
Under Trace Entries, place the cursor on [refresh] and type enter.
Then place the cursor on [fetch next batch] and type enter. Two results should appear for the two square calls that were made due to step 7. The trace information would be folded under each call.
Move the cursor to each fold line and enter zo in normal mode to open the fold. After opening both the folds, the following result should be visible:
The lines starting with `>` show the arguments and the ones starting with `<` show the return values.
Nifty Features
In this section, we will go over some of the nifty features that these plugins offer. Not all features will be covered here. I have chosen only a few features for the discussion here that I felt would be useful to beginners and at the same time also demonstrate the versatility of these plugins.
Evaluate Top-Level Form
In the previous sections, we saw how to evaluate the current expression under the cursor. In this section, we will see how to evaluate the top-level expression around the current cursor position. Let us do a small exercise to see this:
Create a file with Vim, say foo.lisp and enter the following code into it:
(+ 1 (* 2 (/ 6 2)))
With Slimv or Vlime connected to Swank, let us do a quick recap of how to evaluate the current expression.
With Slimv, enter the normal mode command ,e to evaluate the current expression.
With Vlime, enter the normal mode command \ss to evaluate the current expression.
The current expression, i.e. (/ 6 2) should get evaluated and the result 3 should appear in the REPL buffer.
Let us now see how to evaluate the top-level expression.
With Slimv, enter the normal mode command ,d to evaluate the top-level expression.
With Vlime, enter the normal mode command \st to evaluate the top-level expression.
The top-level expression should get evaluated and the result 7 should appear in the REPL buffer.
Rainbow Parentheses
Rainbow parentheses make it easy to see matching parentheses by colouring different levels of parentheses with different colours. Matching parentheses have the same colour. To enable this feature in Slimv, add this command to ~/.vimrc:
let g:lisp_rainbow=1
This feature is not available in Vlime. But there are several Vim plugins that support rainbow parentheses. Here are the steps to install one such plugin that is quite popular:
In case you ever want to uninstall it, enter these commands:
rm -rf ~/.vim/pack/plugins/start/rainbow_parentheses
sed -i.bkp '/autocmd.*RainbowParentheses/d' ~/.vimrc
Argument List
You must have seen this feature already while trying out the sections earlier. While editing a Lisp source file, after typing a function name, as soon as a space is typed or the enter key is typed, the argument list for the function appears to serve as a reference. In Slimv, the argument list appears in the status line at the bottom. In Vlime, the argument list appears in a split window at the top.
Omni-Completion
Type a function name partially, e.g. form and type tab while still in insert mode. The omni-completion menu should appear with the list of completions if there are multiple choices. Type ctrl+n to select the next choice and ctrl+p to select the previous choice. Selecting a choice also immediately inserts that choice in the buffer. This works in both Slimv and Vlime. In Slimv, we can also type tab to select the next choice.
By default, omni-completion is fuzzy. For example, type wl and type tab and omni-complete should insert write-line automatically as well as show other matching choices.
Describe Symbol
With Slimv, enter the normal mode command ,s to describe the symbol under the cursor. This brings up the documentation of the symbol in the Vim message area. This feature works while editing Common Lisp and Clojure source files but not while editing Scheme source file. This feature is not supported for Scheme at this time. See the Other Lisp Dialects section for details on how to set up Slimv with Clojure and MIT/GNU Scheme.
With Vlime, enter \da in normal mode to describe the symbol under the cursor. This brings up the documentation of the symbol in a split window.
Expand Macro
Here is an excercise that shows how to expand macros interactively while editing a Lisp source file:
Create a file with Vim, say foo.lisp and enter the following code into it:
(defmacro calc (a op b)
(list op a b))
(defmacro square (x)
(list 'calc x '* x))
(square 2)
With Slimv, enter ,b in normal mode to evaluate the entire buffer.
With Vlime, save the file, connect to Vlime server and type \of in normal mode to compile the entire buffer.
With Slimv, while the cursor is on the last expression, enter ,1 in normal mode to expand the macro form once.
With Vlime, enter \m1 in normal mode to do the same thing.
The following expansion should appear as the result:
(CALC 2 * 2)
Slimv displays the expansion in the REPL buffer whereas Vlime displays it in a new split window.
With Slimv, enter ,m in normal mode to recursively expand the current expression until it is no longer a macro.
With Vlime, enter \ma in normal mode to do the same thing.
The following expansion should appear as the result:
(* 2 2)
Cross Reference
Here is an exercise that shows how to use the cross-reference commands in Slimv and Vlime:
Create a file with Vim, say foo.lisp and enter the following code into it:
With Slimv, enter ,b in normal mode to evaluate the entire buffer.
With Vlime, save the file, connect to Vlime server and type \of in normal mode to compile the entire buffer.
With Slimv, place the cursor on any occurrence of the symbol square and enter ,xl in normal mode. A prompt would appear to confirm the symbol name. Type enter to confirm. The list of all callers should now appear in the REPL buffer.
With Vlime, place the cursor on any occurrence of the symbol square and enter \xc in normal mode to list all callers of the function. The output appears in a split window containing the cross reference (xref) buffer. Type enter on any item in the xref buffer and Vlime will take you directly to the referenced location.
Other Common Lisp Implementations
The previous sections used SBCL as the implementation of Common Lisp. How well do Slimv and Vlime work with other Common Lisp implementations?
I have found that both plugins are pretty well tested with SBCL. However, they may not be so well tested with other implementations. Due to the lack of sufficient testing with Common Lisp implementations other than SBCL, certain errors may occur while using other implementations. Sometimes it is possible to work around these errors and sometimes it isn't. We will see an example of this in an upcoming section when we try to start Swank server automatically using Vlime and CLISP.
For this section, I choose CLISP and Embeddable Common-Lisp (ECL) as two other implementations of Common Lisp that will be used with Slimv and Vlime. After following the upcoming subsections, you should get the hang of how to make Slimv or Vlime work with other implementations of Common Lisp.
Use Slimv with CLISP
If you have read and tried the steps in the Get Started with Slimv and SBCL section, it is going to be quite easy to use Slimv with CLISP. The steps are similar with a few minor modifications. They are explained below:
Uninstall SBCL and install CLISP with these commands:
Then edit a Lisp source file and enter the normal command ,c to connect to it and bring up the REPL window.
To start Swank automatically from Slimv, there is nothing more to be done. Just edit a Lisp source file and enter the normal mode command ,c. While running in GNU Screen, tmux or a desktop environment, Slimv can automatically detect CLISP and start Swank server with it.
In general, to start Swank server manually with another Common Lisp implementation, we need to figure out how to load start-swank.lisp with it.
Use Slimv with ECL
The steps to use Slimv with Embeddable Common-Lisp (ECL) are very similar too. Once again, only if we need to start Swank server manually, we need to figure out the command to do so. Otherwise, there is no other difference. Here are the steps:
Ensure that SBCL and CLISP are uninstalled and ECL is installed.
Then edit a Lisp source file and enter the normal command ,c to connect to it and bring up the REPL window.
To start Swank automatically from Slimv, there is nothing more to be done. Just edit a Lisp source file and enter the normal mode command ,c. While running in GNU Screen, tmux or a desktop environment, Slimv can automatically detect CLISP and start Swank server with it.
There is a possible timeout issue to be aware of though. ECL can take a minute or two to compile the code it loads the first time Swank server is started. However, Slimv has a default timeout period of 20 seconds, so Slimv may fail with the following error message:
SWANK server is not running. Press ENTER to continue.
If this happens, just wait for ECL to complete compiling Swank server. Once it starts Swank server, enter the normal mode command ,c again and it should connect immediately.
Use Vlime with CLISP
This subsection assumes that you have already read and tried the Get Started with Vlime and SBCL section, so you are familiar with Vlime basics. Now we will see what more it takes to use Vlime with CLISP in the steps below:
Let us assume we want to start afresh with CLISP, i.e. we do not have previous artefacts created by SBCL. To clean up old artefacts, enter these commands:
Unlike Slimv, automatic start of Swank server with Common Lisp implementations other than SBCL are not supported out of the box, so the above Vim script tells Vlime how to start Swank server with CLISP. The -repl option is used to work around an issue that is explained in the next point.
Vlime is now ready to be used with CLISP. Just edit a Lisp source file and enter the normal mode command \rr to start Swank server and connect to it automatically.
You may see the following error in the SLIME debugger (sldb) split window:
SOCKET-STATUS on #1=# is illegal
Despite the above error, the following message should appear at the bottom:
Vlime Connection 1 established.
If the above message occurs, you can ignore this error, close the debugger window as well as the console output window and continue to use Vlime normally.
The -repl option used in the previous step ensures that the REPL starts despite this error. Without it, this step would not have succeeded. This is what I meant when I said earlier that we may need to work around certain errors while using these plugins with a Common Lisp implementation other than SBCL.
Use Vlime with ECL
Here are the steps to use Vlime with ECL:
Let us assume we want to start afresh with ECL, i.e. we do not have previous artefacts created by SBCL or ECL. To clean up old artefacts, enter these commands:
Edit a Lisp source file and enter the normal mode command \rr to start Swank server and connect to it automatically.
Other Lisp Dialects
So far, we have seen how to use Slimv or Vlime with a Common Lisp implementation. Now let us see how well these plugins work with other Lisp dialects. Vlime does not support other Lisp dialects. It supports Common Lisp only. Slimv supports two other popular dialects of Lisp: Scheme and Clojure. In the next two subsections, we see how
Use Slimv with MIT/GNU Scheme
Slimv is documented to work with MIT/GNU Scheme on Linux only. Enter :help slimv-installation in Vim to read more about it. It says the following under the "Prerequisites" section.
Lisp or Clojure or MIT/GNU Scheme (Linux only) installed.
Further, the Swank loader script for MIT/GNU Scheme named swank-mit-scheme.scm says the following in its source code comments:
You need MIT/GNU Scheme 9.2
At the time of writing this article, I have confirmed that both these requirements indeed need to be met to use Slimv with MIT/GNU Scheme. Here are the steps to use Slimv with MIT/GNU Scheme:
This is an optional step. To start Swank server automatically from Slimv, run Vim in tmux, GNU Screen or a desktop environment. In this article, we use tmux, so start tmux with this command:
tmux
This step is necessary only if you are not using tmux, GNU Screen or a desktop environment. In such a case, enter this command to start Swank server manually:
Create a new Scheme source code file, say, foo.scm with this command:
vim foo.scm
To connect to Swank server, enter the following command in Vim normal mode:
,c
Type some code into the buffer for the new file. To do so, first type i to enter insert mode and type this code:
(display "hello, world\n")
Type esc to return to normal mode. To evaluate, the current expression under the cursor, enter the following command in normal mode:
,e
Both the current expression and its result should appear in the REPL window.
I have confirmed that the steps above work fine with MIT/GNU Scheme 9.1.1 on Debian GNU/Linux 9.11 (stretch). Like I mentioned before, Slimv requires Linux to work with MIT/GNU Scheme. For example, trying to start Swank server with MIT/GNU Scheme 9.2 on macOS High Sierra 10.13.6 fails with this error:
; /usr/local/Cellar/mit-scheme/9.2_2/lib/mit-scheme-c/include/config.h:879:10:
fatal error: 'sys/types.h' file not found
Further, the version of MIT/GNU Scheme really needs to be 9.x. For example, when I try to start Swank with MIT/GNU Scheme 10.1.5 on Debian GNU/Linux 10.1 (buster), the following error occurs:
;The object #[package 12 (user)], passed as an argument to ->environment, is not an environment.
Use Slimv with Clojure
Slimv works fine with Clojure too. However, it may have some trouble locating Clojure on the system if we attempt to start Swank server automatically with Clojure. That is because where and how Clojure is installed varies from operating system to operating system and also depends on the installation procedure chosen to set up Clojure.
On Unix-like systems, Slimv looks for JAR files that match the glob pattern clojure*.jar at paths that match the glob pattern /usr/local/bin/*clojure* and ~/*clojure, in that order. On Windows, it looks for the JAR files at directory paths that match the glob pattern C:\*clojure* and C:\*clojure*\lib. Additionally, Slimv also looks for the JAR files at the paths mentioned in the PATH environment variable. There are a few more strategies too to locate Clojure but we will not get into that here.
In this section, I will show how to build Clojure from source with Maven and install it at ~/clojure/clojure.jar, a path Slimv can easily find, so installing it here would mean that the steps below would work everywhere regardless of the operating system. If you are on Windows, install Clojure at C:\clojure\clojure.jar instead.
Here are the steps to install Clojure at ~/clojure/clojure.jar and use it with Slimv:
Choose one of the two sets of commands below to install Maven:
# On Debian, Ubuntu, etc.
sudo apt-get install maven
# On macOS
brew install openjdk maven
export JAVA_HOME=/usr/local/opt/openjdk
export PATH="$JAVA_HOME/bin:$PATH"
This is an optional step. To start Swank server automatically from Slimv, run Vim in tmux, GNU Screen or a desktop environment. In this article, we use tmux, so start tmux with this command:
tmux
This step is necessary only if you are not using tmux, GNU Screen or a desktop environment. In such a case, enter these commands to start Swank server manually:
Create a new Clojure source code file, say, foo.clj with this command:
vim foo.clj
To connect to Swank server, enter the following command in Vim normal mode:
,c
Type some code into the buffer for the new file. To do so, first type i to enter insert mode and type this code:
(println "hello, world")
Type esc to return to normal mode. To evaluate, the current expression under the cursor, enter the following command in normal mode:
,e
Both the current expression and its result should appear in the REPL window.
Comparison of Slimv and Vlime
Finally, let me provide a comparison of both Slimv and Vlime side by side. This comparison table below is not exhaustive. There are more differences between the tools than what is mentioned below.
Slimv
Vlime
Slimv's directory structure conforms to the directory structure of plugins in a Vim package as well as the default directory structure expected by popular Vim plugin managers, so installing Slimv is quite straightforward.
|
Vlime's directory structure does not conform to the directory structure of plugins in a Vim package or the default directory structure expected by popular Vim plugin managers. As a result, Vim's native support for packages cannot be used to install Vlime. Installing it via a plugin manager requires fiddling with Vim's runtimepath option in order to load it successfully.
|
|
Slimv requires a Vim package that is compiled with support for Python interface.
|
Vlime does not have this requirement. It can work with basic Vim that does not have Python interface.
|
|
Slimv requires Vim to be running within tmux, GNU Screen or a desktop environment to be able to start Swank server automatically. If you have none of these, Swank server needs to be started manually.
|
Vlime does not require tmux, GNU Screen or a desktop environment in order to start Vlime server automatically. It can start Vlime server on its own.
|
|
Slimv does not require Quicklisp to install Swank. Slimv bundles the Swank server code with itself.
|
Vlime requires Quicklisp to be installed. It relies on Quicklisp to install Swank the first time it is needed.
|
|
Slimv bundles Paredit with itself. Installing Slimv also provides Paredit.
|
Vlime does not bundle Paredit with itself. Paredit needs to be installed separately.
|
|
The buffer for REPL is interactive in Slimv. We can type code directly into the REPL window and type enter to execute it.
|
The buffer for REPL is not interactive in Vlime. Its nomodifiable option is set, so we cannot type code directly into the REPL window.
|
|
Paredit electric returns work fine with Slimv. Slimv remaps the "enter" key to show argument list of the current function after inserting electric returns. It takes care of preserving the electric return functionality of Paredit.
|
Paredit electric returns do not work fine with Vlime. Vlime remaps the "enter" key to show argument list of the current function without inserting electric returns.
|
|
Slimv shows argument list of a function, symbol description, etc. in the status line or message area at the bottom.
|
Vlime shows argument list of a function, symbol description, etc. in separate split windows. These are extra windows to skip over while cycling between windows with the normal mode ctrl + w w command which could feel inconvenient.
|
|
Slimv shows trace results, macro expansion, cross reference, etc. in the REPL buffer.
|
Vlime shows resultions of trace results, macro expansion, cross reference, etc. in split windows. These are extra windows to skip over while cycling between windows. This could feel inconvenient.
|
|
Slimv supports programming in Common Lisp, MIT/GNU Scheme and Clojure.
|
Vlime supports programming in Common Lisp only. It does not support Scheme or Clojure.
|
|
Slimv supports rainbow parentheses by adding let g:lisp_rainbow=1 to ~/.vimrc. With this feature, parentheses at different levels have different colours and matching parentheses have the same colour.
|
Vlime does not have rainbow parentheses. However, this is not a major problem because there are several independent plugins available that provide rainbow parentheses.
|
|
Slimv cross-reference commands do not help us to jump directly to a function listed in the results.
|
Vlime cross-reference commands create a xref buffer that allows us to jump directly to a function listed in the results by moving the cursor to the function name in the xref buffer and typing enter.
|
Quick Recommendation
If you are looking for a quick recommendation on which plugin to use, I am going to recommend Slimv. It has been around for much longer. It supports a wider variety of Lisp implementations. I find its default key bindings more convenient. A truly interactive REPL buffer is also a bonus. Also, Slimv supports Scheme and Clojure whereas Vlime does not. Having said that, I think it is a good idea to try out both the plugins on your own and then find out which one suits you more.
Disclosure
Four bugs were harmed while writing this article!
While writing this article, I found the following four bugs in Slimv which were then promptly squashed: #87, #88, #89 and #90.
Instagram Engineering
Shopify Engineering
