[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

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
    }
}

Syntax properties

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", "let"]

syntax.operators array

Anything you enter in this array will be highlighted as a operator.

"keywords": ["typeof", "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.defineFunctionKeyword string

Everything that follows this word is defined as a function

"defineFunctionKeyword": "func"

syntax.functionCalls regex

Anything that matches the regex is treated as a function call

"functionCalls": "\\b\\w+(?=\\()"

syntax.characters regex

Anything that matches this regex will be highlighted as a character

"characters": "::|\\.\\.\\.|&|\\|"

syntax.defineClassKeyword array

Everything that follows this word is defined as a class

"defineClassKeyword": "class"

syntax.types array

Anything that is added to the array is treated as a type

"types": ["int", "string"]

Autocomplete properties

autocomplete.auto bool

If true, this enables default autocomplete features. For example, auto-closing of parentheses

"auto": true

autocomplete.keywords array

Custom, unique autocomplete suggestions. Similar to snippets in Visual Studio Code. Let’s look at a simple example:

"keywords":[
    {
        "prefix": "func",
        "body": [
            "func ${0:foo}() {",
            "\t${1}",
            "}"
        ],
        "description": "Function definition"
    }
]

Explanation:

• prefix - What everything starts with. As soon as you type this word into the editor, it will suggest the completion
• body - The completion itself. Here you can use \n for line breaks and \t for tabs. At the location of ${0:foo} or ${1}, you will be prompted for input; however, in the case of ${0}, the input is predefined but still editable.
• description - A description of the snippet. It will be displayed in the suggestions.

Setting up your own syntax

To do this, you need to define syntax.custom and add your own rules to the array. Example:

"custom": [
    {
        "regex": "@[A-Za-zА-Яа-яЁё_]+",
        "type": ["string"]
    }
]

Breakdown:

• regex - This is a regular expression that also appears in other parameters
• type - Highlighting token. Determines the color of the text that matches the regex. See the full list of tokens here

syntax.states object

There is no documentation yet...