Implementing LSP specific commands (MetaLS, in this case)

[KaranAhlawat]

Hi, I really enjoy using eglot. I use it primarily with Metals, and it provides a lot of workspace/commands that are specific to it, that make life just a bit easier for Scala users.

In particular, I'm wanting to get started with implementing it's new-scala-file command, which says the client must have the metals/inputBox capability. Now, I understand this is not something you'd put into the core of eglot, and as such, I see no point in opening an issue for it. But I'm a bit lost on how I could implement that myself? Where should I even start :)

TL;DR: How does one implement a custom capability (metals/inputBox) in this case

[joaotavora]

The most recent version of the manual has a new section on this topic of server-specific extensions, but it's not published in HTML yet. I'll do that later (please ping me if I forget).

In the meantime, check the source material directly https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/misc/eglot.texi#n1268

[KaranAhlawat]

Thank you! I'll keep an eye out.

[KaranAhlawat]

Another thing I'd like to ask is, eglot-execute takes an ACTION as the second argument. How exactly are we supposed to construct that? In the eglot source code, I mostly saw it being constructed with eglot--request method, is that the right API?

[joaotavora]

I mostly saw it being constructed with eglot--request method, is that the right API?

yes, though it's consider internal yet, perhaps it shouldn't be. If you want an existing public external API, just use jsonrpc-request. ACTION is a fragment of given LSP response from the server. Normally you (the client) feed it back to the server so that it knows what it to do in your behalf (start a compilation process, execute automatic tests, cleanup some files, etc).

[KaranAhlawat]

I'm a bit confused. If I want to execute a workspace/executeCommand method (and this is purely client initiated), should I use eglot-execute or eglot--request then? Because from what I understand, eglot--request already sends sends a message to the server, so what would be the need of eglot-execute?

[joaotavora]

eglot-request the specific method, server replies with a number of actions, choose one of those actions in Elisp, use them as the ACTION argument for a eglot-execute request

[KaranAhlawat]

Alright, thanks for the prompt answers! As an aside, you asked me to ping you to release the HTML version of the Eglot manual in case you forgot. :)

[joaotavora]

Indeed I did forget. here's the uploaded version in HTML: https://joaotavora.github.io/eglot/#Extending-Eglot

[KaranAhlawat]

Hello, it's me again

eglot-request the specific method, server replies with a number of actions, choose one of those actions in Elisp, use them as the ACTION argument for a eglot-execute request

So, I'm not exactly sure what you meant by eglot--request the specific method (I also apologize if this is getting too distracting, or not appropriate). Is there somewhere I could see an example of it? I was able to successfully utilize eglot--request for running the server commands, but then what is the purpose of eglot-execute still?

I asked around a bit in the MetaLS community, and didn't really find anything that says I can request all the commands. They did say that at initialize time, it sends a list of commands under the executeCommandProvider key

:executeCommandProvider
            (:commands
             ["analyze-stacktrace" "zip-reports" "list-build-targets" "extract-method" "debug-adapter-start" "new-scala-file" "build-connect" "reset-workspace" "doctor-run" "insert-inferred-type" "build-restart" "discover-jvm-run-command" "generate-bsp-config" "build-disconnect" "copy-worksheet-output" "presentation-compiler-restart" "browser-open-url:https://github.com/scalameta/metals-feature-requests/issues/new?template=feature-request.yml" "reset-choice" "goto" "open-new-github-issue" "new-scala-project" "ammonite-stop" "scalafix-run" "build-import" "inline-value" "sources-scan" "bsp-switch" "new-java-file" "reset-notifications" "extract-member-definition" "ammonite-start" "compile-cancel" "goto-super-method" "goto-position" "compile-cascade" "convert-to-named-arguments" "discover-tests" "scala-cli-stop" "super-method-hierarchy" "scala-cli-start" "file-decode" "compile-clean" "scalafix-run-only"])

[joaotavora]

