Добавляем поддержку пользовательского языка в IntelliJ с помощью ANTLR / forpes.ru

Главная
Добавляем поддержку пользовательского языка в IntelliJ с помощью ANTLR

Добавляем поддержку пользовательского языка в IntelliJ с помощью ANTLR +6

18.07.2023 11:37

ris58h 0 737 Источник

В этой статье я не буду описывать как создать плагин для IntelliJ с поддержкой %lang_name% с нуля. Кроме официальной документации и туториала от JetBrains в сети есть множество статей и примеров. На Хабре тоже есть пара весьма подробных статей от @pyltsinm. Фокус будет на разработке плагина с использованием ANTLR и моём опыте в этом нелёгком деле.

Примером в этой статье будет WebCalm - плагин для IntelliJ с поддержкой JavaScript и CSS, который я сделал с помощью ANTLR.

Почему ANTLR

Для поддержки пользовательского языка в IntelliJ существует Grammar-Kit - набор инструментов для задания грамматики и генерации по ней необходимых для IntelliJ классов для представления языка. Для лексера используется JFlex, а парсер описывается с помощью специального *.bnf файла, который представляет собой грамматику в РБНФ нотации с дополнительными директивами.

Для тех кто не знает, ANTLR - это, грубо говоря, генератор парсеров. На входе - грамматика в форме РБНФ, на выходе - лексер и парсер описанного языка. Для ANTLR имеется множество готовых грамматик для различных формальных языков. Код его открыт, а сам он бесплатен и распространяется под лицензией BSD-3.

Если для языка, поддержку которого вы хотите добавить, уже имеется готовая ANTLR-грамматика, а вы не горите желанием переписывать её под Grammar-Kit, то логично попытаться её каким-то образом переиспользовать. В этом нам поможет antlr4-intellij-adaptor - адаптер ANTLR для IntelliJ, как можно понять из названия. Это официальный проект от создателей ANTLR содержащий набор классов адаптеров для использования лексеров и парсеров сгенерированных ANTLR в IntelliJ.

База

Думаю, не будет лишним кратко пробежаться по основам представления языка в InetlliJ.

Начинается всё, конечно, с лексического анализа (токенизации). За это отвечает класс Lexer. Он выдаёт последовательность токенов. Каждый токен имеет свой тип - IElementType. Причём лексера уже достаточно чтобы добавить базовую подсветку для вашего языка - за это отвечает SyntaxHighlighter.

За парсинг отвечает PsiParser. На выходе он даёт AST - дерево состоящее из ASTNode. Каждый узел также имеет свой тип (IElementType). Но плагины и сама IntelliJ зачастую (но далеко не всегда) не используют AST напрямую - всё это добро скрывается за Program Structure Interface или сокращённо PSI. PSI-классы скрывают в себе логику для работы с конкретным элементом языка - идентификатором, выражением, функцией и т.д.

Типичное добавление пользовательского языка в IntelliJ выглядит так:

Описываем лексер и парсер во *.flex и *.bnf файлах соответственно.
Генерируем лексер, парсер и, что самое главное, PSI-классы соответствующие правилам заданной грамматики. Вручную из IDE с помощью Grammar-Kit плагина для IntelliJ или из Gradle с помощью gradle-grammar-kit-plugin.
Добавляем необходимую обвязку чтоб всё это завелось.

Использование ANTLR

Теперь разберём как использовать ANTLR-грамматику в IntelliJ для языковой поддержки.

Грамматика

Начинаем, конечно, с грамматики. Ищем нужную нам среди официальных. В моём случае это javascript и css3 для JavaScript и CSS соответственно. Также для некоторых грамматик могут понадобиться базовые классы. Для JavaScript это JavaScriptLexerBase и JavaScriptParserBase.

Возможно, грамматики для вашего языка не оказалось и вы решили написать её с нуля. В таком случае я бы рекомендовал подумать нужна ли она где-то ещё кроме IntelliJ. Если нет, то лучше написать грамматику для Grammar-Kit, т.к. этот инструмент заточен для IntelliJ и даёт некоторые преимущества (о них позже).

Подключение ANTLR в Gradle

