Features List

[ckipp01]

This is an ongoing demonstration of features that exist while using nvim-metals.

Feel free to subscribe to this to get notified when new features are added!

A couple things to keep in mind when looking at the examples.

1. I'm using some other plugins which might change the appearance of the defaults. For example, I use telescope.nvim along with the telescope extension nvim-metals provides to trigger all my metals commands. All commands are available this way. They are also all available with their :command equivalents. For example :MetalsImportBuild is the same as the Import Build command in the telescope extension.
2. I use nvim-bqf to give a nice preview of what's in my quickfix. So commands that will by default pipe stuff into my quickfix window will then be automatically previewed.

Again, this is just my workflow. The beauty of the built-in LSP of Neovim is that you can mix and match all sorts of stuff to get the exact experience you want. The above extensions work great for me, but maybe not for you. You'll have to experiment or just use the default, that works too.

Features

• Importing your build
• Triggering specific compiles
• Goto definition
• Find references
• Find implementations
• Hovers (plus inferred types, implicit params, and other synthetics)
• Goto super method
• Rename
• Insert type annotation
• Organize imports
• Formatting
• Signature help
• Document symbols
• Workspace symbols
• Workspace diagnostics
• Switching your build server
• Worksheet support
• Analyzing stacktraces
• Find in dependency jars (useful for searching configs)
• Generating a BSP config
• Info about Metals, locations of files, etc
• Creating a new Scala file
• TVP Support
• Show various formats of the file
• Debugging support
• Creating a new Scala project
• Creating a new Java file
• Show build target info
• Toggling the Metals Logs
• Run Scalafix Rules

[ckipp01]

Importing your build

Upon opening a new project for any supported build tool, you'll see a prompt to import your build. This should happen automatically in a new workspace and also when you change something in your build. Keep in mind that if you make multiple changes it a row, it may not prompt you every time because there is a refresh time so we don't constantly spam you with requests if you're making a lot of changes in succession.

For some reason if you either ignore this request by saying Not now or Don't show again and you want to manually trigger that, you can using the Import Build command. (:MetalsImportBuild).

[arbitrary-dev]

How to trigger this "Metals Commands" popup? I don't see a mapping for it or it being listed among available :Metals* commands...

[antosha417]

How to trigger this "Metals Commands" popup? I don't see a mapping for it or it being listed among available :Metals* commands...

it is done via telescope extensions. So you need to have it installed. Then try this command
:lua require"telescope".extensions.metals.commands()

[jaime-paredesp]

Can I import a build with a specific heap size?

[ckipp01]

Triggering specific compiles

Apart from the default save, which triggers a compile for your current build target and it's dependencies, you may also find situations where you want to not only compile those, but also the inverse dependencies. You can use a cascade compile for this (:MetalsCompileCascade).

Since cascades can take a while, there is also a Cancel Compilation command (:MetalsCompileCancel).

For those times where things may get out of wack, there is also a Compile Clean command to both clean and then compile (:MetalsCompileClean).

[ckipp01]

Goto Definition

In order to use this you'll need a mapping for vim.lsp.buf.definition(). This works for both internal and external dependencies. You can also jump to java dependencies.

[arbitrary-dev]

But how does one open a class in nvim-metals?

In coc-metals it was: <space>s<class_name><Enter>

[ckipp01]

So looking at the config it looks like that calls CocList -I symbols, so the equivalent in nvim-metals would actually be be #279 (comment). It might look a bit different depending on if you're using a plugin like telescope or not.

[jaime-paredesp]

Is it enough if I have a map to builtin.lsp_definitions with Telescope? i.e. vim.keymap.set('n', '<leader>gd', '<cmd>Telescope lsp_definitions<cr>')

[ckipp01]

If you want to use telescope for this, then sure.

[ckipp01]

Find references

In order to use this you'll need a mapping for vim.lsp.buf.references.

[ckipp01]

It's actually a plugin that I use that is showing the preview. It's called nvim-bqf.

[V4G4X]

Thanks I got it.

[z4f1r0v]

When I select a reference, the window that popped up doesn't close. Do you have some special configuration for telescope, @ckipp01?

[ckipp01]

Hey @z4f1r0v I don't use Telescope for this feature so I'm not really sure. You may have to minimize it and report a bug to them if it's not closing correctly since this feature is actually just a core LSP feature that telescope hooks into unrelated to nvim-metals.

[mvillafuertem]

@ckipp01 I try to reproduce this same example, using a case class, but I get ‘No references found’, any thoughts?

vim.keymap.set("n", "gr", vim.lsp.buf.references)

MetalsRunDoctor

