Syntactic and Semantic movement shortcuts

[PizieDust]

Intro

• Semantic movement is navigation based on the meaning and structure of code, rather than its textual representation. E.g:
  • Jumping to the definition or declaration of a function, type, or variable.
  • Moving to the next or previous function definition.
  • Jumping to matching braces, parentheses, or other paired symbols.
• Syntactic movement involves navigating based on the syntactical structure of the code. This includes moving through the code in a way that respects its syntax rules and formatting. For example:
  • Jumping to the next or previous statement or expression.
  • Moving to the start or end of a block of code.
  • Navigating through different levels of indentation or nesting.

Limitations of the Standard LSP Protocol

LSP protocol contains four specifications for code navigation:

• Goto Definition (implemented): This usually takes the user to where a symbol (like a variable or function) is defined.
• Goto Declaration (implemented): Similar to "Go to Definition," but often takes the user to where the symbol is first declared.
• Goto Type Definition (implemented): This might take the user to where a type is defined.
• Goto Implementation (not implemented): Resolves the implementation location of a symbol at a given text document position.

Advanced Navigation from Merlin

Merlin finetunes navigation by understanding the semantics of OCaml code, providing features that go beyond standard navigation:

• Jump to Specific Targets: Merlin can jump to different kinds of constructs like function definitions, let bindings, or specific cases in a match expression.
• Handling Multiple Matches: OCaml's pattern matching often means that a single pattern can be matched in multiple places. Merlin allows developers to jump to the next or previous match case, which is something standard LSP requests cannot do.
• Module System Navigation: Merlin understands the entire module system, including functor applications and module inclusions. It can navigate between these complex structures.
• Semantic Awareness: Merlin’s navigation considers the semantics of the code, not just the syntax. This means it understands the meaning of the code, not just where symbols are declared or defined.

This functionality in Merlin is provided by the Jump command.

Using Code Actions

Using a CodeAction in combination with LSP's ShowDocumentRequest, we can be able to move the cursor within the same file to any position.

[rgrinberg]

Looks like a very interesting proposal, but it's missing a plan for the client side. This might sound obvious, but it's worth re-iterating that custom requests only provide value to users when there's clients that make use of them. Without the client side support, custom requests are just dead code.

For all the other custom requests that we've added, there was concrete motivation and an implementation in vscode quickly followed. Do you plan to implement client side support for using these navigtion requests? If so, describing how those might look like will make this feature far more compelling.

[PizieDust]

@rgrinberg Yes as a matter of fact we do have plans for the client integrations, at least for VS code. At this moment, we are also considering the possibility of using code actions and a custom command which is general and then each client can implement this general command which can just be a simple "go to location" implementation, which we believe is easier to do as most clients already have some manner of moving the cursor.

[rgrinberg]

Okay, that's reassuring. It seems like your proposal of a "go to location" (seems very similar to window/showDocument) + code actions would make the the custom request redundant? Am I understanding that correctly?

[voodoos]

It seems like your proposal of a "go to location" (seems very similar to window/showDocument) + code actions would make the the custom request redundant?

Yes, we are still exploring the various options to improve navigation and "code-actions + go-to-location" would be an alternative to the custom query that is more lightweight to support from the clients side.

The showDocument request looks promising though, as the optional range parameter might allow us to perform the jumps. It looks like a similar trick is already used by the go to mli code action. It makes for an additional client-server round-trip but if it works it might be the best compromise.