Кусочек build.gradle.kts из WebCalm:

// ...

plugins {
    // ...
    id("antlr")
}

// ...

val antlrVersion = "4.12.0"

dependencies {
    implementation("org.antlr:antlr4-intellij-adaptor:0.1") {
        constraints {
            implementation("org.antlr", "antlr4-runtime", antlrVersion) {
                because("Old runtime leads to 'Could not deserialize ATN' error.")
            }
        }
    }
    antlr("org.antlr", "antlr4", antlrVersion) {
        // Not required for 'generateGrammarSource' task.
        exclude("com.ibm.icu", "icu4j")
        exclude("org.abego.treelayout", "org.abego.treelayout.core")
    }
}
//TODO: a hack to exclude antlr4 dependencies from the resulting distribution zip. See https://github.com/gradle/gradle/issues/820
configurations[JavaPlugin.API_CONFIGURATION_NAME].let { apiConfiguration ->
    apiConfiguration.setExtendsFrom(apiConfiguration.extendsFrom.filter { it.name != "antlr" })
}

// ...

Сперва в plugins подключаем antlr плагин. В dependencies настраиваем версии зависимостей (ANLTR и адаптера) и исключаем ненужные зависимости. Напоследок втыкаем хак, чтобы обойти проблему с добавлением всего antlr в финальный артефакт.

Теперь у нас есть generateGrammarSource Gradle-задача для генерации лексера и парсера (для ANTLR, но не для IntelliJ). По-умолчанию, ANTLR-плагин ожидает грамматики в src/main/antlr, но это можно настроить.

Лексер

После генерации лексера из ANTLR-грамматики мы получаем класс лексера унаследованный от org.antlr.v4.runtime.Lexer. Чтобы превратить его в com.intellij.lexer.Lexer, который использует IntelliJ, существует org.antlr.intellij.adaptor.lexer.ANTLRLexerAdaptor. Вроде всё просто, но если код на вашем языке встроен в код на другом (например, JavaScript и CSS встроенные в HTML), то, скорее всего, вы столкнётесь с проблемой java.lang.IndexOutOfBoundsException. Что ж, пишем костыль:

open class FixedANTLRLexerAdaptor(language: Language, lexer: Lexer) : ANTLRLexerAdaptor(language, lexer) {
    // TODO: it's a hack to prevent IndexOutOfBounds exception. See https://github.com/antlr/antlr4-intellij-adaptor/issues/31
    override fun toLexerState(state: Int): ANTLRLexerState {
        if (state == 0) {
            return initialState
        }
        return super.toLexerState(state)
    }
}

Чтобы токены можно было различать при работе с ними, каждый из них имеет соответствующий IElementType. Для их создания необходимо вызвать org.antlr.intellij.adaptor.lexer.PSIElementTypeFactory#defineLanguageIElementTypes с соответствующими аргументами. Для получения - org.antlr.intellij.adaptor.lexer.PSIElementTypeFactory#getTokenIElementTypes. Пример из WebCalm:

object JavaScriptTypes {
    init {
        PSIElementTypeFactory.defineLanguageIElementTypes(
            JavaScriptLanguage, JavaScriptLexer.tokenNames, JavaScriptParser.ruleNames
        )
    }

    val FILE = IFileElementType(JavaScriptLanguage)

    private val TOKENS = PSIElementTypeFactory.getTokenIElementTypes(JavaScriptLanguage)
    val UNEXPECTED_CHARACTER = TOKENS[JavaScriptLexer.UnexpectedCharacter]!!
    val WS = TOKENS[JavaScriptLexer.WhiteSpaces]!!
    val EOL = TOKENS[JavaScriptLexer.LineTerminator]!!
    val LINE_COMMENT = TOKENS[JavaScriptLexer.SingleLineComment]!!
    val MULTILINE_COMMENT = TOKENS[JavaScriptLexer.MultiLineComment]!!
    val STRING = TOKENS[JavaScriptLexer.StringLiteral]!!
    // ...
}

Grammar-Kit же генерирует всё это автоматически - это его преимущество перед ANTLR-адаптером.

Парсер

