README.md

Wolfram Language Server

Table of Contents

• Wolfram Language Server
  • Installation
  • Run the Server
  • Language Server Features
    • DocumentSymbol
    • Hover
    • Completion
    • Diagnostics
    • Definition / References / Document Highlight
    • Code Action
    • Document Color / Color Presentation
    • Notes
  • Debug Adapter Features
    • Evaluate
    • Variables
    • Notes
  • Contribute
    • Design Principles
    • Todo list
  • Donations 💵
  • Footnotes

Wolfram Language Server (WLServer) is an implementation of the Microsoft's Language Server Protocol (LSP) for Wolfram Language. This server is implemented in Wolfram Language itself.

Our current goal is to provide the experience as good as the Mathematica FrontEnd with addition power from the editor.

We have provided the client-side code for VS Code here, which is based on some slight modifications of Microsoft's LSP example. If you are using other editors supporting LSP, some adaptation to the client would certainly work too.

Installation

0. Wolfram Mathematica (11.2 or higher¹) or Wolfram Engine (12.0 or higher).

1. Use git to clone this repository.

   git clone https://github.com/kenkangxgwe/lsp-wl.git

2. Install the dependent paclets with the latest versions from the Wolfram kernel / Mathematica. (This will cost some time for the first time) :

   PacletInstall["CodeParser"]
   PacletInstall["CodeInspector"]
   PacletInstall["ZeroMQLink"] (* 1.2.6+ *)

3. Install the client. Currently, we provide the VS Code extension on Visual Studio Marketplace: Wolfram Language Server For other editors, please refer to the wiki.

Run the Server

This section is usually handled by the client (editor). If you want to introduce lsp-wl to a new client, please continue reading.

Clients can start the server by running the init.wls file from Wolfram Mathematica executables

wolfram -script /path/to/lsp-wl/init.wls [args]
# or
wolframscript -f /path/to/lsp-wl/init.wls [args]

The possible arguments for the server are

• --help, -h to print help information.
• --socket=port to assign the port to which the server will connect. (Default: 6536)
• --tcp-server=port to assign the port at which the server will start. (Default: 6536)
• --pipe=pipename to specify the pipe name for the server to connect to.
• --log=level, -l level to specify the logging level of the server. (Levels: error, warn, info, debug. Default: info)
• --test, -t to run the unit test for the server.

If you want to run the server from Mathematica you can use the following code.

initfile = "/path/to/lsp-wl/init.wls";
args = {};
Block[{$ScriptCommandLine = Prepend[args, initfile], Quit = Function[{}, Throw[Null]]},
    Catch[<< (initfile)]
];

To use the debugger adapter (current in a very early stage), you need to include debuggerPort in the initializationOptions. And attach the frontend to that port. For VS Code, it is automatically done by the extension.

Language Server Features

DocumentSymbol

You may typeset your package in the same way that Mathematica FrontEnd handles it: a cell begins with two lines of comments, where the first line specifies the style of the cell and the second line names it. So you may get the outline structure of the file.

(* ::Title:: *)
(*Title of the file*)

(* ::Section:: *)
(*Section 1*)

Hover

Provide documentations for functions, variables and operators from the System` context, such as String, $Path and /@.

Also provide for MessageName and the special numerical literals with ^^ or *^.

Completion (Resolve)

The completion is shown by the client automatically. Functions and system variables from the System` context that matches the input would be displayed. Further information (such as documentation) would be provided for the items in the list.

To enter an unicode character, you may use the leader key \ followed by the alias just like esc in Wolfram FrondEnd. E.g., <esc>a in the FrontEnd is input as \a in the editor and the server will show you the available completions.

