UltiSnips-advanced.txt

*UltiSnips-advanced.txt*    Advanced topics for UltiSnips


1. Debugging                                    |UltiSnips-Advanced-Debugging|
   1.1 Setting breakpoints                      |UltiSnips-Advanced-breakpoints|
   1.2 Accessing Pdb                            |UltiSnips-Advanced-Pdb|

=============================================================================
1. Debugging                                   *UltiSnips-Advanced-Debugging*
                                               *g:UltiSnipsDebugServerEnable*
UltiSnips comes with a remote debugger disabled        *g:UltiSnipsDebugHost*
by default. When authoring a complex snippet           *g:UltiSnipsDebugPort*
with python code, you may want to be able to     *g:UltiSnipsPMDebugBlocking*
set breakpoints to inspect variables.
It is also useful when debugging UltiSnips itself.

Note: Due to some technical limitations, it is not possible for pdb to print
the code of the snippet with the `l`/`ll` commands.

You can enable it and configure it with the folowing variables: >

    let g:UltiSnipsDebugServerEnable=0
        (bool) Set to 1 to Enable the debug server. If an exception occurs or
        a breakpoint (see below) is set, a Pdb server is launched, and you can
        connect to it through telnet.

    let g:UltiSnipsDebugHost='localhost'
        (string) The host the server listens on

    let g:UltiSnipsDebugPort=8080
        (int) The port the server listens to

    let g:UltiSnipsPMDebugBlocking=0
        (bool) Set whether the post mortem debugger should freeze vim.
        If set to 0, vim will continue to run if an exception
        arises while expanding a snippet and the error message describing the
        error will be printed with the directives to connect to the remote
        debug server. Internally, Pdb will run in another thread and the session
        will use the python trace back object stored at the moment the error
        was caught. The variable values and the application state may not reflect
        the exact state at the moment of the error.
        If set to 1, vim will simply freeze on the error and will resume
        only after quiting the debugging session (you must connect via telnet
        to type the Pdb's `quit` command to resume vim). However, the
        execution is paused right after caughting the exception, reflecting
        the exact state when the error occured.

NOTE: Do not run vim as root with `g:UltiSnipsDebugServerEnable=1` since anything
can connect to it and do anything with root privileges.
Try to use these features only for...  debugging... and turn it off when you
are done.

These variables can be set at any moment. The debug server will be active
only when an exception arises (or a breakpoint set as below is reached),
and only if `g:UltiSnipsDebugServerEnable` is set at the moment of the
error. It will be innactive as soon as the `quit` command is issued
from telnet.

1.1 Setting breakpoints                      *UltiSnips-Advanced-breakpoints*
-----------------------

The easiest way of setting a breakpoint inside a snippet or UltiSnips
internal code is the following: >

    from UltiSnips.remote_pdb import RemotePDB
    RemotePDB.breakpoint()

...You can also raise an exception since it will be caught, and then will
launch the post-mortem session. However, using the breakpoint method allows
to continue the execution once the debugger quit.

1.2 Accessing Pdb                                    *UltiSnips-Advanced-Pdb*
-----------------

Even though it's possible to use the builtin Pdb, (or any other compatible
debugger), the best experience is achived with Pdb++.
You can install it this way: >

    pip install pdbpp

It is a no-configuration replacement of the built-in pdb.

To connect to the pdb server, simply use a telnet-like client.
To have readline support (arrow keys working and history), you can use socat: >

    socat READLINE,history=$HOME/.ultisnips-dbg-history TCP:localhost:8080

(Change `localhost` and `8080` to match your configuration)
To leave the server and continue the execution, run Pdb's `quit` command

Known issue: Tab completion is not supported yet.