Для парсера тоже есть адаптер - org.antlr.intellij.adaptor.parser.ANTLRParserAdaptor. Он отвечает за построение AST, с которым работает IntelliJ, с помощью парсера сгенерированного ANTLR. Внутри адаптер превращает org.antlr.v4.runtime.tree.ParseTree, которое выдаёт парсер сгенерированный ANTLR, в com.intellij.lang.ASTNode. Делается это с помощью org.antlr.intellij.adaptor.parser.ANTLRParseTreeToPSIConverter. Это та точка расширения, где мы можем скорректировать абстрактное синтаксическое дерево.

Модификация AST

В ANTLR-грамматике могут быть правила, состоящие из одного нетерминального символа или выбора из нетерминальных символов. Такие правила удлиняют ветки дерева, но не несут практической пользы:

declaration
    : variableStatement
    | classDeclaration
    | functionDeclaration
    ;

Конечно, вы можете удалить такие правила, но это может сказаться на читаемости грамматики. Поэтому мы можем выкинуть такие правила на этапе конвертации в AST с помощью самописного конвертера:

class CustomParseTreeToPsiConverter(language: Language, parser: Parser, builder: PsiBuilder) : ANTLRParseTreeToPSIConverter(language, parser, builder) {
    private var rulesToDrop: Set<Int> = emptySet()
    // ...

    override fun exitEveryRule(ctx: ParserRuleContext) {
        ProgressIndicatorProvider.checkCanceled()
        val ruleIndex = ctx.ruleIndex
        if (rulesToDrop.contains(ruleIndex)) {
            val marker = markers.pop()
            marker.drop()
        } else {
            // ...
        }
    }

    // ...
}

Ещё в ANTLR-грамматике есть возможность помечать альтернативы выбора с помощью меток:

anonymousFunction
    : Async? Function_ '*'? '(' formalParameterList? ')' functionBody    # AnonymousFunctionDecl
    | Async? arrowFunctionParameters '=>' arrowFunctionBody              # ArrowFunction
    ;

AnonymousFunctionDecl и ArrowFunction как раз являются такими метками. Они не создают новое правило, но определить правило с таким же именем вы уже не сможете. Проблема в том, что при обходе дерева полученного из ANTLR, нет доступа к этим меткам. Что ж, нам не помешает лишний костыль:

private fun label(ctx: ParserRuleContext): String? {
    val javaClass = ctx.javaClass
    val isLabeled = javaClass.superclass.canonicalName != "org.antlr.v4.runtime.ParserRuleContext"
    return if (isLabeled) {
        javaClass.simpleName.removeSuffix("Context")
    } else null
}

В коде выше извлекается название метки из имени класса контекста текущего правила.

Добавляем метки к нашему конвертеру:

class CustomParseTreeToPsiConverter(language: Language, parser: Parser, builder: PsiBuilder) : ANTLRParseTreeToPSIConverter(language, parser, builder) {
    private var rulesToDrop: Set<Int> = emptySet()
    private var labeledRules: Map<String, IElementType> = emptyMap()

    override fun exitEveryRule(ctx: ParserRuleContext) {
        ProgressIndicatorProvider.checkCanceled()
        val ruleIndex = ctx.ruleIndex
        if (rulesToDrop.contains(ruleIndex)) {
            val marker = markers.pop()
            marker.drop()
        } else {
            val marker = markers.pop()
            val label = label(ctx)
            val ruleIElementType = labeledRules[label] ?: getRuleElementTypes()[ctx.ruleIndex]
            marker.done(ruleIElementType)
        }
    }

    fun withRulesToDrop(rulesToDrop: Set<Int>): CustomParseTreeToPsiConverter {
        this.rulesToDrop = rulesToDrop
        return this
    }

    fun withLabeledRules(labeledRuleElements: Map<String, IElementType>): CustomParseTreeToPsiConverter {
        this.labeledRules = labeledRuleElements
        return this
    }

    private fun label(ctx: ParserRuleContext): String? {
        val javaClass = ctx.javaClass
        val isLabeled = javaClass.superclass.canonicalName != "org.antlr.v4.runtime.ParserRuleContext"
        return if (isLabeled) {
            javaClass.simpleName.removeSuffix("Context")
        } else null
    }
}

