- Read This Before Contributing!
- Expanding the LSP Client
- Expanding the LSP Server
- Expanding the Language Parsers
- Expanding Java Code and Updating JARs
- Server Logging
- Localization
This project is a VSCode language extension that uses the LSP architecture. Therefore before any contributions can be made, it is important to first familiarize yourself with the following information:
Learn about VSCode Language Extensions.
Learn about LSP.
There is also a good example-project that contains both a client and server.
The server is using LSP 3.1.15 protocol version.
Learn about Tree-Sitter and our language parsers.
In this project we use the web-tree-sitter project (can be found at https://www.npmjs.com/package/web-tree-sitter) to generate the parsers in .wasm format. The parsers are located in the Parsers directory under root. Both the client and server use this directory. Therefore if anyone wishes to use only one of them, it is necessary to also include the parsers in the new project.
Syntax coloring in VSCode uses Text-Mate grammers (as described at https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide). However, for easier maintainability we wanted to use our Tree-Sitter parsers for the syntax coloring, instead of having to maintain 2 different grammers. Our syntax coloring is heavily inspired by the works in this project. Our coloring functions are located here. There is a coloring function for each language which maps different syntax nodes to different color themes. To change the coloring, simply edit the way the function maps the themes.
The server currently supports the following capabililtes: Auto-complete, Go To references, Go To Definition and Error highlighting. If you wish to add new capabilites to the server you first need to familiarize yourself with the LSP protocol.
To enable more capabilites you need to add the relevant settings in the server capabilites response to client in code.
To answer LSP requests we have implemented language features which can be found in the following files:
LanguageUtils holds a collection of static methods that store no information and cause no side-effects. They answer basic queries on a given syntax tree. LanguageServices composes the methods mentioned above to answer more complicated queries regarding several syntax trees.
The general structure is as shown in this minimal class diagram:
- LanguageFacade exposes an LSP-like interface for the other components in the Server. It acts as an adapter between the rest of the Server classes and LanguageServices class.
- LanguagServices answers language queries regarding a workspace of a Policy Model. This class holds several FileManager instances, each representing a file in said workspace.
- FileManagerFactory is pretty self-explanatory: creates FileManager instances.
- FileManager represents a Policy Model file. Answers language queries regarding a single file.
To add more functionalities will require changing the LanguageFacade class and, if need be, the rest of the classes to support the new queries. To change / optimize the algorithms that answer the queries, please make new classes that inherit from FileManager )note that this is an abstract class) and change the FileManagerFactory to create instances of these new classes.
Our parsers are made using Tree-sitter. You must first familirize yourself with creating such parsers. If you want to modify the language parsers, look at the repositories of the parsers. After changing the parser projects, the WebAssembly parsers in the Parsers directory must be updated as well. There is a script for that, however it currently only works on Linux.
The project uses java code and external Jars to enable the features: Grpah visualization, Localization file creation, New model creation and Running model.
To run the model we are using the CLI Jar located here. this Jar is taken from Policymodel CLI. This Jar can be updated freely because it is only used for running the model, and has no code dependency.
Graph visualization, Creating localization files and New model creation features use the LibServiceApp Jar.
This jar is generated from the code located here.
When generating this jar you need to make sure that all Jar files in the resources folder are also used as dependencies to this jar.
The LibServiceApp code is also using CLI Jar (different path to jar from the Running Modle jar, thus updating one won't affect the other). The LibServiceApp code is tightly coupled to the CLI Jar, So be careful when updating the CLI Jar.
Creating new model has another JAR, this is the input form it is generated form the code in here. When generating this jar make sure to include all the jackson jars (3 jars) located in the resources folder.
The logging in the server is based on Winston logger.
By default logging is disabled. To activate it see here.
When activating the logging you can have only one instance of VSCode open with the logging activated.
You can't use logging before the initLogger function is called. This function is called after the client finished initialization.
How to log: use the getLogger function from Logger with the relevatnt logging domain.
Logger files are created in the plugin location dir (VScode installation dir) under Logs folder.
- serverHttp - To log any requests recieved from client.
- server - For logging in Solver and server
- documents - For loggin in documents and document manager
- parser - For logging relevant to Language Services
The globalLog.log file has the logging infromation from all domains together.
The Log also log all errors to a file named unhandeled_exceptions.log.
The localization interface is a web client app, presented by the vscode using the Webview API.
The LocalizationContainer.ts is the main component that responsible to render all the view.
The localization interface can be used as an independently app that LocalizationContainer.ts is its entry point.
The webview API provides a platform to present web view content inside the visual code.
The ViewLoader.ts is creating the webview and send it the proper html content.
For more Information click here
Our Web client use react javaScript library for building the user interface.
We are using version 16.
For more Information click here
We use webpack to bundle the react files.
The app bundle file configViewer.js located at client/configViewer/
For more Information click here