Soar Language Server

This project provides editor/IDE support for the Soar language via the Language Server Protocol.

Features

Multiple IDE Support: VSCode is the gold standard, and it has also been heavily tested in Emacs. Other IDEs that have been tried include Intellij, Eclipse, and Sublime; it works to varying degrees in these IDEs, depending on the completeness of their generic LSP support plugins.
Tcl Expansion: The LSP will create a file (by default, ~tcl-expansion.soar) that will show the Soar rules generated by any selected top level command that generates them (e.g., sp or other custom procs). "Selected" means the cursor is in the command or its arguments.
Go to Definition: For Tcl variables and procs. Depending on your IDE and OS, this can be activated via Ctrl+left-click, right-click context menu, and/or F12.
Find references: Find all references to a selected Tcl variable or proc. This may be accessible via a right-click context menu.
Hover for Tcl Variable Values: Hovering over a Tcl variable will show the value that variables has at that point in the code.
Hover for Tcl Proc Documentation: Hovering over a Tcl proc call will show the comments immediately preceding its definition.
Error and Warning Reporting: All code is actually executed in an internal JSoar instance. If this produces any errors or warnings, these are captured and displayed within the IDE. The IDE attempts to continue past errors so that the analysis is as complete as possible.
Rename: Tcl variables can be renamed, and the known instances are all updated.
Autocomplete: A list of Tcl procs will be shown when typing top-level commands or [. A list of Tcl variables is shown after typing a $.
Code Folding: Comments, rules, and Tcl procs can be folded.

A note on syntax highlighting: This is not actually a built-in feature (it is not directly supported by LSP), but some IDEs already have plugins that provide Soar syntax highlighting. Search your plugin repository for existing plugins, such these plugins for VSCode and Sublime.

Installing

The Soar Language Server can be used with any editor or IDE that supports the Language Server Protocol. Prebuilt executables can be found on the releases page.

VSCode: Install the Soar Language Support plugin from the Visual Studio Marketplace.
Sublime: Download the server from the releases page and follow the instructions in integrations/sublime.
Emacs: Download the server from the releases page and use the plugin found at integrations/emacs.
Intellij: Download the server from the releases page and install the plugin found in integrations/intellj.
Eclipse: Download the server from the releases page and follow the instructions in integrations/eclipse.

Any other editor that supports the Language Server Protocol will work too. Some only require some configuration, while others need a small plugin. Contributions are welcome!

Project Setup

In order for the Soar LSP to know how to load your agent, you need to create a soarAgents.json file at the root of your workspace. This file defines the agents that are present in the workspace, and which one to use as the default. A default is needed because there is currently no way to resolve conflicts for things like "Go to Definition" when two different agents define the same variable. (Note that currently only the default agent is actually analyzed.)

Here's an example:

{
    "entryPoints": [
        {
            "path": "agent1/load.soar",
            "name": "agent1"
        },
        {
            "path": "agent2/load.soar",
            "name": "agent2"
        }
    ],
    "active": "agent1",
    "rhsFunctions": ["force-learn"]
}

The entryPoints list defines the name and start file for each agent. There should be at least one entry in here. The active field is the name of the agent to use as the default. This should match the name of one of the entries in the entryPoint list.

The rhsFunctions list is optional. This is a list of right hand side functions that should not produce warnings even though they are not defined by default.

If you modify this file, you may have to restart the LSP server (e.g., re-open your workspace or restart your IDE).

FAQ

Q: How can I contribute? A: See Developing below.

Q: Why is nothing working? (e.g., I get a bunch of errors, etc.) A: First, make sure you have Java installed. Next, make sure you have created a soarAgents.json file as described in Project Setup.

Q: How do I see Tcl expansions? A: A special file (called ~tcl-expansions.soar by default) is created. If your IDE doesn't automatically open that file, you should and arrange it so you can see it and your main code at the same time (e.g., side-by-side). As you click around in your code, it will just update. This is a temporary file that you can delete -- there's no need to save it.

Q: Why is there no syntax highlighting? A: LSP does not directly handle syntax highlighting -- other IDE-specific plugins do that. In VSCode, the Soar Language Server plugin automatically installs the other existing plugin that provides syntax highlighting. For other IDEs, you may have to install an appropriate plugin separately (many other IDEs have Soar syntax highlighters of varying quality).

Q: Can I comment out selected code? I don't see that in the features list. A: This is not handled directly by LSP, but it probably handled by the syntax highlighting plugin (in concert with your IDE). For example, in VSCode, Ctrl+/ comments/uncomments, but this is provided by the Soar syntax highlighting plugin (which the Soar Language Server plugin depends on), not directly by the LSP.

Developing

An overview of the design of the language server can be found in the design directory.

First, clone this repository:

$ git clone https://github.com/soartech/soar-language-server
$ cd soar-language-server

After the initial setup, the language server can be built with Gradle. The Gradle wrapper script is included:

$ ./gradlew test
$ ./gradlew installDist

This will create an executable at ./build/install/soar-language-server/bin/soar-language-server.

Before pushing changes, please run the Spotless Java checker:

$ ./gradlew spotlessJavaCheck

If this finds any format issues, apply them:

$ ./gradlew spotlessApply

Releasing

To release a new version of the language server:

Edit the version field in /integrations/vscode/package.json.
Create a tagged Git commit, using the same version number as the tag name.
Push the tag to GitHub

soartech / soar-language-server

readme