Skip to content

Latest commit

 

History

History
625 lines (533 loc) · 18 KB

overview.md

File metadata and controls

625 lines (533 loc) · 18 KB
Raw
id title sidebar_label slug
overview
Text Editors
Overview
/

Latest Metals server versions

To find out how to set the version in your editor please check out the editor specific sections.



Snapshot releases are not guaranteed to work.


Editor support


Metals works with the following text editors with varying degree of
functionality.




  

    
    Visual Studio Code
    Vim
    Sublime Text
    Emacs
    Helix
  



  

    Installation
    Single click
    Single click
    Single click
    Single click
    Manual
  

  

    Build import
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Diagnostics
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Goto definition
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Goto type definition
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Completions
    ✅
    ✅*
    ✅
    ✅
    ✅
  

  

    Hover
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Hover for selection
    ✅
    ✅
    ✅
    ❌
    ✅
  

  

    Parameter hints
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Find references
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Run/Debug
    ✅
    
    
    ✅
    ❌
  

  

    Find implementations
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Rename symbol
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Code actions
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Worksheets
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Document symbols
    ✅
    Flat
    Flat
    ✅
    Flat
  

  

    Workspace symbols
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Formatting
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Folding
    ✅
    ✅
     
    ✅
    ❌
  

  

    Highlight
    ✅
    ✅
    ✅
    ✅
    ✅
  

  

    Metals Extensions
    ✅
    ✅
    Status bar, Input box, Decoration protocol, Did focus
    ✅
    ❌
  

  

     Organize imports
     ✅
     ✅
     ✅
     ✅
     ❌
  

  

     Implicit decorations
     ✅
     Shown in hover
     ✅
     ✅
     ✅
  

  

     Source file analyzer
     ✅
     ✅
     ✅
     ✅
     ❌
  

  

     Find text in dependency JAR files
     ✅
     ✅
     ✅
     ❌
     ✅
  

  

     Run scalafix rules
     ✅
     ✅
     ✅
     ✅
     ❌
  





Installation


Single click: Metals is easy to install and requires minimal configuration
out-of-the-box.


Few steps: installing Metals requires a few custom steps and minimal
configuration to work.


You can find instructions on how to install Metals for your editor on its
specific page.


Build import


✅: it is possible to import a build such as an sbt project directly from
the editor.


Requires browser: importing a build requires additional steps in a web
browser using a localhost server. It is not possible to import a build within
the editor.


Diagnostics


✅: Diagnostics are correctly published on compile.


Compile errors are reported as red squiggles in the editor. Compilation is
triggered on file save for the build target (project/module) containing the
focused text file.


Diagnostics


Known limitations


    

  • Slow feedback for type errors. Syntax errors are published as you type but
type errors are handled by the build tool, meaning diagnostics may take a
while to publish for large projects.
    • 



Goto definition


Navigate to symbol definitions for project sources and Scala/Java library
dependencies.


Symbols are resolved according to the last successful compilation in the build
tool and navigation continues to work despite syntax errors in the open unsaved
buffer.


Goto Definition


Known limitations


    

  • Navigation does not work for buffers that do not tokenize, for example due to
unclosed string literals.
    • 

  • scalameta/scalameta#1802
reflective invocations (methods calls on structural types) do not resolve to a
definition.
    • 



Completions


Use code completions to explore APIs, implement interfaces, generate exhaustive
pattern matches and more.


2019-04-12 14 19 39


    

  • Auto-import: imports are inserted at the bottom of the global import list.
Imports still need to be sorted and grouped manually, we are exploring ways to
automate this workflow in the future.
    • 

  • Override def: implement methods from the super class.
    • 

  • Exhaustive match: generate an exhaustive pattern match for sealed types.
    • 

  • String interpolator: automatically convert string literals into string
interpolators.
    • 

  • Filename: complete classnames based on the enclosing file.
    • 

  • Documentation: read the docstring for method symbols by pressing
ctrl+space in VS Code.
    • 



Known limitations


    

  • completion results don't include symbols that have just been typed in separate
files without a successful compilation in the build tool.
    • 



Hover (aka. type at point)


See the expression type and symbol signature under the cursor.




    

  • Expression type: shows the non-generic type of the highlighted expression.
    • 

  • Symbol signature: shows the generic signature of symbol under the cursor
along with its docstring, if available.
    • 



Signature help (aka. parameter hints)


View a method signature and method overloads as you fill in the arguments.




Find references


Find symbol references in project sources. References include implicits,
inferred .apply, desugared .flatMap from for comprehensions and other
symbols that may not be explicitly written in source, making it possible to
discover usages of difficult-to-grep symbols. The Metals navigation index is
low-overhead and should only require a few megabytes of memory even for large
projects.


Find references


Known limitations


    

  • References to overridden methods are not included in the results. For example,
