Add dap.ABORT to allow config functions to abort session

Closes #1036

doc/dap.txt

@@ -280,6 +280,20 @@ Things to note:
     end,
 <
 
+- Functions for top level properties can return the `dap.ABORT` constant to
+  signal that you want to abort starting a debug session. An example:
+
+>lua
+    program = function()
+      local path = vim.fn.input({
+        prompt = 'Path to executable: ',
+        default = vim.fn.getcwd() .. '/',
+        completion = 'file'
+      })
+      return (path and path ~= "") and path or dap.ABORT
+    end
+<
+
 - The configuration can have an optional metatable with `__call`
   implementation. The function will get called when the configuration is used
   and it must return a new configuration table. This can be used to

lua/dap.lua

@@ -24,6 +24,8 @@ local function notify(...)
   lazy.utils.notify(...)
 end
 
+--- Sentinel value; signals an operation should be aborted.
+M.ABORT = {}
 
 M.status = function(...)
   return lazy.progress.status(...)
@@ -321,6 +323,9 @@ local var_placeholders = {
 
 local function expand_config_variables(option)
   option = eval_option(option)
+  if option == M.ABORT then
+    return option
+  end
   if type(option) == "table" then
     local mt = getmetatable(option)
     local result = {}
@@ -487,6 +492,12 @@ function M.run(config, opts)
       assert(config and type(config) == "table", "config metatable __call must return a config table")
     end
     config = vim.tbl_map(expand_config_variables, config)
+    for _, val in pairs(config) do
+      if val == M.ABORT then
+        notify("Run aborted", vim.log.levels.INFO)
+        return
+      end
+    end
     local adapter = M.adapters[config.type]
     if type(adapter) == 'table' then
       lazy.progress.report('Launching debug adapter')

tests/integration_spec.lua

@@ -363,6 +363,24 @@ describe('dap with fake server', function()
     dap.step_over()
     assert.are.same(session, dap.session())
   end)
+
+  it("Run aborts if config value is dap.ABORT", function()
+    local msg = nil
+    require('dap.utils').notify = function(m)
+      msg = m
+    end
+    dap.run({
+      name = "dummy",
+      type = "dummy",
+      request = "launch",
+      foo = function()
+        return dap.ABORT
+      end,
+    })
+    wait(function() return msg ~= nil end)
+    assert.is_nil(dap.session())
+    assert.are.same("Run aborted", msg)
+  end)
 end)
 
 describe('session disconnect', function()