diff --git a/lisp/vlime-api.md b/lisp/vlime-api.md new file mode 100644 index 0000000..c499414 --- /dev/null +++ b/lisp/vlime-api.md @@ -0,0 +1,1153 @@ +*vlime-api.txt*....................................................*vlime-api* + +* [link to source](https://github.com/vlime/vlime/blob/master/vim/doc/vlime-api.txt) + +============================================================================== +CONTENTS *vlime-api-contents* + 1. Dictionaries............................................|vlime-api-dicts| + 2. Functions...........................................|vlime-api-functions| + +============================================================================== +DICTIONARIES *vlime-api-dicts* + + *vlime-api.VlimeConnection* +Vlime uses |vlime-api.VlimeConnection| objects to represent connections to the +servers. You can create such an object by calling |vlime#plugin#ConnectREPL()| +or |vlime#New()|. + +Most of the connection object's methods are thin wrappers around raw +SLIME/SWANK messages, and they are asynchronous. These async methods have an +optional callback argument, to allow a function be registered for handling the +result returned by the server. The callback functions should accept two +arguments: + + function! SomeCallbackFunc({conn_obj}, {result}) ... + +{conn_obj} is the connection object in question, and {result} is the returned +value. + +See below for a detailed list of methods for |vlime-api.VlimeConnection| +objects. + + +VlimeConnection.Connect({host}, {port}, [remote_prefix], [timeout]) + *VlimeConnection.Connect()* + + Connect to a server. + + {host} and {port} specify the server to connect to. [remote_prefix], if + specified, is an SFTP URL prefix, to tell Vlime to open remote files via + SFTP (see |vlime-remote-server|). [timeout] is the time to wait for the + connection to be made, in milliseconds. + +VlimeConnection.IsConnected() *VlimeConnection.IsConnected()* + + Return |TRUE| for a connected connection, |FALSE| otherwise. + +VlimeConnection.Close() *VlimeConnection.Close()* + + Close this connection. + +VlimeConnection.Call({msg}) *VlimeConnection.Call()* + + Send a raw message {msg} to the server, and wait for a reply. + +VlimeConnection.Send({msg}, [callback]) *VlimeConnection.Send()* + + Send a raw message {msg} to the server, and optionally register an async + [callback] function to handle the reply. + +VlimeConnection.FixRemotePath({path}) *VlimeConnection.FixRemotePath()* + + Fix the remote file paths after they are received from the server, so that + Vim can open the files via SFTP. {path} can be a plain string or a Swank + source location object. + +VlimeConnection.FixLocalPath({path}) *VlimeConnection.FixLocalPath()* + + Fix the local file paths before sending them to the server, so that the + server can see the correct files. {path} should be a plain string or v:null. + +VlimeConnection.GetCurrentPackage() *VlimeConnection.GetCurrentPackage()* + + Return the Common Lisp package bound to the current buffer. See + |vlime-current-package|. + +VlimeConnection.SetCurrentPackage({package}) + *VlimeConnection.SetCurrentPackage()* + + Bind a Common Lisp package to the current buffer. See + |vlime-current-package|. This method does NOT check whether the argument is + a valid package. See |VlimeConnection.SetPackage()| for a safer alternative. + +VlimeConnection.GetCurrentThread() *VlimeConnection.GetCurrentThread()* + + Return the thread bound to the current buffer. Currently this method only + makes sense in the debugger buffer. + +VlimeConnection.SetCurrentThread({thread}) + *VlimeConnection.SetCurrentThread()* + + Bind a thread to the current buffer. Don't call this method directly, unless + you know what you're doing. + +VlimeConnection.WithThread({thread}, {Func}) *VlimeConnection.WithThread()* + + Call {Func} with {thread} set as the current thread. The current thread will + be reset once this method returns. This is useful when you want to e.g. + evaluate something in certain threads. + +VlimeConnection.WithPackage({package}, {Func}) *VlimeConnection.WithPackage()* + + Call {Func} with {package} set as the current package. The current package + will be reset once this method returns. + +VlimeConnection.MakeLocalChannel([chan_id], [callback]) + *VlimeConnection.MakeLocalChannel()* + + Create a local channel (in the sense of SLIME channels). [chan_id], if + provided and not v:null, should be be a unique integer to identify the new + channel. A new ID will be generated if [chan_id] is omitted or v:null. + [callback] is a function responsible for handling the messages directed to + this very channel. It should have such a signature: + + SomeCallbackFunction(, , ) + + is a |vlime-api.VlimeConnection| object. is the channel object + in question, and is the channel message received from the server. + +VlimeConnection.RemoveLocalChannel({chan_id}) + *VlimeConnection.RemoveLocalChannel()* + + Remove a local channel with the ID {chan_id}. + +VlimeConnection.MakeRemoteChannel({chan_id}) + *VlimeConnection.MakeRemoteChannel()* + + Save the info for a remote channel (in the sense of SLIME channels). + {chan_id} should be an ID assigned by the server. + +VlimeConnection.RemoveRemoteChannel({chan_id}) + *VlimeConnection.RemoveRemoteChannel()* + + Remove a remote channel with the ID {chan_id} + +VlimeConnection.EmacsChannelSend({chan_id}, {msg}) + *VlimeConnection.EmacsChannelSend()* + + Construct an :EMACS-CHANNEL-SEND message. {chan_id} should be the + destination remote channel ID, and {msg} is the message to be sent. Note + that, despite the word "Send" in its name, this function WILL NOT send the + constructed message. You still need to call |VlimeConnection.Send()| for + that. + +VlimeConnection.EmacsRex({cmd}) *VlimeConnection.EmacsRex()* + + Construct an :EMACS-REX message, with the current package and the current + thread. {cmd} should be a raw :EMACS-REX command. + +VlimeConnection.Ping() *VlimeConnection.Ping()* + + Send a PING request to the server, and wait for the reply. + +VlimeConnection.ConnectionInfo([return_dict], [callback]) + *VlimeConnection.ConnectionInfo()* + + Ask the server for some info regarding this connection, and optionally + register a [callback] function to handle the result. + + If [return_dict] is specified and |TRUE|, this method will convert the + result to a dictionary before passing it to the [callback] function. + +VlimeConnection.SwankRequire({contrib}, [callback]) + *VlimeConnection.SwankRequire()* + + Require Swank contrib modules, and optionally register a [callback] function + to handle the result. + + {contrib} can be a string or a list of strings. Each string is a contrib + module name. These names are case-sensitive. Normally you should use + uppercase. + + For example, "conn_obj.SwankRequire('SWANK-REPL')" tells Swank to load the + SWANK-REPL contrib module, and "conn_obj.SwankRequire(['SWANK-REPL', + 'SWANK-PRESENTATIONS'])" tells Swank to load both SWANK-REPL and + SWANK-PRESENTATIONS. + +VlimeConnection.Interrupt({thread}) *VlimeConnection.Interrupt()* + + Interrupt {thread}. {thread} should be a numeric thread ID, or {"package": + "KEYWORD", "name": "REPL-THREAD"} for the REPL thread. The debugger will be + activated upon interruption. + +VlimeConnection.SLDBAbort([callback]) *VlimeConnection.SLDBAbort()* + + When the debugger is active, invoke the ABORT restart. + +VlimeConnection.SLDBBreak({func_name}, [callback]) + *VlimeConnection.SLDBBreak()* + + Set a breakpoint at entry to a function with the name {func_name}. + +VlimeConnection.SLDBContinue([callback]) *VlimeConnection.SLDBContinue()* + + When the debugger is active, invoke the CONTINUE restart. + +VlimeConnection.SLDBStep({frame}, [callback]) *VlimeConnection.SLDBStep()* + + When the debugger is active, enter stepping mode in {frame}. {frame} should + be a valid frame number presented by the debugger. + +VlimeConnection.SLDBNext({frame}, [callback]) *VlimeConnection.SLDBNext()* + + When the debugger is active, step over the current function call in {frame}. + +VlimeConnection.SLDBOut({frame}, [callback]) *VlimeConnection.SLDBOut()* + + When the debugger is active, step out of the current function in {frame}. + +VlimeConnection.SLDBReturnFromFrame({frame}, {str}, [callback]) + *VlimeConnection.SLDBReturnFromFrame()* + + When the debugger is active, evaluate {str} and return from {frame} with the + evaluation result. {str} should be a plain string containing the lisp + expression to be evaluated. + +VlimeConnection.SLDBDisassemble({frame}, [callback]) + *VlimeConnection.SLDBDisassemble()* + + Disassemble the code for {frame}. + +VlimeConnection.InvokeNthRestartForEmacs({level}, {restart}, [callback]) + *VlimeConnection.InvokeNthRestartForEmacs()* + + When the debugger is active, invoke a {restart} at {level}. {restart} should + be a valid restart number, and {level} a valid debugger level. + +VlimeConnection.RestartFrame({frame}, [callback]) + *VlimeConnection.RestartFrame()* + + When the debugger is active, restart a {frame}. + +VlimeConnection.FrameLocalsAndCatchTags({frame}, [callback]) + *VlimeConnection.FrameLocalsAndCatchTags()* + + When the debugger is active, get info about local variables and catch tags + for {frame}. + +VlimeConnection.FrameSourceLocation({frame}, [callback]) + *VlimeConnection.FrameSourceLocation()* + + When the debugger is active, get the source location for {frame}. + +VlimeConnection.EvalStringInFrame({str}, {frame}, {package}, [callback]) + *VlimeConnection.EvalStringInFrame()* + + When the debugger is active, evaluate {str} in {package}, and within the + context of {frame}. + +VlimeConnection.InitInspector({thing}, [callback]) + *VlimeConnection.InitInspector()* + + Evaluate {thing} and start inspecting the evaluation result with the + inspector. {thing} should be a plain string containing the lisp expression + to be evaluated. + +VlimeConnection.InspectorReinspect([callback]) + *VlimeConnection.InspectorReinspect()* + + Reload the object being inspected, and update inspector states. + +VlimeConnection.InspectorRange({r_start}, {r_end}, [callback]) + *VlimeConnection.InspectorRange()* + + Pagination for inspector content. {r_start} is the first index to retrieve + in the inspector content list. {r_end} is the last index plus one. + +VlimeConnection.InspectNthPart({nth}, [callback]) + *VlimeConnection.InspectNthPart()* + + Inspect an object presented by the inspector. {nth} should be a valid part + number presented by the inspector. + +VlimeConnection.InspectorCallNthAction({nth}, [callback]) + *VlimeConnection.InspectorCallNthAction()* + + Perform an action in the inspector. {nth} should be a valid action number + presented by the inspector. + +VlimeConnection.InspectorPop([callback]) *VlimeConnection.InspectorPop()* + + Inspect the previous object in the stack of inspected objects. + +VlimeConnection.InspectorNext([callback]) *VlimeConnection.InspectorNext()* + + Inspect the next object in the stack of inspected objects. + +VlimeConnection.InspectCurrentCondition([callback]) + *VlimeConnection.InspectCurrentCondition()* + + When the debugger is active, inspect the current condition. + +VlimeConnection.InspectInFrame({thing}, {frame}, [callback]) + *VlimeConnection.InspectInFrame()* + + When the debugger is active, evaluate {thing} in the context of {frame}, and + start inspecting the evaluation result. + +VlimeConnection.ListThreads([callback]) *VlimeConnection.ListThreads()* + + Get a list of running threads. + +VlimeConnection.KillNthThread({nth}, [callback]) + *VlimeConnection.KillNthThread()* + + Kill a thread presented in the thread list. {nth} should be a valid index in + the thread list, instead of a thread ID. + +VlimeConnection.DebugNthThread({nth}, [callback]) + *VlimeConnection.DebugNthThread()* + + Activate the debugger in a thread presented in the thread list. {nth} should + be a valid index in the thread list, instead of a thread ID. + +VlimeConnection.UndefineFunction({func_name}, [callback]) + *VlimeConnection.UndefineFunction()* + + Undefine a function with the name {func_name}. + +VlimeConnection.UninternSymbol({sym_name}, [package], [callback]) + *VlimeConnection.UninternSymbol()* + + Unintern a symbol with the name {sym_name}. {sym_name} should be a plain + string containing the name of the symbol to be uninterned. + +VlimeConnection.SetPackage({package}, [callback]) + *VlimeConnection.SetPackage()* + + Bind a Common Lisp package to the current buffer. See + |vlime-current-package|. + +VlimeConnection.DescribeSymbol({symbol}, [callback]) + *VlimeConnection.DescribeSymbol()* + + Get a description for {symbol}. {symbol} should be a plain string containing + the symbol name. + +VlimeConnection.OperatorArgList({operator}, [callback]) + *VlimeConnection.OperatorArgList()* + + Get the arglist description for {operator}. {operator} should be a plain + string containing a symbol name. + +VlimeConnection.SimpleCompletions({symbol}, [callback]) + *VlimeConnection.SimpleCompletions()* + + Get a simple completion list for {symbol}. {symbol} should be a plain string + containing a (partial) symbol name. + +VlimeConnection.SwankMacroExpandOne({expr}, [callback]) + *VlimeConnection.SwankMacroExpandOne()* + + Perform one macro expansion on {expr}. {expr} should be a plain string + containing the lisp expression to be expanded. + +VlimeConnection.SwankMacroExpand({expr}, [callback]) + *VlimeConnection.SwankMacroExpand()* + + Expand {expr}, until the resulting form cannot be macro-expanded anymore. + +VlimeConnection.SwankMacroExpandAll({expr}, [callback]) + *VlimeConnection.SwankMacroExpandAll()* + + Recursively expand all macros in {expr}. + +VlimeConnection.DisassembleForm({expr}, [callback]) + *VlimeConnection.DisassembleForm()* + + Compile and disassemble {expr}. + +VlimeConnection.CompileStringForEmacs({expr}, {buffer}, {position}, + {filename}, [policy], [callback]) *VlimeConnection.CompileStringForEmacs()* + + Compile {expr}. {buffer}, {position} and {filename} specify where {expr} is + from. When {buffer} or {filename} is unknown, one can pass v:null instead. + [policy] should be a dictionary specifying a compiler policy. For example, + + {"DEBUG": 3, "SPEED": 0} + + This means no optimization in runtime speed, and maximum debug info. + +VlimeConnection.CompileFileForEmacs({filename}, [load], [policy], [callback]) + *VlimeConnection.CompileFileForEmacs()* + + Compile a file with the name {filename}. [load], if present and |TRUE|, + tells Vlime to automatically load the compiled file after successful + compilation. [policy] is the compiler policy, see + |VlimeConnection.CompileStringForEmacs()|. + +VlimeConnection.LoadFile({filename}, [callback]) *VlimeConnection.LoadFile()* + + Load a file with the name {filename}. + +VlimeConnection.XRef({ref_type}, {name}, [callback]) *VlimeConnection.XRef()* + + Cross reference lookup. {ref_type} can be "CALLS", "CALLS-WHO", + "REFERENCES", "BINDS", "SETS", "MACROEXPANDS", or "SPECIALIZES". {name} is + the symbol name to lookup. + +VlimeConnection.FindDefinitionsForEmacs({name}, [callback]) + *VlimeConnection.FindDefinitionsForEmacs()* + + Lookup definitions for symbol {name}. + +VlimeConnection.FindSourceLocationForEmacs({spec}, [callback]) + *VlimeConnection.FindSourceLocationForEmacs()* + + Lookup source locations for certain objects. {spec} specifies what to look + for. When {spec} is ['STRING', , ], evaluate in + , and then find the source for the resulting object. When {spec} is + ['INSPECTOR', ], find the source for the object shown in the + inspector with . When {spec} is ['SLDB', , ], find the + source for the local variable in in the debugger. + +VlimeConnection.AproposListForEmacs({name}, {external_only}, {case_sensitive}, + {package}, [callback]) *VlimeConnection.AproposListForEmacs()* + + Lookup symbol names containing {name}. If {external_only} is |TRUE|, only + return external symbols. {case_sensitive} specifies whether the search is + case-sensitive or not. {package} limits the search to a specific package, + but one can pass v:null to search all packages. + +VlimeConnection.DocumentationSymbol({sym_name}, [callback]) + *VlimeConnection.DocumentationSymbol()* + + Find the documentation for symbol {sym_name}. + +VlimeConnection.Autodoc({raw_form}, [margin], [callback]) + *VlimeConnection.Autodoc()* + + Get the arglist description for {raw_form}. {raw_form} should be a value + returned by |vlime#ui#CurRawForm()| or |vlime#ToRawForm()|. See the source + of SWANK:AUTODOC for an explanation of the raw forms. [margin], if specified + and not v:null, gives the line width to wrap to. + + This method needs the SWANK-ARGLISTS contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.FuzzyCompletions({symbol}, [callback]) + *VlimeConnection.FuzzyCompletions()* + + Get a completion list for {symbol}, using a more clever fuzzy algorithm. + {symbol} should be a plain string containing a (partial) symbol name. + + This method needs the SWANK-FUZZY contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.CreateMREPL([chan_id], [callback]) + *VlimeConnection.CreateMREPL()* + + Create an REPL listener using SWANK-MREPL. [chan_id] should be a unique + number identifying the local channel. Use a automatically generated ID if + [chan_id] is omitted or v:null. + + This method needs the SWANK-MREPL contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.InspectPresentation({pres_id}, {reset}, [callback]) + *VlimeConnection.InspectPresentation()* + + Start inspecting an object saved by SWANK-PRESENTATIONS. {pres_id} should be + a valid ID presented by PRESENTATION-START messages. If {reset} is |TRUE|, + the inspector will be reset first. + + This method needs the SWANK-PRESENTATIONS contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.CreateREPL([coding_system], [callback]) + *VlimeConnection.CreateREPL()* + + Create the REPL thread, and optionally register a [callback] function to + handle the result. + + [coding_system] is implementation-dependent. Omit this argument or pass + v:null to let the server choose it for you. + + This method needs the SWANK-REPL contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.ListenerEval({expr}, [callback]) + *VlimeConnection.ListenerEval()* + + Evaluate {expr} in the current package and thread, and optionally register a + [callback] function to handle the result. {expr} should be a plain string + containing the lisp expression to be evaluated. + + This method needs the SWANK-REPL contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.ClearTraceTree([callback]) *VlimeConnection.ClearTraceTree()* + + Clear all trace entries in SWANK-TRACE-DIALOG. + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.DialogToggleTrace({name}, [callback]) + *VlimeConnection.DialogToggleTrace()* + + Toggle the traced state of a function in SWANK-TRACE-DIALOG. {name} can be a + plain string specifying the function name, or "(setf )" to refer to a + SETF function. You can also pass raw JSON objects. + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.DialogTrace({name}, [callback]) + *VlimeConnection.DialogTrace()* + + Trace a function in SWANK-TRACE-DIALOG. See + |VlimeConnection.DialogToggleTrace()| for the use of {name}. + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.DialogUntrace({name}, [callback]) + *VlimeConnection.DialogUntrace()* + + Untrace a function in SWANK-TRACE-DIALOG. See + |VlimeConnection.DialogToggleTrace()| for the use of {name}. + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.DialogUntraceAll([callback]) + *VlimeConnection.DialogUntraceAll()* + + Untrace all functions in SWANK-TRACE-DIALOG. + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.FindTrace({id}, [callback]) *VlimeConnection.FindTrace()* + + Retrieve a trace entry by {id}. + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.FindTracePart({id}, {part_id}, {type}, [callback]) + *VlimeConnection.FindTracePart()* + + Retrieve an argument or return value saved in a trace entry. {id} is the + trace entry ID. {part_id} is the argument or return value ID. {type} can be + "ARG" or "RETVAL". + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.InspectTracePart({id}, {part_id}, {type}, [callback]) + *VlimeConnection.InspectTracePart()* + + Inspect an argument or return value saved in a trace entry. See + |VlimeConnection.FindTracePart()| for the use of the arguments. + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.ReportPartialTree({key}, [callback]) + *VlimeConnection.ReportPartialTree()* + + Retrieve at most SWANK-TRACE-DIALOG:*TRACES-PER-REPORT* trace entries. {key} + should be a uniqe number or string to identify the requesting entity. + Subsequent requests should provide the same key. + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.ReportSpecs([callback]) *VlimeConnection.ReportSpecs()* + + Retrieve traced function specs from SWANK-TRACE-DIALOG. + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.ReportTotal([callback]) *VlimeConnection.ReportTotal()* + + Retrieve the total count of trace entries. + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + +VlimeConnection.ReportTraceDetail({id}, [callback]) + *VlimeConnection.ReportTraceDetail()* + + Retrieve the details of a trace entry by {id}. + + This method needs the SWANK-TRACE-DIALOG contrib module. See + |VlimeConnection.SwankRequire()|. + + *vlime-api.VlimeUI* +The |vlime-api.VlimeUI| object is a singleton. It's meant to be injected into +|vlime-api.VlimeConnection| objects, to grant them access to the user +interface. See |vlime#New()|. + + +VlimeUI.GetCurrentPackage([buffer]) *VlimeUI.GetCurrentPackage()* + + Return the Common Lisp package bound to the specified [buffer]. If no + package is bound yet, try to guess one by looking into the buffer content. + [buffer], if specified, should be an expression as described in |bufname()|. + When [buffer] is omitted, work on the current buffer. + + The returned value is a list of two strings. The first string is the full + name of the package, and the second string is one of the package's + nicknames. + +VlimeUI.SetCurrentPackage({pkg}, [buffer]) *VlimeUI.SetCurrentPackage()* + + Bind a Common Lisp package {pkg} to the specified [buffer]. {pkg} should be + a list of two strings, i.e. in the same format as the return value of + |VlimeUI.GetCurrentPackage()|. See |VlimeUI.GetCurrentPackage()| for the use + of [buffer]. + + Note that this method doesn't check the validity of {pkg}. + +VlimeUI.GetCurrentThread([buffer]) *VlimeUI.GetCurrentThread()* + + Return the thread bound to [buffer]. See |VlimeUI.GetCurrentPackage()| for + the use of [buffer]. + + Currently, this method only makes sense in the debugger buffer. + +VlimeUI.SetCurrentThread({thread}, [buffer]) *VlimeUI.SetCurrentThread()* + + Bind a thread to [buffer]. See |VlimeUI.GetCurrentPackage()| for the use of + [buffer]. + +============================================================================== +FUNCTIONS *vlime-api-functions* + +vlime#New([cb_data], [ui]) *vlime#New()* + + Create a |vlime-api.VlimeConnection|. + + [cb_data] is arbitrary data, accessible from the connection callbacks. [ui] + is an instance of |vlime-api.VlimeUI|, see |vlime#ui#GetUI()|. + + This function is seldom used directly. To connect to a server, call + |vlime#plugin#ConnectREPL()|. + +vlime#PListToDict({plist}) *vlime#PListToDict()* + + Convert a {plist} sent from the server to a native |dict|. + +vlime#ChainCallbacks([func_and_cb...]) *vlime#ChainCallbacks()* + + Make a chain of async calls and corresponding callbacks. For example: + + call vlime#ChainCallbacks(, , , , , ) + + will be called after has finished, and will be called after + has finished, and so on. + +vlime#ParseSourceLocation({loc}) *vlime#ParseSourceLocation()* + + Parse a source location object {loc} sent from the server, and convert it + into a native |dict|. + +vlime#GetValidSourceLocation({loc}) *vlime#GetValidSourceLocation()* + + Normalize a source location object parsed by |vlime#ParseSourceLocation()|. + +vlime#ToRawForm({expr}) *vlime#ToRawForm()* + + Parse {expr} and turn it into a raw form usable by + |VlimeConnection.Autodoc()|. See the source of SWANK:AUTODOC for an + explanation of the raw forms. + +vlime#plugin#CloseCurConnection() *vlime#plugin#CloseCurConnection()* + + Close the connection bound to the current buffer. If no connection is bound, + show a menu to choose one. + +vlime#plugin#RenameCurConnection() *vlime#plugin#RenameCurConnection()* + + Rename the connection bound to the current buffer. If no connection is + bound, show a menu to choose one. + +vlime#plugin#ShowSelectedServer() *vlime#plugin#ShowSelectedServer()* + + Show the output buffer for a server started by Vlime. + +vlime#plugin#StopSelectedServer() *vlime#plugin#StopSelectedServer()* + + Stop a server started by Vlime. + +vlime#plugin#RenameSelectedServer() *vlime#plugin#RenameSelectedServer()* + + Rename a server started by Vlime. Prompt for the new server name. + +vlime#plugin#ConnectREPL([host], [port], [remote_prefix], [timeout], [name]) + *vlime#plugin#ConnectREPL()* + + Connect to a server, and return a connection object (see + |vlime-api.VlimeConnection|). + + [host] and [port] specify the server to connect to. This function will use + the value in |g:vlime_address| if they are omitted. [remote_prefix], if + specified, is an SFTP URL prefix, to tell Vlime to open remote files via + SFTP (see |vlime-remote-server|). [timeout] is the time to wait for the + connection to be made, in milliseconds. [name] gives the new connection a + name. Omit this argument to use an automatically generated name. + +vlime#plugin#CreateMREPL() *vlime#plugin#CreateMREPL()* + + Create a new REPL thread using SWANK-MREPL. This function needs the + SWANK-MREPL contrib module. See |g:vlime_contribs| and + |vlime#plugin#SwankRequire()|. + +vlime#plugin#SelectCurConnection() *vlime#plugin#SelectCurConnection()* + + Show a menu to let you choose a connection, and bind this connection to the + current buffer. + +vlime#plugin#SendToREPL([content], [edit]) *vlime#plugin#SendToREPL()* + + Evaluate [content] in the REPL and show the result in the REPL buffer. If + [content] is omitted, or [edit] is present and |TRUE|, show an input buffer. + +vlime#plugin#Compile([content], [policy], [edit]) *vlime#plugin#Compile()* + + Compile [content], with the specified [policy], and show the result in the + REPL buffer. If [content] is omitted or v:null, or [edit] is present and + |TRUE|, show an input buffer. If [policy] is omitted, try to use + |g:vlime_compiler_policy|. Open the compiler notes window when there are + warnings or errors etc. + +vlime#plugin#Inspect([content], [edit]) *vlime#plugin#Inspect()* + + Evaluate [content] and launch the inspector with the evaluation result + loaded. If [content] is omitted, or [edit] is present and |TRUE|, show an + input buffer. + +vlime#plugin#DialogToggleTrace([func], [edit]) + *vlime#plugin#DialogToggleTrace()* + + Toggle the traced state of [func]. [func] should be a string specifying a + plain function name, or in the form "(setf )", to trace a + setf-expander. If [func] is omitted, or [edit] is present and |TRUE|, show + an input buffer. + + This function needs the SWANK-TRACE-DIALOG contrib module. See + |g:vlime_contribs| and |vlime#plugin#SwankRequire()|. + +vlime#plugin#OpenTraceDialog() *vlime#plugin#OpenTraceDialog()* + + Show the trace dialog. + +vlime#plugin#CompileFile([file_name], [policy], [load], [edit]) + *vlime#plugin#CompileFile()* + + Compile a file named [file_name], with the specified [policy], and show the + result in the REPL buffer. If [file_name] is omitted or v:null, or [edit] is + present and |TRUE|, prompt for the file name. If [policy] is omitted, try to + use |g:vlime_compiler_policy|. If [load] is present and |FALSE|, do not load + the compiled file after successful compilation. Open the compiler notes + window when there are warnings or errors etc. + +vlime#plugin#ExpandMacro([expr], [type], [edit]) *vlime#plugin#ExpandMacro()* + + Perform macro expansion on [expr] and show the result in the preview window. + If [expr] is omitted or v:null, or [edit] is present and |TRUE|, show an + input buffer. + + [type] specifies the type of expansion to perform. It can be "expand", + "one", or "all". When it's omitted or "expand", repeatedly expand [expr] + until the resulting form cannot be expanded anymore. When it's "one", only + expand once. And "all" means to recursively expand all macros contained in + [expr]. + +vlime#plugin#DisassembleForm([content], [edit]) + *vlime#plugin#DisassembleForm()* + + Compile and disassemble [content]. Show the result in the preview window. If + [content] is omitted, or [edit] is present and |TRUE|, show an input buffer. + +vlime#plugin#LoadFile([file_name], [edit]) *vlime#plugin#LoadFile()* + + Load a file named [file_name]. If [file_name] is omitted, or [edit] is + present and |TRUE|, prompt for the file name. + +vlime#plugin#SetPackage([pkg]) *vlime#plugin#SetPackage()* + + Bind a Common Lisp package [pkg] to the current buffer. If [pkg] is omitted, + show an input buffer. + +vlime#plugin#SwankRequire({contribs}, [do_init]) *vlime#plugin#SwankRequire()* + + Require Swank contrib modules. {contribs} should be a plain string or a list + of strings. Each string is a contrib module name. These names are + case-sensitive. Normally you should use uppercase. If [do_init] is present + and |FALSE|, suppress initialization for newly loaded contrib modules. + +vlime#plugin#ShowOperatorArgList([op], [edit]) + *vlime#plugin#ShowOperatorArgList()* + + Show the arglist description for operator [op] in the arglist window. If + [op] is omitted, or [edit] is present and |TRUE|, show an input buffer. + +vlime#plugin#CurAutodoc() *vlime#plugin#CurAutodoc()* + + Show the arglist description for the current expression and cursor position, + in the arglist window. If the SWANK-ARGLISTS contrib module is available, + the current argument will be marked in the arglist. + +vlime#plugin#DescribeSymbol([symbol], [edit]) *vlime#plugin#DescribeSymbol()* + + Show a description for [symbol] in the preview window. If [symbol] is + omitted, or [edit] is present and |TRUE|, show an input buffer. + +vlime#plugin#XRefSymbol({ref_type}, [sym], [edit]) *vlime#plugin#XRefSymbol()* + + Lookup cross references for [sym], and show the results in the xref window. + If [sym] is omitted, or [edit] is present and |TRUE|, show an input buffer. + See |VlimeConnection.XRef()| for possible values for {ref_type}. + +vlime#plugin#XRefSymbolWrapper() *vlime#plugin#XRefSymbolWrapper()* + + A wrapper function for |vlime#plugin#XRefSymbol()| and + |vlime#plugin#FindDefinition()|. Pick the type of cross reference + interactively. + +vlime#plugin#FindDefinition([sym], [edit]) *vlime#plugin#FindDefinition()* + + Find the definition for [sym], and show the results in the xref window. If + [sym] is omitted, or [edit] is present and |TRUE|, show an input buffer. + +vlime#plugin#AproposList([pattern], [edit]) *vlime#plugin#AproposList()* + + Apropos search for [pattern]. Show the results in the preview window. If + [pattern] is omitted, or [edit] is present and |TRUE|, show an input buffer. + +vlime#plugin#DocumentationSymbol([symbol], [edit]) + *vlime#plugin#DocumentationSymbol()* + + Show the documentation for [symbol] in the preview window. If [symbol] is + omitted, or [edit] is present and |TRUE|, show an input buffer. + +vlime#plugin#SetBreakpoint([sym], [edit]) *vlime#plugin#SetBreakpoint()* + + Set a breakpoint at entry to a function with the name [sym]. If [sym] is + omitted, or [edit] is present and |TRUE|, show an input buffer. + +vlime#plugin#ListThreads() *vlime#plugin#ListThreads()* + + Show the thread list window. + +vlime#plugin#UndefineFunction([sym], [edit]) *vlime#plugin#UndefineFunction()* + + Undefine a function with the name [sym]. If [sym] is omitted, or [edit] is + present and |TRUE|, show an input buffer. + +vlime#plugin#UninternSymbol([sym], [edit]) *vlime#plugin#UninternSymbol()* + + Unintern a symbol [sym]. If [sym] is omitted, or [edit] is present and + |TRUE|, show an input buffer. + +vlime#plugin#UndefineUninternWrapper() + *vlime#plugin#UndefineUninternWrapper()* + + A wrapper function for |vlime#plugin#UndefineFunction()| and + |vlime#plugin#UninternSymbol()|. Pick the type of action to perform + interactively. + +vlime#plugin#CloseWindow([win_name]) *vlime#plugin#CloseWindow()* + + Close Vlime special windows. [win_name] is the type of windows to close. See + |vlime#ui#GetWindowList()| for valid values for [win_name]. If [win_name] is + omitted, show a menu to let you choose which window to close. + +vlime#plugin#CompleteFunc({findstart}, {base}) *vlime#plugin#CompleteFunc()* + + The completion function. This function is meant to be used as |omnifunc| or + |completefunc|. It is asynchronous, and will NOT return the completion list + immediately. + +vlime#plugin#CalcCurIndent([shift_width]) *vlime#plugin#CalcCurIndent()* + + Calculate the indent size for the current line, in number of + characters. [shift_width] is the size for one indent level, defaults to 2 if + omitted. + +vlime#plugin#Setup([force]) *vlime#plugin#Setup()* + + Set up Vlime for the current buffer. Do nothing if the current buffer is + already initialized. If [force] is present and |TRUE|, always perform the + initialization. + +vlime#plugin#InteractionMode([value]) *vlime#plugin#InteractionMode()* + + Toggle interaction mode if no [value] is given. If [value] is |TRUE| enable + interaction mode, if [value] is |FALSE| disable it. + +vlime#ui#New() *vlime#ui#New()* + + Create a |vlime-api.VlimeUI| object. One should probably use + |vlime#ui#GetUI()| instead. + +vlime#ui#GetUI() *vlime#ui#GetUI()* + + Return the UI singleton. + +vlime#ui#OnWriteString({conn}, {str}, {str_type}) *vlime#ui#OnWriteString()* + + Write an arbitrary string {str} to the REPL buffer. {conn} should be a valid + |vlime-api.VlimeConnection|. {str_type} is currently ignored. + +vlime#ui#CurChar() *vlime#ui#CurChar()* + + Return the current character under the cursor. If there's no character, an + empty string is returned. + +vlime#ui#CurExprOrAtom() *vlime#ui#CurExprOrAtom()* + + If there is a parentheses-enclosed expression under the cursor, return it. + Otherwise look for an atom under the cursor. Return an empty string if + nothing is found. + +vlime#ui#CurAtom() *vlime#ui#CurAtom()* + + Return the atom under the cursor, or an empty string if there is no atom. + +vlime#ui#CurExpr([return_pos]) *vlime#ui#CurExpr()* + + Return the parentheses-enclosed expression under the cursor, or an empty + string, when there is no expression. If [return_pos] is specified and + |TRUE|, return a list containing the expression, as well as the beginning + and ending positions. + +vlime#ui#CurExprPos({cur_char}, [side]) *vlime#ui#CurExprPos()* + + Return the beginning or ending position of the parentheses-enclosed + expression under the cursor. {cur_char} is the character under the cursor, + which can be obtained by calling |vlime#ui#CurChar()|. If [side] is "begin", + the beginning position is returned. If [side] is "end", the ending position + is returned. "begin" is the default when [side] is omitted. + +vlime#ui#CurTopExpr([return_pos]) *vlime#ui#CurTopExpr()* + + Return the top-level parentheses-enclosed expression. See + |vlime#ui#CurExpr()| for the use of [return_pos]. + +vlime#ui#CurTopExprPos([side], [max_level], [max_lines]) + *vlime#ui#CurTopExprPos()* + + Return the beginning or ending position of the top-level + parentheses-enclosed expression under the cursor. See + |vlime#ui#CurExprPos()| for the use of [side]. + + Stop when [max_level] parentheses are seen, or [max_lines] lines have been + searched. Pass v:null or ommit these two arguments to impose no limit at + all. + +vlime#ui#CurRawForm([max_level], [max_lines]) *vlime#ui#CurRawForm()* + + Retrieve the parentheses-enclosed expression under the cursor, and parse it + into a "raw form" usable by |VlimeConnection.Autodoc()|. See the source of + SWANK:AUTODOC for an explanation of the raw forms. + + The raw-form-parsing operation is quite slow, you can pass [max_level] and + [max_lines] to impose some limits when searching for expressions. See + |vlime#ui#CurTopExprPos()| for the use of these arguments. + +vlime#ui#CurInPackage() *vlime#ui#CurInPackage()* + + Search for an "in-package" expression in the current buffer, and return the + package name specified in that expression. If no such an expression can be + found, an empty string is returned. + +vlime#ui#CurOperator() *vlime#ui#CurOperator()* + + Return the operator symbol name of the parentheses-enclosed expression under + the cursor. If no expression is found, return an empty string. + +vlime#ui#SurroundingOperator() *vlime#ui#SurroundingOperator()* + + Similar to |vlime#ui#CurOperator()|, but return the operator of the + surrounding expression instead, if the cursor is on the left enclosing + parentheses. + +vlime#ui#CurSelection([return_pos]) *vlime#ui#CurSelection()* + + Return the content of current/last selection. See |vlime#ui#CurExpr()| for + the use of [return_pos]. + +vlime#ui#CurBufferContent([raw]) *vlime#ui#CurBufferContent()* + + Get the text content of the current buffer. Lines starting with ";" will be + dropped, unless [raw] is specified and |TRUE|. + +vlime#ui#GetText({from_pos}, {to_pos}) *vlime#ui#GetText()* + + Retrieve the text in the current buffer from {from_pos} to {to_pos}. These + positions should be lists in the form [, ]. + +vlime#ui#KeepCurWindow({Func}) *vlime#ui#KeepCurWindow()* + + Call {Func}. When {Func} returns, move the cursor back to the current + window. + +vlime#ui#WithBuffer({buf}, {Func}, [ev_ignore]) *vlime#ui#WithBuffer()* + + Call {Func} with {buf} set as the current buffer. {buf} should be an + expression as described in |bufname()|. [ev_ignore] specifies what autocmd + events to ignore when switching buffers. When [ev_ignore] is omitted, all + events are ignored by default. + +vlime#ui#OpenBuffer({name}, {create}, {show}, [vertical], [initial_size]) + *vlime#ui#OpenBuffer()* + + Open a buffer with the specified {name}. {name} should be an expression as + described in |bufname()|. Return -1 if the buffer doesn't exist, unless + {create} is |TRUE|. In that case, a new buffer is created. + + When {show} is |TRUE| or a non-empty string, the buffer will be shown in a + new window, but if the buffer is already visible, move the cursor to it's + window instead. The string values can be "aboveleft", "belowright", + "topleft", or "botright", to further specify the window position. See + |aboveleft| and the alike to get explanations of these positions. + + [vertical], if specified and |TRUE|, indicates that the new window should be + created vertically. [initial_size] assigns an initial size to the newly + created window. + +vlime#ui#OpenBufferWithWinSettings({buf_name}, {buf_create}, {win_name}) + *vlime#ui#OpenBufferWithWinSettings()* + + Like |vlime#ui#OpenBuffer()|, but consult |g:vlime_window_settings| when + creating a new window. {buf_name} should be an expression as described in + |bufname()|. {buf_create} specifies whether to create a new buffer or not. + {win_name} is the type of the window to create. See + |g:vlime_window_settings| for a list of Vlime window types. + +vlime#ui#CloseBuffer({buf}) *vlime#ui#CloseBuffer()* + + Close all windows that contain {buf}. It's like "execute 'bunload!' {buf}", + but the buffer remains loaded, and the local settings for {buf} are kept. + {buf} should be a buffer number as returned by |bufnr()|. + +vlime#ui#ShowPreview({conn}, {content}, {append}) *vlime#ui#ShowPreview()* + + Show {content} in the preview buffer. {conn} should be a + |vlime-api.VlimeConnection|. When {append} is |TRUE|, append {content} to + the existing content in the preview buffer. + +vlime#ui#ShowArgList({conn}, {content}) *vlime#ui#ShowArgList()* + + Show {content} in the arglist buffer. {conn} should be a + |vlime-api.VlimeConnection|. + +vlime#ui#GetWindowList({conn}, {win_name}) *vlime#ui#GetWindowList()* + + Return a list of Vlime windows. {conn} should be a + |vlime-api.VlimeConnection| or v:null. When {conn} is v:null, windows + associated with all connections are returned. {win_name} is the type of + window to look for, or an empty string to indicate all window types. See + |g:vlime_window_settings| for a full list of window types. + +vlime#ui#GetFiletypeWindowList({ft}) *vlime#ui#GetFiletypeWindowList()* + + Return a list of windows containing buffers of filetype {ft}. + +vlime#ui#CloseWindow({conn}, {win_name}) *vlime#ui#CloseWindow()* + + Close Vlime windows. See |vlime#ui#GetWindowList()| for the use of {conn} + and {win_name}. + +vlime#ui#AppendString({str}, [line]) *vlime#ui#AppendString()* + + Append {str} to [line] in the current buffer. Append to the last line if + [line] is omitted. Elaborately handle newline characters. + +vlime#ui#ReplaceContent({str}, [first_line], [last_line]) + *vlime#ui#ReplaceContent()* + + Replace the content of the current buffer, from [first_line] to [last_line] + (inclusive), with {str}. If [first_line] is omitted, start from line 1. If + [last_line] is omitted, stop at the last line of the current buffer. + +vlime#ui#IndentCurLine({indent}) *vlime#ui#IndentCurLine()* + + Adjust the indentation of the current line. {indent} is the amount to + indent, in number of space characters. + +vlime#ui#CurArgPos([pos]) *vlime#ui#CurArgPos()* + + Return the index of the argument under the cursor, inside a + parentheses-enclosed expression. A returned value of zero means the cursor + is on the operator. If no parentheses-enclosed expression is found, -1 is + returned. [pos] should be the position where the parentheses-enclosed + expression begins, in the form [, ]. If [pos] is omitted, this + function will try to find the beginning position. + +vlime#ui#ErrMsg({msg}) *vlime#ui#ErrMsg()* + + Show an error message. + +vlime#ui#JumpToOrOpenFile({file_path}, {byte_pos}, [snippet], [edit_cmd], + [force_open]) *vlime#ui#JumpToOrOpenFile()* + + Open a file specified by {file_path}, and move the cursor to {byte_pos}. If + the specified file is already loaded in a window, move the cursor to that + window instead. + + [snippet] is used to fine-tune the cursor position to jump to. One can pass + v:null to safely ignore the fine-tuning. [edit_cmd] is the command used to + open the specified file, if it's not loaded in any window yet. The default + is "hide edit". When [force_open] is specified and |TRUE|, always open the + file with [edit_cmd]. + +vlime#ui#ShowSource({conn}, {loc}, [edit_cmd], [force_open]) + *vlime#ui#ShowSource()* + + Open the source location specified by {loc}. {conn} should be a + |vlime-api.VlimeConnection|, and {loc} a normalized source location returned + by |vlime#GetValidSourceLocation()|. See |vlime#ui#JumpToOrOpenFile()| for + the use of [edit_cmd] and [force_open]. + +vlime#ui#GetWindowSettings({win_name}) *vlime#ui#GetWindowSettings()* + + Return settings for a window type {win_name}. See |g:vlime_window_settings| + for the format of the settings and a full list of window types. + +vlime#ui#EnsureKeyMapped({mode}, {key}, {cmd}, [force], [log], [flags]) + *vlime#ui#EnsureKeyMapped()* + + Ensure the specified {key} or {cmd} is mapped in {mode}. If both {key} and + {cmd} are not mapped, map {key} to run {cmd}. If [force] is specified and + |TRUE|, always do the mapping. [log] is the category for logging conflicting + keys, should usually be the buffer type. See the value of + g:vlime_default_mappings for all buffer types. [flags] is a string + specifying |:map-arguments|. + +vlime#ui#MapBufferKeys({buf_type}, [force]) *vlime#ui#MapBufferKeys()* + + Map default Vlime keys for buffer type {buf_type}. See the value of + g:vlime_default_mappings for all buffer types. This function consults + |g:vlime_force_default_keys| when trying to map the keys. If [force] is + specified, it's value overrides the global variable. + +vlime#ui#ChooseWindowWithCount({default_win}) + *vlime#ui#ChooseWindowWithCount()* + + Choose a window with |v:count|. The special variable v:count should contain + a valid window number (see |winnr()|) or zero when this function is called. + The coresponding window ID is returned. If v:count is zero, try to use + {default_win} as the result. In that case, if {default_win} is not a legal + window number, try to find a window automatically. + + When all measures fail, zero is returned. + + +vim:tw=78:ts=8:ft=help:norl: \ No newline at end of file diff --git a/lisp/vlime-tutor.md b/lisp/vlime-tutor.md new file mode 100644 index 0000000..af88497 --- /dev/null +++ b/lisp/vlime-tutor.md @@ -0,0 +1,733 @@ +*vlime-tutor.txt* A tutorial for Vlime *vlime-tutor* +* [soure of text](https://github.com/vlime/vlime/blob/master/vim/doc/vlime-tutor.txt) + +====================================================================== +CONTENTS *vlime-tutor-contents* + + 1. Introduction .............................. |vlime-tutor-intro| + 2. Starting the Server ................ |vlime-tutor-start-server| + 3. Connecting .............................. |vlime-tutor-connect| + 4. The REPL ................................... |vlime-tutor-repl| + 5. Coding ..................................... |vlime-tutor-code| + 6. Compiling ............................... |vlime-tutor-compile| + 7. Debugging ................................. |vlime-tutor-debug| + 8. The inspector ......................... |vlime-tutor-inspector| + 9. Conclusion ........................... |vlime-tutor-conclusion| + +====================================================================== +1. Introduction *vlime-tutor-intro* + +This is a guided tour to show the major features of Vlime. For a +complete list of the features and key mappings etc., see |vlime.txt|. + +This tutorial was written on a Linux machine, so there may be some +Linux-specific commands. Vlime also works fine on Windows, and maybe +MacOS, but these systems will not be covered here. + +Before we get started, please make sure your system has all these +prerequisites: + + * A decent Common Lisp implementation. SBCL is strongly + recommended, but other implementations that support the debugger + may also be fine. See |vlime-intro| for a list of supported + implementations. + + * The Paredit plugin for Vim (https://github.com/kovisoft/paredit). + + * Vlime being properly installed. See README.md in the Vlime + source repo for installation instructions. + +We will be building a Fibonacci sequence generator in the rest of this +tutorial. Fascinating, right? + +====================================================================== +2. Starting the Server *vlime-tutor-start-server* + +Vlime works in a client-server fashion. The server is written in +Common Lisp. You can let Vlime start the server for you (see +|vlime-start-up|), but let's do it manually for the first time. To +start the server on the local machine: + + sbcl --load /lisp/start-vlime.lisp + +To run the server on a remote machine, see |vlime-remote-server|. + +The server is fully functional when we see something like this in the +console: + + [10:08:07] vlime-usocket - Server created: .... + +It will be listening on port 7002 by default. + +====================================================================== +3. Connecting *vlime-tutor-connect* + +Now we can create a new *.lisp file in Vim: + + :tabedit ad-hoc.lisp + +Then type "\cc" (without the quote marks) in normal mode to create a +connection. The backslash "\" is the default mapping for +||. See |vlime-mappings|. + +Vlime will show a message in Vim if everything went well: + + Vlime Connection 1 established. + +There can be multiple Vlime connections in a single Vim process. You +can use "\cc" to make more connections to the same server (though that +usually doesn't make any sense), or call vlime#plugin#ConnectREPL() in +Vim to connect to another server. For example: + + :call vlime#plugin#ConnectREPL("127.0.0.1", 9999) + +This will try to make a connection to 127.0.0.1:9999. + +Now, just for demostrating, let's type "\cc" a few more times, to +create more connections. Then type "\cs" (without the quote marks) in +the ad-hoc.lisp buffer to see the connection list. A list with three +connections should look like this: + + Which connection to use? + 1. Vlime Connection 1 (127.0.0.1:7002) + 2. Vlime Connection 2 (127.0.0.1:7002) + 3. Vlime Connection 3 (127.0.0.1:7002) + Type number and or click with mouse (empty cancels): + +From there you can also choose a connection for the current buffer to +use by typing it's ID and then . See +|vlime-current-connection|. + +When you're done with a connection, type "\cd" (without the quote +marks) in a *.lisp buffer to close it. The connection list may pop up +if Vlime was not sure which connection to close. + +You may try out the "\cc", "\cs", and "\cd" commands now, until you +feel comfortable to move on. Please leave at least one connection open +before proceeding to the next section. + +====================================================================== +4. The REPL *vlime-tutor-repl* + +Now that we have an active connection, let's try something simple. + +Vlime has good REPL integration, but it's different from other Lisp +environments, in that Vlime's REPL buffer is dedicated for output, +i.e. you can not type and evaluate an expression directly in the REPL +buffer. To evaluate something in the REPL, you send it using key +mappings listed in |vlime-mappings-send|. + +Let's go to ad-hoc.lisp, the file we created in |vlime-tutor-connect|, +and write a simple expression in it: + + (cons 1 2) + +Note: You may notice some "strange" behaviors when typing the + expression, such as parentheses being paired up automatically. + They are in fact features to aid you in code editing. We will + get to them in |vlime-tutor-code|. + +Make sure the cursor is on or inside the parentheses, then type "\ss" +(without the quote marks) in normal mode. A new buffer will pop up at +the bottom, showing some info about the server and the evaluation +result: + + SWANK version 2016-04-19, pid 14403 + =================================== + -- + (1 . 2) + +This is the REPL buffer. + +Try typing "i" (without the quote marks) in the REPL buffer. It will +result in an error message: + + E21: Cannot make changes, 'modifiable' is off + +Indeed, it's read-only. + +To make sending things to the REPL easier, Vlime has an interaction +mode for *.lisp buffers. Go back to the ad-hoc.lisp buffer at the top, +then type "\i" (without the quote marks) to activate interaction mode. + +To send something to the REPL in interaction mode, simply press . +Consider the expression we just wrote: + + (cons 1 2) + +Again, make sure the cursor is on or inside the parentheses, then +press , the new result will also come out in the REPL buffer: + + SWANK version 2016-04-19, pid 14403 + =================================== + -- + (1 . 2) + -- + (1 . 2) + +Be careful with nested expressions though. Vlime will only match the +nearest parentheses that enclose the cursor. Let's add one more line +to ad-hoc.lisp: + + (cons 1 2) + (+ 1 (- 10 2)) ; the new line + +When is pressed, if the cursor was on the "+" operator, the whole +expression "(+ 1 (- 10 2))" will be sent, and the result will be 9. If +the cursor was on the "-" operator, only the nested expression +"(- 10 2)" will be sent, and the result will be 8. + +To disable interaction mode, type "\i" (without the quote marks) again +in the ad-hoc.lisp buffer. + +But in what package were those expressions evaluated? Let's have a +look. Add one more line to ad-hoc.lisp and evaluate it by typing "\ss" +(without the quote marks) in normal mode or in interaction mode: + + (cons 1 2) + (+ 1 (- 10 2)) + (symbol-value (find-symbol "*PACKAGE*" "COMMON-LISP")) ; the new line + +The result should look like + + -- + # + +When evaluating an expression, Vlime would use the package associated +with the buffer containing that expression (see +|vlime-current-package|). And the default package is COMMON-LISP-USER. + +In the examples above, we never explicitly set the package for +ad-hoc.lisp, so it used the default package, and all the expressions +are evaluated in the default package too. + +There are two methods to set the package for a buffer: + + 1. Write an "in-package" expression in the buffer. Change the + content of ad-hoc.list to + + (cons 1 2) + (+ 1 (- 10 2)) + (in-package :vlime) ; the new line + (symbol-value (find-symbol "*PACKAGE*" "COMMON-LISP")) + + And then evaluate the last line again, the result would be + + -- + # + + 2. Type "\p" (without the quote marks) in a buffer in normal mode. + Vim will then prompt for the new package name, with the current + package displayed as the default. You can edit the package name + like you edit any other text in a normal buffer, and then press + in normal mode to submit (see |vlime-input-buffer|). The + name to enter can be a nickname, and is case-insensitive. This + method will take precedence over method 1. + + Now type "\p" in ad-hoc.lisp, and set the package to "cl-user" + (without the quote marks). Evaluate the last line again, the + result would be + + -- + # + +You may try out the REPL and the interaction mode now, until you feel +comfortable to move on. Try writing some complex expressions in +ad-hoc.lisp, such as multi-line DEFUNs, and evaluate them using +interaction mode. + +====================================================================== +5. Coding *vlime-tutor-code* + +Finally, we are going to write some real code. Our goal is to build a +Fibonacci sequence generator. Let's create a new file in Vim: + + :tabedit fibonacci.lisp + +And then type the content in it: + + (in-package #:cl-user) + + (defpackage #:fibonacci + (:use #:cl) + (:export #:generate)) + + (in-package #:fibonacci) + + (defun generate (n &optional (a 0) (b 1) (acc (list))) + (if (<= n 0) + (reverse acc) + (generate (1- n) b (+ a b) (push acc a)))) + +The GENERATE function should build a list of N Fibonacci numbers. If +you typed the code manually instead of copy-and-paste, You may have +noticed a few things when typing: + + 1. The parentheses are automatically paired. This is done by the + Paredit plugin. It's an invaluable tool for editing Lisp code. + See |paredit.txt| for details and more advanced usage. + + 2. When pressing or inside a pair of parentheses in + insert mode, a small preview window may pop up at the top, + showing the argument list for the current expression. + + 3. The code is automatically indented. See |vlime-auto-indent|. + + 4. You can press or the old-school CTRL-x CTRL-o keys in + insert mode to activate the omni-completion menu, and then + use CTRL-n or CTRL-p to select a candidate. See + |vlime-completions|. + +Note: If you have other completion plugins installed, the key + may be mapped to the other plugins, and may not work as + expected. You can fall back to CTRL-x CTRL-o, or remap the + key as described in |vlime-mappings-remap|. + +These are the most frequently used features when editing the source +code. + +Vlime also has support for showing document strings and cross +references. Move the cursor inside the word "reverse", and type "\dda" +(without the quote marks), a preview buffer will then show a brief +description of the REVERSE function: + + Documentation for the symbol REVERSE: + + Function: + Arglist: (SEQUENCE) + + Return a new sequence containing the same elements but in reverse order. + +This information varies between Common Lisp implementations, but is +generally helpful. See |vlime-mappings-describe| for more operations +on describing symbols. + +Now keep the cursor inside the word "reverse", and type "\xc" (without +the quote marks). The cross reference (a.k.a. xref) buffer will pop up +with some content like this: + + SB-WALKER::LET*-BINDINGS + SB-SYS:CLOSE-SHARED-OBJECTS + SB-PCL::MAKE-PRELIMINARY-LAYOUT + SB-PCL::STD-COMPUTE-SLOTS + SB-PCL::STANDARD-COMPUTE-EFFECTIVE-METHOD + SB-PCL::COMPUTE-STD-CPL-PHASE-3 + SB-PCL::%UPDATE-LISP-CLASS-LAYOUT + .... + +Note: Depending on how your Common Lisp implementation was built, you + may get the "No xref found" error message instead. Don't worry. + You can try other xrefs listed in |vlime-mappings-invoke-xref|, + or skip this operation and proceed to the next section. + +These are the locations where the REVERSE function is called. Press + on one of them and Vlime will take you directly to the referenced +location, provided the source code is readable. Use |CTRL-O| to go +back to previous cursor locations. There are other kinds of cross +references, see |vlime-mappings-invoke-xref|. + +Before proceeding to the next section, you can close all Vlime windows +in the current tab page by typing "\wA" (without the quote marks) in +fibonacci.lisp in normal mode. See |vlime-mappings-close-window| for +all window-manipulating commands. + +====================================================================== +6. Compiling *vlime-tutor-compile* + +Make sure you have saved fibonacci.lisp, and then type "\of" (without +the quote marks) in it's buffer in normal mode. Go back to the REPL +buffer, you'll see the compilation result: + + -- + ; compiling file "/home/user/fibonacci.lisp" (written 28 FEB 2017 11:16:53 AM): + + ; /home/user/fibonacci.fasl written + ; compilation finished in 0:00:00.093 + +Note: If you have closed the window containing the REPL buffer, it + should now pop up again. + +This result means our code compiled cleanly, with no errors or +warnings etc. To generate a warning message, let's change the +expression calling the GENERATE function from + + (generate (1- n) b (+ a b) (push acc a)) + +To + + (some-other-func (1- n) b (+ a b) (push acc a)) + +SOME-OTHER-FUNC is not defined, of course. Save the file, and Compile +it again by typing "\of" (without the quote marks). A buffer will pop +up with a warning message: + + STYLE-WARNING: undefined function: SOME-OTHER-FUNC + +Pressing on the message will take you to the exact location where +the undefined function is called. + +Let's change the function call back to GENERATE, then save and compile +fibonacci.lisp again. The compiler messages (a.k.a. notes) buffer +should say: + + No message from the compiler. + +We will see whether the GENERATE function can work as expected in +|vlime-tutor-debug|. See |vlime-mappings-compile| for other compiling +operations. + +You can close the notes window before proceeding to the next section. + +====================================================================== +7. Debugging *vlime-tutor-debug* + +The first step of debugging in Common Lisp is usually trying out the +new function in the REPL. We'll do the same here. + +Go back to ad-hoc.lisp, write an expression to call +FIBONACCI:GENERATE: + + (fibonacci:generate 10) + +And send it to the REPL, via either "\ss" or interaction mode. + +A new buffer came out instead of the evaluation result. The buffer +content looks quite scary: + + Thread: 1; Level: 1 + + The value + 34 + is not of type + LIST + [Condition of type TYPE-ERROR] + + Restarts: + 0. RETRY - Retry SLIME REPL evaluation request. + 1. *ABORT - Return to SLIME's top level. + 2. ABORT - abort thread (#. The debugger +will then disappear, leaving a printed condition in the REPL buffer to +indicate the evaluation was aborted: + + -- + # + +There's an option in Vlime to tell the compiler our preference. Let's +use it now to preserve all available debug info: + + :let g:vlime_compiler_policy = {"DEBUG": 3} + +See |g:vlime_compiler_policy| for a detailed description of this +variable. + +With the compiler policy set, we compile fibonacci.lisp and call +FIBONACCI:GENERATE in the REPL again. Of course the debugger will +still pop up, but this time it has more detailed stack info: + + Thread: 1; Level: 1 + + The value + 34 + is not of type + LIST + [Condition of type TYPE-ERROR] + + Restarts: + 0. RETRY - Retry SLIME REPL evaluation request. + 1. *ABORT - Return to SLIME's top level. + 2. ABORT - abort thread (#) + + Frames: + 0. (SB-IMPL::LIST-REVERSE 34) + 1. (FIBONACCI:GENERATE 0 55 89 (((# . 13) . 21) . 34)) + 2. (FIBONACCI:GENERATE 1 (((# . 13) . 21) . 34) 55 (((# . 8) . 13) . 21)) + 3. (FIBONACCI:GENERATE 2 (((# . 8) . 13) . 21) 34 (((# . 5) . 8) . 13)) + 4. (FIBONACCI:GENERATE 3 (((# . 5) . 8) . 13) 21 (((# . 3) . 5) . 8)) + 5. (FIBONACCI:GENERATE 4 (((# . 3) . 5) . 8) 13 (((# . 2) . 3) . 5)) + 6. (FIBONACCI:GENERATE 5 (((# . 2) . 3) . 5) 8 (((# . 1) . 2) . 3)) + 7. (FIBONACCI:GENERATE 6 (((# . 1) . 2) . 3) 5 (((# . 1) . 1) . 2)) + 8. (FIBONACCI:GENERATE 7 (((# . 1) . 1) . 2) 3 (((NIL . 0) . 1) . 1)) + 9. (FIBONACCI:GENERATE 8 (((NIL . 0) . 1) . 1) 2 ((NIL . 0) . 1)) + 10. (FIBONACCI:GENERATE 9 ((NIL . 0) . 1) 1 (NIL . 0)) + 11. (FIBONACCI:GENERATE 10 (NIL . 0) 1 NIL) + 12. (SB-INT:SIMPLE-EVAL-IN-LEXENV (FIBONACCI:GENERATE 10) #) + 13. (EVAL (FIBONACCI:GENERATE 10)) + .... + +This stack deserves careful examination. We can see each call of the +FIBONACCI:GENERATE function and the values of it's arguments. To see +more details, move the cursor to frame 2 and press "d" (without the +quote marks). A preview buffer will show all local variable names and +their values, plus other useful info: + + Frame: 2 (Restartable) + + Locals: + A: ((((# . 8) . 13) . 21) . 34) + ACC: ((((# . 5) . 8) . 13) . 21) + B: 55 + N: 1 + + Location: + File: /home/user/fibonacci.lisp + Position: 239 + Snippet: + (generate (1- n) b (+ a b) (push acc a)))) + .... + +The variables A and B should be adjacent Fibonacci numbers, but A is +in fact a strange cons struct. + +To make it more challenging, I'll let you use what you learnt to +figure out what's wrong with our program. Don't worry if you can't +make it right. There is a corrected version of fibonacci.lisp in the +next section. See |vlime-mappings-debugger| for all available debugger +operations. + +====================================================================== +8. The Inspector *vlime-tutor-inspector* + +Now that we have fixed fibonacci.lisp, it should look like this: + + (in-package #:cl-user) + + (defpackage #:fibonacci + (:use #:cl) + (:export #:generate)) + + (in-package #:fibonacci) + + (defun generate (n &optional (a 0) (b 1) (acc (list))) + (if (<= n 0) + (reverse acc) + (generate (1- n) b (+ a b) (push a acc)))) + +It works well, but It's a boring function after all. We should +probably add some fancy classes and methods: + + (in-package #:cl-user) + + (defpackage #:fibonacci + (:use #:cl) + (:export #:generate + #:generator + #:next)) + + (in-package #:fibonacci) + + (defun generate (n &optional (a 0) (b 1) (acc (list))) + (if (<= n 0) + (values (reverse acc) a b) + (generate (1- n) b (+ a b) (push a acc)))) + + (defclass generator () + ((param-a :accessor generator-param-a :initform 0) + (param-b :accessor generator-param-b :initform 1))) + + (defgeneric next (obj) + (:method ((obj generator)) + (with-slots (param-a param-b) obj + (multiple-value-bind (result a b) (generate 1 param-a param-b) + (setf param-a a + param-b b) + (car result))))) + +We use a modified GENERATE function as a backend to build a GENERATOR +class. Now let's test it by first creating an instance. Save +fibonacci.lisp, and compile it by typing "\of" (without the quote +marks), then go back to ad-hoc.lisp, write down this MAKE-INSTANCE +expression and send it to the REPL: + + (make-instance 'fibonacci:generator) + +The REPL buffer will show the result: + + -- + # + +We can call the accessors or SLOT-VALUE to see whether the slots are +initialized correctly, but there is an easier way. We should bring up +the inspector. + +Go to the REPL buffer, and move the cursor to the printed +representation of our newly created instance, then type "\I" (without +the quote marks). The inspector buffer should appear. The info +displayed in the inspector will look like this: + + # + =================================== + + Class: # + -------------------- + Group slots by inheritance [ ] + Sort slots alphabetically [X] + + All Slots: + [ ] PARAM-A = 0 + [ ] PARAM-B = 1 + + [set value] [make unbound] + +We can see that PARAM-A is 0 and PARAM-B is 1. They are initialized +correctly. + +Now we are going to test the FIBONACCI:NEXT method. We want to call +the method on the instance we just created, and see if the slot values +are changed correctly. + +We didn't save a reference to the generator instance, but that's not +a problem. The REPL buffer remembers all evaluation results it has +seen. We can just yank the result from the REPL buffer. + +Keep the inspector open, go back to the REPL buffer, and make sure the +cursor is still on the printed representation of our +FIBONACCI:GENERATOR instance. Type "\y" (without the quote marks) to +yank the object into the register |quotequote|. + +Then add a new line in ad-hoc.lisp: + + (fibonacci:next ) + +Place the cursor on the space character just before the right +parentheses, and type "p" (without the quote marks). The new line +should now look like this: + + (fibonacci:next (swank:lookup-presented-object 10)) + +You may have a number other than "10", and that's OK. The +SWANK:LOOKUP-PRESENTED-OBJECT expression returns the +FIBONACCI:GENERATOR instance saved by the REPL. + +Evaluate the whole FIBONACCI:NEXT expression a few times, and we'll +get a series of Fibonacci numbers in the REPL buffer. + +Now go to the inspector and press "R" (without the quote marks) to +refresh it. We can see that PARAM-A and PARAM-B are successfully +changed: + + # + =================================== + + Class: # + -------------------- + Group slots by inheritance [ ] + Sort slots alphabetically [X] + + All Slots: + [ ] PARAM-A = 377 + [ ] PARAM-B = 610 + + [set value] [make unbound] + +The inspector is also capable of setting slot values. The square +brackets in the inspector buffer denote buttons, we can use these +buttons to manipulate PARAM-A and PARAM-B. + +Say we want to fast forward the generator to the 50th Fibonacci +number. Move the cursor inside the brackets just before PARAM-A, and +press or . An "X" will appear to indicate that this slot +is selected. Do the same with PARAM-B. The inspector should now look +like this: + + # + =================================== + + Class: # + -------------------- + Group slots by inheritance [ ] + Sort slots alphabetically [X] + + All Slots: + [X] PARAM-A = 377 + [X] PARAM-B = 610 + + [set value] [make unbound] + +Now move the cursor to "[set value]" and press or . A +buffer will pop up at the bottom prompting for the value of slot +PARAM-A. Let's write an expression to calculate the 50th Fibonacci +number: + + ; Set slot FIBONACCI::PARAM-A to (evaluated) : + (car (last (fibonacci:generate 50))) + +Then go back to normal mode and press . Another buffer will +appear, prompting for the value of PARAM-B. We give it the 51st +number: + + ; Set slot FIBONACCI::PARAM-B to (evaluated) : + (car (last (fibonacci:generate 51))) + +Remember to press in normal mode after you have done editing the +expression. The inspector should be automatically updated and look +like this: + + # + =================================== + + Class: # + -------------------- + Group slots by inheritance [ ] + Sort slots alphabetically [X] + + All Slots: + [X] PARAM-A = 7778742049 + [X] PARAM-B = 12586269025 + + [set value] [make unbound] + +We can call FIBONACCI:NEXT again to confirm that the internal state of +our generator instance is indeed changed: + + (fibonacci:next (swank:lookup-presented-object 10)) + +And the REPL buffer shows: + + -- + 7778742049 + +The inspector can also look inside lists, vectors, hashtables, and +packages. You can try to create some of these data structures and peek +inside. See |vlime-mappings-inspector| for all available operations in +the inspector. + +You can simply close the inspector window when you've done playing +with it. + +====================================================================== +9. Conclusion *vlime-tutor-conclusion* + +Our Finbonacci sequence generator is working, and we have covered the +most frequently used features of Vlime. You should now be able to use +Vlime to write and debug Common Lisp programs. You can then read the +full documentation in |vlime.txt|. \ No newline at end of file diff --git a/lisp/vlime.md b/lisp/vlime.md new file mode 100644 index 0000000..507a22f --- /dev/null +++ b/lisp/vlime.md @@ -0,0 +1,1450 @@ +*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. \ No newline at end of file