<astyle="font-size: 120%"href="https://www.udemy.com/course/common-lisp-programming/?couponCode=LISPY-XMAS2023"title="This course is under a paywall on the Udemy platform. Several videos are freely available so you can judge before diving in. vindarel is (I am) the main contributor to this Cookbook."> Discover our contributor's Lisp course with this Christmas coupon.</a>
<li>Installing it from <ahref="http://wikemacs.org/wiki/Melpa">MELPA</a> is straightforward. Search package-list-packages for ‘slime’ and click to install. It will install itself and all dependencies.</li>
<p>Check out this <strong><ahref="https://www.youtube.com/watch?v=sBcPNr1CKKw">video tutorial</a></strong> ! (and the author’s channel, full of great stuff)</p>
<h5id="slime-fancy-contrib-packages-and-other-extensions">SLIME fancy, contrib packages and other extensions</h5>
<p>SLIME’s functionalities live in packages and so-called <ahref="https://common-lisp.net/project/slime/doc/html/Contributed-Packages.html">contrib
modules</a>
must be loaded to add further functionalities. The default
<code>slime-fancy</code> includes:</p>
<ul>
<li>slime-autodoc</li>
<li>slime-c-p-c</li>
<li>slime-editing-commands</li>
<li>slime-fancy-inspector</li>
<li>slime-fancy-trace</li>
<li>slime-fontifying-fu</li>
<li>slime-fuzzy</li>
<li>slime-mdot-fu</li>
<li>slime-macrostep</li>
<li>slime-presentations</li>
<li>slime-references</li>
<li>slime-repl</li>
<li>slime-scratch</li>
<li>slime-package-fu</li>
<li>slime-trace-dialog</li>
</ul>
<p>SLIME also has some nice extensions like
<ahref="https://github.com/emacs-helm/helm-slime">Helm-SLIME</a> which features, among
others:</p>
<ul>
<li>Fuzzy completion,</li>
<li>REPL and connection listing,</li>
<li>Fuzzy-search of the REPL history,</li>
<li>Fuzzy-search of the <em>apropos</em> documentation.</li>
</ul>
<h5id="repl-interactions">REPL interactions</h5>
<p>From the SLIME REPL, press <code>,</code> to prompt for commands. There is completion
over the available systems and packages. Examples:</p>
<ul>
<li><code>,load-system</code></li>
<li><code>,reload-system</code></li>
<li><code>,in-package</code></li>
<li><code>,restart-inferior-lisp</code></li>
</ul>
<p>and many more.</p>
<p>With the <code>slime-quicklisp</code> contrib, you can also <code>,ql</code> to list all systems
available for installation.</p>
<h4id="sly-sylvester-the-cats-common-lisp-ide">SLY: Sylvester the Cat’s Common Lisp IDE</h4>
<p><ahref="https://github.com/joaotavora/sly">SLY</a> is a SLIME fork that contains
<h3id="finding-ones-way-into-emacs-built-in-documentation">Finding one’s way into Emacs’ built-in documentation</h3>
<p>Emacs comes with built-in tutorials and documentation. Moreover, it is
a self-documented and self-discoverable editor, capable of introspection to let you
know about the current keybindings, to let you search about function documentation,
available variables,source code, tutorials, etc. Whenever you ask yourself questions like
“what are the available shortcuts to do x” or “what does this
keybinding really do”, the answer is most probably a keystroke away,
right inside Emacs. You should learn a few keybindings to be able to
discover Emacs with Emacs flawlessly.</p>
<p>The help on the topic is here:</p>
<ul>
<li><ahref="https://www.gnu.org/software/emacs/manual/html_node/emacs/Help.html#Help">Help page: commands for asking Emacs about its commands</a></li>
</ul>
<p>The help keybindings start with either <code>C-h</code> or <code>F1</code>. Important ones are:</p>
<ul>
<li><code>C-h k <keybinding></code>: what function does this keybinding call?</li>
<li><code>C-h f <function name></code>: what keybinding is linked to this function?</li>
<li><code>C-h a <topic></code>: show a list of commands whose name match the given <em>topic</em>. It accepts a keyword, a list of keywords or a regular expression.</li>
<li><code>C-h i</code>: show the Info page, a menu of major topics.</li>
</ul>
<p>Some Emacs packages give even more help.</p>
<h4id="more-help-and-discoverability-packages">More help and discoverability packages</h4>
<p>Sometimes, you start typing a key sequence but you can’t remember it
completely. Or, you wonder what other keybindings are related. Comes
<ahref="https://github.com/justbur/emacs-which-key">which-key-mode</a>. This
packages will display all possible keybindings starting with the key(s) you just typed.</p>
<p>For example, I know there are useful keybindings under <code>C-x</code> but I don’t remember which ones… I just type <code>C-x</code>, I wait for half a second, and which-key shows all the ones available.</p>
<p>See also <ahref="https://github.com/Wilfred/helpful">Helpful</a>, an alternative to the built-in Emacs help that provides much more contextual information.</p>
<p>Use <code>C-M-k</code> (<code>kill-sexp</code>) and <code>C-M-backspace</code> (<code>backward-kill-sexp</code>) (but caution: this keybinding may restart the system on GNU/Linux).</p>
<p>For example, if point is before <code>(progn</code> (I’ll use [] as an indication where the cursor is):</p>
<p>Use <code>C-x n n</code> (narrow-to-region) and <code>C-x n w</code> to widen back.</p>
<p>See also <ahref="http://wikemacs.org/wiki/Folding">code folding</a>.</p>
<h5id="comments">Comments</h5>
<p>Insert a comment, comment a region with <code>M-;</code>, adjust text with <code>M-q</code>.</p>
<p><aname="Slide-11"></a></p>
<h4id="evaluating-and-compiling-lisp-in-slime">Evaluating and Compiling Lisp in SLIME</h4>
<p>Compile the entire <strong>buffer</strong> by pressing <code>C-c C-k</code> (<code>slime-compile-and-load-file</code>).</p>
<p>Compile a <strong>region</strong> with <code>M-x slime-compile-region</code>.</p>
<p>Compile a <strong>defun</strong> by putting the cursor inside it and pressing <code>C-c C-c</code> (<code>slime-compile-defun</code>).</p>
<p>To <strong>evaluate</strong> rather than compile:</p>
<ul>
<li>evaluate the <strong>sexp</strong> before the point by putting the cursor after
its closing paren and pressing <code>C-x C-e</code>
(<code>slime-eval-last-expression</code>). The result is printed in the minibuffer.</li>
<li>similarly, use <code>C-c C-p</code> (<code>slime-pprint-eval-last-expression</code>) to eval and pretty-print the expression before point. It shows the result in a new “slime-description” window.</li>
<li>evaluate a region with <code>C-c C-r</code>,</li>
<li>evaluate a defun with <code>C-M-x</code>,</li>
<li>type <code>C-c C-e</code> (<code>slime-interactive-eval</code>) to get a prompt that asks for code to eval in the current context. It prints the result in the minibuffer. With a prefix argument, insert the result into the current buffer.</li>
<li>type <code>C-c C-j</code> (<code>slime-eval-last-expression-in-repl</code>), when the cursor is after the closing parenthesis of an expression, to send this expression to the REPL and evaluate it.</li>
</ul>
<p>See also other commands in the menu.</p>
<hr/>
<p><strong>EVALUATION VS COMPILATION</strong></p>
<p>There are a couple of pragmatic differences when choosing between compiling or evaluating.
In general, it is better to <em>compile</em> top-level forms, for two reasons:</p>
<ul>
<li>Compiling a top-level form highlights warnings and errors in the editor, whereas evaluation does not.</li>
<li>SLIME keeps track of line-numbers of compiled forms, but when a top-level form is evaluated, the file line number information is lost. That’s problematic for code navigation afterwards.</li>
</ul>
<p><code>eval</code> is still useful to observe results from individual non top-level forms. For example, say you have this function:</p>
<pre><codeclass="language-lisp">(defun foo ()
(let ((f (open "/home/mariano/test.lisp")))
...))
</code></pre>
<p>Go to the end of the OPEN expression and evaluate it (<code>C-x C-e</code>), to observe the result:</p>
<pre><code>=> #<SB-SYS:FD-STREAM for "file /mnt/e6b00b8f-9dad-4bf4-bd40-34b1e6d31f0a/home/marian/test.lisp" {1003AAAB53}>
</code></pre>
<p>Or on this example, with the cursor on the last parentheses, press <code>C-x C-e</code> to evaluate the <code>let</code>:</p>
<pre><codeclass="language-lisp">(let ((n 20))
(loop for i from 0 below n
do (print i)))
</code></pre>
<p>You should see numbers printed in the REPL.</p>
<p>See also <ahref="https://github.com/kaz-yos/eval-in-repl">eval-in-repl</a> to send any form to the repl.</p>
<p>Put the cursor on any symbol and press <code>M-.</code> (<code>slime-edit-definition</code>) to go to its
definition. Press <code>M-,</code> to come back.</p>
<h5id="go-to-symbol-list-symbols-in-current-source">Go to symbol, list symbols in current source</h5>
<p>Use <code>C-u M-.</code> (<code>slime-edit-definition</code> with a prefix argument, also available as <code>M-- M-.</code>) to autocomplete the symbol and navigate to it. This command always asks for a symbol even if the cursor is on one. It works with any loaded definition.Here’s a little <ahref="https://www.youtube.com/watch?v=ZAEt73JHup8">demonstration video</a>.</p>
<p>You can think of it as a <code>imenu</code> completion that always work for any Lisp symbol. Add in <ahref="https://common-lisp.net/project/slime/doc/html/Fuzzy-Completion.html">Slime’s fuzzy completion</a> for maximum powerness!</p>
<h5id="crossreferencing-find-whos-calling-referencing-setting-a-symbol">Crossreferencing: find who’s calling, referencing, setting a symbol</h5>
<p>Slime has nice cross-referencing facilities. For example, you can ask
what calls a particular function, what expands a macro, or where a global variable is being used.</p>
<p>Results are presented in a new buffer, listing the places which reference a particular entity.
From there, we can press Enter to go to the corresponding source line,
or more interestingly we can recompile the place at point by pressing <strong>C-c C-c</strong> on that
line. Likewise, <strong>C-c C-k</strong> will recompile all the references. This is useful when
modifying macros, inline functions, or constants.</p>
<p>The bindings are the following (they are also shown in Slime’s menu):</p>
<ul>
<li><strong>C-c C-w c</strong> (<code>slime-who-calls</code>) callers of a function</li>
<li><strong>C-c C-w m</strong> (<code>slime-who-macroexpands</code>) places where a macro is expanded</li>
<li><strong>C-c C-w r</strong> (<code>slime-who-references</code>) global variable references</li>
<li><strong>C-c C-w b</strong> (<code>slime-who-bind</code>) global variable bindings</li>
<li><strong>C-c C-w s</strong> (<code>slime-who-sets</code>) global variable setters</li>
<li><strong>C-c C-w a</strong> (<code>slime-who-specializes</code>) methods specialized on a symbol</li>
</ul>
<p>And when the <code>slime-asdf</code> contrib is enabled,
<li><strong>C-c C-d d</strong> shows the symbols’ documentation on a new window (same result as using <code>describe</code>).</li>
</ul>
<p>Other bindings which may be useful:</p>
<ul>
<li><strong>C-c C-d f</strong> describes a function</li>
<li><strong>C-c C-d h</strong> looks up the symbol documentation in CLHS by opening the web browser. But it works only on symbols, so there are two more bindings:</li>
<li><strong>C-c C-d #</strong> for reader macros</li>
<li><strong>C-c C-d ~</strong> for format directives</li>
<p>You can enhance the help buffer with the Slime extension <ahref="https://github.com/mmontone/slime-doc-contribs">slime-doc-contribs</a>. It will show more information in a nice looking buffer, and it will add choices to the documentation command:</p>
<ul>
<li><strong>slime-help-package</strong> will display information about a CL package: it will nicely show its exported variables, conditions, classes, generic functions, functions and macros, with their documentation. It is a great way to see at a glance what a package provides.</li>
<li><strong>slime-help-system</strong> does the same for a <em>system</em>.</li>
<li><strong>slime-help-apropos-documentation</strong> will show symbols whose documentation contains matches for “PATTERN”, which is a great way to lookup for functions.</li>
<p>You can call <code>(inspect 'symbol)</code> from the REPL or call it with <code>C-c I</code> from a source file.</p>
<h4id="macroexpand">Macroexpand</h4>
<p>Use <code>C-c M-m</code> to macroexpand a macro call</p>
<h4id="consult-the-hyper-spec-clhs-offline">Consult the Hyper Spec (CLHS) offline</h4>
<p>The <ahref="http://www.lispworks.com/documentation/common-lisp.html">Common Lisp Hyper Spec</a> is the
official online version of the ANSI Common Lisp standard. We can start
browsing it from <ahref="http://www.lispworks.com/documentation/HyperSpec/Front/StartPts.htm">starting points</a>:
a shortened <ahref="http://www.lispworks.com/documentation/HyperSpec/Front/Hilights.htm">table of contents of highlights</a>,
a <ahref="http://www.lispworks.com/documentation/HyperSpec/Front/Hilights.htm">symbols index</a>,
a glossary, a master index.</p>
<p>Since January of 2023, we have the Common Lisp Community Spec: <ahref="https://cl-community-spec.github.io/pages/index.html">https://cl-community-spec.github.io/pages/index.html</a>, a new web rendering of the specification. It is a more modern rendering:</p>
<ul>
<li>it has a <em>search box</em></li>
<li>it has <em>syntax highlihgting</em></li>
<li>it is hosted on GitHub and we have the right to modify it: https://github.com/fonol/cl-community-spec</li>
</ul>
<p>If you want other tools to do a quick look-up of symbols on the CLHS,
since the official website doesn’t have a search bar, you can use:</p>
<li>and we can use Duckduckgo’s or Brave Search’s <code>!clhs</code> “bang”.</li>
</ul>
<p>We can <strong>browse the CLHS offline</strong> with <ahref="https://kapeli.com/dash">Dash</a> on MacOS, <ahref="https://zealdocs.org/">Zeal</a> on GNU/Linux and <ahref="https://velocity.silverlakesoftware.com/">Velocity</a> on Windows.</p>
<p>But we can also browse it offline from Emacs. We have to install a CL package and to configure the Emacs side with one command:</p>
<p>Now, you can use <code>C-c C-d h</code> to look-up the symbol at point in the
HyperSpec. This will open your browser, but look at its URL starting
with “file://home/”: it opens a local file.</p>
<p>Other commands are available:</p>
<ul>
<li>when you want to look-up a reader macro, such as <code>#'</code>
(sharpsign-quote) or <code>(</code> (left-parenthesis), use
<code>M-x common-lisp-hyperspec-lookup-reader-macro</code>, bound to <code>C-c C-d #</code>.</li>
<li>to look-up a <code>format</code> directive, such as <code>~A</code>, use <code>M-x
common-lisp-hyperspec-format</code>, bound to <code>C-c C-d ~</code>.
<ul>
<li>of course, you can TAB-complete on Emacs’ minibuffer prompt to see all the available format directives.</li>
</ul>
</li>
<li>you can also look-up glossary terms (for example, you can look-up “function” instead of “defun”), use <code>M-x common-lisp-hyperspec-glossary-term</code>, bound to <code>C-c C-d g</code>.</li>
<p>From the REPL, we can use <code>,ql</code> to install a package known by name already.</p>
<p>In addition, we can use the <ahref="https://github.com/mmontone/quicklisp-systems">Quicklisp-systems</a> Slime extension to search, browse and load Quicklisp systems from Emacs.</p>
<h3id="questionsanswers">Questions/Answers</h3>
<h4id="utf-8-encoding">utf-8 encoding</h4>
<p>You might want to set this to your init file:</p>
<p><em>I am so used to C-c, C-v and friends to copy and paste text that
the default Emacs shortcuts don’t make any sense to me.</em></p>
<p>Luckily, you have a solution! Install <ahref="http://www.emacswiki.org/cgi-bin/wiki.pl?CuaMode">cua-mode</a> and you can continue to use these shortcuts.</p>
<li><ahref="https://bnmcgn.github.io/lisp-guide/lisp-exploration.html">Common Lisp REPLexploration guide</a> - a concise and curated set of highlights to find one’s way in the REPL.</li>
