erlang-ls/erlang_ls

The Erlang Language Server

erlang_ls

An Erlang server implementing Microsoft's Language Server Protocol 3.17.

Documentation

Minimum Requirements

• Erlang OTP 24+
• rebar3 3.9.1+

Supported OTP versions

• 24, 25, 26

Quickstart

Compile the project:

make

To install the produced erlang_ls escript in /usr/local/bin:

make install

To install to a different directory set the PREFIX environment variable:

PREFIX=/path/to/directory make install

Command-line Arguments

These are the command-line arguments that can be provided to the erlang_ls escript:

Usage: Erlang LS [-v] [-t [<transport>]] [-p [<port>]] [-d [<log_dir>]]
                 [-l [<log_level>]]

  -v, --version    Print the current version of Erlang LS
  -t, --transport  Specifies the transport the server will use for the
                   connection with the client, either "tcp" or "stdio".
                   [default: tcp]
  -p, --port       Used when the transport is tcp. [default: 10000]
  -d, --log-dir    Directory where logs will be written.
                   [default: filename:basedir(user_log, "erlang_ls")]
  -l, --log-level  The log level that should be used. [default: info]

Configuration

It is possible to customize the behaviour of the erlang_ls server via a configuration file, named erlang_ls.config or erlang_ls.yaml. That file should be placed in the root directory of a given project to store the configuration for that project. It is also possible to store a system-wide default configuration, which is shared across multiple projects.

Please refer to the configuration section of the documentation to learn how to configure Erlang LS for a specific project.

Getting in Touch

If you have any questions about the project, feel free to open a new issue. You can also join the #erlang-ls channel in the Erlanger Slack if you would like to get involved or if you prefer a more informal mean of communication.

All contributions are welcome, be them in the form of a bug report, a question, feedback, or code.

I occasionally blog about the project on Medium.

References

https://microsoft.github.io/language-server-protocol/

License

The erlang_ls project is licensed under the Apache License 2.0. Please refer to the LICENSE file for details.

erlang_ls's Issues

Code Completion

Possible candidates:

• Erlang keywords (e.g. case, receive)
• Variables in the current scope
• Local function names
• Built-in functions (e.g. now())
• Module names
• Macros
• Record names
• Record fields
• Atom names
• Module attributes

Explain how to prune blacklisted dirs in Emacs setup

Generic LS implementation

This is a simple server that just translates JSON-RPC to calls to Erlang library functions, keeping track of the ongoing requests.

