Skip to content

KaFileSymbol

@SubclassOptInRequired(markerClass = [KaImplementationDetail::class])
abstract class KaFileSymbol : KaAnnotatedSymbol

KaFileSymbol represents a KtFile.

The symbol may for example be used to retrieve and analyze the file's annotations.

Constructors

KaFileSymbol

constructor()

Properties

anchorPsi

abstract val anchorPsi: PsiElement?

A PsiElement associated with the symbol. Usually, it is the best PsiElement representation for a particular KaSymbol.

It reuses realPsi, but can also provide a value for other origins.

While anchorPsi aims to be the most related element, it is still an approximation, and there are no strict guarantees that it is a particular element.

Examples:

class MyClass

For this code, KaNamedClassSymbol represents the class, while KaConstructorSymbol represents the implicit constructor. The class is present in the code as a KtClassOrObject, so that element is used. In contrast, the constructor is not present in the code, but can be obtained from the class, so anchorPsi for it is the same KtClassOrObject.

For declarations generated by compiler plugins, it usually points to the declaration from which the symbol was generated, but the behavior is effectively defined by the compiler plugin itself, and the Analysis API use it unchanged.

An alternative can be getting realPsi or the containing declaration instead for more predictable behavior.

See also

annotations

A list of annotations applied to the annotated entity.

containingDeclaration

The KaDeclarationSymbol which contains this symbol, or null if there is no containing declaration:

  • For top-level declarations, a containing KaScriptSymbol, or null for non-script declarations.

  • For class members, the containing class symbol.

  • For property members, the corresponding property.

  • For local declarations, the symbol of the containing declaration.

containingFile

context(session: KaSession)
val KaSymbol.containingFile: KaFileSymbol?

The KaFileSymbol which contains this symbol, or null if this symbol is already a KaFileSymbol, since it has no containing file. Also null for Java and library declarations.

containingModule

context(session: KaSession)
val KaSymbol.containingModule: KaModule

The KaModule which contains this symbol.

containingSymbol

context(session: KaSession)
val KaSymbol.containingSymbol: KaSymbol?

The KaSymbol which contains this symbol, or null if there is no containing declaration:

defaultAnnotationTargets

A set of annotation targets matching for the given symbol, or null if the symbol cannot be annotated. Annotations with one of targets from the returned set can be placed on the KaSymbol without an explicit use-site target.

Such as, annotations with KaAnnotationTarget.PROPERTY or KaAnnotationTarget.VALUE_PARAMETER can be directly placed on a 'val' value parameter, while annotations for KaAnnotationTarget.PROPERTY_GETTER and KaAnnotationTarget.PROPERTY_SETTER can only be applied using the @set:AnnotationName syntax.

Check the Annotation use-site targets documentation for additional information.

deprecation

context(session: KaSession)
val KaSymbol.deprecation: KaDeprecation?

The deprecation status of the given symbol, or null if the symbol is not deprecated.

This considers deprecation annotations applied to the symbol itself and, for property-related symbols, deprecation annotations with appropriate use-site targets.

fileScope

context(session: KaSession)
val KaFileSymbol.fileScope: KaScope

A KaScope containing the top-level declarations (such as classes, functions and properties) in the given KaFileSymbol.

importableFqName

context(session: KaSession)
val KaSymbol.importableFqName: FqName?

A FqName which can be used to import the given symbol, or null if the symbol cannot be imported.

isDeprecated

context(session: KaSession)
val KaSymbol.isDeprecated: Boolean

Whether the symbol is deprecated at any level.

This is a convenience property equivalent to deprecation != null.

isLocal

Indicates whether a symbol is defined locally within a body.

See also

isTopLevel

Indicates whether a KaSymbol is at the top level.

A symbol is considered top-level if it is not a part of other symbols.

See also

location

override val location: KaSymbolLocation

The kind of location where a symbol is declared in code, e.g. KaSymbolLocation.TOP_LEVEL for top-level declarations.

The location is not to be confused with the origin, which is concerned with the kind of data source or generation the symbol originates from.

name

val KaSymbol.name: Name?

The name of the KaSymbol if it has one.

origin

abstract val origin: KaSymbolOrigin

The kind of data source or generation the symbol originates from (e.g. source files, libraries, compiler plugins).

The origin is not to be confused with the location, which is concerned with the symbol's location in code.

psi

abstract val psi: PsiElement?

The API is obsolete and will be deprecated soon. Use <strong>realPsi</strong> or <strong>anchorPsi</strong> instead.

A PsiElement corresponding to this KaSymbol.

The property is only defined for the following origins:

For other (usually synthetic) origins, the psi might be null or non-null. The Analysis API makes no consistent guarantees about the PSI of such origins.

See also

realPsi

abstract val realPsi: PsiElement?

A PsiElement explicitly present in the code (source or library). This PsiElement is sufficient to restore the symbol via the symbol API without any additional information.

It can have a value only for the following origins:

For all other origins, the value is null.

Examples:

class MyClass

For this code, KaNamedClassSymbol represents the class, while KaConstructorSymbol represents the implicit constructor. The class is present in the code as a KtClassOrObject, and this is sufficient to obtain the same symbol. In contrast, the constructor is not present in the code and can only be obtained via the class, so realPsi is null for it.

See also

token

abstract val token: KaLifetimeToken

The KaLifetimeToken which determines the lifetime of the lifetime owner.

Functions

asFacadePsiClass

context(session: KaSession)
fun KaFileSymbol.asFacadePsiClass(): PsiClass?

Converts the given KaFileSymbol to Java facade PsiClass in the context of the useSiteModule.

assertIsValidAndAccessible

createPointer

abstract override fun createPointer(): KaSymbolPointer<KaFileSymbol>

Creates a KaSymbolPointer which can be used to retrieve the symbol in a different analyze block (i.e. a different KaSession).

isValid

Whether the lifetime owner is still valid, i.e. we are still in the scope of the lifetime owner's regular lifetime.

psi

inline fun <reified PSI : PsiElement> KaSymbol.psi(): PSI

The API is obsolete and will be deprecated soon. Use <strong>realPsi</strong> or <strong>anchorPsi</strong> instead.

Returns the symbol's PsiElement if its type is PSI, and otherwise throws a ClassCastException.

See also

psiSafe

inline fun <reified PSI : PsiElement> KaSymbol.psiSafe(): PSI?

The API is obsolete and will be deprecated soon. Use <strong>realPsi</strong> or <strong>anchorPsi</strong> instead.

Returns the symbol's PsiElement if its type is PSI, or null otherwise.

See also

sourcePsi

inline fun <reified PSI : PsiElement> KaSymbol.sourcePsi(): PSI?

The API is obsolete and will be deprecated soon. Use <strong>realPsi</strong> or <strong>anchorPsi</strong> instead.

Returns the symbol's PsiElement. Returns null if its KaSymbol.origin is not KaSymbolOrigin.SOURCE. Throws a ClassCastException if its type is not PSI.

See also

sourcePsiSafe

inline fun <reified PSI : PsiElement> KaSymbol.sourcePsiSafe(): PSI?

The API is obsolete and will be deprecated soon. Use <strong>realPsi</strong> or <strong>anchorPsi</strong> instead.

Returns the symbol's PsiElement if its type is PSI and KaSymbol.origin is KaSymbolOrigin.SOURCE or KaSymbolOrigin.JAVA_SOURCE, and null otherwise.

See also

withValidityAssertion

inline fun <R> KaLifetimeOwner.withValidityAssertion(action: () -> R): R

Executes action only if the KaLifetimeOwner is still valid and accessible. Otherwise, throws a validity exception based on the concrete violation.