Пример его реального использования вы можете посмотреть в JavaScriptParser.

PSI-элементы

И так, у нас есть парсер, который даёт на выходе com.intellij.lang.ASTNode. Следующий шаг - превратить это в структуру из PSI-элементов. За это в IntelliJ отвечает com.intellij.lang.ParserDefinition#createElement. Этот метод, обычно делегируется какой-нибудь фабрике элементов. В случае Grammar-Kit, она будет сгенерирована автоматически, но в нашем случае её придётся написать ручками. Пример можно посмотреть в JavaScriptTypes$Factory:

object JavaScriptTypes {
    init {
        PSIElementTypeFactory.defineLanguageIElementTypes(
            JavaScriptLanguage, JavaScriptLexer.tokenNames, JavaScriptParser.ruleNames
        )
    }

    // ...

    object Factory {
        // ...

        private val RULES = PSIElementTypeFactory.getRuleIElementTypes(JavaScriptLanguage)
        private val IDENTIFIER = RULES[JavaScriptParser.RULE_identifier]
        private val IDENTIFIER_NAME = RULES[JavaScriptParser.RULE_identifierName]
        private val LITERAL = RULES[JavaScriptParser.RULE_literal]
        private val FUNCTION_DECLARATION = RULES[JavaScriptParser.RULE_functionDeclaration]
        // ...

        fun createElement(node: ASTNode): PsiElement {
            return when (node.elementType) {
                IDENTIFIER -> JavaScriptIdentifier(node)
                IDENTIFIER_NAME -> JavaScriptIdentifierName(node)
                LITERAL -> JavaScriptLiteral(node)
                FUNCTION_DECLARATION -> JavaScriptFunctionDeclaration(node)
                // ...
                else -> ASTWrapperPsiElement(node)
            }
        }

        // ...
    }
}

В коде выше по IElementType узла дерева создаётся соответствующий PSI-элемент. Классы PSI-элементов тоже придётся написать ручками, в отличие от Grammar-Kit, который их сгенерирует сам.

Остальные фишки

Лексер и парсер готовы (спасибо ANTLR за это) и теперь вы можете приступать к добавлению остальных фишек: подсветка кода, свёртка кода, поиск использований, переименование и т.п. Большинство из этого описано в официальной документации и туториале. Не стесняйтесь подсмотреть что-то в WebCalm или других плагинах на GitHub.

Плюсы и минусы

Плюсы:

Переиспользование существующей грамматики.
Высокая скорость создания прототипа.

Минусы:

Грамматики не идеальны. Я создал более 15 issue на GitHub для JavaScript и CSS грамматик. Благо, ребята из ANTLR достаточно шустро принимают правки.
ANTLR-адаптер всё ещё имеет версию 0.1, и в нём встречаются проблемы, которые приходится обходить хаками. Всё же, инструмент весьма нишевый.
Приходится много чего писать ручками, в то время как Grammar-Kit генерирует почти всё необходимое из файла описания грамматики. Есть даже запрос на использования ANTLR грамматик в Grammar-Kit, но не думаю что он будет удовлетворён.
В ANTLR отсутствуют некоторые фишки Grammar-Kit. Например, я так и не нашёл способ сделать восстановление после ошибок. В Grammar-Kit это делается чуть ли не автоматически.

Выводы

Если у вас есть готовая ANTLR-грамматика для языка, поддержку которого вы хотите добавить в IntelliJ, то вы можете весьма быстро получить работающий прототип с помощью ANTLR-адаптера.

Если такой грамматики нет, и она не пригодится где-то ещё, то лучше использовать Grammar-Kit и написать грамматику для него.

Полезные ссылки

Оффициальная документация и туториал от JetBrains по написанию языковых плагинов.
https://github.com/antlr/grammars-v4/ - набор грамматик для ANTLR.
https://github.com/antlr/antlr4-intellij-adaptor/ - ANTLR-адаптер для IntelliJ.
https://github.com/ris58h/WebCalm/ - мой плагин для поддержки JavaScript и CSS основанный на инструментах ANTLR.