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.symbol.KSAnnotated 20 21 /** 22 * [SymbolProcessor] is the interface used by plugins to integrate into Kotlin Symbol Processing. 23 * SymbolProcessor supports multiple rounds of execution, a processor may return a list of deferred symbols at the end 24 * of every round, which will be passed to processors again in the next round, together with the newly generated symbols. 25 * On exceptions, KSP will try to distinguish between exceptions from KSP and exceptions from processors. 26 * Exceptions from processors will immediately terminate processing and be logged as an error in KSPLogger. 27 * Exceptions from KSP should be reported to KSP developers for further investigation. 28 * At the end of the round where exceptions or errors happened, all processors will invoke onError() function to do 29 * their own error handling. 30 */ 31 interface SymbolProcessor { 32 /** 33 * Called by Kotlin Symbol Processing to run the processing task. 34 * 35 * @param resolver provides [SymbolProcessor] with access to compiler details such as Symbols. 36 * @return A list of deferred symbols that the processor can't process. Only symbols that can't be processed at this round should be returned. Symbols in compiled code (libraries) are always valid and are ignored if returned in the deferral list. 37 */ processnull38 fun process(resolver: Resolver): List<KSAnnotated> 39 40 /** 41 * Called by Kotlin Symbol Processing to finalize the processing of a compilation. 42 */ 43 fun finish() {} 44 45 /** 46 * Called by Kotlin Symbol Processing to handle errors after a round of processing. 47 */ onErrornull48 fun onError() {} 49 } 50