Lisp in Vim with Slimv or Vlime

By Susam Pal on 07 Dec 2019

Introduction

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 is much better now. 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.

If you are looking only for a comparison of the two plugins or a quick recommendation, jump directly to the Comparison of Slimv and Vlime section or the Quick Recommendation section.

Contents

Background

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 parenthesized 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:

XKCD comic on Lisp
Lisp by Randall Munroe (Source: https://xkcd.com/224/)
XKCD comic on Lisp Cycles
Lisp Cycles by Randall Munroe (Source: https://xkcd.com/297/)

Developed in 1958 by John McCarthy, Lisp is the second oldest programming language in use today. Only Fortran is older, by one year. There are three Lisp dialects popular today: 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 Lisp programmers while writing Lisp code in Emacs.

Vim: Slimv/Vlime

Is there anything similar to SLIME for Vim? Yes, there are two popular options:

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 don't use 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, I 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 subsection, I will note down the versions of various software tools I used while writing this article. Here they are:

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:

  1. 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. I usually install vim-gtk on Debian, MacVim on macOS, and GVim on Windows because I like my editor to be a GUI window on the desktop. However, 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.

  2. Installing Slimv is pretty simple. Here is how I 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's 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.

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

  4. 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:

    sbcl --load ~/.vim/pack/plugins/start/slimv/slime/start-swank.lisp

    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.

  5. Create a new Lisp source code file, say, foo.lisp with this command:

    vim foo.lisp
  6. 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.

  7. Type some code into the buffer for the new file. To do so, first press i to enter insert mode and type this code:

    (format t "hello, world~%")

    Press esc to return to normal mode.

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

  9. The REPL is interactive. Press ctrl + w w to switch to the REPL window. Then press i to enter insert mode and type this code:

    (+ 1 2)

    Press enter to evaluate the expression just like you would do in a real REPL. The result should then appear in the REPL.

    Press esc to return to normal mode again. Use the normal mode command ctrl + w w to switch between the split windows.

  10. 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 8 of the previous section, 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's 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:

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

  2. Install Quicklisp with these commands:

    curl -O https://beta.quicklisp.org/quicklisp.lisp
    sbcl --load quicklisp.lisp --eval '(quicklisp-quickstart:install)' --eval '(exit)'
    sbcl --load ~/quicklisp/setup.lisp --eval '(ql:add-to-init-file)' --eval '(exit)'
    

    Press enter in the end, when prompted, to complete the installation.

  3. Install Vlime and Paredit with these commands:

    git clone https://github.com/l04m33/vlime.git ~/.vim/bundle/vlime
    git clone https://github.com/kovisoft/paredit ~/.vim/pack/plugins/start/paredit
    echo 'set runtimepath^=~/.vim/bundle/vlime/vim' >> ~/.vimrc
    vim +'helptags ~/.vim/bundle/vlime/vim/doc' +'helptags ~/.vim/pack/plugins/start/paredit/doc' +q
    

    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.

    You should really 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.

  4. Create a new Lisp source code file, say, foo.lisp with this command:

    vim foo.lisp
  5. 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

  6. Type some code into the buffer for the new file. To do so, first press i to enter insert mode and type this code:

    (format t "hello, world~%")

    Press 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 it. 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.

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

  8. 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; /runtimepath.*paredit/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:

  1. Create a new Lisp source code file, say, foo.lisp with this command:

    vim foo.lisp
  2. Press 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 underbar above shows where the cursor should be.

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

  4. You should still be in insert mode. Press enter to create a new line below. Now one of two things are 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.

  5. 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)
      )
    
  6. Now, type one more closing parenthesis to advance past the automatically inserted closing parenthesis like this:

    (defun square (x)
      (* x x) 
      )
    
  7. 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.

  8. Let us see what happens if we try to delete the opening parenthesis around the product function (the * function). Press 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 just after the last x in the code like this:

    (defun square (x)
      (* x x))
    

    Now enter ( in normal mode to move the cursor to the opening parenthesis of the product function call like this:

    (defun square (x)
      (* x x))
    

    Press x to delete the opening parenthesis. Nothing gets deleted! Instead the cursor just skips over the opening parenthesis like this:

    (defun square (x)
      (* x x))
    

    Paredit refuses to delete the opening parenthesis because it encloses a non-empty list. It would have deleted the opening parenthesis along with the closing 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, ( moves the cursor one sentence backward and x deletes the character under the cursor, but when Paredit is enabled, it remaps these commands to behave the way they did in this step.

  9. Let us now try to delete the current line. Press dd to do so. The result looks like this:

    (defun foo (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.

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 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:

  1. Create a file with Vim, say foo.lisp and enter the following code into it:

    (defun square (x)
      (* x x))
    
    (square "foo")
    
  2. Enter ,b to evaluate the buffer.

  3. 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]
    
    Restarts:
      0: [RETRY] Retry SLIME REPL evaluation request.
      1: [*ABORT] Return to SLIME's top level.
      2: [ABORT] abort thread (#)
    
    Backtrace:
      0: (SB-KERNEL:TWO-ARG-* "foo" "foo") [external]
      1: (SQUARE "foo")
      2: (SB-DEBUG::TRACE-CALL # # "foo")
      3: (SB-INT:SIMPLE-EVAL-IN-LEXENV (SQUARE "foo") #)
      4: (EVAL (SQUARE "foo"))
      5: (SWANK::EVAL-REGION "(defun square (x) ..)
      6: ((LAMBDA NIL :IN SWANK-REPL::REPL-EVAL))
      ...
    

    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.

  4. In the SLDB window, move the cursor to the second line of backtrace, i.e., on the following line:

      1: (SQUARE "foo")

    Then press enter. This line should now unfold to show the following details:

      1: (SQUARE "foo")
          in "(SB-INT:NAMED-LAMBDA SQUARE-----------------------------------
        Locals:
          X = "foo"
    
  5. Move the cursor to the line that begins with in, i.e., the following line:

          in "(SB-INT:NAMED-LAMBDA SQUARE-----------------------------------

    Then press 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"
    
  6. Move the cursor to the following line:

          X = "foo"

    Then press ,i to inspect this variable. A prompt would appear to confirm the variable name. Press 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
    
  7. Press enter to inspect any object under the cursor and drill down further.

  8. Press backspace in normal mode to return to the previous object.

  9. Enter ,q in normal mode to quit the inspector.

  10. Finally, move the cursor to the following line in the SLDB window:

      1: [*ABORT] Return to SLIME's top level.

    Then press enter to execute this restart. Alternatively, enter ,a in normal mode to select the abort restart or ,q to quit to toplevel.

Most of the times when an error occurs, I quickly take a look at the stack trace to realize that I have made a silly mistake and enter the ,a command to select the abort restart. This is one of my most favourite commands in Slimv because it allows me to return from debugging to coding really fast 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:

  1. Create a file with Vim, say foo.lisp and enter the following code into it:

    (defun square (x)
      (* x x))
    
    (square "foo")
    
  2. Save the file, connect to Vlime server, and enter \of in normal mode to compile the entire buffer.

  3. 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]
    
    Restarts:
      0. *ABORT - Return to SLIME's top level.
      1.  ABORT - abort thread (#)
    
    Frames:
      0.  (SB-KERNEL:TWO-ARG-* "foo" "foo") [external]
      1.  (SQUARE "foo")
      2.  (SB-FASL::LOAD-FASL-GROUP #S(SB-FASL::FASL-INPUT :STREAM # :TABLE #(41 # SB-IMPL::%DEFUN #..
      3.  (SB-FASL::LOAD-AS-FASL # NIL NIL)
      4.  ((FLET SB-FASL::THUNK :IN LOAD))
      5.  (SB-FASL::CALL-WITH-LOAD-BINDINGS # #)
      ...
    

    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.

  4. In the SLDB window, move the cursor to the second line of backtrace, i.e., on the following line:

      1.  (SQUARE "foo")

    Then press 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")
    
  5. While the cursor is on the same line as mentioned in the previous point, press i to bring up the inspector window for this frame.

  6. In the inspector window, press i to enter insert mode. Enter the following variable name in insert mode:

    x

    Then press esc to return to normal mode. Then press 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
  7. Press enter to inspect any object under the cursor and drill down further.

  8. Press p to return to the previous object.

  9. Enter the regular Vim command :q in command-line mode to quit the inspector window.

  10. Finally, move the cursor to the following line in the SLDB window:

      1: [*ABORT] Return to SLIME's top level.

    Then press 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:

  1. Create a file with Vim, say foo.lisp and enter the following code into it:

    (defun square (x)
      (* x x))
    
    (square (square 2))
    
  2. Enter ,b in normal mode to evaluate the entire buffer.

  3. 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. Press enter to confirm.

  4. 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:

  1. Add the following statement to ~/.vimrc:

    let g:vlime_contribs = ['SWANK-ASDF', 'SWANK-PACKAGE-FU',
                          \ 'SWANK-PRESENTATIONS', 'SWANK-FANCY-INSPECTOR',
                          \ 'SWANK-C-P-C', 'SWANK-ARGLISTS', 'SWANK-REPL',
                          \ 'SWANK-FUZZY', 'SWANK-TRACE-DIALOG']
    

    The above variable defines the list of Swank contrib modules to load while initializing 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.

  2. Create a file with Vim, say foo.lisp and enter the following code into it:

    (defun square (x)
      (* x x))
    
    (square (square 2))
    
  3. Save the file, connect to Vlime server, and enter \of in normal mode to compile the entire buffer.

  4. Enter \TD in normal mode to show the trace dialog in a split window.

  5. Enter ctrl + w w in normal mode to go back to the source code window.

  6. Place the cursor on the function name, i.e., on square, and enter \TT in normal mode to toggle tracing for this function.

  7. While the cursor is on the last expression, enter \st in normal mode to evaluate the top-level form.

  8. Enter ctrl + w w in normal mode twice to go to the trace window.

  9. Under Trace Entries, place the cursor on [refresh] and press enter.

  10. Then place the cursor on [fetch next batch] and press 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.

  11. 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:

    0 - COMMON-LISP-USER::SQUARE
        > 2
        < 4
    1 - COMMON-LISP-USER::SQUARE
        > 4
        < 16
        16
    

    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:

  1. Create a file with Vim, say foo.lisp and enter the following code into it:

    (+ 1 (* 2 (/ 6 2)))
  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.

  3. 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:

git clone https://github.com/junegunn/rainbow_parentheses.vim.git ~/.vim/pack/plugins/start/rainbow_parentheses
echo 'autocmd FileType lisp,scheme,clojure RainbowParentheses' >> ~/.vimrc

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 pressed, 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 press tab while still in insert mode. The omni-completion menu should appear with the list of completions if there are multiple choices. Press 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 press tab to select the next choice.

By default, omni-completion is fuzzy. For example, type wl and press 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:

  1. 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)
    
  2. With Slimv, enter ,b in normal mode to evaluate the entire buffer.

    With Vlime, save the file and press \of in normal mode to compile the entire buffer.

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

  4. 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:

  1. Create a file with Vim, say foo.lisp and enter the following code into it:

    (defun square (x)
      (* x x))
    
    (defun square-of-sum (x y)
      (square (+ x y)))
    
    (defun sum-of-squares (x y)
      (+ (square x) (square y)))
    
    (square-of-sum 2 3)
    (sum-of-squares 2 3)
    
  2. With Slimv, enter ,b in normal mode to evaluate the entire buffer.

    With Vlime, save the file and press \of in normal mode to compile the entire buffer.

  3. With Slimv, place the cursor on any occurrence of the symbol square and enter ,xl in normal mode to list all callers of the function. The output appears 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. Press 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:

  1. Uninstall SBCL and install CLISP with these commands:

    sudo apt-get remove sbcl
    sudo apt-get install clisp
  2. To start Swank server manually, enter this command:

    clisp ~/.vim/pack/plugins/start/slimv/slime/start-swank.lisp

    Then edit a Lisp source file and enter the normal command ,c to connect to it and bring up the REPL window.

  3. 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:

  1. Ensure that SBCL and CLISP are uninstalled and ECL is installed.

    sudo apt-get remove sbcl clisp
    sudo apt-get install ecl
  2. To start Swank server manually, enter this command:

    ecl --load ~/.vim/pack/plugins/start/slimv/slime/start-swank.lisp

    Then edit a Lisp source file and enter the normal command ,c to connect to it and bring up the REPL window.

  3. 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:

  1. Let us assume we want to start afresh with CLISP, i.e., we do not have previous artifacts created by SBCL. To clean up old artifacts, enter these commands:

    rm -rf ~/.sbclrc ~/quicklisp
    sudo apt-get remove sbcl
    
  2. Install CLISP with this command:

    sudo apt-get install clisp
  3. Install Quicklisp using CLISP with these commands:

    curl -O https://beta.quicklisp.org/quicklisp.lisp
    clisp -i quicklisp.lisp -x '(quicklisp-quickstart:install)'
    clisp -i ~/quicklisp/setup.lisp -x '(ql:add-to-init-file)'
    

    Press enter in the end, when prompted, to complete the installation.

  4. Add the following code to ~/.vimrc:

    let g:vlime_cl_impl = 'clisp'
    function! VlimeBuildServerCommandFor_clisp(vlime_loader, vlime_eval)
        return ['clisp', '-i', a:vlime_loader,
                       \ '-x', a:vlime_eval,
                       \ '-repl']
    endfunction
    

    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.

  5. 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=#<INPUT STRING-INPUT-STREAM> 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:

  1. Let us assume we want to start afresh with ECL, i.e., we do not have previous artifacts created by SBCL or ECL. To clean up old artifacts, enter these commands:

    rm -rf ~/.sbclrc ~/.clisprc.lisp ~/quicklisp
    sudo apt-get remove sbcl clisp
    
  2. Install ECL with this command:

    sudo apt-get install ecl
  3. Install Quicklisp using ECL with these commands:

    curl -O https://beta.quicklisp.org/quicklisp.lisp
    ecl --load quicklisp.lisp --eval '(quicklisp-quickstart:install)' --eval '(quit)'
    ecl --load ~/quicklisp/setup.lisp --eval '(ql:add-to-init-file)' --eval '(quit)'
    

    Press enter in the end, when prompted, to complete the installation.

  4. Add the following code to ~/.vimrc:

    let g:vlime_cl_impl = 'ecl'
    function! VlimeBuildServerCommandFor_ecl(vlime_loader, vlime_eval)
        return ['ecl', '--load', a:vlime_loader,
                     \ '--eval', a:vlime_eval]
    endfunction
    
  5. 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 saw 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. Thankfully, Vlime 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:

  1. Install MIT/GNU Scheme with this command:

    sudo apt-get mit-scheme

    Ensure that vim-nox, tmux, and Slimv are installed as explained in the Get Started with Slimv and SBCL subsection earlier.

  2. 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
  3. 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:

    scheme --load ~/.vim/pack/plugins/start/slimv/slime/contrib/swank-mit-scheme.scm
  4. Create a new Scheme source code file, say, foo.scm with this command:

    vim foo.scm
  5. To connect to Swank server, enter the following command in Vim normal mode:

    ,c

  6. Type some code into the buffer for the new file. To do so, first press i to enter insert mode and type this code:

    (display "hello, world\n")

    Press 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's 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:

  1. 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"
    
  2. Enter these commands to install Clojure:

    git clone https://github.com/clojure/clojure.git ~/clojure
    git -C ~/clojure checkout clojure-1.10.1
    mvn -f ~/clojure/pom.xml -Plocal -Dmaven.test.skip=true package
    
  3. Ensure that vim-nox, tmux, and Slimv are installed as explained in the Get Started with Slimv and SBCL subsection earlier.

  4. 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
  5. 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:

    SWANK_DIR=~/.vim/pack/plugins/start/slimv/swank-clojure
    java -cp "$HOME/clojure/clojure.jar:$SWANK_DIR" clojure.main -i "$SWANK_DIR/swank/swank.clj" -e '(swank.swank/start-repl)' -r
    
  6. Create a new Clojure source code file, say, foo.clj with this command:

    vim foo.clj
  7. To connect to Swank server, enter the following command in Vim normal mode:

    ,c

  8. Type some code into the buffer for the new file. To do so, first press i to enter insert mode and type this code:

    (println "hello, world")

    Press 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 press enter to execute it.

The buffer for REPL is not interactive in Slimv. 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 pressing 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.

I use Slimv myself. The additional dependency on Python interface for Vim is not a problem for me because I use one of GVim, MacVim, or vim-gtk anyway and these are compiled with support for Python interface.

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.

References