Contributing

The easiest way to get started contributing to the Antlers Language Server and Client are setting your environment up to run the various components.

The extension is written in both PHP 7+ and TypeScript.

#Environment Requirements

In order to run and build the extension's projects locally, your development machine will require the following to be available:

• node.js and npm

• TypeScript

#Installing Dependencies

Once your environment has the required software and tools available, we must download the source code for both the Visual Studio Code extension and the language server. To do this, either clone or download the https://github.com/Stillat/vscode-antlers-language-server repository.

Once you have a local copy of the repository, we must install the project's dependencies. To do this, issue the following command from the root of the project:

1npm install

This command will install the required node dependencies across all projects.

#Running the Project

Once you have the project dependencies installed, you may open the project in Visual Studio Code. From within the Run and Debug panel, select the Client + Server startup task and start the debugging session.

The Antlers Language for Statamic extension is implemented as a client and server. The server is an implementation of Microsoft's Language Server Protocol. You are encouraged to read about these technologies here:

https://code.visualstudio.com/api/language-extensions/language-server-extension-guide

#Syntax Highlighting

There are two ways syntax highlighting is provided by the Antlers Language for Statamic extension: grammar files and semantic highlighting. If you are used to TextMate grammars, or regular expression based grammar files, contributing to the grammar files would be the easiest way to get started.

#Grammar Files

The Antlers TextMate grammar is located within the client's source directory, and be found at client/syntaxes/antlers.json.

#Semantic Highlighting

Semantic highlight support is offered in addition to the TextMate grammar file, and is capable of providing much more accurate and pleasing highlighting results. This highlighting strategy utilizes the results of the server's Antlers parser, scope engine, and project analysis engines to determine what each part of a user's template actually is, and suggest the most accurate highlighting type it can.

The Semantic Highlighting Guide from the Visual Studio Code documentation is a great place to start if you are unfamiliar with semantic highlighting, and would like to contribute to it.

The Antlers semantic highlight implementation makes use the Antlers lexer results, and can be found within the server/src/services/semanticTokens.ts source file.

#Testing Code Changes

The language server contains a test suite that should be be run periodically when working on the language server's parsers, formatters, and related features.

The test suite can be ran by issuing the following command from the root of the project:

1npm run test:server

If you submit a pull request that has broken some tests, simply add a note to the PR with a description of the failing tests if you are unable to resolve them yourself. Someone looking to merge the PR will work to resolve the issues depending on the usefulness of the PR.