dap.txt

DAP client                                           *dap.txt*


nvim-dap is a Debug Adapter Protocol client, or "debugger", or "debug-frontend".

With the help of a debug adapter it can:

- Launch an application to debug
- Attach to running applications to debug them
- Set breakpoints and step through code
- Inspect the state of the application

A debug adapter is a facilitator between nvim-dap (the client), and a
language-specific debugger:


    DAP-Client ----- Debug Adapter ------- Debugger ------ Debugee
    (nvim-dap)  |   (per language)  |   (per language)    (your app)
                |                   |
                |        Implementation specific communication
                |        Debug adapter and debugger could be the same process
                |
         Communication via the Debug Adapter Protocol


To debug applications, you need to configure two things per language:

- A debug adapter (|dap-adapter|).
- How to launch your application to debug or how to attach to a running
  application (|dap-configuration|).


Available debug adapters:
  https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/

Debug adapter configuration and installation instructions:
  https://github.com/mfussenegger/nvim-dap/wiki/Debug-Adapter-installation

Debug Adapter Protocol:
  https://microsoft.github.io/debug-adapter-protocol/

                                      Type |gO| to see the table of contents.

==============================================================================
ADAPTER CONFIGURATION                                *dap-adapter*


Neovim needs a debug adapter with which it can communicate. Neovim can either
launch the debug adapter itself, or it can attach to an existing one.

To tell Neovim if it should launch a debug adapter or connect to one, and if
so, how, you need to configure them via the `dap.adapters` table. The key of
the table is an arbitrary name that debug adapters are looked up by when using
a |dap-configuration|.

For example, to register the `debugpy` debug adapter under the type `python` you
can add the following entry:

>
    lua << EOF
    local dap = require('dap')
    dap.adapters.python = {
      type = 'executable';
      command = os.getenv('HOME') .. '/.virtualenvs/tools/bin/python';
      args = { '-m', 'debugpy.adapter' };
    }
    EOF


`dap.adapters.<name>` is set to a `Adapter`.

The `Adapter` needs to contain a `type`, which can be one of:

- `executable`, to indicate that nvim-dap must launch the debug adapter. In
  this case nvim-dap will spawn the given process and communicate with it using
  stdio.

- `server`, to indicate that nvim-dap can connect to an already-running
  debug adapter via TCP.

For `executable` the following options are supported:

>
    command: string         -- command to invoke
    args:    string[]       -- arguments for the command
    options?: {
      env?: {}              -- Set the environment variables for the command
      cwd?: string          -- Set the working directory for the command
      detached?: boolean    -- Spawn the debug adapter process in a detached state.
                               Defaults to true.
    }
    id?: string             -- Identifier of the adapter. This is used for the
                               `adapterId` property of the initialize request.
                               For most debug adapters setting this is not
                               necessary.

For `server` the following options are supported:

>
    host?: string       -- host to connect to, defaults to 127.0.0.1
    port:  number       -- port to connect to
    id?: string         -- Identifier of the adapter. This is used for the
                           `adapterId` property of the initialize request.
                           For most debug adapters setting this is not
                           necessary.


Both types support the following additional options:

