*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| ====================================================================== 1. 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 /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 "/lisp/" directory (or a symlink pointing to it) is in your "/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 /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 =vlime#plugin#VlimeKey("tab") 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 S \ :call vlime#plugin#SendToREPL(vlime#ui#CurExprOrAtom()) 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 was already mapped. This may imply a key conflict. "Command already mapped": The command specified in was already mapped to. This usually means you have remapped 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* cc *vlime-mappings-conn-cc* Connect to Vlime server. 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. cd Disconnect. cR Rename the current connection. Server Management *vlime-mappings-invoke-server* rr *vlime-mappings-invoke-server-rr* Run a new Vlime server and connect to it. To customize the server, see |g:vlime_cl_impl|. rv View the console output of the current server. rV Show a list of Vlime servers and view the console output of the chosen one. rs *vlime-mappings-invoke-server-rs* Stop the current server. rS Show a list of Vlime servers and stop the chosen one. rR Rename a server. Sending Stuff To The REPL *vlime-mappings-send* 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. se Send the s-expression under the cursor to the REPL. st Send the top-level s-expression under the cursor to the REPL. sa Send the atom under the cursor to the REPL. si Open an input buffer and compose a snippet to send to the REPL. See |vlime-input-buffer|. s (In visual mode) Send the current selection to the REPL. Expanding Macros *vlime-mappings-expand-macros* mm Expand the macro under the cursor. m1 Expand the macro under the cursor once. ma Expand the macro under the cursor and all nested macros. Compiling *vlime-mappings-compile* oe Compile the form under the cursor. ot Compile the top-level form under the cursor. of Compile the current file. o (In visual mode) Compile the current selection. Cross References (xref) *vlime-mappings-invoke-xref* xc *vlime-mappings-invoke-xref-xc* Show callers of the function under the cursor. xC Show callees of the function under the cursor. xr Show references of the variable under the cursor. xb Show bindings of the variable under the cursor. xs Show who sets the value of the variable under the cursor. xe Show who expands the macro under the cursor. xm Show specialized methods for the class under the cursor. xd Show the definition for the name under the cursor. 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. "8xi" would look for definitions. See |vlime-input-buffer|. Describing Things *vlime-mappings-describe* do Describe the "operator" of the s-expression under the cursor. da Describe the atom under the cursor. di Prompt for the symbol to describe. See |vlime-input-buffer|. ds Apropos search. An input buffer would pop up, prompting for the search pattern. See |vlime-input-buffer|. ddo Show the documentation for the "operator" of the s-expression under the cursor. dda Show the documentation for the atom under the cursor. ddi Show the documentation for the symbol entered in an input buffer. See |vlime-input-buffer|. dr Show the arglist for the s-expression under the cursor. Undefining Things uf Undefine the function under the cursor. us Unintern the symbol under the cursor. 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. "2ui" would unintern a symbol. See |vlime-input-buffer|. Inspection *vlime-mappings-invoke-inspector* 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. Ii Same as II IE Evaluate and inspect the s-expression under the cursor. Ie Same as IE IT Evaluate and inspect the top-level s-expression under the cursor. It Same as It IA Evaluate and inspect the atom under the cursor. Ia Same as IA IN Prompt for the expression to inspect. See |vlime-input-buffer|. In Same as IN I (In visual mode) Evaluate and inspect the current selection. Invoking The Trace Dialog *vlime-mappings-invoke-trace-dialog* TD *vlime-mappings-invoke-trace-dialog-TD* Show the trace dialog. Td Same as TD TT Toggle the traced state of the function name under the cursor. Tt Same as TT 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 )". Ti Same as TI Closing Windows *vlime-mappings-close-window* wp Close all visible preview windows. wr Close all visible arglist windows. wn Close all visible compiler notes windows. wR Close all visible REPL windows. wA Close all Vlime windows. wl Show a list of visible Vlime windows, and choose which to close. Other Stuff *vlime-mappings-misc* i *vlime-mappings-misc-i* Interaction Mode. See |vlime-interaction-mode|. l Load the current file. a Disassemble the form under the cursor. p *vlime-mappings-misc-p* Specify the package for the current buffer. An input buffer would pop up for this. See |vlime-input-buffer|. b Set a breakpoint at entry to a function. An input buffer would pop up, prompting for the function name. See |vlime-input-buffer|. 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. I Inspect the evaluation result under the cursor. 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. C Clear the REPL buffer. Move the cursor to the next prensented object. CTRL-n Same as . CTRL-p Move the cursor to the previous presented object. ...................................................................... 4.3.3 Debugger Mappings *vlime-mappings-debugger* Key mappings available in the debugger: 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: Activate the interactable field/button under the cursor. Same as s Send the value of the field under the cursor to the REPL. S Send the value being inspected to the REPL. Select the next interactable field/button. CTRL-n Same as 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: 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" would show the source file in the second visible window. t Like , 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: c *vlime-mappings-server-c* Connect to this server. 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: Activate the interactable field/button under the cursor. Same as . s Send the value of the field under the cursor to the REPL. i Inspect the value of the field under the cursor. Select the next interactable field/button. CTRL-n Same as . 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: (In insert mode) Submit the text snippet between the last prompt and EOF to the REPL. CTRL-j (In insert mode) Insert a newline. (In insert mode) Trigger omni-completion. CTRL-c (In insert mode) Interrupt the MREPL thread. C Clear the MREPL buffer. 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_" 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 /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.