Custom command support - better argument helpers

[spenczar]

Hi, thanks eglot! It's so clean and nice to work with. I've been hacking on a plugin for the Python Language Server. My plugin provides custom commands.

I'd like to write a little bit of elisp to be able to invoke the custom commands. I can almost do this with eglot-execute-command, but one hard part is formatting the arguments. I have to reach into eglot internals to do that, which feels unsafe:

(defun swn-inject-docstrings ()
  (interactive)
  (let (arguments)
    (setq arguments (vector (eglot--path-to-uri buffer-file-name)
			    `(:start
			      ,(eglot--pos-to-lsp-position)
			      :end
			      ,(eglot--pos-to-lsp-position))))
    (eglot-execute-command (eglot-current-server) "swn.injectDocstrings" arguments)))

Note the use of eglot--path-to-uri and eglot--pos-to-lsp-position.

I think my concrete request is for:

• a bit of improvement to the documentation for eglot-execute-command. It took some spelunking to figure out that arguments needs to be a vector.
• making public functions for constructing typical LSP-format arguments

[nemethf]

The long #802 discusses (among other things) Eglot's public API. Maybe that's a good place to collect requests of "public functions for constructing typical LSP-format arguments".

Are you sure, @spenczar, that the last argument of eglot-execute-command needs to be a vector? Isn't this just the requirement of swn.injectDocstrings?

[joaotavora]

Are you sure, @spenczar, that the last argument of eglot-execute-command needs to be a vector? Isn't this just the requirement of swn.injectDocstrings?

Indeed, According to the spec it's "LSPAny": https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_executeCommand

That said, it's clear some of those -- functions have to become - functions. This isn't particularly hard and I want to do it.

But two things:

1. Going from -- to - is easy, but if we make a mistake, going back is much harder
2. I wanted to stash all this API in a separate file, maybe even in a separate namespace. The reason is that some of these things aren't really LSP-specific. They can be used for the DAP, too: https://microsoft.github.io/debug-adapter-protocol/specification#Events_Exited

[spenczar]

Of course, you are right about the vector. I think this was really just my own confusion about how Emacs works with JSON.

A separate namespace for these low-level functions would be great. I agree that it's good to be cautious, because you would be walking through a one-way door.

Is there a way I can help build some confidence? Perhaps by continuing to work on the plugin, and listing out functions and variables that I find myself using, to help identify what a real-world user uses?