>
    options?: {
      initialize_timeout_sec?: number  -- How many seconds the client waits for a
                                       -- response on a initialize request before
                                       -- emitting a warning. Defaults to 4

      disconnect_timeout_sec?: number  -- How many seconds the client waits for
                                       -- a disconnect response from the debug
                                       -- adapter before emitting a warning and
                                       -- closing the connection. Defaults to 3

      source_filetype?: string         -- The filetype to use for content
                                       -- retrieved via a source request.


`dap.adapters.<name>` can also be set to a function which takes two arguments.
This first argument is a callback which must be called with the adapter table.
The second argument is the |dap-configuration| which the user wants to use.

This can be used to defer the resolving of the values to when a configuration
is used. An example use is java with eclipse.jdt.ls and java-debug, where the
debug adapter is spawned via a LSP command:
>

    dap.adapters.java = function(callback, config)
      M.execute_command({command = 'vscode.java.startDebugSession'}, function(err0, port)
        assert(not err0, vim.inspect(err0))

        callback({ type = 'server'; host = '127.0.0.1'; port = port; })
      end)
    end
<

There is an additional `enrich_config` property available for both adapter
types. This property is a function which allows an adapter to enrich a
configuration with additional information. It receives a configuration as first
argument, and a callback that must be called with the final configuration as
second argument.

An example use-case of this is the Java Debug Adapter, which can resolve
classPaths or modulePaths dynamically, so that users don't have to do that.

>


    local adapter = {
      type = 'server';
      host = '127.0.0.1';
      port = 8080;
      enrich_config = function(config, on_config)
        local final_config = vim.deepcopy(config)
        final_config.extra_property = 'This got injected by the adapter'
        on_config(final_config)
      end;
    }

<

==============================================================================
DEBUGEE CONFIGURATION                                *dap-configuration*


In addition to launching (possibly) and connecting to a debug adapter, Neovim
needs to instruct the debug adapter itself how to launch and connect to the
debugee. The debugee is the application you want to debug.

This is controlled via a `Configuration`, which has 3 required fields:

>
    type: string        -- Which debug adapter to use.
    request: string     -- Either `attach` or `launch`. Indicates whether the
                        -- debug adapter should launch a debugee or attach to
                        -- one that is already running.
    name: string        -- A user-readable name for the configuration.
<

In addition, a `Configuration` accepts an arbitrary number of further options
which are debug-adapter-specific.

Configurations are set in the `dap.configurations` table. The keys are
filetypes. If you run |dap-continue| it will look up configurations under the
current filetype.

For example:

>
    lua << EOF
    local dap = require('dap')
    dap.configurations.python = {
      {
        type = 'python';
        request = 'launch';
        name = "Launch file";
        program = "${file}";
        pythonPath = function()
          return '/usr/bin/python'
        end;
      },
    }
    EOF


Things to note:

- Values for properties other than the 3 required properties `type`,
  `request`, and `name` can be functions. If a value is given as a function,
  the function will be evaluated to get the property value when the
  configuration is used.

- Some variables are supported:
  - `${file}`: Active filename
  - `${fileBasename}`: The current file's basename
  - `${fileBasenameNoExtension}`: The current file's basename without extension
  - `${fileDirname}`: The current file's dirname
  - `${fileExtname}`: The current file's extension
  - `${relativeFile}`: The current file relative to |getcwd()|
  - `${relativeFileDirname}`: The current file's dirname relative to |getcwd()|
  - `${workspaceFolder}`: The current working directory of Neovim
  - `${workspaceFolderBasename}`: The name of the folder opened in Neovim

==============================================================================
DEBUGEE CONFIGURATION via launch.json                *dap-launch.json*


nvim-dap supports a subset of the `launch.json` file format used to configure
debug adapters in Visual Studio Code.

To load a `launch.json` file, use the `load_launchjs` function from the
`dap.ext.vscode` module.

Unlike VS Code, nvim-dap only supports standard JSON. Trailing commas on the
last item of a list are an error.


load_launchjs({path}, {type_to_filetypes})        *dap.ext.vscode.load_launchjs*

  Parses a JSON file at {path} and adds the entries to `dap.configurations`.
  This extends `dap.configurations` each time it is called.

  Parameters:
      {path}    Path to the `launch.json` file. Defaults to
                `.vscode/launch.json` in the current working directory.

      {type_to_filetypes}  A table mapping `type` values in `launch.json` to
                           one or more filetypes.
                           By default, the `type` values in `launch.json` will
                           be used as filetypes verbatim.

An example `launch.json` might look like this:

>
  {
      "version": "0.2.0",
      "configurations": [
          {
              "type": "java",
              "request": "launch"
          },
          {
              "type": "cppdbg",
              "request": "launch"
          }
      ]
  }

<

For the above configuration, calling `load_launchjs` adds the first entry to
`dap.configurations.java` and the second entry to `dap.configurations.cppdbg`.
If you wanted to add the second entry to the `c` or `cpp` configurations you
could call `load_launchjs` like this instead:
>
  require('dap.ext.vscode').load_launchjs(nil, { cppdbg = {'c', 'cpp'} })
<
==============================================================================
SIGNS CONFIGURATION


nvim-dap uses five signs:

- `DapBreakpoint` for breakpoints (default: `B`)
- `DapBreakpointCondition` for conditional breakpoints (default: `C`)
- `DapLogPoint` for log points (default: `L`)
- `DapStopped` to indicate where the debugee is stopped (default: `→`)
- `DapBreakpointRejected` to indicate breakpoints rejected by the debug
  adapter (default: `R`)

You can customize the signs by overriding their definitions after you've
loaded `dap`. For example:

>
    lua << EOF
    require('dap')
    vim.fn.sign_define('DapBreakpoint', {text='🛑', texthl='', linehl='', numhl=''})
    EOF
<

==============================================================================
REPL COMPLETION                                               *dap-completion*


nvim-dap includes an omnifunc implementation which uses the active debug
session to get completion candidates.

It is enabled by default in the REPL, which means you can use `CTRL-X CTRL-O`
to trigger completion within the REPL.

You can also configure completion to trigger automatically:

>
  au FileType dap-repl lua require('dap.ext.autocompl').attach()
<

Completion will then trigger automatically on any of the completion trigger
characters reported by the debug adapter, or on `.` if none are reported.

==============================================================================
MAPPINGS                                             *dap-mappings*


nvim-dap does not configure any mappings by default.

Some example mappings you could configure:

>
    nnoremap <silent> <F5> <Cmd>lua require'dap'.continue()<CR>
    nnoremap <silent> <F10> <Cmd>lua require'dap'.step_over()<CR>
    nnoremap <silent> <F11> <Cmd>lua require'dap'.step_into()<CR>
    nnoremap <silent> <F12> <Cmd>lua require'dap'.step_out()<CR>
    nnoremap <silent> <Leader>b <Cmd>lua require'dap'.toggle_breakpoint()<CR>
    nnoremap <silent> <Leader>B <Cmd>lua require'dap'.set_breakpoint(vim.fn.input('Breakpoint condition: '))<CR>
    nnoremap <silent> <Leader>lp <Cmd>lua require'dap'.set_breakpoint(nil, nil, vim.fn.input('Log point message: '))<CR>
    nnoremap <silent> <Leader>dr <Cmd>lua require'dap'.repl.open()<CR>
    nnoremap <silent> <Leader>dl <Cmd>lua require'dap'.run_last()<CR>


==============================================================================
TERMINAL CONFIGURATION                               *dap-terminal*


Some debug adapters support launching the debugee in an integrated or external
terminal.

For that they usually provide a `console` option in their |dap-configuration|.
The supported values are sometimes called `internalConsole`,
`integratedTerminal` and `externalTerminal`, but you need to consult the debug
adapter documentation to figure out the concrete property name and values.


If you want to use the `externalTerminal` you need to setup the terminal which
should be launched by nvim-dap:

>

  lua << EOF
  local dap = require('dap')
  dap.defaults.fallback.external_terminal = {
    command = '/usr/bin/alacritty';
    args = {'-e'};
  }
  EOF

<

Some debug adapters support launching the debugee in a terminal, but don't
provide an option to choose between integrated terminal or external terminal.
`nvim-dap` provides an option to force the external terminal.

>

  lua << EOF
  local dap = require('dap')
  dap.defaults.fallback.force_external_terminal = true
  EOF

<

If you're using the integrated terminal, you can configure the command
that is used to create a split window:

>

  lua << EOF
  local dap = require('dap')
  dap.defaults.fallback.terminal_win_cmd = '50vsplit new'
  EOF

<

The `terminal_win_cmd` defaults to `belowright new`. The value can also be a
function which returns a buffer number and optionally a window ID.

Be default `dap` opens the integrated terminal but keeps focus on the current
buffer. If you rather have focus to be shifted to the terminal when it opens
you can configure:

>

  lua << EOF
  local dap = require('dap')
  dap.defaults.fallback.focus_terminal = true
  EOF

<

`fallback` can be replaced with the |dap-adapter| type to have type
specific terminal configurations.

==============================================================================
API                                                  *dap-api*


Lua module: dap

The API is currently unstable.

(Incomplete)

continue()                                                      *dap.continue()*
        `continue()` resumes the execution of an application if a debug session
        is active and a thread was stopped.  Threads are usually stopped when a
        breakpoint is hit or an exception occurred.

        If no debug session is active, `continue()` will start a new debug session by:

        - Looking up the configurations (|dap-configuration|) for the current filetype.
        - If there is more than one configuration it will prompt the user to
          select one of them.
        - It calls |dap.run()| on the selected configuration.

        `continue()` is the main entry-point for users to start debugging an
        application.


run({config})                                                        *dap.run()*
        Looks up a debug adapter entry for the given configuration and runs it.
        This is implicitly called by |dap.continue()| if no debug session is
        active.

        Most users will want to start debugging using |dap.continue()| instead
        of using `run()`.  `run()` is intended for nvim-dap extensions which
        create configurations dynamically, for example to debug individual test
        cases.

        Parameters:
            {config}  |dap-configuration| to run


run_last()                                                      *dap.run_last()*
        Re-runs the last debug adapter / configuration that ran using
        |dap.run()|.


launch({adapter}, {config})                                       *dap.launch()*
        Launch a new debug adapter and then initialize it with the given
        |dap-configuration|

        You typically do not want to call this directly but use
        |dap.continue()| or |dap.run()|

        Parameters: ~
            {adapter}   `Adapter` to launch, see |dap-adapter|, the `type` is
                        not required in this case.
            {config}    |dap-configuration|


terminate(terminate_opts, disconnect_opts, cb),                                           *dap.terminate()*
        Terminates the debug session.

        If the debug adapter doesn't support the `terminateRequest`
        capability, this will instead call |dap.disconnect()| with
        `terminateDebugee = true`.

        Parameters: ~
            {terminate_opts}      Options for the `terminate` request.
                                  Defaults to empty.
                                  Not used if |dap.disconnect| is used.

            {disconnect_opts}     Opts for |dap.disconnect|
                                  Defaults to `{ terminateDebuggee = true }`

            {cb}                  Callback that is invoked once the session
                                  terminated or immediately if no session is
                                  active.

disconnect(opts, cb)                                              *dap.disconnect()*

        disconnect asks the debug adapter to disconnect from the debuggee and
        to terminate the debug adapter.

        The client session may remain open if the debug adapter does not
        terminate. To ensure the session gets closed, also call |dap.close()|.

        Requires an active session.

        Parameters: ~
            {opts}    Table with options for the disconnect request.
                      Defaults to `{ restart = false, terminateDebuggee = null }`

            {cb}      Callback that is invoked once the session
                      disconnected or immediately if no session is active.


close()                                                            *dap.close()*
        Closes the current session.

        This does NOT terminate the debug adapter or debugee.
        You usually want to use either |dap.terminate()| or |dap.disconnect()|
        instead.


attach({adapter}, {config})                                       *dap.attach()*
        Attach to a running debug adapter and then initialize it with the
        given |dap-configuration|

        You typically do not want to call this directly but use
        |dap.continue()| or |dap.run()|


set_breakpoint({condition}, {hit_condition}, {log_message})
                                                          *dap.set_breakpoint()*

        Same as |toggle_breakpoint|, but is guaranteed to overwrite previous 
        breakpoint.

toggle_breakpoint({condition}, {hit_condition}, {log_message})
                                                       *dap.toggle_breakpoint()*

        Creates or removes a breakpoint at the current line.

        Parameters: ~
            {condition}     Optional condition that must be met for the debugger
                            to stop at the breakpoint.
            {hit_condition} Optional hit condition, e.g. a number as a string
                            that tells how often this breakpoint should be visited
                            to stop.
            {log_message}   Optional log message. This transforms the breakpoint 
                            into a log point. Variable interpolation with {foo} is
                            supported within the message.

list_breakpoints()                                     *dap.list_breakpoints()*

        Lists all breakpoints and log points in quickfix window.

clear_breakpoints()                                   *dap.clear_breakpoints()*

    Removes all breakpoints

set_exception_breakpoints({filters}, {exceptionOptions})
                                              *dap.set_exception_breakpoints()*

    Sets breakpoints on exceptions filtered by `filters`. If `filters` is not
    provided it will prompt the user to choose from the available filters of the
    debug adapter.

    Parameters: ~
        {filters}          A list of exception types to stop on (optional).
                           Most debug adapters offer categories like `"uncaught"` and
                           `"raised"` to filter the exceptions.
                           If set to "default" instead of a table, the
                           default options as recommended by the debug adapter are
                           used.
        {exceptionOptions} ExceptionOptions[]?
                           (https://microsoft.github.io/debug-adapter-protocol/specification#Types_ExceptionOptions)
         
    >
        -- Ask user to stop on which kinds of exceptions
        require'dap'.set_exception_breakpoints()
        -- don't stop on exceptions
        require'dap'.set_exception_breakpoints({})
        -- stop only on certain exceptions (debugpy offers "raised", "uncaught")
        require'dap'.set_exception_breakpoints({"uncaughted"})
        require'dap'.set_exception_breakpoints({"raised", "uncaught"})
        -- use default settings of debug adapter
        require'dap'.set_exception_breakpoints("default")
    <

    You can also set the default value via a `defaults.fallback` table:

    >
        require('dap').defaults.fallback.exception_breakpoints = {'raised'}
    <

    Or per config/adapter type:

    >
        require('dap').defaults.python.exception_breakpoints = {'raised'}
    <

    In this example `python` is the type. This is the same type used in
    |dap-configuration| or the |dap-adapter| definition.


step_over([{opts}])                                            *dap.step_over()*
        Requests the debugee to run again for one step.

        For {opts} see |step_into|.


step_into([{opts}])                                            *dap.step_into()*
        Requests the debugee to step into a function or method if possible.
        If it cannot step into a function or method it behaves like
        |dap.step_over()|.

        If the debug adapter has the `supportsStepInTargetsRequest` and  
        {ask_for_targets} is true, the user can choose into which function they
        want to step into if there are multiple.

        Some debug adapters allow a more fine-grained control over the
        behavior of this command using the {opts} parameter:

        steppingGranularity:
          Can be 'statement' | 'line' | 'instruction'
          Will fall back to dap.defaults.fallback.stepping_granularity
          Default: 'statement'

        askForTargets:
          Ask the user to step into which function if there are multiple choices.
          Only for step_into.


step_out([{opts}])                                              *dap.step_out()*
        Requests the debugee to step out of a function or method if possible.

        For options see |step_into|.

step_back([{opts}]                                             *dap.step_back()*
        Steps one step back. Debug adapter must support reverse debugging.

        For {opts} see |step_into|.

pause({thread_id})                                                 *dap.pause()*
        Requests debug adapter to pause a thread. If there are multiple threads
        it stops `thread_id` from the optional parameter or asks the user which
        thread to pause.

reverse_continue()                                      *dap.reverse_continue()*
        Continues execution reverse in time until last breakpoint.
        Debug adapter must support reverse debugging.

up()                                                                  *dap.up()*
        Go up in current stacktrace without stepping.

down()                                                              *dap.down()*
        Go down in current stacktrace without stepping.


goto_({line})                                                      *dap.goto_()*
        Let the debugger jump to a specific line or line under cursor.
        This is an optional feature and not all debug adapters support it.

        The code between the current location and the goto target is not
        executed but skipped.

        Parameters: ~
            {line}  Line number or line under cursor if nil.


run_to_cursor()                                            *dap.run_to_cursor()*
        Continues execution to the current cursor.

        This temporarily removes all breakpoints, sets a breakpoint at the
        cursor, resumes execution and then adds back all breakpoints again.


repl.open({winopts}, {wincmd})                                 *dap.repl.open()*
        Open a REPL / Debug-console.

        Parameters: ~
            {winopts}  optional table which may include:
                        `height` to set the window height
                        `width` to set the window width
                        Any other key/value pair, that will be treated as window
                        option.

            {wincmd} command that is used to create the window for
                     the REPL. Defaults to 'belowright split'


        The REPL can be used to evaluate expressions. A `omnifunc` is set to
        support completion of expressions. It supports the following special
        commands:

          .exit               Closes the REPL
          .c or .continue     Same as |dap.continue|
          .n or .next         Same as |dap.step_over|
          .into               Same as |dap.step_into|
          .into_target        Same as |dap.step_into{askForTargets=true}|
          .out                Same as |dap.step_out|
          .up                 Same as |dap.up|
          .down               Same as |dap.down|
          .goto               Same as |dap.goto_|
          .scopes             Prints the variables in the current scopes
          .threads            Prints all threads
          .frames             Print the stack frames
          .capabilities       Print the capabilities of the debug adapter
          .b or .back         Same as |dap.step_back|
          .rc or
          .reverse-continue   Same as |dap.reverse_continue|

        You can customize the builtin command names or define your own
        custom commands by extending `dap.repl.commands`:
        >
          local repl = require 'dap.repl'
          repl.commands = vim.tbl_extend('force', repl.commands, {
            -- Add a new alias for the existing .exit command
            exit = {'exit', '.exit', '.bye'},
            -- Add your own commands; run `.echo hello world` to invoke
            -- this function with the text "hello world"
            custom_commands = {
              ['.echo'] = function(text)
                dap.repl.append(text)
              end,
              -- Hook up a new command to an existing dap function
              ['.restart'] = dap.restart,
            },
          }

        <


repl.toggle({winopts}, {wincmd})                             *dap.repl.toggle()*
        Opens the REPL if it is closed, otherwise closes it.

        See |dap.repl.open| for a description of the argument.


repl.close()                                                  *dap.repl.close()*
        Closes the REPL if it is open.


set_log_level(level)                                       *dap.set_log_level()*
        Sets the log level. Defaults to `INFO`  >

            :lua require('dap').set_log_level('TRACE')
<

        Available log levels:

          TRACE
          DEBUG
          INFO
          WARN
          ERROR

        The log file is in the |stdpath| `cache` folder.
        To print the location:  >

            :lua print(vim.fn.stdpath('cache'))
<
        The filename is `dap.log`


session()                                                        *dap.session()*
        Returns the current session or nil if no session exists.


status()
        Returns the status of the current debug session as text
        This is intended to be used within the statusline

        If no debug session is active the result is empty.

==============================================================================
WIDGET API                                                    *dap-widgets*


Warning: API is experimental and subject to change.


The UI of nvim-dap is by default minimal and noninvasive, but it provides
widget primitives that can be used to build and customize a UI.

Some examples:


View the current scopes in a sidebar:

>
  local widgets = require('dap.ui.widgets')
  local my_sidebar = widgets.sidebar(widgets.scopes)
  my_sidebar.open()
<

View the current frames in a sidebar:

>
  local widgets = require('dap.ui.widgets')
  local my_sidebar = widgets.sidebar(widgets.frames)
  my_sidebar.open()
<


View the current scopes in a centered floating window:

>
  local widgets = require('dap.ui.widgets')
  widgets.centered_float(widgets.scopes)
<


View the value for the expression under the cursor in a floating window:

>
  require('dap.ui.widgets').hover()
<


The widgets may have the following custom mappings enabled:

- `<CR>` to expand or collapse an entry
- `a` to show a menu with available actions


Available widgets entities:

- scopes
- frames
- expression
- threads


Available widget builder functions:

- sidebar({widget}, {winopts}, {wincmd})
    Creates a view for a sidebar. You must call `open` on the result to open the window.

    See |dap.repl.open()| for a description of `winopts` and `wincmd`.

- cursor_float({widget}, {winopts})
    Opens the contents of the widget in a floating window anchored at the cursor.

- centered_float({widget}, {winopts})
    Opens the contents of the widget in a centered floating window.

- hover({expr}, {winopts})
    Evaluates the expression and displays the result in a floating window.

    {expr} defaults to `<cexpr>`.
    It can be either a string as described in |expand()| or a function that
    should return the variable or expression that should be evaluated.

All widget builder functions return a `view`. A view has the following methods:

- open()
- close()
- toggle()


You could also customize the buffer and window creation using a low-level builder:

>
  local widgets = require('dap.ui.widgets')
  widgets.builder(widgets.scopes)
    .new_buf(function_that_creates_and_returns_a_buffer)
    .new_win(function_that_creates_and_returns_a_window)
    .build()
<


==============================================================================
EXTENSIONS API                                                *dap-extensions*


nvim-dap supports subscribing and listening to all responses or events that a
debug adapter might send to nvim-dap.

There are two tables for that:

- `dap.listeners.before`
- `dap.listeners.after`

Both `before` and `after` are nested tables where the first key is
`event_<event>` for events or `<command>` for request responses. The second key
is an arbitrary key used to identify the subscription. The second key must be
unique. If you're developing a plugin, using the plugin name might be a good
option to avoid conflicts with others.

`<event>` is the name of the event.
`<command>` is the name of the command that got executed and resulted in the
response.

Please refer to the Debug Adapter Protocol specification to get a list of all
events or requests and their response formats:

- https://microsoft.github.io/debug-adapter-protocol/specification#Requests
- https://microsoft.github.io/debug-adapter-protocol/specification#Events

For example:

>
  local dap = require('dap')
  dap.listeners.before['event_terminated']['my-plugin'] = function(session, body)
    print('Session terminated', vim.inspect(session), vim.inspect(body))
  end
<

Listeners registered in the `before` table are called *before* the internal `nvim-dap` handlers are called. The listeners registered in the `after` table are called *after* internal `nvim-dap` handlers.


For commands (request responses), the listeners are called with four arguments:

1. The session
2. An error: A optional table with `message` and `body` properties.
3. A table with the response. `nil` if an error occurred.
4. The original payload of the request

For events, the listeners are called with two arguments:

1. The session
2. The event payload

==============================================================================
UTILS API                                                          *dap-utils*


Lua module: dap.utils

pick_process()                                         *dap.utils.pick_process*
        Show a prompt to pick a PID from a list of processes.

        This uses `ps ah` to retrieve the process list and won't work if `ps ah`
        is not available. On windows this method uses `tasklist /nh /fo csv` command.

vim:ft=help