Is there somewhere I could see an example of it?

Of course, in the source code of eglot.el, for example in eglot-code-actions.

(let* ((server (eglot--current-server-or-lose))
         (actions
          (eglot--request
           server
           :textDocument/codeAction
           (list :textDocument (eglot--TextDocumentIdentifier)
                 :range (list :start (eglot--pos-to-lsp-position beg)
                              :end (eglot--pos-to-lsp-position end))
                 :context
                 `(:diagnostics
                   [,@(cl-loop for diag in (flymake-diagnostics beg end)
                               when (cdr (assoc 'eglot-lsp-diag
                                                (eglot--diag-data diag)))
                               collect it)]
                   ,@(when action-kind `(:only [,action-kind]))))))

Here :textDocument/codeAction is the "specific method" that returns actions. Afterwards, one of the elements of this actions array is passed to eglot-execute.

I was able to successfully utilize eglot--request for running the server commands, but then what is the purpose of eglot-execute still?

Of course eglot-execute calls eglot--request itself (again, you can see this in the source code).

(cl-defgeneric eglot-execute (server action)
  "Ask SERVER to execute ACTION.
ACTION is an LSP object of either `CodeAction' or `Command' type."
  (:method
   (server action) "Default implementation."
   (eglot--dcase action
     (((Command)) (eglot--request server :workspace/executeCommand action))
     (((CodeAction) edit command data)
      (if (and (null edit) (null command) data
               (eglot-server-capable :codeActionProvider :resolveProvider))
          (eglot-execute server (eglot--request server :codeAction/resolve action))
        (when edit (eglot--apply-workspace-edit edit this-command))
        (when command (eglot--request server :workspace/executeCommand command)))))))

But if you want you can call eglot--request yourself directly.

[KaranAhlawat]

After going through quite a bit of the source code, I was finally able to figure out how everything fits together. (It took a lot of edebug and macroexpand, but honestly I learnt quite a bit so i'm happy).

Would I be correct in saying that eglot-execute is a more general mechanism than eglot--request, and can essentially be thought of as a highly customisazle middleware to the eglot--request itself?
I saw that the default implementation primarily guards against sending the wrong data using a lot of type and key checking, and other checks as well.

[joaotavora]

Would I be correct in saying that eglot-execute is a more general mechanism than eglot--request, and can essentially be thought of as a highly customisazle middleware to the eglot--request itself?

"highly customizable middleware" is a bit exaggerated 😄

It's just a convenience function for calling eglot--request when the point is to is to run an "action", which, as the docstring indicated, can be a CodeAction or a Command. It does the right thing each time.

If you haven't yet, you should familiarize yourself with some of the LSP specification https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/ , particularly the parts about commands and actions.

[KaranAhlawat]

Yes, but if I were to override it, using cl-defmethod, it could do more than Commands and CodeActions, yes? Not that I'm thinking of doing that. Also, any idea how I can extract that `executeCommandProvider` list at initialisation, and if it would even be beneficial to do so? I'm leaning towards how lsp-metals does it and just create a new interactive method for each server command.

…

On Mon, 16 Oct, 2023, 2:27 am João Távora, ***@***.***> wrote: Would I be correct in saying that eglot-execute is a more general mechanism than eglot--request, and can essentially be thought of as a highly customisazle middleware to the eglot--request itself? "highly customizable middleware" is a bit exaggerated 😄 It's just a convenience function for calling eglot--request when the point is to is to run an "action", which, as the docstring indicated, can be a CodeAction or a Command. It does the right thing each time. If you haven't yet, you should familiarize yourself with some of the LSP specification https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/ , particularly the parts about commands and actions. — Reply to this email directly, view it on GitHub <#1305 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ANMDSZ2HNBFNEKENHONQ77TX7RE27AVCNFSM6AAAAAA6AE537CVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM3TEOBWHA3DA> . You are receiving this because you authored the thread.Message ID: ***@***.***>