1 /*
2  * Copyright (C) 2023 The Android Open Source Project
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  *      http://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 
17 package com.android.tools.metalava.model.source
18 
19 import com.android.tools.metalava.model.ClassResolver
20 import com.android.tools.metalava.model.Codebase
21 import java.io.File
22 
23 /** Provides support for creating [Codebase] related objects from source files (including jars). */
24 interface SourceParser {
25 
26     /**
27      * Get a [ClassResolver] instance that will resolve classes provided by jars on the [classPath].
28      *
29      * @param classPath a list of jar [File]s.
30      */
getClassResolvernull31     fun getClassResolver(classPath: List<File>): ClassResolver
32 
33     /**
34      * Parse a set of sources into a [SourceCodebase].
35      *
36      * @param sourceSet the list of source files and root directories.
37      * @param commonSourceSet the list of source files and root directories in the common module.
38      * @param description the description to use for [Codebase.description].
39      * @param classPath the possibly empty list of jar files which may provide additional classes
40      *   referenced by the sources.
41      *
42      * "Common module" is the term used in Kotlin multi-platform projects where platform-agnostic
43      * business logic and `expect` declarations are declared. (Counterparts, like platform-specific
44      * logic and `actual` declarations are declared at platform-specific modules, of course.) To
45      * that end, [commonSourceSet] will be used for Kotlin multi-platform projects only. All others,
46      * such as Java only or non-KMP Kotlin projects, won't need to set it, i.e., should pass source
47      * files and root directories via [sourceSet], not [commonSourceSet].
48      */
49     fun parseSources(
50         sourceSet: SourceSet,
51         commonSourceSet: SourceSet,
52         description: String,
53         classPath: List<File>,
54     ): SourceCodebase
55 
56     /**
57      * Load a [SourceCodebase] from a single jar.
58      *
59      * @param apiJar the jar file from which the [SourceCodebase] will be loaded.
60      */
61     fun loadFromJar(apiJar: File): SourceCodebase
62 }
63