61 KiB
vlime.txt A Common Lisp dev environment for Vim vlime
====================================================================== CONTENTS vlime-contents
1. Introduction ................................ |vlime-intro|
2. Concepts ................................. |vlime-concepts|
3. Usage ....................................... |vlime-usage|
3.1 Starting Up ......................... |vlime-start-up|
3.2 Completions ...................... |vlime-completions|
3.3 Automatic Indentation ............ |vlime-auto-indent|
3.4 REPL .................................... |vlime-repl|
3.5 Debugger ............................ |vlime-debugger|
3.6 Inspector .......................... |vlime-inspector|
3.7 Cross References ........................ |vlime-xref|
3.8 Compiler Messages ............... |vlime-compiler-msg|
3.9 Managing Threads ................. |vlime-thread-list|
3.10 Remote Servers ................ |vlime-remote-server|
3.11 Input Buffers .................. |vlime-input-buffer|
3.12 Trace Dialog ................... |vlime-trace-dialog|
3.13 Multiple REPLs ........................ |vlime-mrepl|
3.14 Integrations ................... |vlime-integrations|
3.14.1 asyncomplete |vlime-integrations-asyncomplete|
4. Mappings ................................. |vlime-mappings|
4.1 Remap Keys .................... |vlime-mappings-remap|
4.2 Key Conflicts ................... |vlime-key-conflict|
4.3 List of Key Mappings ........... |vlime-mappings-list|
4.3.1 CL Source File Mappings |vlime-mappings-source|
4.3.2 REPL Buffer Mappings ..... |vlime-mappings-repl|
4.3.3 Debugger Mappings .... |vlime-mappings-debugger|
4.3.4 Inspector Mappings .. |vlime-mappings-inspector|
4.3.5 XRef List & Compiler Notes Mappings ..........
.......................... |vlime-mappings-xref|
4.3.6 Thread List Mappings .........................
................... |vlime-mappings-thread-list|
4.3.7 Server Output Buffer Mappings ................
........................ |vlime-mappings-server|
4.3.8 Input Buffer Mappings ... |vlime-mappings-input|
4.3.9 Trace Dialog Mappings ........................
.................. |vlime-mappings-trace-dialog|
4.3.10 MREPL buffer Mappings .. |vlime-mappings-mrepl|
4.4 Overlays ................... |vlime-mappings-overlays|
5. Configuration .............................. |vlime-config|
6. API ..................................... |vlime-api-intro|
7. License ................................... |vlime-license|
8. Bugs ......................................... |vlime-bugs|
9. Contributing .............................. |vlime-contrib|
======================================================================
- Introduction vlime-intro
Vlime is a Common Lisp dev environment for Vim, similar to SLIME for Emacs and SLIMV for Vim.
It provides REPL integration, as well as omni-completions, cross reference utilities, a nice inspector, debugger support, and many other great facilities to aid you in your glorious Common Lisp hacking quest.
These Common Lisp implementations are supported:
Implementation Version Notes
---------------------------------------------------------------
ABCL 1.4.0 Supported by the vlime-patched backend
Allegro CL 10.0 Tested with the Express Edition
CLISP 2.49+ No multithreading support
ECL 16.1.3 No debugger support
CCL 1.11
SBCL 1.3.13
LispWorks 6.1 Tested with the Personal Edition
====================================================================== 2. Concepts vlime-concepts
Connection vlime-connection A connection between Vim and a Vlime server. Most of Vlime's functionalities need an active connection to work. Each Vim process can have multiple connections. See |vlime-mappings-conn| for available operations regarding connections.
The Current Connection vlime-current-connection A connection (|vlime-connection|) that's bound to the current Vim buffer. All Vlime operations in the current buffer will use this connection. Vlime will try to choose and remember an open connection for a buffer automatically, but it's also possible to select one via |vlime-mappings-conn-cs|.
The Current Package vlime-current-package A Common Lisp package that's bound to the current Vim buffer. All Vlime operations that concern about the Common Lisp package, such as omni-completions, will use this value. Vlime will try to figure out the current package automatically, but it's also possible to specify a package via |vlime-mappings-misc-p|.
====================================================================== 3. Usage vlime-usage
3.1 Starting Up vlime-start-up
If you have sbcl in your $PATH, Vlime can start a server for you:
1. Set up Quicklisp properly.
2. Start editing a Common Lisp source file, and use
|vlime-mappings-invoke-server-rr| to run a server.
3. Wait for the server. Vlime will automatically connect to it
when it's ready, and become fully operational.
Note: If it's your first time running the server, Vlime will try to install it's dependencies via Quicklisp. This may take some time.
See |vlime-mappings-invoke-server| for more operations on Vlime servers, and |vlime-mappings-server| for operations available in the server output buffer. See |vlime-mappings| for all available Vlime operations.
When you need to use some other Common Lisp implementation, run an instance of sbcl in arbitrary locations, or pass special arguments to the server, use the |g:vlime_cl_impl| option.
*vlime-start-up-manually*
You may also start the server manually:
1. Set up Quicklisp properly.
2. Run the server:
sbcl --load <vlime repo>/lisp/start-vlime.lisp
3. Start editing a Common Lisp source file, and use
|vlime-mappings-conn-cc| to create a new
connection.
4. Vlime shoud now be fully operational.
*vlime-start-up-in-running-image*
If you have a running Common Lisp image, and want to start the server in it:
1. Make sure the Quicklisp client is loaded (by loading the
corresponding "setup.lisp" file, for example).
2. Make sure the "<vlime repo>/lisp/" directory (or a symlink
pointing to it) is in your "<quicklisp>/local-projects/"
directory.
3. Evaluate "(ql:quickload :vlime)" to load the bootstrapping
code.
4. Evaluate "(vlime:main)" to start the server, or something like
(vlime:main :interface #(127 0 0 1)
:port 7002
:backend :vlime-usocket)
to specify the backend and the address to bind to.
See |vlime-server-options| for a full list of parameters you can pass to the VLIME:MAIN function.
*vlime-server-backends*
Note that Vlime's server has three backends:
:vlime-usocket Suitable for environments that support
multithreading. Depends on usocket.
:vlime-sbcl Suitable for SBCL without multithreading.
Only works on Linux/Unix systems. Depends
on SBCL-specific APIs.
:vlime-patched Suitable for other environments. Patches
Swank to support the Vlime protocol. Has
the least dependencies.
The bootstrapping code takes special measures to automatically detect and load the correct backend. Usually you can just omit the :BACKEND argument of the VLIME:MAIN function.
*vlime-include-server-in-cl-image*
To include the Vlime server in your Common Lisp image, just load the VLIME system and at least one backend that works for your. For example, a typical SBCL image can be generated by:
(ql:quickload :vlime)
(ql:quickload :vlime-usocket)
(sb-ext:save-lisp-and-die ...)
To start the server, call "(vlime:main :backend :vlime-usocket)" in your running image.
*vlime-slime-secret*
When connecting to a server, Vlime will try to use the file "$HOME/.slime-secret" to authenticate the connection. Just put one single line containing a secret phrase in this file, make sure it's readable, and Vlime will automatically enable authentication for all connections.
*vlime-server-options*
The server entry point (i.e. the VLIME:MAIN function) accepts some keyword arguments to allow the caller to fine-tune server behavior:
:backend
One of the backends listed in |vlime-server-backends|, or NIL
to let the server choose a backend automatically. Default: NIL
:interface
A vector specifying the IP address of the interface to bind
to. Default: #(127 0 0 1)
:port
An integer specifying the TCP port number to listen on. A
value of zero tells the server to choose an arbitrary port.
Default: 0
:port-file
If this argument is not NIL, the server will write the port
number on which it's listening in the specified file, once the
server is fully operational. Default: NIL
:start-swank
Whether to start a Swank server or not. Usually the Vlime
server will start a Swank server automatically, and relay all
requests to it. If you have a Swank server that's already
running, and you want to use that instead, pass NIL to this
argument, and point :swank-interface and :swank-port to the
existing Swank server. Default: T
:swank-interface
When the :start-swank argument is T, this argument specifies
the interface that the new Swank server binds to. Otherwise
this should be the interface for a running Swank server.
Default: #(127 0 0 1)
:swank-port
When the :start-swank argument is T, this argument specifies
the port that the new Swank server listens on. Otherwise this
should be the port for a running Swank server. Default: 0
:dont-close
Do not shutdown the server after the first connection. Pass
NIL to allow one client only. Default: T
3.2 Completions vlime-completions
Pressing in insert mode will trigger omni-completion. Vlime has swank-fuzzy enabled by default, so you can, for example, input "vpe" and then press for "vector-push-extend".
Note: Vlime currently doesn't set a limit to the number of completion results showed. A large number of results may delay the completion menu a bit, temporarily showing the error message "Pattern not found".
3.3 Automatic Indentation vlime-auto-indent
The auto indent feature will just work as you type. It supports both space and tab characters. Which to use is determined by the |expandtab| Vim option.
To adjust mis-indented lines, press at the start of those lines in insert mode, or use |=| command.
Vlime has a set of indent rules that are similar to the ones SLIME used. Multi-line expressions are generally indented by the width of two space characters, regardless of the value of |shiftwidth|. Macros and special operators with "&BODY" arguments are treated specially, in that all the arguments before "&BODY" will be indented one more level. For example, MULTIPLE-VALUE-BIND has two arguments before "&BODY", so a call to it will be indented this way:
(multiple-value-bind
(val exist-p)
(gethash "key" hash-table)
(do-something)
(do-other-thing))
You can control how an operator and its arguments are indented using |g:vlime_indent_keywords|.
3.4 REPL vlime-repl
The REPL integration is different from other Lisp environments, in that Vlime's REPL buffer is read-only. One can send expressions to the REPL from any lisp source buffer using normal mode commands such as |vlime-mappings-send-ss|, instead of typing the input directly in the REPL buffer.
Note: It's a design decision to make the REPL buffer read-only, since emulating a command line in Vim buffers is often complicated and buggy.
When the REPL needs user input, e.g. (read) or (read-line) is being evaluated, a dedicated buffer for string input would pop up at the bottom. Write the input inside this buffer, and hit in normal mode, then the REPL would receive your text. The input buffer is a generic mechanism for the commands that need user input. See |vlime-input-buffer|.
*vlime-interaction-mode*
There's an interaction mode to make sending things to the REPL easier. It's enabled via |vlime-mappings-misc-i| in Common Lisp source buffers. In this mode, simply pressing will send the s-expression under the cursor.
One can inspect the evaluation results right from the REPL buffer. See |vlime-mappings-repl| for key mappings.
3.5 Debugger vlime-debugger
The debugger works just like SLDB in SLIME. It pops up a buffer when a condition is signalled. The buffer shows a list of restarts and a backtrace. One can press on a restart to select it.
The debugger can also do single-stepping, examine the local variables, restart frames, evaluate expressions in frames, etc., provided the Common Lisp implementation Vlime server is running on supports these. For more available operations in the debugger buffer, see |vlime-mappings-debugger|.
Note: Some debugger features are not supported by some Common Lisp implementations. These unsupported operations will most likely result in an error message.
3.6 Inspector vlime-inspector
The inspector can be used to examine the slot values of instances, the members of structs, the items of hashtables, etc. It's a very handy tool in many circumstances.
There're multiple ways to invoke the inspector, but the most convenient one is using |vlime-mappings-invoke-inspector-II| on an expression.
The content shown in the inspector buffer usually contains multiple interactable fields and buttons. Pressing will move the cursor between theses fields/buttons, and interact with them. If the interaction needs extra user input, an input buffer would pop up. See |vlime-input-buffer|.
For more available operations in the inspector buffer, see |vlime-mappings-inspector|.
3.7 Cross References vlime-xref
The cross references (a.k.a xref) buffer shows where a symbol is referenced. For example, use |vlime-mappings-invoke-xref-xc| on a function name to see where the function is called. Pressing on an entry inside the xref buffer will take you directly to the reference location.
For more xref types and key mappings, see |vlime-mappings-invoke-xref|. For all available key mappings in the xref buffer, see |vlime-mappings-xref|.
3.8 Compiler Messages vlime-compiler-msg
When issuing compilation commands specified in |vlime-mappings-compile|, any message (warnings and errors etc.) emitted by the compiler would pop up in a dedicated buffer. Just select a message by pressing , and Vlime will take you to the referenced source location.
For all available key mappings in the compiler message buffer, see |vlime-mappings-compiler-notes|.
3.9 Managing Threads vlime-thread-list
For CL implementations that support threads, there's a simple buffer that shows all running threads. Use |vlime-mappings-misc-t| to show it.
While in the thread list, you can perform tasks such as killing a thread, or activating the debugger in a thread. See |vlime-mappings-thread-list| for a full list of available operations.
3.10 Remote Servers vlime-remote-server
Vlime can connect to a server running on a remote machine. The most secure way is to use SSH tunnels. Say we want to run a Vlime server on Mars:
ssh watney@mars-hab \
-L 7002:localhost:7002 \
sbcl --load <vlime repo>/lisp/start-vlime.lisp
This command will also set up local port forwarding, so that we can connect to the server right here on Earth. Then, in Vim, call vlime#plugin#ConnectREPL():
:call vlime#plugin#ConnectREPL("127.0.0.1", 7002, "sftp://watney@mars-hab/", 5000)
The third argument is an SFTP URL to tell Vlime that all filenames returned by the server resides in the remote machine, and should be opened through SFTP. The last argument is the time to wait for the connection to be made, in milliseconds (Let's just pretend we can connect to Mars in 5 seconds). When running through a network with high latency, you may want to raise this value.
Note: When connecting to a remote server, relative file paths may cause problems. Please make sure the remote Vlime server runs in the directory that your paths are relative to. Vlime always tries to use absolute paths.
3.11 Input Buffers vlime-input-buffer
When Vlime needs user input, a dedicated input buffer would pop up. One can use it as a normal Vim buffer, to compose any text snippet in it, and then press in normal mode to submit the snippet to Vlime.
If the operation that brought up the input buffer can be cancelled, submitting an empty snippet would usually cancel that operation.
Submitted text snippets are remembered as a linear input history. You can move to the previous/next item in history with /. See |vlime-mappings-input|.
The input buffer can be customized using |FileType| |autocmd|s. For example, omni-completion and auto indent are not enabled in the input buffer by default, but you can enable them by adding these autocmds in your |vimrc|:
augroup CustomVlimeInputBuffer
autocmd!
autocmd FileType vlime_input inoremap <silent> <buffer> <tab> <c-r>=vlime#plugin#VlimeKey("tab")<cr>
autocmd FileType vlime_input setlocal omnifunc=vlime#plugin#CompleteFunc
autocmd FileType vlime_input setlocal indentexpr=vlime#plugin#CalcCurIndent()
augroup end
"Vlime_input" is the filetype set by Vlime to identify input buffers. See |vlime-buffer-types| for a full list of available filetypes.
3.12 Trace Dialog vlime-trace-dialog
Note: This feature needs the SWANK-TRACE-DIALOG contrib module. See |g:vlime_contribs| and |vlime#plugin#SwankRequire()|.
Vlime can trace functions and show the results in a dedicated window for you. It's called the trace dialog, named after the similar component in SLIME. One can use |vlime-mappings-invoke-trace-dialog-TD| to have it open.
The trace dialog will show two kinds of info: a list of traced functions, and the trace results. It also contains multiple interactable fields and buttons. You can navigate through these fields/buttons by pressing , and interact with them using .
Nested trace entries are folded by default. Use standard |fold-commands| to handle the |folds|.
For more available operations for the trace dialog, see |vlime-mappings-trace-dialog|, and |vlime-mappings-invoke-trace-dialog|.
3.13 Multiple REPLs vlime-mrepl
Note: This feature needs the SWANK-MREPL contrib module. See |g:vlime_contribs| and |vlime#plugin#SwankRequire()|. And it works best on CL implementations with multithreading support.
Vlime usually creates a single REPL upon connection. If this REPL were blocked by a time-consuming operation, the server may seem unresponsive. The multiple REPL support may come in handy in this case.
One can call |vlime#plugin#CreateMREPL()| to spawn a new REPL, and open an "mrepl" command line buffer automatically. Just enter |Insert| mode and use it as you may use any other REPL prompts. But note that the command line is somewhat fragile, in that it is implemented by simply extracting the text between the last prompt string and EOF. Modifying text outside this range may cause unexpected bahavior.
See |vlime-mappings-mrepl| for all available operations in the MREPL buffer.
3.14 Integrations vlime-integrations
...................................................................... 3.14.1 asyncomplete vlime-integrations-asyncomplete
Vlime provides an integration to asyncomplete.vim. The following configuration is required to enable it:
autocmd User asyncomplete_setup call asyncomplete#register_source(asyncomplete#sources#vlime#get_source_options({ 'priority': 10 }))
====================================================================== 4. Mappings vlime-mappings
Most normal mode and visual mode mappings in Vlime starts with ||, which defaults to the backslash "". If you feel uncomfortable reaching out for the backslash key, you may change it by adding this line to your |vimrc| file, to use the comma instead:
let maplocalleader = ","
Or, if you don't want to change your ||, set |g:vlime_leader| instead:
let g:vlime_leader = ","
You can type "?" (without the quote marks) in most of Vlime buffers, including Common Lisp source files, to see a quick reference for the exact mappings defined in those buffers.
4.1 Remap Keys vlime-mappings-remap
You can also remap a single function using |FileType| |autocmd|s. Vlime will automatically skip the Vlime functions mapped in your |vimrc|. For example:
augroup LocalVlimeKeys
autocmd!
autocmd FileType lisp nnoremap <silent> <buffer> <LocalLeader>S
\ :call vlime#plugin#SendToREPL(vlime#ui#CurExprOrAtom())<cr>
augroup end
This will change the mapping for |vlime-mappings-send-ss| from "ss" to "S".
*vlime-buffer-types*
Vlime uses these filetypes to distiguish different buffers:
lisp Normal Lisp source file.
vlime_sldb The debugger buffer.
vlime_repl The REPL buffer.
vlime_inspector The inspector buffer.
vlime_xref The cross reference buffer.
vlime_notes The compiler notes buffer.
vlime_threads The threads buffer.
vlime_server The server output buffer.
vlime_preview The preview buffer.
vlime_arglist The arglist buffer.
vlime_input The input buffer.
vlime_trace The trace dialog buffer.
vlime_mrepl The MREPL buffer.
You can remap any Vlime key mapping in these buffers. See the source code (autoload/vlime/ui/mapping.vim) for all default mappings.
4.2 Key Conflicts vlime-key-conflict
Vlime tries to be nice when mapping the default keys. If a key sequence was already mapped, Vlime would NOT overwrite the existing mapping. You'll have to resolve the conflict either by remapping the Vlime function or by disabling the existing mapping. If you don't want this behavior, use |g:vlime_force_default_keys| to force Vlime to always override existing mappings.
*g:vlime_skipped_mappings*
When Vlime detects any conflicting default mappings, it will log them in the global variable g:vlime_skipped_mappings, which is a |dict|, in the following format:
{ "": { " ": ["", ""], ... }, ... }
The designates which buffer should these mappings be applied to. The is a single character designating the Vim mode, as described in |map-listing|. and are things to be mapped. And describes why this mapping was skipped. There are currently two possible reasons:
"Key already mapped":
The key combination specified in <key> was already mapped.
This may imply a key conflict.
"Command already mapped":
The command specified in <command> was already mapped to. This
usually means you have remapped <command> to other keys.
Reports with this reason can be safely ignored.
If you are using the default Vlime mappings, and some of them don't work properly, you should inspect g:vlime_skipped_mappings, and resolve key conflicts, if any. Use the method described in |vlime-mappings-remap| to remap keys or forcibly override existing mappings.
4.3 List of Key Mappings vlime-mappings-list
All the mappings listed below are defined in normal mode, unless specified otherwise.
...................................................................... 4.3.1 CL Source File Mappings vlime-mappings-source
Key mappings available in lisp source files:
Connection Management *vlime-mappings-conn*
<LocalLeader>cc *vlime-mappings-conn-cc*
Connect to Vlime server.
<LocalLeader>cs *vlime-mappings-conn-cs*
Switch Vlime connections. This command shows a list of
connections, and the current connection will be marked
with an asterisk "*" at the end.
<LocalLeader>cd
Disconnect.
<LocalLeader>cR
Rename the current connection.
Server Management *vlime-mappings-invoke-server*
<LocalLeader>rr *vlime-mappings-invoke-server-rr*
Run a new Vlime server and connect to it. To customize the
server, see |g:vlime_cl_impl|.
<LocalLeader>rv
View the console output of the current server.
<LocalLeader>rV
Show a list of Vlime servers and view the console output of the chosen one.
<LocalLeader>rs *vlime-mappings-invoke-server-rs*
Stop the current server.
<LocalLeader>rS
Show a list of Vlime servers and stop the chosen one.
<LocalLeader>rR
Rename a server.
Sending Stuff To The REPL *vlime-mappings-send*
<LocalLeader>ss *vlime-mappings-send-ss*
If there's an s-expression under the cursor, send it to
the REPL, else send the atom under the cursor, if any.
<LocalLeader>se
Send the s-expression under the cursor to the REPL.
<LocalLeader>st
Send the top-level s-expression under the cursor to the
REPL.
<LocalLeader>sa
Send the atom under the cursor to the REPL.
<LocalLeader>si
Open an input buffer and compose a snippet to send to the
REPL. See |vlime-input-buffer|.
<LocalLeader>s
(In visual mode) Send the current selection to the REPL.
Expanding Macros *vlime-mappings-expand-macros*
<LocalLeader>mm
Expand the macro under the cursor.
<LocalLeader>m1
Expand the macro under the cursor once.
<LocalLeader>ma
Expand the macro under the cursor and all nested macros.
Compiling *vlime-mappings-compile*
<LocalLeader>oe
Compile the form under the cursor.
<LocalLeader>ot
Compile the top-level form under the cursor.
<LocalLeader>of
Compile the current file.
<LocalLeader>o
(In visual mode) Compile the current selection.
Cross References (xref) *vlime-mappings-invoke-xref*
<LocalLeader>xc *vlime-mappings-invoke-xref-xc*
Show callers of the function under the cursor.
<LocalLeader>xC
Show callees of the function under the cursor.
<LocalLeader>xr
Show references of the variable under the cursor.
<LocalLeader>xb
Show bindings of the variable under the cursor.
<LocalLeader>xs
Show who sets the value of the variable under the cursor.
<LocalLeader>xe
Show who expands the macro under the cursor.
<LocalLeader>xm
Show specialized methods for the class under the cursor.
<LocalLeader>xd
Show the definition for the name under the cursor.
<LocalLeader>xi
Interactively prompt for the symbol to search. A menu will
pop up, to let you choose from xref types. You can prepend
a count to skip this menu, e.g. "8<LocalLeader>xi" would
look for definitions. See |vlime-input-buffer|.
Describing Things *vlime-mappings-describe*
<LocalLeader>do
Describe the "operator" of the s-expression under the
cursor.
<LocalLeader>da
Describe the atom under the cursor.
<LocalLeader>di
Prompt for the symbol to describe. See
|vlime-input-buffer|.
<LocalLeader>ds
Apropos search. An input buffer would pop up, prompting
for the search pattern. See |vlime-input-buffer|.
<LocalLeader>ddo
Show the documentation for the "operator" of the
s-expression under the cursor.
<LocalLeader>dda
Show the documentation for the atom under the cursor.
<LocalLeader>ddi
Show the documentation for the symbol entered in an input
buffer. See |vlime-input-buffer|.
<LocalLeader>dr
Show the arglist for the s-expression under the cursor.
Undefining Things
<LocalLeader>uf
Undefine the function under the cursor.
<LocalLeader>us
Unintern the symbol under the cursor.
<LocalLeader>ui
Interactively prompt for the function/symbol to
undefine/unintern. A menu will pop up, to let you choose
what to do. You can prepend a count to skip this menu,
e.g. "2<LocalLeader>ui" would unintern a symbol. See
|vlime-input-buffer|.
Inspection *vlime-mappings-invoke-inspector*
<LocalLeader>II *vlime-mappings-invoke-inspector-II*
If there's an s-expression under the cursor, evaluate it,
else evaluate the atom under the cursor, if any. The
evaluation result is then shown in the inspector.
<LocalLeader>Ii
Same as <LocalLeader>II
<LocalLeader>IE
Evaluate and inspect the s-expression under the cursor.
<LocalLeader>Ie
Same as <LocalLeader>IE
<LocalLeader>IT
Evaluate and inspect the top-level s-expression under the
cursor.
<LocalLeader>It
Same as <LocalLeader>It
<LocalLeader>IA
Evaluate and inspect the atom under the cursor.
<LocalLeader>Ia
Same as <LocalLeader>IA
<LocalLeader>IN
Prompt for the expression to inspect. See
|vlime-input-buffer|.
<LocalLeader>In
Same as <LocalLeader>IN
<LocalLeader>I
(In visual mode) Evaluate and inspect the current
selection.
Invoking The Trace Dialog *vlime-mappings-invoke-trace-dialog*
<LocalLeader>TD *vlime-mappings-invoke-trace-dialog-TD*
Show the trace dialog.
<LocalLeader>Td
Same as <LocalLeader>TD
<LocalLeader>TT
Toggle the traced state of the function name under the
cursor.
<LocalLeader>Tt
Same as <LocalLeader>TT
<LocalLeader>TI
Show an input buffer, and prompt for the name of the
function to be traced. See |vlime-input-buffer|. You can
also trace setf expanders by specifying "(setf <name>)".
<LocalLeader>Ti
Same as <LocalLeader>TI
Closing Windows *vlime-mappings-close-window*
<LocalLeader>wp
Close all visible preview windows.
<LocalLeader>wr
Close all visible arglist windows.
<LocalLeader>wn
Close all visible compiler notes windows.
<LocalLeader>wR
Close all visible REPL windows.
<LocalLeader>wA
Close all Vlime windows.
<LocalLeader>wl
Show a list of visible Vlime windows, and choose which to
close.
Other Stuff *vlime-mappings-misc*
<LocalLeader>i *vlime-mappings-misc-i*
Interaction Mode. See |vlime-interaction-mode|.
<LocalLeader>l
Load the current file.
<LocalLeader>a
Disassemble the form under the cursor.
<LocalLeader>p *vlime-mappings-misc-p*
Specify the package for the current buffer. An input
buffer would pop up for this. See |vlime-input-buffer|.
<LocalLeader>b
Set a breakpoint at entry to a function. An input buffer
would pop up, prompting for the function name. See
|vlime-input-buffer|.
<LocalLeader>t *vlime-mappings-misc-t*
Show a list of the running threads. See
|vlime-thread-list|.
...................................................................... 4.3.2 REPL Buffer Mappings vlime-mappings-repl
Key mappings avaialble in the REPL buffer:
CTRL-c
Interrupt the REPL thread.
<LocalLeader>I
Inspect the evaluation result under the cursor.
<LocalLeader>y *vlime-mappings-repl-y*
Yank the evaluation result under the cursor into the default
register |quotequote|. Note that this yanked value is an
expression to be evaluated in the same REPL session. It is
meaningless in other contexts.
<LocalLeader>C
Clear the REPL buffer.
<Tab>
Move the cursor to the next prensented object.
CTRL-n
Same as <Tab>.
CTRL-p
Move the cursor to the previous presented object.
...................................................................... 4.3.3 Debugger Mappings vlime-mappings-debugger
Key mappings available in the debugger:
<CR>
Choose a restart.
d
Show the details (local variables and source location etc.)
of the frame under the cursor.
S
Jump to the source code for the frame under the cursor. If the
source file is already opened in a window, simply move the
cursor to that window. Otherwise, this command opens the
source file in the current window by default. A count can be
prepended to specify which window to use. For example, "2S"
would open the source file in the second visible window.
T
Like "S", but open the source file in a new tab, if it's not
yet opened in any window. To always create a new tab, prepend
an arbitrary count, such as "1T".
r
Restart the frame under the cursor.
s
Start stepping in the frame under the cursor.
x
Step over the current function call.
o
Step out of the current function.
c
Invoke the restart labeled CONTINUE.
a
Invoke the restart labeled ABORT.
C
Inspect the current condition object.
i *vlime-mappings-debugger-i*
Evaluate and inspect an expression in the frame under the
cursor. An input buffer would pop up, prompting for the
expression. See |vlime-input-buffer|.
e
Evaluate an expression in the frame under the cursor. An input
buffer would pop up, prompting for the expression. See
|vlime-input-buffer|.
E
Evaluate an expression in the frame under the cursor, and then
send the result to the REPL, so that you can yank the value
with |vlime-mappings-repl-y| and further manipulate it. An
input buffer would pop up, prompting for the expression. See
|vlime-input-buffer|.
D
Disassemble the frame under the cursor.
R
Return a manually specified result from the frame under the
cursor. An input buffer would pop up, prompting for the
expression that would generate the result. See
|vlime-input-buffer|.
...................................................................... 4.3.4 Inspector Mappings vlime-mappings-inspector
Key mappings avaialble in the inspector:
<CR>
Activate the interactable field/button under the cursor.
<Space>
Same as <CR>
s
Send the value of the field under the cursor to the REPL.
S
Send the value being inspected to the REPL.
<Tab>
Select the next interactable field/button.
CTRL-n
Same as <Tab>
CTRL-p
Select the previous interactable field/button.
p
Return to the previous inspected object.
P
Move to the next inspected object.
R
Refresh the inspector.
...................................................................... 4.3.5 XRef List & Compiler Notes Mappings vlime-mappings-xref vlime-mappings-compiler-notes
Key mappings avaialble in the cross reference list and the compiler notes window:
<CR>
Jump to the selected source location. If the source file is
already opened, simply move the cursor to the window
containing that file. Otherwise, open the source file in the
window where the xref command was initiated. A count can be
prepended to specify which window to use. For example, "2<CR>"
would show the source file in the second visible window.
t
Like <CR>, but open the source file in a new tab, if it's not
yet opened in any window. To always create a new tab, prepend
an arbitrary count, such as "1t".
s
Open the selected source location in a horizontal split
window. A count can be prepended to specify which window to
split.
S
Like "s", but open a vertical split window.
...................................................................... 4.3.6 Thread List Mappings vlime-mappings-thread-list
Key mappings avaialble in the thread list:
CTRL-c
Interrupt the thread under the cursor. The debugger will be
activated.
K
Kill the thread under the cursor.
D
Invoke the debugger in the thread under the cursor.
r
Refresh the thread list.
...................................................................... 4.3.7 Server Output Buffer Mappings vlime-mappings-server
Key mappings avaialble in the server output buffer:
<LocalLeader>c *vlime-mappings-server-c*
Connect to this server.
<LocalLeader>s
Stop this server.
...................................................................... 4.3.8 Input Buffer Mappings vlime-mappings-input
Key mappings avaialble in the input buffer:
CTRL-p or Shift-Tab
Show the previous item in input history.
CTRL-n or Tab
Show the next item in input history.
...................................................................... 4.3.9 Trace Dialog Mappings vlime-mappings-trace-dialog
Key mappings avaialble in the trace dialog:
<CR>
Activate the interactable field/button under the cursor.
<Space>
Same as <CR>.
s
Send the value of the field under the cursor to the REPL.
i
Inspect the value of the field under the cursor.
<Tab>
Select the next interactable field/button.
CTRL-n
Same as <Tab>.
CTRL-p
Select the previous interactable field/button.
R
Refresh the trace dialog.
...................................................................... 4.3.10 MREPL Buffer Mappings vlime-mappings-mrepl
Key mappings avaialble in the MREPL buffer:
<CR>
(In insert mode) Submit the text snippet between the last
prompt and EOF to the REPL.
CTRL-j
(In insert mode) Insert a newline.
<Tab>
(In insert mode) Trigger omni-completion.
CTRL-c
(In insert mode) Interrupt the MREPL thread.
<LocalLeader>C
Clear the MREPL buffer.
<LocalLeader>D
Disconnect from this REPL.
4.4 Overlays vlime-mappings-overlays
Vlime has a huge set of key mappings, which was mostly defined to the author's liking. It's sometimes desirable to provide a full different set of mappings to suit one's specific needs. Vlime provides Overlays for this.
An overlay is basically a hook into Vlime's initialization process. One can redefine all the default mappings, and even create new behavior in an overlay. Use |g:vlime_overlay| to specify which overlay to use.
*vlime-mappings-slimv*
Currently Vlime has only one overlay built-in, which mimics the behavior of Slimv. It provides most of Slimv's default mappings, and recognizes the g:slimv_leader and g:slimv_keybindings options. Please consult the Slimv manual for explanations of these options and the default key mappings. Note that there are still differences in mappings and behavior, you may optionally check the quick reference by typing ",?" (without the quote marks) in a Common Lisp source file buffer, to confirm what features are mapped.
To use the Slimv overlay, add this to your vimrc:
let g:vlime_overlay = "slimv"
====================================================================== 5. Configuration vlime-config
These variables can be set in |vimrc|, to affect the behavior of Vlime:
g:vlime_force_default_keys g:vlime_force_default_keys A boolean flag to tell Vlime to always use the default key mappings. See |vlime-key-conflict|. Default: v:false
g:vlime_leader g:vlime_leader A |string| to override the leader key used in Vlime key mappings. This supersedes |maplocalleader|. Please use key notations for special keys, as described in |key-notation|. For example, setting this variable to "" would instruct Vlime to use the space key as the leader. Also see |vlime-mappings|. Default: ""
g:vlime_cl_impl g:vlime_cl_impl A |string| to designate the CL implementation to use when starting a server via |vlime-mappings-invoke-server-rr|. This option has no effect when connecting to an existing server via |vlime-mappings-conn-cc|. Default: "sbcl"
You can define a function named
"VlimeBuildServerCommandFor_<impl>" to build a command line for
your implementation. For maximum compatibility, this function
should return a list containing all the command line components.
See |job_start()| in Vim or |jobstart()| in Neovim for detailed
explanation on command lines.
For example, to use a custom SBCL and a custom Quicklisp setup,
add these to your |vimrc|:
let g:vlime_cl_impl = "my_sbcl"
function! VlimeBuildServerCommandFor_my_sbcl(vlime_loader, vlime_eval)
return ["/path/to/my/custom/sbcl",
\ "--load", "/path/to/my/custom/quicklisp/setup.lisp",
\ "--load", a:vlime_loader,
\ "--eval", a:vlime_eval]
endfunction
Or, if you prefer using Roswell to manage your implementations:
let g:vlime_cl_impl = "ros"
function! VlimeBuildServerCommandFor_ros(vlime_loader, vlime_eval)
return ["ros", "run",
\ "--load", a:vlime_loader,
\ "--eval", a:vlime_eval]
endfunction
Then restart Vim and call vlime#server#BuildServerCommand() to see
whether the new command is OK:
:echo vlime#server#BuildServerCommand()
The command returned by vlime#server#BuildServerCommand() will be
executed to start a Vlime server when the
|vlime-mappings-invoke-server-rr| command is invoked.
Vlime has these builder functions predefined:
" For SBCL, the default
vlime#server#BuildServerCommandFor_sbcl()
" For Clozure CL, set g:vlime_cl_impl to "ccl"
vlime#server#BuildServerCommandFor_ccl()
If you use other implementations, such as clisp and abcl, or need
to pass special arguments to the server, you'll need to define the
builder functions.
Note: If you use symlinks on Windows systems to point to Vlime, it may fail to locate the server entry point automatically. In this case you'll have to define a command builder function and overwrite "vlime_loader" with the absolute path of "load-vlime.lisp":
function! VlimeBuildServerCommandFor_xxx(vlime_loader, vlime_eval)
return ["sbcl",
\ "--load", "c:\\path\\to\\vlime\\lisp\\load-vlime.lisp",
\ "--eval", a:vlime_eval]
endfunction
g:vlime_cl_use_terminal g:vlime_cl_use_terminal When starting a server via |vlime-mappings-invoke-server-rr|, and if this flag is |TRUE|, Vlime will use a terminal emulator built-in to Vim (or Neovim) to show the server output, so you can interact with the Common Lisp process directly. If this flag is set to |FALSE|, a plain buffer will be used, and no input to the Common Lisp process will be allowed. See |terminal|. Default: v:false
g:vlime_cl_wait_time g:vlime_cl_wait_time DEPRECATED: Vlime now uses async callbacks to handle server start-up/tear-down events. Setting this option has no effect at all.
An integer specifying the time Vlime should wait when starting a
server via |vlime-mappings-invoke-server-rr|, or stopping a server
via |vlime-mappings-invoke-server-rs|, in seconds. Default: 10
g:vlime_address g:vlime_address A |list| specifying the default address of the Vlime server. This address will be used as the default host and port values in the |vlime-mappings-conn-cc| command. Default: ["127.0.0.1", 7002]
g:vlime_connect_timeout g:vlime_connect_timeout An integer specifying the time to wait when connecting to the server, in milliseconds. If set to |v:null|, Vlime would try to use the default timeout values on different platforms. Default: v:null
g:vlime_compiler_policy g:vlime_compiler_policy A |dict| to hold the compiler policy. Setting this variable would affect the subsequent compiling operations. For example, a value of {"DEBUG": 3, "SPEED": 0} means no optimization in runtime speed, and maximum debug info. Note that the keys are case-sensitive. Please use only uppercase. Default: {}
g:vlime_window_settings g:vlime_window_settings A |dict| to specify window positions and sizes. Vlime will consult this variable when creating a new window. The keys should be Vlime window types, and the values should be |dict|s containing "pos", "size", and "vertical" parameters. For example:
let g:vlime_window_settings = {
\ "sldb": {
\ "pos": "botright",
\ "size": 60,
\ "vertical": v:true
\ }
\ }
These settings will cause the debugger window to be created
on the right, vertically.
You can also replace the window parameters dict with a |Funcref|
or a |lambda| expression to generate the parameters dynamically:
let g:vlime_window_settings = {
\ "sldb": { -> {"pos": "belowright", "size": winheight(".") / 3}}
\ }
With this setting, the debugger window will be one third of the
current window size.
*vlime-window-types*
Available window types:
"sldb" The debugger window.
"repl" The REPL window.
"inspector" The inspector window.
"xref" The cross reference window.
"notes" The compiler notes window.
"threads" The threads window.
"preview" The preview window.
"arglist" The arglist window.
"input" The input buffer window.
"server" The server output window.
"trace" The trace dialog window.
"mrepl" The MREPL window.
Legal values for the parameters:
"pos":
"aboveleft", "belowright", "topleft", "botright".
(See |aboveleft| and the alike to get explanations of
these positions)
"size":
Any positive integer, or v:null to tell Vlime not to
resize the window.
"vertical":
v:true or v:false.
*g:vlime_default_window_settings*
Vlime will try to use default values when any of these parameters
are missing. See the value of g:vlime_default_window_settings for
the defaults. This variable uses the same format as
|g:vlime_window_settings|. For example, to see the default
settings for the debugger window, run this in Vim after Vlime was
loaded:
:echo g:vlime_default_window_settings["sldb"]
g:vlime_indent_keywords g:vlime_indent_keywords A |dict| specifying indent rules for operators. The keys should be operator names in lowercase, and the values should be the number of arguments before "&BODY", or other numbers that you prefer. Also see |vlime-auto-indent|. For example,
let g:vlime_indent_keywords = {"dummy-op": 1}
Will cause a DUMMY-OP expression to be indented this way:
(dummy-op
expr1
expr2
expr3
...)
And
let g:vlime_indent_keywords = {"dummy-op": 2}
Will cause the same expression to be indented this way:
(dummy-op
expr1
expr2
expr3
...)
To see the default operator indent settings,
:echo g:vlime_default_indent_keywords
g:vlime_input_history_limit g:vlime_input_history_limit An integer to specify how many input history items to store. A non-positive value disables input history. See |vlime-input-buffer|. Default: 200
g:vlime_contribs g:vlime_contribs A |list| of Swank contribs to load when initializing a Vlime connection. Note that the names are case-sensitive. Please use only uppercase. Default: ["SWANK-ASDF", "SWANK-PACKAGE-FU", "SWANK-PRESENTATIONS", "SWANK-FANCY-INSPECTOR", "SWANK-C-P-C", "SWANK-ARGLISTS", "SWANK-REPL", "SWANK-FUZZY"]
Some contrib modules will just work once they are loaded, but
others may need specialized support on the client side. Vlime
elaborately supports these contribs by providing conforming client
code:
SWANK-ARGLISTS
Show a fancy arglist. See |g:vlime_enable_autodoc|.
SWANK-FUZZY
Enable fuzzy search in completions. See
|vlime-completions|.
SWANK-MREPL
Support for multiple REPLs. See |vlime-mrepl|.
SWANK-PRESENTATION-STREAMS
Enable presentations on the standard output stream, and
other similar streams, so that you can use
|vlime-mappings-repl-y| and similar mappings on printed
objects.
SWANK-PRESENTATIONS
Turn evaluation results in the REPL into presentations,
so that you can use |vlime-mappings-repl-y| and similar
mappings on the results.
SWANK-REPL
The default REPL implementation.
SWANK-TRACE-DIALOG
Interactively trace functions, and view the trace results.
See |vlime-trace-dialog|.
Please consult the SLIME documentation for detailed descriptions
for these modules.
Alternatively, you can call |vlime#plugin#SwankRequire()| to load
contrib modules.
g:vlime_user_contrib_initializers g:vlime_user_contrib_initializers A |dict| of |Funcref|s for initializing user contrib modules. The keys should be contrib module names (usually in uppercase). If your Swank contrib module needs special initialization, add an initializer function here. See autoload/vlime/contrib.vim for examples. Default: {}
g:vlime_enable_autodoc g:vlime_enable_autodoc A boolean value specifying whether to enable the autodoc feature or not. If enabled, the current argument will be marked in the arglist, when typing parentheses-enclosed expressions. Default: v:false
g:vlime_autodoc_max_level g:vlime_autodoc_max_level A positive integer specifying how many levels of enclosing parentheses should Vlime search for, when determining the arglist for the autodoc feature. Setting this to a smaller value may improve performance. Default: 5
g:vlime_autodoc_max_lines g:vlime_autodoc_max_lines A positive integer specifying how many lines to search, when determining the arglist for the autodoc feature. Setting this to a smaller value may improve performance. Default: 50
g:vlime_overlay g:vlime_overlay A |string| specifying which overlay to use. Set it to an empty string or |unlet| this variable to disable overlays. See |vlime-mappings-overlays| for an explanation of overlays. Default: ""
g:vlime_buf_name_sep g:vlime_buf_name_sep A |string| used as the separator between segments of Vlime special buffer names. The default works fine on Linux and Windows, but if your OS or Vim complained about illegal characters in filenames, try changing this variable. Default: " | "
====================================================================== 6. API vlime-api-intro
Vlime's source code on the Vim side is roughly organized into these groups, and some of them are exported to be user-callable APIs:
"vlime#plugin#..." functions
Top-level entry points to Vlime features. Most of Vlime's key
mappings are mapped to these functions. Some of these
functions are exported as APIs. See |vlime-api-functions|.
"vlime#ui#..." functions
UI-related code, which handles user input and special windows
etc. Some of these functions are exported as APIs. See
|vlime-api-functions|.
"vlime#connection#..." functions
Connection management. Internal use only.
"vlime#server#..." functions
Server management. Internal use only.
"vlime#contrib#..." functions
Support for Swank contrib modules. Internal use only.
"vlime#compat#..." functions
Compatibility code, dealing with the differences between Vim
and Neovim. Internal use only.
|vlime-api.VlimeConnection| object
The low-level code encapsulating Vlime's protocol and Swank
messages. Most of the methods are exported as APIs.
Simply put, when you want to build something on top of Vlime's infrastructure, start from the top-level "vlime#plugin#..." API functions. Then, if you don't find what you want in the top-level API, resort to the |vlime-api.VlimeConnection| object, and maybe the "vlime#ui#..." API functions.
All exported APIs are listed in |vlime-api-functions| and |vlime-api.VlimeConnection|. You can take a glance at the documentation to see what exactly a certain group of functions can do.
Note that The API documentation is far from complete. When in doubt, use the source. And please file an issue if you find any mistake in it (see |vlime-contrib|).
====================================================================== 7. License vlime-license
This plugin is licensed under the terms of the MIT license. See LICENSE.txt for details.
====================================================================== 8. Bugs vlime-bugs
-
In Vim prior to version 8.0.0312, there was a bug in the channel implementation that caused large messages to be dropped incorrectly. Channel messages from Vlime server can be quite large, so using 8.0.0312 or a more recent version is strongly recommended.
-
Vlime is asynchronous. When the server takes too much time to process a request, you can still invoke other commands or input text, but the delayed result may cause some interference when it arrives.
-
The Vim interface may sometimes freeze until a command is issued (e.g. move the cursor).
Please file an issue on https://github.com/l04m33/vlime/issues if you find any other problem.
====================================================================== 9. Contributing vlime-contrib
The source repo for Vlime is hosted on GitHub:
https://github.com/l04m33/vlime
Please send pull requests, and feel free to contact me at l04m33(at)gmail.com if you have any suggestions for improving Vlime.
*vlime-tests*
To make sure Vlime works as intended on your platform, or to check if something is broken after patching, it's recommended to run the tests.
To run the tests for the client side, make sure you have the Vim plugin properly installed, and then source the test runner script:
vim -S <vlime repo>/vim/test/run_tests.vim
To run the tests for the server side, make sure "/lisp" directory is in your "/local-projects" directory (or make a symlink), and then run the tests:
sbcl --eval "(ql:quickload '(:vlime-test :vlime-sbcl-test))" \
--eval "(test-with-coverage:main '(:vlime :vlime-sbcl) \"/path/to/coverage/output/\")" \
--quit
The coverage output is only available for SBCL. If you're using another implementation, or don't care about the coverage, just call "(asdf:test-system ...)" directly. For example, using CCL:
ccl --eval "(ql:quickload '(:vlime-test))" \
--eval "(asdf:test-system 'vlime)" \
--eval "(quit)"
The tests (both client-side and server-side) are organized in a rather simple/naive way. Please refer to the existing test code if you want to add new tests.