## Metals Info
  - Metals Server version: 1.3.0
  - Metals Java: 17.0.3 from Azul Systems, Inc. located at /nix/store/znr41d41j7qp60y61lqcish0vhzwldmf-zulu17.34.19-ca-jdk-17.0.3/zulu-17.jdk/Contents/Home

Below are listed the build targets for this workspace. One build target corresponds to one classpath. For example, normally one sbt project maps to two build targets: main and test.

## Workspaces

### Workspace: /Users/user1/project/my-service
 - Build definition is coming from sbt.
 - Build server currently being used is Bloop v1.5.17.

## Build Targets

### my-service
  - target type: Scala 2.13.10
  - goto functionality: metalsDecode:file:///Users/user1/project/my-service/my-service.metals-buildtarget
  - compilation: ✅ 
  - diagnostics: ✅ 
  - interactive: ✅ 
  - semanticdb: ⚠️ 
  - debugging: ✅ 
  - java: ✅ 

[ckipp01]

Find implementations

In order to use this you'll need a mapping for vim.lsp.buf.implementation().

[bblfish]

The trick to find out what to put in the lua config file is to run the :Telescope command which opens a list of the commands and a search field. For the find implementations examples shown above, searching for "implement" returns lsp_implementations which I could then get to work by adding the following command in my lua/plugins.lua file:

vim.keymap.set("n", "gi", require("telescope.builtin").lsp_implementations )

after of course removing the default gi binding.

[ckipp01]

Hovers (plus inferred types, implicit params, and other synthetics)

In order to make this work you'll need a mapping for vim.lsp.buf.hover().

If you'd also like the extra information shown in the With synthetics added, you'll also need to enable this in your metals config since they are off by default. See examples of this under the metals-settings section of the nvim-metals docs.

[ckipp01]

Goto super method

In order to use this you'll need to have a mapping for vim.lsp.codelens.run() and then trigger it where you see the code lens on an overridden member.

In more advanced situations there is al an option to see the entire hierarchy and choose where you jump to using the Super Method Hierarchy command (:MetalsSuperMethodHierarchy).

[ckipp01]

Rename

In order to use this you'll need a mapping for vim.lsp.buf.rename().

[ckipp01]

Insert type annotation

In order to use this you'll need a mapping for vim.lsp.buf.code_action().

[ckipp01]

Organize imports

There are multiple ways to organize your imports. The first is using the Organize Imports command (:MetalsOrganizeImports).

The second method is to be on top of an unused warning on an import and triggering a code action via your vim.lsp.buf.code_action() mapping.

[ckipp01]

Formatting

In order to use this you'll need a mapping for vim.lsp.buf.formatting().

[ckipp01]

Signature help

In order to use this you'll need a mapping set up for vim.lsp.buf.signature_help().

[ckipp01]

Document symbols

In order to use this you'll need a mapping set up for vim.lsp.buf.document_symbol(). My gif below is utilizing telescope.nvim for this.

[V4G4X]

How does your open line that? I have nvim-bqf installed so it uses that.
But just for this command I'd love to have this window.

[ckipp01]

For this specific command I'm not actually using nvim-bqf, but rather telescope.nvim.

[V4G4X]

Got it.
So basically it was :Telescope and then enter "Document" until the comands says lsp_document_symbols.
Press enter and you get the above.

Just mapped :Telescope to a keymapping so I get all the telescope command without having to learn each specific one.

[ckipp01]

Keep in mind that all these have lua api's as well. For example in my own config for this I use:

vim.keymap.set("n", "gds", require("telescope.builtin").lsp_document_symbols)

[ckipp01]

Workspace symbols

In order to use this you'll need a mapping set up for vim.lsp.buf.workspace_symbol(). My gif below is utilizing telescope.nvim for this.

A couple extra things to note for using this:

1. Metals has some cool extra things here. If you preface your search with ; for example you can also search your external deps. You can also do shortened querys like j.t.i to search for java.time.Instant.
2. Depending on what you're using to display these results, some send in an empty query string to start off the process. Since this can potentially be a huge amount of symbols, metals won't respond to an empty query search. So for example with telescope, I need to use builtin.lsp_dynamic_workspace_symbols not the normal builtin.lsp_workspace_symbols.

[bblfish]