• transport should be configurable (at least TCP and stdio, as they are what's used currently)
• define naming of the library callbacks implementing the LSP methods
• should the method parameters and results be translated to/from Erlang terms independent of the LSP format? That's maybe an internal detail.
• handle cancellable requests; optionally, be able to return partial results.

Unify the location representation for POIs in the language server

Is your feature request related to a problem? Please describe.
Only for some POIs the location is offset by -1 in the erlang_ls_tree, which creates some confusion when developing other features.

Describe the solution you'd like
Only include the offset in a single place (e.g. erlang_ls_protocol:range/1) and keep all other places agnostic.

Describe alternatives you've considered
N/A.

Additional context
N/A.

Test Language Server with multiple clients

Currently the LS has only been tested with a single client and it needs to be modified to support multiple clients at the same time.

Code Formatting / Pretty Printing

It should be possible to format entire Erlang modules or given portions of code via the Erlang Language Server.

Several tools and APIs exist in the Erlang / Elixir ecosystem that should be considered, either for inspiration or as libraries. For example:

• erl_tidy (which seems to use erl_prettypr
• Code.format_string (Elixir)
• erl_pp
• erl_prettypr
• io_lib_pretty (apparently used by EDTS)
• prettypr

Ideally, some customizations should be possible. For example, one may prefer spaces over tabs or viceversa. Some organizations use a comma-first convention, whilst others don't.

Something that should also be investigated is how to treat code that does not compile (since some of the above tools work directly on the .beam files).

Useful References:

• The "Programming Elixir" book should have a section about pretty-printing
• This talk by Jose Valim covers the code formatter in Elixir
• In "The design of a pretty-print library" John Hughes introduces an algebraic approach to pretty printing
• This is the PR where formatting has been included in erlang-vscode
• A Medium Post discussing the code formatter in Elixir 1.6.0
• The "Strictly Pretty" paper about pretty-printing
• Demo usages of the Erlang Syntax Tools libraries for pretty-printing

Useful snippets:

c(test, [debug_info]).
{ok,{_,[{abstract_code,{_,AC}}]}} = beam_lib:chunks("test.beam",[abstract_code]),
io:put_chars(erl_prettypr:format(erl_syntax:form_list(AC))).

print(SyntaxTree, Paper, Ribbon) ->
    io:put_chars(erl_prettypr:format(SyntaxTree, [{paper, Paper},
						  {ribbon, Ribbon}])).

read(Name) ->
    {ok, Forms} = epp:parse_file(Name, [], []),
    Comments = erl_comment_scan:file(Name),
    erl_recomment:recomment_forms(Forms, Comments).

Implement auto-completion for exported functions for OTP modules

When pressing ":", auto-completion for exported functions should also work for OTP modules.

Server crashes when trying to go to definition of function

Describe the bug
Server crashes when trying to go to definition of function.

To Reproduce
Open the file jsx.erl from the erlang_ls project and try to go to to the definition of jsx_to_term:to_term/2 in line 84:

82: -spec decode(Source::json_text(), Config::jsx_to_term:config()) -> json_term() | {incomplete, decoder()}.
83: 
84: decode(Source, Config) -> jsx_to_term:to_term(Source, Config).

Expected behavior
Go to the definition of the function requested.

Actual behavior
In the logs you will see the messages:

2019-10-05 11:44:47.388 [error] <0.154.0>@erlang_ls_code_navigation:goto_definition:37 gen_statem <0.154.0> in state connected terminated with reason: no case clause matching [#{info => {function,{to_term,2}}
,range => #{from => {77,0},to => {77,7}},type => poi},#{info => {function,{to_term,2}},range => #{from => {73,0},to => {73,7}},type => poi}] in erlang_ls_code_navigation:goto_definition/3 line 37
2019-10-05 11:44:47.392 [error] <0.154.0>@erlang_ls_code_navigation:goto_definition:37 CRASH REPORT Process <0.154.0> with 0 neighbours crashed with reason: no case clause matching [#{info => {function,{to_te
rm,2}},range => #{from => {77,0},to => {77,7}},type => poi},#{info => {function,{to_term,2}},range => #{from => {73,0},to => {73,7}},type => poi}] in erlang_ls_code_navigation:goto_definition/3 line 37
2019-10-05 11:44:47.392 [error] <0.154.0>@erlang_ls_code_navigation:goto_definition:37 Ranch listener erlang_ls terminated with reason: no case clause matching [#{info => {function,{to_term,2}},range => #{from => {77,0},to => {77,7}},type => poi},#{info => {function,{to_term,2}},range => #{from => {73,0},to => {73,7}},type => poi}] in erlang_ls_code_navigation:goto_definition/3 line 37

Context

• erlang_ls version (tag/sha): 8a6eb98
• Editor used: Emacs
• LSP client used: lsp-mode

Add support for references

Define provider behaviour

Implement EQC model for lsp-client

To properly test the server, let's implement a QuickCheck state machine, where all possible requests to the server are listed as commands.

Support for rebar3 projects

Switch from `eqc` to `proper`

To make things simpler for contributors who do not have a QuickCheck license, let's switch to PropEr.

Goto Definition

The go to definition request is sent from the client to the server to resolve the definition location of a symbol at a given text document position. The result type LocationLink[] depends in the corresponding client capability clientCapabilities.textDocument.definition.linkSupport.

Request:

• method: textDocument/definition
• params: TextDocumentPositionParams

Response:

• result: Location | Location[] | LocationLink[] | null
• error: code and message set in case an exception happens during the definition request.

Registration Options: TextDocumentRegistrationOptions

Define scope of this project

What do we want from this project?

• A common LS implementation?
• An extended LSP with Erlang-specific methods? Would those pertain to editing code, or do we include debugging and other interactions with live runtimes?
• Do we want to include other BEAM languages?

Test and Document Language Server Usage from IntelliJ

So far, I have been interactive with the Erlang LS via Emacs. We should test (and document) its usage from IntelliJ as well, to ensure that the server works correctly independently from the editor.

Extra pass to calculate locations for POIs in attribute entries

When dealing with attributes, location information is lost at parse time, making code navigation hard for things like:

• Import list entries
• Export list entries
• Types in type specs

An extra pass could be used to ensure location information is correctly tracked as a POI in annotated trees.

Do not hard-code application path for code navigation

Instead, use the Root URI specified by the client and assume an OTP structure.

Distinguish Usage POI vs Definition POI

Currently, the same data structure (a POI) is used to represent all points of interest, despite of them being a usage or a definition.

Server crashes in case the module qualifier is a variable

Whenever a variable is used as a module qualifier, the server crashes.

Make POI type opaque

Ensure Point of Interest data structure are created via constructors and accessed only via getters.

Implement POI Database

The list of Points of Interest is calculated multiple times. Instead, we should use a DB (DETS?) to be able to store pre-calculated POIs for unchanged files.

Create CODE-OF-CONDUCT file

https://help.github.com/en/articles/adding-a-code-of-conduct-to-your-project

Exit Notification

A notification to ask the server to exit its process. The server should exit with success code 0 if the shutdown request has been received before; otherwise with error code 1.

Notification:

• method: exit
• params: void

Implement code completion for record fields

When accessing a record, pressing '.' should trigger auto-completion with the field names.

Add support for STDIO transport

Currently, the Language Server only supports TCP. The transport should be configurable and also support STDIO.

Create PR Template

https://help.github.com/en/articles/creating-a-pull-request-template-for-your-repository

Add a section to the README about debugging and troubleshooting erlang_ls

TCP Port should be configurable on startup

When using TCP as the transport, the client starts a server by specifying a port. Therefore, the port used by the server cannot be hard-coded.

Missing specs are not reported by Travis

The Travis build is successful even in absence of specs. This is not the case locally.

Do not re-compute syntax trees for already opened modules

List EDTS features which should be migrated to the erlang-ls based implementation

Be able to disable providers via config file

Create SUPPORT file

https://help.github.com/en/articles/adding-support-resources-to-your-project

Do not hard-code OTP Path for code navigation

CI pipeline occasionally times out

There seems to be a 10 minutes timeout for the Dialyzer step. Check if this can be modified.

Report parse crashes clearly to the user/developer

Implement code completion for record names

This should be triggered by pressing the '#' character.

Rename buffer/file into "document"

In the code base we refer to equivalent entities with different names: buffers and files. The former is an artifact of the initial setup, where processes were representing opened "buffers" in Emacs. document would be a better and more generic name for that kind of entity.

Create CONTRIBUTING file

https://help.github.com/en/articles/setting-guidelines-for-repository-contributors

Update Emacs instructions

The new version of the emacs-lsp package (v 6.0) introduces some backward incompatible changes, so the current Emacs instructions are not valid any longer. Update those instructions.

Add API to list all Points of Interest for a given module/tree

Cancellation Support

The base protocol offers support for request cancellation. To cancel a request, a notification message with the following properties is sent:

Notification:

• method: $/cancelRequest
• params: CancelParams defined as follows:

interface CancelParams {
	/**
	 * The request id to cancel.
	 */
	id: number | string;
}

A request that got canceled still needs to return from the server and send a response back. It can not be left open / hanging. This is in line with the JSON RPC protocol that requires that every request sends a response back. In addition it allows for returning partial results on cancel. If the request returns an error response on cancellation it is advised to set the error code to ErrorCodes.RequestCancelled.

Code navigation does not work record updates

Whenever encountering patterns such as Var#my_record{...} code navigation does not work.

Support funs in code navigation

Shutdown Request

The shutdown request is sent from the client to the server. It asks the server to shut down, but to not exit (otherwise the response might not be delivered correctly to the client). There is a separate exit notification that asks the server to exit. Clients must not send any notifications other than exit or requests to a server to which they have sent a shutdown requests. If a server receives requests after a shutdown request those requests should be errored with InvalidRequest.

Request:

• method: shutdown
• params: void

Response:

• result: null
• error: code and message set in case an exception happens during shutdown request.

Speed up CI by caching Dialyzer's PLT

Building a PLT for this project takes ~10 minutes in Travis. This causes, in the best scenario, a slow build pipeline and, in the worst one, some timeouts. It would be great to cache the PLT to speed up things.

Code navigation tests should use the server

Yasnippet warning on startup

The following warning appears when connecting to erlang_ls from the Emacs client.

Warning (emacs): Yasnippet is not required but ‘lsp-enable-snippet’ is set to ‘t’. You must either required yasnippet or disable snippet support.

Add erlang_ls configuration file