KotlinClassMetadata

Represents the parsed metadata of a Kotlin JVM class file. Entry point for parsing metadata on JVM.

To create an instance of KotlinClassMetadata, first obtain an instance of Metadata annotation on a class file, and then call KotlinClassMetadata.readStrict or KotlinClassMetadata.readLenient, depending on your application (see 'Working with different versions' section in the readme).

Metadata annotation can be obtained either via reflection or created from data from a binary class file, using its constructor or helper function kotlinx.metadata.jvm.Metadata.

KotlinClassMetadata alone exposes only KotlinClassMetadata.version and KotlinClassMetadata.flags; to work with it, it is required to do a when over subclasses. Different subclasses of KotlinClassMetadata represent different kinds of class files produced by Kotlin compiler. It is recommended to study documentation for each subclass and decide what subclasses one has to handle in the when expression, trying to cover as much as possible. Normally, one would need at least a Class and a FileFacade, as these are two most common kinds.

Most of the subclasses declare a property to view metadata as a Km data structure — for example, KotlinClassMetadata.Class.kmClass. Some of them also can contain additional properties, e.g. KotlinClassMetadata.MultiFileClassPart.facadeClassName. Km data structures represent Kotlin declarations and offer a variety of properties to introspect and alter them. After desired changes are made to a Km data structure or to KotlinClassMetadata itself, it is possible to get a new raw metadata instance with a write function.

If metadata has been read with readLenient, write will throw an exception.

Here is an example of reading a content name of some metadata:

fun displayName(metadata: Metadata): String = when (val kcm = KotlinClassMetadata.readStrict(metadata)) {
    is KotlinClassMetadata.Class -> "Class ${kcm.kmClass.name}"
    is KotlinClassMetadata.FileFacade -> "File facade with functions: ${kcm.kmPackage.functions.joinToString { it.name }}"
    is KotlinClassMetadata.SyntheticClass -> kcm.kmLambda?.function?.name?.let { "Lambda $it" } ?: "Synthetic class"
    is KotlinClassMetadata.MultiFileClassFacade -> "Multifile class facade with parts: ${kcm.partClassNames.joinToString()}"
    is KotlinClassMetadata.MultiFileClassPart -> "Multifile class part ${kcm.facadeClassName}"
    is KotlinClassMetadata.Unknown -> "Unknown metadata"
}

In this example, only introspection (reading) is performed. In such cases, to support more broad range of metadata versions, you may also use readLenient method.

Inheritors