[EXTENSIONS] Define your own language

Welcome!

This is a quick guide on how to use an extension to create your own language with custom highlighting and on-hover documentation

Getting Started

First, you’ll need to learn how to create your own extension. You can find detailed instructions here

After that, you need to add the following to your package.json:

{
  "language.register": "language/config"
}

Where language/config is the location of the .json file for your language’s configuration. In other words, the extension manager will interpret this as language/config.json

Language Registration

It is important to understand that your language must not conflict with the languages already present in the application. We are currently discussing language extensions and IDs; everything else can be left as is.

Language configuration refers to its registration. You will define the structure, highlighting, and so on in a separate file. Here is an example of the configuration:

{
    "name": "slim",
    "displayName": "Slim",
    "extensions": ["slim"],
    "rules": "language/rules",
    "icon": "language/icon.svg"
}

Explanation of each field:

• name - The ID of your language. It must be unique
• displayName - The name of the language; it appears at the bottom of the editor when you open a file. It does not have to be unique, but it is recommended
• extensions - Language extensions. You can specify multiple extensions, without a period. They must be unique
• rules - The rules file for our language (highlighting, autocomplete...)
• icon - The language icon in .svg or .png format. It will be displayed in the file explorer and when the file is opened

Important

These values do not necessarily have to be unique if your extension overrides an existing language. Yes, you can create your own “js” by specifying [‘js’, “jsm”] in extensions. But right now we are looking at creating our own, independent language

Defining Structures (Rules configurating)

Now open your rules file. It must not be empty, otherwise you’ll get a runtime error. Set the minimum required content:

{
    "syntax": {},
    "autocomplete": {}
}

• syntax

This is where your syntax will be stored: keywords, definitions, and structures. It’s important to understand that these are static properties, meaning they cannot be changed while the extension is running—the rules will remain constant. However, this can be addressed through code

• autocomplete

Responsible for autocomplete (such as auto-closing brackets) and code snippets (code suggestions)

A Simple Example

To make things easier to understand later, here is a simple example of syntax highlighting. If you add this example to your rules file, the word “hello” will be highlighted in red (the keyword color) in your language.

{
    "syntax": {
        "keywords": [
            "hello"
        ]
    },
    "autocomplete": {
        "auto": true
    }
}

All properties for rules

syntax.keyword array

Anything you enter in this array will be highlighted as a keyword. This is useful for operators and other keywords.

"keywords": ["import", "await"]

syntax.string regex

Defining a string. Highlights everything that matches the regex as a string

"string": "\".*?\""

syntax.comment regex

Comment definition. Highlights anything that matches the regex as a comment

"comment": "//.*$"

syntax.constants array

Everything in the array is highlighted as a constant

"constants": ["async", "await"]

syntax.booleans array

Everything in the array is highlighted as a booleans

"booleans": ["true", "false", "NaN", "undefined", "null"]

syntax.isUppercaseConstant bool

If true, anything written in uppercase will be treated as a constant

"isUppercaseConstant": true

syntax.numbers regex

Anything that matches the regex is highlighted as a number

"numbers": "\\b(?:0x[0-9a-fA-F]+|0b[01]+|0o[0-7]+|\\d+(?:\\.\\d+)?)\\b"

syntax.camelCaseAsClassname bool

If true, anything written in camelCase will be highlighted as a class

"camelCaseAsClassname": true

syntax.camelCaseAsClassname bool

If true, anything written in camelCase will be highlighted as a class

"camelCaseAsClassname": true