Snippet: You can trigger the snippet completion when you enter a [ after an symbol. After commit the completion, you may use Tab to jump to the next placeholder.

You may also trigger completion in other scenarios:

Diagnostics

Syntax error would be underlined. This feature is powered by CodeParser and CodeInspector paclets, thank you @bostick.

To adjust how some of the diagnostics are reported, adding their corresponding tags under the diagnosticsOverrides in initializationOptions. There are two kinds of ways to override the reporting rule:

• mitigated: The tags under this category will not be considered as an issue, and shown in the lowest severity, i.e. "hint". E.g. In VSCode, this will result in a elipesis under the reporting position but will not listed under the Problem tab.
• suppressed: The tags under this category will be completely ignored and not reported.

An example of configuration in JSON format is shown below:

"initializationOptions": {
    "diagnosticsOverrides": {
        "mitigated": [
            "ExperimentalSymbol",
            "UnusedParameter",
            "UnusedVariable",
        ],
        "suppressed": [
            "SuspiciousSessionSymbol"
            "DifferentLine",
        ]
    }
}

Definition / References / Document Highlight

It is now able to look up the definition and references of a local variable in a scope (Function, Module, etc) or pattern rules (SetDelayed, RuleDelayed).

Code Action

Code action is now able to,

• Look up the token in Mathematica Documentation Center (Not available for Wolfram Engine).

• Provide quick fix for some easy diagnostic items.

• Evaluate the selected code if debugger is running. See Evaluate.

InlayHint

Inlay hints are provided for:

• Basic flow control functions and scopes to show their parameters.
  

• Non-standard literal such as number, unicode strings and long names to show its normal text form.
  

• Every system functions, if showCodeCaptions is True and $Language is not "English", to show their translated names if possible.
  (Experimental, may have performance issues.)
  

Rename

Local variable names in the pattern rules (SetDelayed, RuleDelayed) and scopes (Block, With, etc) can be renamed.

Document Color / Color Presentation

Both Named Colors and Color Models with constant parameters are able to show and modify.
(Experimental, may have performance issues.)

Notes

The project is under development, so more features are on the way. Notice that, syntax highlight will not be provided as long as it is excluded from the LSP, but I believe there are already plenty of good Mathematica highlighters available for your editor.

Here is a full list of LSP features.

Debug Adapter Features

Evaluate

Code evaluation can be run from the code action of the selection or code lens. The results are usually shown in the debug console on the editor side.

Expressions can also be directly input from the debug console.

Variables

After evaluation, the symbol values can be retrieved from the editor. This includes the own values of variables and the down/up/sub values of functions defined.

The behavior of the variables mimics the workspace in MATLAB, so all the symbols defined in the debug console as well as evaluated from the file will be recorded. This also includes contexts other than Global` . The editor can also watch on a specific expression after each evaluation if applicable.

Notes

Here is a full list of DAP features.

Contribute

Design Principles

1. The files are located according to its context name. The init.wls is the entry script that parses the commandline arguments, loads packages and starts the server. This is intended to be different from a paclet, since it is not intended to be normally used inside Mathematica / Wolfram Kernel.

2. We implemented a stateless (by passing the state around :)) server in WolframLanguageServer`Server` that will parse and handle messages.

3. DataType` is a simple type system extracted as an independent package in the Matypetica library that supports pattern test on every field of a data structure. The operations on the data objects are designed to be immutable.

4. WolframLanguageServer`Test`* stores the unit tests for some of the functions which are integrated into GitHub Action.

Todo list

It will be nice if you want to make a contribution to the following topic.

• Our server-client communication only supports Socket with TCP protocol. We tried to use ZMQ_Stream protocol and SocketListen[] to enable concurrency, but it fails to send responses back to the client.

• It will be helpful to implement a stdio channel, so that the Mathematica earlier than 11.2 will also be supported, but it is really hard to expose the stdin channel. Hope this will be dicussed in future release of Wolfram kernel.

• More editor clients are needed. You can feel free to open a repository and create a pull request to add the clients in README.md once your client is released.

• Thanks to CodeParser and CodeInspector paclets, we are able to parse the code and extract useful information. Please consider to contribute to them as well.

  If you have ideas about how to use these fantastic language tools to help the language server with more features, please send us issues or pull requests.

If you want to help us with this project, feel free to fork and create a pull request. Do not forget to add unit tests if possible.

Donations 💵

If you really like this project, please donate to us! $5 (or equivalently ￥35). A cup of coffee ☕ would certainly brighten our day! Your donation would be the motivation for us to move forward, thanks in advance 😄.

• Paypal: [email protected]
• Alipay (With QRCode): 13916018006
  

Footnotes

[1] SocketListen[] is used for server-client communication, which is introduced since 11.2. ^