1 /*
2  * Copyright (C) 2017 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
18 
19 import com.android.tools.metalava.model.visitors.ItemVisitor
20 import com.android.tools.metalava.model.visitors.TypeVisitor
21 
22 interface ParameterItem : Item {
23     /** The name of this field */
namenull24     fun name(): String
25 
26     /** The type of this field */
27     override fun type(): TypeItem
28 
29     /** The containing method */
30     fun containingMethod(): MethodItem
31 
32     /** Index of this parameter in the parameter list (0-based) */
33     val parameterIndex: Int
34 
35     /**
36      * The public name of this parameter. In Kotlin, names are part of the
37      * public API; in Java they are not. In Java, you can annotate a
38      * parameter with {@literal @ParameterName("foo")} to name the parameter
39      * something (potentially different from the actual code parameter name).
40      */
41     fun publicName(): String?
42 
43     /**
44      * Returns whether this parameter has a default value. In Kotlin, this is supported directly;
45      * in Java, it's supported via a special annotation, {@literal @DefaultValue("source"). This
46      * does not necessarily imply that the default value is accessible, and we know the body of the
47      * default value.
48      *
49      * @see isDefaultValueKnown
50      */
51     fun hasDefaultValue(): Boolean
52 
53     /**
54      * Returns whether this parameter has an accessible default value that we plan to keep. This is
55      * a superset of [hasDefaultValue] - if we are not writing the default values to the signature
56      * file, then the default value might not be available, even though the parameter does have a
57      * default.
58      *
59      * @see hasDefaultValue
60      */
61     fun isDefaultValueKnown(): Boolean
62 
63     /**
64      * Returns the default value.
65      *
66      * **This method should only be called if [isDefaultValueKnown] returned true!** (This
67      * is necessary since the null return value is a valid default value separate from
68      * no default value specified.)
69      *
70      * The default value is the source string
71      * literal representation of the value, e.g. strings would be surrounded
72      * by quotes, Booleans are the strings "true" or "false", and so on.
73      */
74     fun defaultValue(): String?
75 
76     /**
77      * Whether this is a varargs parameter
78      */
79     fun isVarArgs(): Boolean
80 
81     override fun parent(): MethodItem? = containingMethod()
82 
83     override fun accept(visitor: ItemVisitor) {
84         if (visitor.skip(this)) {
85             return
86         }
87 
88         visitor.visitItem(this)
89         visitor.visitParameter(this)
90 
91         visitor.afterVisitParameter(this)
92         visitor.afterVisitItem(this)
93     }
94 
acceptTypesnull95     override fun acceptTypes(visitor: TypeVisitor) {
96         if (visitor.skip(this)) {
97             return
98         }
99 
100         val type = type()
101         visitor.visitType(type, this)
102         visitor.afterVisitType(type, this)
103     }
104 
requiresNullnessInfonull105     override fun requiresNullnessInfo(): Boolean {
106         return !type().primitive
107     }
108 
hasNullnessInfonull109     override fun hasNullnessInfo(): Boolean {
110         if (!requiresNullnessInfo()) {
111             return true
112         }
113 
114         return modifiers.hasNullnessInfo()
115     }
116 
containingClassnull117     override fun containingClass(strict: Boolean): ClassItem? = containingMethod().containingClass(false)
118     override fun containingPackage(strict: Boolean): PackageItem? = containingMethod().containingPackage(false)
119 
120     // TODO: modifier list
121 }