1 /*
2 * Copyright (C) 2019 Square, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.squareup.kotlinpoet.metadata.specs
17
18 import com.squareup.kotlinpoet.ClassName
19 import com.squareup.kotlinpoet.metadata.KotlinPoetMetadataPreview
20 import kotlinx.metadata.KmClass
21 import kotlinx.metadata.KmDeclarationContainer
22 import kotlinx.metadata.jvm.JvmMethodSignature
23
24 /** A basic interface for looking up JVM information about a given Class. */
25 @KotlinPoetMetadataPreview
26 public interface ClassInspector {
27
28 /**
29 * Indicates if this [ClassInspector] supports [AnnotationRetention.RUNTIME]-retained annotations.
30 * This is used to indicate if manual inference of certain non-RUNTIME-retained annotations should
31 * be done, such as [JvmName].
32 */
33 public val supportsNonRuntimeRetainedAnnotations: Boolean
34
35 /**
36 * Creates a new [ContainerData] instance for a given [declarationContainer].
37 *
38 * @param declarationContainer the source [KmDeclarationContainer] to read from.
39 * @param className the [ClassName] of the target class to to read from.
40 * @param parentClassName the parent [ClassName] name if [declarationContainer] is nested, inner,
41 * or is a companion object.
42 */
containerDatanull43 public fun containerData(
44 declarationContainer: KmDeclarationContainer,
45 className: ClassName,
46 parentClassName: ClassName?,
47 ): ContainerData
48
49 /**
50 * Looks up other declaration containers, such as for nested members. Note that this class would
51 * always be Kotlin, so Metadata can be relied on for this.
52 *
53 * @param className The [ClassName] representation of the class.
54 * @return the read [KmDeclarationContainer] from its metadata. If no class or facade
55 * file was found, this should throw an exception.
56 */
57 public fun declarationContainerFor(className: ClassName): KmDeclarationContainer
58
59 /**
60 * Looks up a class and returns whether or not it is an interface. Note that this class can be
61 * Java or Kotlin, so Metadata should not be relied on for this.
62 *
63 * @param className The [ClassName] representation of the class.
64 * @return whether or not it is an interface.
65 */
66 public fun isInterface(className: ClassName): Boolean
67
68 /**
69 * Looks up the enum entry on a given enum given its member name.
70 *
71 * @param enumClassName The [ClassName] representation of the enum class.
72 * @param memberName The simple member name.
73 * @return the [EnumEntryData]
74 */
75 public fun enumEntry(enumClassName: ClassName, memberName: String): EnumEntryData
76
77 /**
78 * Looks up if a given [methodSignature] within [className] exists.
79 *
80 * @param className The [ClassName] representation of the class.
81 * @param methodSignature The method signature to check.
82 * @return whether or not the method exists.
83 */
84 public fun methodExists(className: ClassName, methodSignature: JvmMethodSignature): Boolean
85 }
86
87 /**
88 * Creates a new [ContainerData] instance for a given [className].
89 *
90 * @param className the [ClassName] of the target class to to read from.
91 * @param parentClassName the parent [ClassName] name if [className] is nested, inner, or is a
92 * companion object.
93 */
94 @KotlinPoetMetadataPreview
95 public fun ClassInspector.containerData(
96 className: ClassName,
97 parentClassName: ClassName?,
98 ): ContainerData {
99 return containerData(declarationContainerFor(className), className, parentClassName)
100 }
101
102 /**
103 * Looks up other classes, such as for nested members. Note that this class would always be
104 * Kotlin, so Metadata can be relied on for this.
105 *
106 * @param className The [ClassName] representation of the class.
107 * @return the read [KmClass] from its metadata. If no class was found, this should throw
108 * an exception.
109 */
110 @KotlinPoetMetadataPreview
classFornull111 public fun ClassInspector.classFor(className: ClassName): KmClass {
112 val container = declarationContainerFor(className)
113 check(container is KmClass) {
114 "Container is not a class! Was ${container.javaClass.simpleName}"
115 }
116 return container
117 }
118