if you run "find references" on the method Dog.name() then it won't include
references to the super method Animal.name().
    • 



Worksheets


✅: Worksheets work via inlay hints.


By default there is a 30 second timeout on worksheet evaluation, this setting can be overridden by -Dmetals.worksheet-timeout=<number of seconds> server property.


Document symbols


✅: Document symbols are displayed in a hierarchical outline.


Flat: Document symbols are displayed in a flat outline.


Document Symbols


Workspace symbols


Fuzzy search a symbol in the workspace of library dependencies by its name.


    

  • All-lowercase queries are treated as case-insensitive searches.
    • 

  • Queries ending with a dot . list nested symbols.
    • 

  • Queries containing a semicolon ; search library dependencies.
    • 



Fuzzy symbol search example


Formatting


Metals uses Scalafmt to respond to formatting requests from the editor,
according to the configuration defined in .scalafmt.conf.


Learn how to configure Scalafmt at
https://scalameta.org/scalafmt/docs/configuration.html.


Formatting


Code folding


Fold ranges such as large multi-line expressions, import groups and comments.




Document highlight


Highlight references to the same symbol in the open file.




Package explorer


Browse packages, classes and methods in the workspace and library dependencies
using the Metals sidebar. This feature is only implemented in VS Code.


Test Explorer


Test Explorer is a feature that allows editors to display tests as a separate
tree representation of tests. Although it was implemented in order to use Visual
Studio Code's
Testing API. The
Test Explorer API is editor agnostic and can be used by other editors than just
VS Code. test-explorer


Work on the Test Explorer is still in progress and the feature has some known
limitations:


    

  • Test Explorer is able to discover single test cases only for JUnit4 test
classes. Support for other test frameworks is being worked on.
    • 

  • detecting suites in cross scala-version projects is inconsistent, see
this issue.
    • 

  • there is no support for JS and Native platforms. For any changes subscribe to
the related
feature request.
    • 



You can find more information about Test Explorer under the
VS Code specific section.


Running Tests


Both run and debug under the hood use BSP's debug request. More information
about it can be found at
Bloop DAP diagram
or
BSP specification
website.


Metals Extensions


Status bar: Editor client implements the metals/status notification.


Tree view: Editor client implements the
Tree View Protocol.


Did focus: Editor client implements the metals/didFocusTextDocument
notification.


Input box: Editor client implements the metals/inputBox request.


Quick pick: Editor client implements the metals/quickPick request.


Window state: Editor client implements the metals/windowStateDidChange
notification.


✅: Editor implements all Metals extension endpoints.


The Metals language server supports custom extensions that are not part of the
Language Server Protocol (LSP). These extensions are not necessary for Metals to
function but they improve the user experience. To learn more about Metals
extensions, see integrating a new editor.


Implicit decorations


✅: Additional information inferred from the code can be show within the
code using virtual text.


Shown in hover: Additional information inferred from the code can be show
when hovering over a specific line. That hover only shows the additional symbols
on the current line.


Additional file types


Not all features are supported in all possible scenarios, especially when it
comes to non-standard Scala files like Ammonite scripts, worksheets or sbt
scripts.




  

    
    sbt scripts
    Worksheets
    Ammonite scripts*
    Standalone Scala files
  



   

    Diagnostics
    ✅\*
    ✅
    ✅
    ✅\*
  

  

    Goto definition
    ✅
    ✅
    ✅
    ✅
  

  

    Completions
    ✅
    ✅
    ✅
    ✅
  

  

    Hover
    ✅
    ✅
    ✅
    ✅
  

  

    Parameter hints
    ✅
    ✅
    ✅
    ✅
  

  

    Find references
    ✅
    ✅
    ✅
    ✅
  

  

    Run/Debug
    
    
    
    
  

  

    Find implementations
    ✅
    
    ✅
    ✅
  

  

    Rename symbol
    ✅
    ✅
    ✅
    ✅
  

  

    Code actions
    ✅
    ✅
    ✅
    ✅
  

  

    Document symbols
    ✅
    ✅
    ✅
    ✅
  

  

    Workspace symbols
    ✅
    All symbols are local
    ✅
    ✅
  

  

    Formatting
    ✅
    ✅
    ✅
    ✅
  

  

    Folding
    ✅
    ✅
    ✅
    ✅
  

  

    Highlight
    ✅
    ✅
    ✅
    ✅
  

  

     Organize imports
     
     
     
     
  

  

    Implicit decorations
    ✅
    
    ✅
    ✅
  

  

    Decode file (cfr, semanticdb, tasty, javap)
    
    
    
    
  





* Note that there are some specific Ammonite features that aren't supported
like multi-stage scripts. Currently
Ammonite support is also limited to Scala 2.


* Diagnostics for sbt script and standalone Scala files will only show parsing
errors, but not diagnostics coming from the compiler.