0
# Class Metadata
1

2
Core functionality for reading, writing, and transforming Kotlin class metadata from .class files. This system handles different types of Kotlin class metadata including regular classes, file facades, synthetic classes, and multi-file class structures.
3

4
## Capabilities
5

6
### KotlinClassMetadata Base Class
7

8
The main sealed class for all Kotlin class metadata operations.
9

10
```kotlin { .api }
11
/**
12
 * Base sealed class for all Kotlin class metadata types
13
 */
14
sealed class KotlinClassMetadata {
15
    /** Encodes metadata to a new Metadata annotation instance */
16
    abstract fun write(): Metadata
17
    
18
    /** Metadata version used for this metadata */
19
    abstract val version: JvmMetadataVersion
20
    
21
    /** Additional class-level flags */
22
    abstract val flags: Int
23
}
24
```
25

26
### Companion Object Functions
27

28
Static functions for reading and transforming metadata from @Metadata annotations with different compatibility modes.
29

30
```kotlin { .api }
31
companion object {
32
    /**
33
     * Reads metadata for supported versions only, throws exception for unsupported versions
34
     * @param annotationData The @Metadata annotation data from a .class file
35
     * @return KotlinClassMetadata instance or null if parsing fails
36
     */
37
    fun readStrict(annotationData: Metadata): KotlinClassMetadata?
38

39
    /**
40
     * Reads metadata with best-effort compatibility for newer versions
41
     * @param annotationData The @Metadata annotation data from a .class file  
42
     * @return KotlinClassMetadata instance or null if parsing fails
43
     */
44
    fun readLenient(annotationData: Metadata): KotlinClassMetadata?
45

46
    /**
47
     * Utility method for reading, transforming, and writing metadata in one operation
48
     * @param metadata The original @Metadata annotation
49
     * @param transformer Function to modify the metadata
50
     * @return New @Metadata annotation with transformations applied
51
     */
52
    fun transform(metadata: Metadata, transformer: (KotlinClassMetadata) -> Unit): Metadata
53

54
    /** Regular Kotlin class metadata kind */
55
    const val CLASS_KIND: Int = 1
56
    
57
    /** File facade metadata kind */
58
    const val FILE_FACADE_KIND: Int = 2
59
    
60
    /** Synthetic class metadata kind */
61
    const val SYNTHETIC_CLASS_KIND: Int = 3
62
    
63
    /** Multi-file class facade metadata kind */
64
    const val MULTI_FILE_CLASS_FACADE_KIND: Int = 4
65
    
66
    /** Multi-file class part metadata kind */
67
    const val MULTI_FILE_CLASS_PART_KIND: Int = 5
68
}
69
```
70

71
**Usage Examples:**
72

73
```kotlin
74
import kotlin.metadata.jvm.KotlinClassMetadata
75

76
// Strict reading - fails on unsupported versions
77
val metadata = KotlinClassMetadata.readStrict(classAnnotation)
78
if (metadata != null) {
79
    when (metadata) {
80
        is KotlinClassMetadata.Class -> {
81
            println("Regular Kotlin class: ${metadata.kmClass.name}")
82
        }
83
        is KotlinClassMetadata.FileFacade -> {
84
            println("File facade with ${metadata.kmPackage.functions.size} functions")
85
        }
86
    }
87
}
88

89
// Lenient reading - best effort for newer versions
90
val lentientMetadata = KotlinClassMetadata.readLenient(classAnnotation)
91

92
// Transform metadata
93
val newMetadata = KotlinClassMetadata.transform(originalMetadata) { metadata ->
94
    when (metadata) {
95
        is KotlinClassMetadata.Class -> {
96
            // Modify class metadata
97
            metadata.kmClass.functions.forEach { fn ->
98
                // Add custom annotations or modify function metadata
99
            }
100
        }
101
    }
102
}
103
```
104

105
### Class Metadata Types
106

107
Different subclasses representing various types of Kotlin class metadata.
108

