Help/input wanted: Changes to `dape` config format and `minibuffer` read functionality
svaante opened this issue · comments
Discussed in #71
Originally posted by svaante February 14, 2024
Intro
I want some feedback on an dape
issue that I have been think about for a while and something I want to get right, especially if the solution will break user defined configurations (calling it configs
was an mistake, templates
would have been better).
Let me just preface this to get your mind in the right place.
- The main goal of
dape
is to be as close to the emacs way of doing things. - The
dape
configuration format is anplist
not an json object. - It's an plus if the user can infer the format of an
dape
configuration from an "launch.json" (necessary evil I think).
Problems
- Currently there is no way of using
dape
to remove or ignore an property in an configuration. - Adapter capabilities needs to know each adapters Readme, wiki etc.
Improve usage ergonomics
If we use the following configuration as an example to illustrate the issue:
(gdb
modes (c-mode c-ts-mode c++-mode c++-ts-mode)
command-cwd dape-command-cwd
command "gdb"
command-args ("--interpreter=dap")
fn (dape-config-tramp)
:request "launch"
:program "a.out"
:cwd "."
:env (:DEBUG 1)
:stopAtBeginningOfMainSubprogram nil)
The user want to debug using the gdb
config but does not want the environment variable DEBUG
to be set.
There is two ways to work around this, both being painful:
- Add an new config to
dape-configs
where:env (:DEBUG 1)
is removed - Use
dape
command withlaunch :request "launch" :program "a.out" ...
with add all properties from thegdb
config without:env (:DEBUG 1)
Improve discoverability in batteries included configs
Let's reuse the same configuration.
(gdb
modes (c-mode c-ts-mode c++-mode c++-ts-mode)
command-cwd dape-command-cwd
command "gdb"
command-args ("--interpreter=dap")
fn (dape-config-tramp)
:request "launch"
:program "a.out"
:env (:DEBUG 1)
:stopAtBeginningOfMainSubprogram nil)
If I where to add this configuration as an batteries included config it would look something like this.
(gdb
modes (c-mode c-ts-mode c++-mode c++-ts-mode)
command-cwd dape-command-cwd
command "gdb"
command-args ("--interpreter=dap")
fn (dape-config-tramp)
:request "launch"
:program "a.out"
:stopAtBeginningOfMainSubprogram nil)
Notice the missing :env
property. Even though I know that :env
exist I can't document the fact in the config without using some strange default value for :env
to make it show up in dape
completions and the hint section.
The user has to lookup the gdb manual to figure out that's the way to set environment variables.
Suggested solutions
Here follows some possible solutions. Split into the categories:
- Change config format
- Change
dape
command read functionality
Introduce an new special config value
One way would be to add an "null" or an "ignore" symbol.
- In the first example: an user would then with
dape
command overwrite the config value withgdb :env some-new-symbol
- In the second example: the property
:env some-new-symbol
can be added (the user still has to know that the value is anplist
), which makes it show up in the hint buffer and as an completion.
JSON "null"
Add an symbol/keyword whatever which allows the user to set a property to json "null" to send null
as part of the launch
/attach
request.
Ramblings on which symbol to use
In lisp `nil` is `false` and `t` is `true`. But when parsing json "null" and "false" is valid values but there is no obvious to translate into in lisp.In json-parse-buffer
the default value is :null
, in jsonrpc
it's 'nil
and "false" is :json-false
.
Not a big fan of any of them as it's not really line up with point (2.) under Solutions but that does not rule out the solution.
One benefit of having an null value is to allow for dape
to actually send "null" if an adapter requires null for some reason.
Ignore symbol
Introduce an symbol, let's call it ignore
which just removes the property at before sending it off to adapter.
And using as follows with the dape
command: gdb :env ignore
Extremely unobtrusive option.
Add an special value construct with docs
This will only solve the problem under "Improve discoverability in batteries included configurations". But can be combined with the other options to solve both.
Something like the following:
(gdb
modes (c-mode c-ts-mode c++-mode c++-ts-mode)
command-cwd dape-command-cwd
command "gdb"
command-args ("--interpreter=dap")
fn (dape-config-tramp)
:request "launch"
:program ("a.out" :doc "Relative or absolut path to program")
:env (:doc "Environment variables, example value (:DEBUG \"1\")")
:stopAtBeginningOfMainSubprogram (nil :doc "Set a temporary breakpoint at the program’s main procedure"))
The :doc
information can then be displayed in the hint section of the minibuffer
.
Rework dape
read config
To allow for removal of properties, which basically means that that all properties needs to be presented in some way to be able to remove them.
Pop up buffer
- Let the
dape
command complete from the available configs nothing more - Add an additional command
dape-edit
which lets you edit the configuration
Using edit-macro
as inspiration and with combination of "Add an special value construct with docs" can show docs as well.
Transient
Maybe transient could be used in some way am not that familiar with transient
.
Define an specialized parser for each config
See #44 (comment)
Hi @svaante,
Have you considered maybe using eioio types to represent debugger configurations. You can form a dedicated debugger class for each non-general type and attach documentation in the same way as customization types (I'm not sure but I think you should also be able to read them back if you want to keep them for a completing read interface).