I got the above to work when typing gwz by adding to my lua/plugins.lua file (after installing telescope and getting it to return a good health check with :checkhealth telescope

vim.keymap.set("n", "gwz",  require("telescope.builtin").lsp_dynamic_workspace_symbols )

just below the command shown in the default setup

map("n", "gws",  vim.lsp.buf.workspace_symbol )

[ckipp01]

Workspace diagnostics

There are a lot of way to view your diagnostics as the vim.diagnostic api is pretty great. By default many use vim.diagnostic.setloclist(), but this only show you the diagnostics in the current buffer. I personally prefer to see all my workspace diagnostics with the ability to only see errors or warnings. You can do this using the following functions in your mappings:

vim.diagnostic.setqflist() // all diagnostics
vim.diagnostic.setqflist({severity = "E"}) // all errors
vim.diagnostic.setqflist({severity = "W"}) // all warnings

[ckipp01]

Switching your build server

You can switch your build server by using the Switch Build Server command (:MetalsSwitchBsp).

[ckipp01]

Worksheet support

By default opening any *.worksheet.sc should be evaluated by Metals as a worksheet. The evaluations will display on the right had side as output.

Long output or printed lines

If you have very long output or you maybe print lines in a function, you see this indicated by …. You can always see the full hover output by having a mapping set for require("metals").hover_worksheet(). Triggering this anywhere on the line will show you it.

Copying all the worksheet output

Sometimes you want to be able to share some code with the output. You can do this by using the Copy Worksheet Output command (:MetalsCopyWorksheetOutput).

[ckipp01]

Analyzing stacktraces

If you have a stack trace that you'd like to analyze it, just copy it and then trigger the Analyze Stacktrace command (:MetalsAnalyzeStacktrace). This will bring you to a stacktrace.scala file in your .metals dir that has code lenses that you can then trigger to jump to the parts of the trace. To utilize the code lens, you'll need to make sure you have a mapping set up for vim.lsp.codelens.run().

[ckipp01]

Find in dependency jars (useful for searching configs)

If you'd like to search through files in your dependency jars to for example find values in a config or another type of file, you can do this using the Find in Dependency Jars command (:MetalsFindInDependencyJars).

[ckipp01]

Generating a BSP config

If you're using a build tool that can also be a build server, such as sbt or mill, Metals can also generate the .bsp/<entry>.json file for that build tool. This is no longer necessary to do before switching via Switch Build Server, but if you'd like to ensure your BSP entry for this build tool is fresh you can use the Generate BSP Config command (:MetalsGenerateBspConfig).

[ckipp01]

Info about Metals, locations of files, etc

To see all this information you can use the Info command (:MetalsInfo).

You can also see information about all of your build targets and info about possibly misconfiguration in the server via the Metals Doctor command (:MetalsRunDoctor).

[amirphl]

It has changed to :MetalsRunDoctor.

[ckipp01]

Creating a new Scala file

Metals can create new files which will include a skeleton structure for the type of file and also the package name. There are multiple ways to trigger this. The first is with the New Scala File command (:MetalsNewScalaFile).

The second way to trigger this is if you create a type that doesn't yet exist that you intend to make a file for, it will offer this to you when you trigger a code action via your vim.lsp.buf.code_action() mapping.

[ckipp01]

TVP Support

Metals has an LSP extension called the Tree View Protocol which can be used to provide various panels of information. nvim-metals implements the metalsPackages portion of this. This provides a few different nice features. In order to use this you'll want mappings for require("metals.tvp").toggle_tree_view() and require("metals.tvp").reveal_in_tree().

NOTE: There are some tvp config options that can be seen in :h metals-tvp-module, but the default ones you'll probably use the most is <CR> to expand a node and r to trigger the node command (jumping from tree into that place in the code).

Jumping into the tree structure from your code and vice versa

NOTE: This also works for your external dependencies.

[ckipp01]

That's extra logic that I don't really feel adds much. I have the node_command_mapping in the docs, so if that's not clear I'd gladly accept a pr making it more clear, but I don't think I'll add the extra logic you mention.

[arbitrary-dev]

:)

 ## TVP Support
 
 Metals has an LSP extension called the [Tree View Protocol](https://scalameta.org/metals/docs/integrations/tree-view-protocol) which can be used to provide various panels of information. `nvim-metals` implements the `metalsPackages` portion of this. This provides a few different nice features. In order to use this you'll want mappings for `require("metals.tvp").toggle_tree_view()` and `require("metals.tvp").reveal_in_tree()`.
+
+Use `r` to jump from tree view to the code.

[antosha417]

That's extra logic that I don't really feel adds much. I have the node_command_mapping in the docs, so if that's not clear I'd gladly accept a pr making it more clear, but I don't think I'll add the extra logic you mention.

I've used a couple of "tree" plugings in vim. And I think all of them open the file if you hit expand shortcut on something that is can't be expanded. For me this feature would add consistency among plugins. And it seems pretty straight forward to implement.

[arbitrary-dev]

And it seems pretty straight forward to implement.

Contribute 😃

[antosha417]

you can try it out in a branch from this pr #440

[ckipp01]

Show various formats of the file

Metals allows you to see your current file in various formats. The formats and their commands that are available are:

• Show Cfr (:MetalsShowCfr)
• Show Javap (:MetalsShowJavap)
• Show Javap Verbose (:MetalsShowJavapVerbose)
• Show Semanticdb Compact (:MetalsShowSemanticdbCompact)
• Show Semanticdb Detailed (:MetalsShowSemanticdbDetailed)
• Show Semanticdb Proto (:MetalsShowSemanticdbProto)
• Show Tasty (:MetalsShowTasty) NOTE: Only for Scala 3

[ckipp01]

Debugging support

Thanks to the great work of mfussenegger/nvim-dap there is also support for running, testing, and debugging your code right in nvim-metals. For more information on this, please do check out the nvim-dap docs and also the section of docs for nvim-metals about the DAP integration. There are lots of extra plugins available to make the experience a bit fancier, but to give you a very general idea only using nvim-dap:

Running your code

Setting a breakpoint and looking at the current scope

Expression evaluation

Running your tests

Using code lenses

You can also directly trigger these via the run, debug, test, or testDebug code lenses.

[arbitrary-dev]

How do I get test output?

When I run test code lens nothing happens.

And I see these in logs:

2022.10.19 21:58:05 INFO  tracing is disabled for protocol dap-server, to enable trac
ing of incoming and outgoing JSON messages create an empty file at /home/user/project/.metals/dap-server.trace.json or /home/user/.cache/metals/da
p-server.trace.json
2022.10.19 21:58:05 INFO  tracing is disabled for protocol dap-client, to enable trac
ing of incoming and outgoing JSON messages create an empty file at /home/user/project/.metals/dap-client.trace.json or /home/user/.cache/metals/da
p-client.trace.json
2022.10.19 21:58:05 INFO  Starting debug proxy for [com.app.AppSpec]
2022.10.19 21:58:09 INFO  Trying to attach to remote debuggee VM localhost:60837 .
2022.10.19 21:58:09 INFO  Attaching to debuggee VM succeeded.
2022.10.19 21:58:15 INFO  Canceling debug proxy for [com.app.AppSpec]
2022.10.19 21:58:15 INFO  Closing debug server tcp://0.0.0.0:38255

[ckipp01]

The output will be in the DAP REPL. You can toggle it with require("dap").repl.toggle().

[gogamid]

@ckipp01 Is there support for conditional breakpoint?

[linux-root]

Posting the code suggested by @ckipp01 here in case anyone needs it. This triggers the DAP REPL (Run Console) to open automatically after running code from nvim-metal, mimicking IntelliJ's behavior :

    dap.listeners.after["event_terminated"]["nvim-metals"] = function()
      dap.repl.open()
    end

[ckipp01]

Creating a new Scala project

Under the hood Metals calls g8 to do this. You can use this with the New Scala Project command (:MetalsNewScalaProject).

[samgj18]

Hello,

For some reason I can only make this work on a already existing Scala project. Is there a way to do it in a blank new git project?

[ckipp01]

Hey! So unfortunately nvim-metals needs to "attach" before the commands become available, meaning you already need to be in a Scala project to create a new one. It's preferable to just use g8 directly if you don't have any project yet, which is what Metals uses under the hood.

[samgj18]

Got it, that makes sense. Thanks a lot!

[ckipp01]

Creating a new Java File

Just like the feature to create a new Scala file, you can also trigger the "New Java File" command (:MetalsNewJavaFile) to get the option to create a new Java Class, Interface, or Enum.

[ckipp01]

Show Build Target Info

Starting with 0.11.2 (or the latest snapshot as of posting this) you can view all sorts of info about a chosen build target by using the :MetalsShowBuildTargetInfo command. This will then give you a picker to choose which target you'd like to see, and then show you all the info.

[ckipp01]

Toggling the Metals Logs

This feature is used to show you the Metals-specific logs for your workspace.

Behind the scenes all this command does is issue a tail -f .metals/metal.log inside of a Neovim term.

[ckipp01]

Run Scalafix Rules

NOTE: This feature currently requires usage of the latest Metals Snapshot serverVersion = latest.snapshot.

Running the :MetalsRunScalafix command will run the rules that are defined in your .scalafix.conf file. Note that external rules (apart from OrganizeImports) currently also require you to defined them in the scalafixRulesDependencies table in your Metals config.