/als

Language Server implementation for AML and AML-defined metadata

Primary LanguageScalaOtherNOASSERTION

AML Language Server

Build Status

Overview

This section explains what is ALS, how does it work, who should use it, and how is ALS used today.

What is ALS?

The AML Language Server (ALS) is an implementation of the Microsoft Language Server Protocol (LSP) with a primary focus towards API tooling and API specifications, such as RAML, OpenAPI, and AsyncAPI. The objective of the ALS is to simplify API development by relying on the LSP to support API specifications in as many integrated development environments (IDEs) as possible. Besides API tooling and API specifications, you can extend the ALS to support any type of documents.

The supported types of documents include:

What does ALS do?

The ALS relies on the Anything Modeling Language (AML), more specifically on AML's dialect functionality. The ALS uses the AML to provide language server functionalities, such as validation, for the documents (also referred to as "instances" or "instance documents"). The ALS can also deduce possible contextual values at any given position of an instance document.

Using the representation of an API in a model, you can generate an outline or Document Symbol to render a more visual abstraction of an instance.

Who should use ALS?

The ALS is the answer for you if you are interested in authoring specification documents, including out-of-the-box API specification documents (API definitions), but also any custom document using AML's dialect functionality, using your favorite IDE. Additionally, developers can use the ALS to create IDE plugins based on the LSP.

What relies on ALS today?

Today, the ALS is used in MuleSoft Anypoint Design Center and in Anypoint Studio to provide feedback when authoring API definitions. You can see a preview in the following section.

Getting started

This section explains how to use the ALS as a language server.

Using ALS as a language server

The ALS can run as a standalone language server that you can use with any IDE. Most modern IDEs either natively support the LSP or provide a way to support the LSP using a plugin.

JVM

You can build the ALS server JAR:

sbt serverJVM/assembly

and then ran independently like so:

java -jar als/als-server/jvm/target/scala-2.12/als-server-assembly-%VERSION%.jar --port <port name>

JS (node-client)

You can build the targz to run it in a lsp-client for example:

sbt buildNodeJsClient 
cd als-server/js/node-package/
npm pack

JS (library)

You can build the targz to run it in monaco for example:

sbt buildJsServerLibrary 
cd als-server/js/node-package/
npm pack

You'll find the tgz at: als-server/js/node-package/aml-org-als-server-%VERSION%.tgz

Adapting Microsoft LSP example for VSCode

You can adapt the Microsoft VSCode LSP example by following these instructions, which guides you to successfully run an ALS client in VSCode.

Other examples

Here are some examples of how to use the ALS with other IDEs:

  • VS Code extension: instructions on how to plug ALS into the VSCode LSP client
  • Sublime Text 3 extension: instructions for plugin ALS into ST3 LSP client
  • IntelliJ extension: instructions for plugin ALS into IntelliJ's LSP client
  • Java LSP4J: example on how to connect to a LSP server in Java using LSP4J, which can then be used for connecting IDE features to a plugin

Previews

This sections illustrates previews of different IDEs.

Anypoint Design Center example:

AD Example

Visual Studio Code completion example (LSP):

VS Code Example

Visual Studio Code document symbol example (LSP):

VS Code Example


Other considerations

This section explains how the LSP is supported in ALS.

LSP support in ALS

The Language Server Protocol (LSP) is a tooling standardization for IDEs that defines a client-server architecture used to abstract a general implementation of used language-specific smarts.

In this client-server architecture, the server works as a standalone (write once with consistent behaviour) functionality provider. With this server, the client (each IDE plugin) independently understands the LSP messaging and communication, agnostic of the server implementation.

Currently supported LSP features

Currently, the following LSP capabilities are supported:

Currently extended features (not defined in LSP)

Besides LSP messages, we also support other custom operations, which are detailed here

Contributing

If you are interested in contributing to this project, ensure that you read our contributing guidelines.