1 /* 2 * Copyright 2020 Google LLC 3 * Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package com.google.devtools.ksp.processing 18 19 import com.google.devtools.ksp.KspExperimental 20 import com.google.devtools.ksp.symbol.* 21 22 /** 23 * [Resolver] provides [SymbolProcessor] with access to compiler details such as Symbols. 24 */ 25 interface Resolver { 26 /** 27 * Get all new files in the module / compilation unit. 28 * 29 * @return new files generated from last last round of processing in the module. 30 */ getNewFilesnull31 fun getNewFiles(): Sequence<KSFile> 32 33 /** 34 * Get all files in the module / compilation unit. 35 * 36 * @return all input files including generated files from previous rounds, note when incremental is enabled, only dirty files up for processing will be returned. 37 */ 38 fun getAllFiles(): Sequence<KSFile> 39 40 /** 41 * Get all symbols with specified annotation. 42 * Note that in multiple round processing, only symbols from deferred symbols of last round and symbols from newly generated files will be returned in this function. 43 * 44 * @param annotationName is the fully qualified name of the annotation; using '.' as separator. 45 * @param inDepth whether to check symbols in depth, i.e. check symbols from local declarations. Operation can be expensive if true. 46 * @return Elements annotated with the specified annotation. 47 */ 48 fun getSymbolsWithAnnotation(annotationName: String, inDepth: Boolean = false): Sequence<KSAnnotated> 49 50 /** 51 * Find a class in the compilation classpath for the given name. 52 * 53 * This returns the exact platform class when given a platform name. Note that java.lang.String isn't compatible 54 * with kotlin.String in the type system. Therefore, processors need to use mapJavaNameToKotlin() and mapKotlinNameToJava() 55 * explicitly to find the corresponding class names before calling getClassDeclarationByName if type checking 56 * is needed for the classes loaded by this. 57 * 58 * This behavior is limited to getClassDeclarationByName; When processors get a class or type from a Java source 59 * file, the conversion is done automatically. E.g., a java.lang.String in a Java source file is loaded as 60 * kotlin.String in KSP. 61 * 62 * @param name fully qualified name of the class to be loaded; using '.' as separator. 63 * @return a KSClassDeclaration, or null if not found. 64 */ 65 fun getClassDeclarationByName(name: KSName): KSClassDeclaration? 66 67 /** 68 * Find functions in the compilation classpath for the given name. 69 * 70 * @param name fully qualified name of the function to be loaded; using '.' as separator. 71 * @param includeTopLevel a boolean value indicate if top level functions should be searched. Default false. Note if top level functions are included, this operation can be expensive. 72 * @return a Sequence of KSFunctionDeclaration 73 */ 74 fun getFunctionDeclarationsByName(name: KSName, includeTopLevel: Boolean = false): Sequence<KSFunctionDeclaration> 75 76 /** 77 * Find a property in the compilation classpath for the given name. 78 * 79 * @param name fully qualified name of the property to be loaded; using '.' as separator. 80 * @param includeTopLevel a boolean value indicate if top level properties should be searched. Default false. Note if top level properties are included, this operation can be expensive. 81 * @return a KSPropertyDeclaration, or null if not found. 82 */ 83 fun getPropertyDeclarationByName(name: KSName, includeTopLevel: Boolean = false): KSPropertyDeclaration? 84 85 /** 86 * Compose a type argument out of a type reference and a variance 87 * 88 * @param typeRef a type reference to be used in type argument 89 * @param variance specifies a use-site variance 90 * @return a type argument with use-site variance 91 */ 92 fun getTypeArgument(typeRef: KSTypeReference, variance: Variance): KSTypeArgument 93 94 /** 95 * Get a [KSName] from a String. 96 */ 97 fun getKSNameFromString(name: String): KSName 98 99 /** 100 * Create a [KSTypeReference] from a [KSType] 101 */ 102 fun createKSTypeReferenceFromKSType(type: KSType): KSTypeReference 103 104 /** 105 * Provides built in types for convenience. For example, [KSBuiltins.anyType] is the KSType instance for class 'kotlin.Any'. 106 */ 107 val builtIns: KSBuiltIns 108 109 /** 110 * map a declaration to jvm signature. 111 * This function might fail due to resolution error, in case of error, null is returned. 112 * Resolution error could be caused by bad code that could not be resolved by compiler, or KSP bugs. 113 * If you believe your code is correct, please file a bug at https://github.com/google/ksp/issues/new 114 */ 115 @KspExperimental 116 fun mapToJvmSignature(declaration: KSDeclaration): String? 117 118 /** 119 * @param overrider the candidate overriding declaration being checked. 120 * @param overridee the candidate overridden declaration being checked. 121 * @return boolean value indicating whether [overrider] overrides [overridee] 122 * Calling [overrides] is expensive and should be avoided if possible. 123 */ 124 fun overrides(overrider: KSDeclaration, overridee: KSDeclaration): Boolean 125 126 /** 127 * @param overrider the candidate overriding declaration being checked. 128 * @param overridee the candidate overridden declaration being checked. 129 * @param containingClass the containing class of candidate overriding and overridden declaration being checked. 130 * @return boolean value indicating whether [overrider] overrides [overridee] 131 * Calling [overrides] is expensive and should be avoided if possible. 132 */ 133 fun overrides(overrider: KSDeclaration, overridee: KSDeclaration, containingClass: KSClassDeclaration): Boolean 134 135 /** 136 * Returns the jvm name of the given function. 137 * This function might fail due to resolution error, in case of error, null is returned. 138 * Resolution error could be caused by bad code that could not be resolved by compiler, or KSP bugs. 139 * If you believe your code is correct, please file a bug at https://github.com/google/ksp/issues/new 140 * 141 * The jvm name of a function might depend on the Kotlin Compiler version hence it is not guaranteed to be 142 * compatible between different compiler versions except for the rules outlined in the Java interoperability 143 * documentation: https://kotlinlang.org/docs/reference/java-to-kotlin-interop.html. 144 * 145 * If the [declaration] is annotated with [JvmName], that name will be returned from this function. 146 * 147 * Note that this might be different from the name declared in the Kotlin source code in two cases: 148 * a) If the function receives or returns an inline class, its name will be mangled according to 149 * https://kotlinlang.org/docs/reference/inline-classes.html#mangling. 150 * b) If the function is declared as internal, it will include a suffix with the module name. 151 * 152 * NOTE: As inline classes are an experimental feature, the result of this function might change based on the 153 * kotlin version used in the project. 154 */ 155 @KspExperimental 156 fun getJvmName(declaration: KSFunctionDeclaration): String? 157 158 /** 159 * Returns the jvm name of the given property accessor. 160 * This function might fail due to resolution error, in case of error, null is returned. 161 * Resolution error could be caused by bad code that could not be resolved by compiler, or KSP bugs. 162 * If you believe your code is correct, please file a bug at https://github.com/google/ksp/issues/new 163 * 164 * The jvm name of an accessor might depend on the Kotlin Compiler version hence it is not guaranteed to be 165 * compatible between different compiler versions except for the rules outlined in the Java interoperability 166 * documentation: https://kotlinlang.org/docs/reference/java-to-kotlin-interop.html. 167 * 168 * If the [accessor] is annotated with [JvmName], that name will be returned from this function. 169 * 170 * By default, this name will match the name calculated according to 171 * https://kotlinlang.org/docs/reference/java-to-kotlin-interop.html#properties. 172 * Note that the result of this function might be different from that name in two cases: 173 * a) If the property's type is an internal class, accessor's name will be mangled according to 174 * https://kotlinlang.org/docs/reference/inline-classes.html#mangling. 175 * b) If the function is declared as internal, it will include a suffix with the module name. 176 * 177 * NOTE: As inline classes are an experimental feature, the result of this function might change based on the 178 * kotlin version used in the project. 179 * see: https://kotlinlang.org/docs/reference/java-to-kotlin-interop.html#properties 180 */ 181 @KspExperimental 182 fun getJvmName(accessor: KSPropertyAccessor): String? 183 184 /** 185 * Returns the [binary class name](https://asm.ow2.io/javadoc/org/objectweb/asm/Type.html#getClassName()) of the 186 * owner class in JVM for the given [KSPropertyDeclaration]. 187 * 188 * For properties declared in classes / interfaces; this value is the binary class name of the declaring class. 189 * 190 * For top level properties, this is the binary class name of the synthetic class that is generated for the Kotlin 191 * file. 192 * see: https://kotlinlang.org/docs/java-to-kotlin-interop.html#package-level-functions 193 * 194 * Note that, for properties declared in companion objects, the returned owner class will be the Companion class. 195 * see: https://kotlinlang.org/docs/java-to-kotlin-interop.html#static-methods 196 */ 197 @KspExperimental 198 fun getOwnerJvmClassName(declaration: KSPropertyDeclaration): String? 199 200 /** 201 * Returns the [binary class name](https://asm.ow2.io/javadoc/org/objectweb/asm/Type.html#getClassName()) of the 202 * owner class in JVM for the given [KSFunctionDeclaration]. 203 * 204 * For functions declared in classes / interfaces; this value is the binary class name of the declaring class. 205 * 206 * For top level functions, this is the binary class name of the synthetic class that is generated for the Kotlin 207 * file. 208 * see: https://kotlinlang.org/docs/java-to-kotlin-interop.html#package-level-functions 209 * 210 * Note that, for functions declared in companion objects, the returned owner class will be the Companion class. 211 * see: https://kotlinlang.org/docs/java-to-kotlin-interop.html#static-methods 212 */ 213 @KspExperimental 214 fun getOwnerJvmClassName(declaration: KSFunctionDeclaration): String? 215 216 /** 217 * Returns checked exceptions declared in a function's header. 218 * @return A sequence of [KSType] declared in `throws` statement for a Java method or in @Throws annotation for a Kotlin function. 219 * Checked exceptions from class files are not supported yet, an empty sequence will be returned instead. 220 */ 221 @KspExperimental 222 fun getJvmCheckedException(function: KSFunctionDeclaration): Sequence<KSType> 223 224 /** 225 * Returns checked exceptions declared in a property accessor's header. 226 * @return A sequence of [KSType] declared @Throws annotation for a Kotlin property accessor. 227 * Checked exceptions from class files are not supported yet, an empty sequence will be returned instead. 228 */ 229 @KspExperimental 230 fun getJvmCheckedException(accessor: KSPropertyAccessor): Sequence<KSType> 231 232 /** 233 * Returns declarations with the given package name. 234 * @param packageName the package name to look up. 235 * @return A sequence of [KSDeclaration] with matching package name. 236 * This will return declarations from both dependencies and source. 237 */ 238 @KspExperimental 239 fun getDeclarationsFromPackage(packageName: String): Sequence<KSDeclaration> 240 241 /** 242 * Returns the corresponding Kotlin class with the given Java class. 243 * 244 * E.g. 245 * java.lang.String -> kotlin.String 246 * java.lang.Integer -> kotlin.Int 247 * java.util.List -> kotlin.List 248 * java.util.Map.Entry -> kotlin.Map.Entry 249 * java.lang.Void -> null 250 * 251 * @param javaName a Java class name 252 * @return corresponding Kotlin class name or null 253 */ 254 @KspExperimental 255 fun mapJavaNameToKotlin(javaName: KSName): KSName? 256 257 /** 258 * Returns the corresponding Java class with the given Kotlin class. 259 * 260 * E.g. 261 * kotlin.Throwable -> java.lang.Throwable 262 * kotlin.Int -> java.lang.Integer 263 * kotlin.Nothing -> java.lang.Void 264 * kotlin.IntArray -> null 265 * 266 * @param kotlinName a Java class name 267 * @return corresponding Java class name or null 268 */ 269 @KspExperimental 270 fun mapKotlinNameToJava(kotlinName: KSName): KSName? 271 272 /** 273 * Same as KSDeclarationContainer.declarations, but sorted by declaration order in the source. 274 * 275 * Note that this is SLOW. AVOID IF POSSIBLE. 276 */ 277 @KspExperimental 278 fun getDeclarationsInSourceOrder(container: KSDeclarationContainer): Sequence<KSDeclaration> 279 280 /** 281 * Returns a set of effective Java modifiers, if declaration is being / was generated to Java bytecode. 282 */ 283 @KspExperimental 284 fun effectiveJavaModifiers(declaration: KSDeclaration): Set<Modifier> 285 286 /** 287 * Compute the corresponding Java wildcard, from the given reference. 288 * 289 * @param reference the reference to the type usage 290 * @return an equivalent type reference from the Java wildcard's point of view 291 */ 292 @KspExperimental 293 fun getJavaWildcard(reference: KSTypeReference): KSTypeReference 294 295 /** 296 * Tests a type if it was declared as legacy "raw" type in Java - a type with its type arguments fully omitted. 297 * 298 * @param type a type to check. 299 * @return True if the type is a "raw" type. 300 */ 301 @KspExperimental 302 fun isJavaRawType(type: KSType): Boolean 303 } 304