85 lines
3.3 KiB
Markdown
85 lines
3.3 KiB
Markdown
KotlinPoet-metadata
|
|
===================
|
|
|
|
`interop:kotlinx-metadata` is an API for working with Kotlin `@Metadata` annotations. Its API
|
|
sits atop [kotlinx-metadata](https://github.com/JetBrains/kotlin/tree/master/libraries/kotlinx-metadata/jvm),
|
|
offering extensions for its types + JVM metadata information. This can be used to read
|
|
Kotlin language semantics off of `Class` or `TypeElement` `@Metadata` annotations.
|
|
|
|
### Example
|
|
|
|
```kotlin
|
|
data class Taco(val seasoning: String, val soft: Boolean) {
|
|
fun prepare() {
|
|
|
|
}
|
|
}
|
|
|
|
val kmClass = Taco::class.toKmClass()
|
|
|
|
// Now you can access misc information about Taco from a Kotlin lens
|
|
println(kmClass.name)
|
|
kmClass.properties.forEach { println(it.name) }
|
|
kmClass.functions.forEach { println(it.name) }
|
|
```
|
|
|
|
### Flags
|
|
|
|
There are a number of boolean flags available to types as well under `Flags.kt`. These read the
|
|
underlying kotlinx-metadata `Flags` property.
|
|
|
|
Using the Taco example above, we can glean certain information:
|
|
|
|
```kotlin
|
|
println("Is class? ${kmClass.isClass}")
|
|
println("Is data class? ${kmClass.isData}")
|
|
```
|
|
|
|
### Interop with KotlinPoet
|
|
|
|
`interop:kotlinx-metadata` offers an API for converting core kotlinx-metadata `Km` types to
|
|
KotlinPoet source representations of their APIs. This includes full type resolution, signatures,
|
|
enclosed elements, and general stub source representations of the underlying API.
|
|
|
|
### Example
|
|
|
|
```kotlin
|
|
data class Taco(val seasoning: String, val soft: Boolean) {
|
|
fun prepare() {
|
|
}
|
|
}
|
|
|
|
val typeSpec = Taco::class.toTypeSpec()
|
|
|
|
// Or FileSpec
|
|
val fileSpec = Taco::class.toFileSpec()
|
|
```
|
|
|
|
### Source representation
|
|
|
|
The generated representations are a _best effort_ representation of the underlying source code.
|
|
This means that synthetic elements will be excluded from generation. Kotlin-specific language
|
|
features like lambdas or delegation will be coerced to their idiomatic source form.
|
|
|
|
To aid with this, `toTypeSpec()` and `toFileSpec()` accept optional `ClassInspector` instances
|
|
to assist in parsing/understanding the underlying JVM code. This is important for things like
|
|
annotations, companion objects, certain JVM modifiers, overrides, and more. While it is optional,
|
|
represented sources can be incomplete without this information available. Reflective and javax
|
|
`Elements` implementations are available under the
|
|
`com.squareup.kotlinpoet.metadata.classinspectors` package.
|
|
|
|
Generated sources are solely _stub_ implementations, meaning implementation details of elements
|
|
like functions, property getters, and delegated properties are simply stubbed with `TODO()`
|
|
placeholders.
|
|
|
|
### Known limitations
|
|
|
|
- Only `KotlinClassMetadata.Class` and `KotlinClassMetadata.FileFacade` are supported for now. No support for `SyntheticClass`, `MultiFileClassFacade`, or `MultiFileClassPart`
|
|
- `@JvmOverloads` annotations are only supported with `ElementsClassInspector` and not reflection.
|
|
- Non-const literal values are only supported with `ElementsClassInspector` and not reflection.
|
|
- ClassInspector data sourced from `synthetic` constructs are only supported with
|
|
`ReflectiveClassInspector` and not elements. This is because the javax Elements API does not model
|
|
synthetic constructs. This can yield some missing information, like static companion object properties
|
|
or `property:` site target annotations.
|
|
- Annotations annotated with `AnnotationRetention.SOURCE` are not parsable in reflection nor javax elements.
|