API обработки символов Kotlin

Обзор

API KSP обрабатывает Kotlin-программы идиоматично. KSP понимает специфичные для Kotlin функции, такие как расширяющие функции, вариативность объявления на месте и локальные функции. Он также явно моделирует типы и предоставляет базовые проверки типов, такие как эквивалентность и совместимость присваивания.

API моделирует структуры Kotlin-программ на уровне символов в соответствии с грамматикой Kotlin. Когда плагины на основе KSP обрабатывают исходные программы, конструкции, такие как классы, члены классов, функции и связанные параметры, доступны для обработчиков, в то время как такие вещи, как if блоки и for циклы — нет.

По концепции KSP похож на KType в Kotlin reflection. API позволяет обработчикам переходить от объявлений классов к соответствующим типам со специфическими аргументами типа и наоборот. Вы также можете подставлять аргументы типа, указывать вариативность, применять проекции звёздочек и отмечать необязательность типов.

Ещё один способ понять KSP — это как фреймворк препроцессора для Kotlin-программ. Рассматривая плагины на основе KSP как обработчики символов или просто обработчики, поток данных в компиляции можно описать следующими шагами:

1. Обработчики читают и анализируют исходные программы и ресурсы.

2. Обработчики генерируют код или другие формы вывода.

3. Kotlin-компилятор компилирует исходные программы вместе с сгенерированным кодом.

В отличие от полнофункционального плагина компилятора, обработчики не могут изменять код. Плагин компилятора, изменяющий семантику языка, может быть очень запутанным. KSP избегает этого, обрабатывая исходные программы как только для чтения.

Вы также можете получить обзор KSP в этом видео:

Как KSP рассматривает исходные файлы

Большинство обработчиков перемещаются по различным структурам программы входного исходного кода. Прежде чем углубиться в использование API, давайте посмотрим, как файл может выглядеть с точки зрения KSP:

KSFile
  packageName: KSName
  fileName: String
  annotations: List<KSAnnotation>  (File annotations)
  declarations: List<KSDeclaration>
    KSClassDeclaration // class, interface, object
      simpleName: KSName
      qualifiedName: KSName
      containingFile: String
      typeParameters: KSTypeParameter
      parentDeclaration: KSDeclaration
      classKind: ClassKind
      primaryConstructor: KSFunctionDeclaration
      superTypes: List<KSTypeReference>
      // contains inner classes, member functions, properties, etc.
      declarations: List<KSDeclaration>
    KSFunctionDeclaration // top level function
      simpleName: KSName
      qualifiedName: KSName
      containingFile: String
      typeParameters: KSTypeParameter
      parentDeclaration: KSDeclaration
      functionKind: FunctionKind
      extensionReceiver: KSTypeReference?
      returnType: KSTypeReference
      parameters: List<KSValueParameter>
      // contains local classes, local functions, local variables, etc.
      declarations: List<KSDeclaration>
    KSPropertyDeclaration // global variable
      simpleName: KSName
      qualifiedName: KSName
      containingFile: String
      typeParameters: KSTypeParameter
      parentDeclaration: KSDeclaration
      extensionReceiver: KSTypeReference?
      type: KSTypeReference
      getter: KSPropertyGetter
        returnType: KSTypeReference
      setter: KSPropertySetter
        parameter: KSValueParameter

Этот вид отображает распространённые объявления в файле: классы, функции, свойства и так далее.

SymbolProcessorProvider: точка входа

KSP ожидает реализацию SymbolProcessorProvider интерфейса для создания SymbolProcessor.

interface SymbolProcessorProvider {
    fun create(environment: SymbolProcessorEnvironment): SymbolProcessor
}

В то время как SymbolProcessor определяется как:

interface SymbolProcessor {
    fun process(resolver: Resolver): List<KSAnnotated> // Let's focus on this
    fun finish() {}
    fun onError() {}
}

A Resolver предоставляет SymbolProcessor доступ к деталям компилятора, таким как символы. Обработчик, который находит все функции верхнего уровня и функции, не являющиеся локальными, в классах верхнего уровня, может выглядеть примерно так:

class HelloFunctionFinderProcessor : SymbolProcessor() {
    // ...
    val functions = mutableListOf<String>()
    val visitor = FindFunctionsVisitor()

    override fun process(resolver: Resolver) {
        resolver.getAllFiles().map { it.accept(visitor, Unit) }
    }

    inner class FindFunctionsVisitor : KSVisitorVoid() {
        override fun visitClassDeclaration(classDeclaration: KSClassDeclaration, data: Unit) {
            classDeclaration.getDeclaredFunctions().map { it.accept(this, Unit) }
        }

        override fun visitFunctionDeclaration(function: KSFunctionDeclaration, data: Unit) {
            functions.add(function)
        }

        override fun visitFile(file: KSFile, data: Unit) {
            file.declarations.map { it.accept(this, Unit) }
        }
    }
    // ...
    
    class Provider : SymbolProcessorProvider {
        override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor = TODO()
    }
}

Ресурсы

• Быстрое начало

• Почему использовать KSP?

• Примеры

• Как KSP моделирует Kotlin-код

• Справочник для авторов обработчиков аннотаций Java

• Примечания по обработке инкрементально

• Примечания по обработке в несколько раундов

• KSP в многоплатформенных проектах

• Запуск KSP из командной строки

• Вопросы и ответы

Поддерживаемые библиотеки

В таблице ниже представлен список популярных библиотек на Android и различные стадии их поддержки KSP.