109
```kotlin { .api }
110
/**
111
 * Represents metadata for a regular Kotlin class
112
 * @param kmClass The class metadata structure
113
 * @param version Metadata version
114
 * @param flags Additional class-level flags
115
 */
116
class Class(
117
    val kmClass: KmClass, 
118
    override val version: JvmMetadataVersion, 
119
    override val flags: Int
120
) : KotlinClassMetadata() {
121
    override fun write(): Metadata
122
}
123

124
/**
125
 * Represents metadata for top-level declarations (file facades)
126
 * @param kmPackage The package metadata containing top-level declarations
127
 * @param version Metadata version
128
 * @param flags Additional class-level flags
129
 */
130
class FileFacade(
131
    val kmPackage: KmPackage, 
132
    override val version: JvmMetadataVersion, 
133
    override val flags: Int
134
) : KotlinClassMetadata() {
135
    override fun write(): Metadata
136
}
137

138
/**
139
 * Represents metadata for synthetic classes (lambdas, SAM wrappers, etc.)
140
 * @param kmLambda The lambda metadata (null for non-lambda synthetic classes)
141
 * @param version Metadata version
142
 * @param flags Additional class-level flags
143
 */
144
class SyntheticClass(
145
    val kmLambda: KmLambda?, 
146
    override val version: JvmMetadataVersion, 
147
    override val flags: Int
148
) : KotlinClassMetadata() {
149
    override fun write(): Metadata
150
}
151

152
/**
153
 * Represents metadata for multi-file class facades
154
 * @param partClassNames List of class names that are parts of this facade
155
 * @param version Metadata version
156
 * @param flags Additional class-level flags
157
 */
158
class MultiFileClassFacade(
159
    val partClassNames: List<String>, 
160
    override val version: JvmMetadataVersion, 
161
    override val flags: Int
162
) : KotlinClassMetadata() {
163
    override fun write(): Metadata
164
}
165

166
/**
167
 * Represents metadata for multi-file class parts
168
 * @param kmPackage The package metadata for this part
169
 * @param facadeClassName The name of the facade class this part belongs to
170
 * @param version Metadata version
171
 * @param flags Additional class-level flags
172
 */
173
class MultiFileClassPart(
174
    val kmPackage: KmPackage, 
175
    val facadeClassName: String, 
176
    override val version: JvmMetadataVersion, 
177
    override val flags: Int
178
) : KotlinClassMetadata() {
179
    override fun write(): Metadata
180
}
181

182
/**
183
 * Represents metadata for unsupported class files
184
 * @param version Metadata version
185
 * @param flags Additional class-level flags
186
 */
187
class Unknown(
188
    override val version: JvmMetadataVersion, 
189
    override val flags: Int
190
) : KotlinClassMetadata() {
191
    override fun write(): Metadata
192
}
193
```
194

195

196
**Usage Examples:**
197

198
```kotlin
199
// Working with different metadata types
200
when (metadata) {
201
    is KotlinClassMetadata.Class -> {
202
        val klass = metadata.kmClass
203
        println("Class name: ${klass.name}")
204
        println("Functions: ${klass.functions.map { it.name }}")
205
        println("Properties: ${klass.properties.map { it.name }}")
206
        
207
        // Access constructors
208
        klass.constructors.forEach { constructor ->
209
            println("Constructor with ${constructor.valueParameters.size} parameters")
210
        }
211
    }
212
    
213
    is KotlinClassMetadata.FileFacade -> {
214
        val pkg = metadata.kmPackage
215
        println("Top-level functions:")
216
        pkg.functions.forEach { function ->
217
            println("  ${function.name}: ${function.returnType}")
218
        }
219
        
220
        println("Top-level properties:")
221
        pkg.properties.forEach { property ->
222
            println("  ${property.name}: ${property.returnType}")
223
        }
224
    }
225
    
226
    is KotlinClassMetadata.SyntheticClass -> {
227
        val lambda = metadata.kmLambda
228
        if (lambda != null) {
229
            println("Lambda function: ${lambda.function}")
230
        }
231
    }
232
    
233
    is KotlinClassMetadata.MultiFileClassFacade -> {
234
        println("Multi-file facade with parts: ${metadata.partClassNames}")
235
    }
236
    
237
    is KotlinClassMetadata.MultiFileClassPart -> {
238
        println("Multi-file part of facade: ${metadata.facadeClassName}")
239
        println("Contains ${metadata.kmPackage.functions.size} functions")
240
    }
241
    
242
    is KotlinClassMetadata.Unknown -> {
243
        println("Unknown or unsupported metadata format")
244
    }
245
}
246
```
247

248
## Error Handling
249

250
The metadata reading functions return `null` when parsing fails or the metadata format is unsupported. The `readStrict` function is more restrictive and may throw exceptions for incompatible versions, while `readLenient` attempts best-effort parsing.
251

252
Always check for null return values and handle the `Unknown` metadata type for robust metadata processing.