Symbols

Symbols vs. PSI

While the PSI represents the concrete syntax in Kotlin code, KaSymbol provides access to the semantic information of declarations. The table below summarizes the key differences:

Semantic information

In the context of the Analysis API symbols, the word "semantic" refers to the meaning and relationships of declarations within the code from the compiler's standpoint, as opposed to their purely syntactic representation.

Here are a couple of examples of semantic symbol information that is unavailable in KtDeclaration (which primarily focuses on syntactic structure).

fun print(text: String) {}

abstract class Base {
    protected abstract fun check(value: String): Boolean
}

class Impl : Base() {
    override fun check(value: String) = value.isNotEmpty()
}

Kinds of symbols

The graph below shows the relation between high-level parts of the KaSymbol type hierarchy.

KaSymbol is a root type for the whole symbol hierarchy. Here are a few subtypes of it:

• KaFileSymbol: Represents a Kotlin file.

• KaPackageSymbol: Represents a package with declarations and subpackages.

• KaDeclarationSymbol: Represents a declaration in a Kotlin file.

• KaClassifierSymbol: Represents a class, type alias, or a type parameter.

• KaCallableSymbol: Represents a function or a variable.

• KaScriptSymbol: Represents a script declaration (implicitly nested in a script file).

See more information on specific subtypes of KaSymbol in dedicated documentation pages.

Getting a KaSymbol

To get a KaSymbol instance, use the symbol extension property:

// Let's say you have a KtNamedFunction
val ktNamedFunction: KtNamedFunction = ...

analyze(ktNamedFunction) {
    val functionSymbol = ktNamedFunction.symbol
    // Although the PSI element is named 'KtNamedFunction',
    // it can be an anonymous one (the name is 'null')
    if (functionSymbol is KaNamedFunctionSymbol) {
        // Here we have a truly named function
        check(functionSymbol.isOperator)
    }
}

This code snippet retrieves the symbol for a KtNamedFunction. You can then check the type of the symbol and access its properties, such as its return type, visibility, and more.

The symbol property is overloaded, and the compiler automatically chooses the most specific variant. For a KtDeclaration, it will return a base KaDeclarationSymbol. However, for a KtTypeAlias the result will be a KaTypeAliasSymbol.

The KtClassOrObject hierarchy includes a KtEnumEntry. In the old compiler, an enum entry was a class with a specific kind. In the Analysis API, though, similarly to the K2 compiler, it is a KaVariableSymbol. Because of this inconsistency, the Analysis API provides specific nullable versions of symbol properties:

public val KtClassOrObject.classSymbol: KaClassSymbol?
public val KtClassOrObject.namedClassSymbol: KaNamedClassSymbol?

KaSymbolPointer

KaSymbolPointer is a mechanism for referencing a KaSymbol across different analysis sessions. Since symbols are valid only within the specific analysis session in which they were created, symbol pointers offer a way to persist references and restore the corresponding symbols later.

val symbol: KaFunctionSymbol = ...
val pointer = symbol.createPointer()

analyze(someKtElement) {
    val restoredSymbol = functionPointer.restoreSymbol()
    if (restoredSymbol != null) {
        // Use the restored symbol
    }
}