1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
|
package scala.reflect
package api
trait Mirrors { self: Universe =>
type RuntimeClass >: Null
// [Eugene] also, it might make sense to provide shortcuts for the API
//
// for example, right now to invoke the same method for several different instances, you need:
// 1) get the method symbol
// 2) get the instance mirror for every instance
// 3) call reflectMethod on the instance mirrors for every instance
// 4) call apply for every instance (okay, this can be united with step #3, but still)
//
// I have several suggestions that we can discuss later:
// 1) For every `reflectXXX(sym: Symbol): XXXMirror`, add `reflectXXX(name: String, types: Type*): XXXMirror` and `reflectXXXs(): List[XXXMirror]`
// 2) Provide a way to skip obtaining InstanceMirror (step #2 in the outline provided above)
// [Eugene] another improvement would be have mirrors reproduce the structure of the reflection domain
// e.g. a ClassMirror could also have a list of fields, methods, constructors and so on
// read up more on the proposed design in "Reflecting Scala" by Y. Coppel
/** A mirror that reflects a runtime value */
trait InstanceMirror {
/** The instance value reflected by this mirror */
def instance: Any
/** The symbol corresponding to the run-time class of the reflected instance */
def symbol: ClassSymbol
/** Reflects against a field symbol and returns a mirror
* that can be used to get and, if appropriate, set the value of the field.
*
* To get a field symbol by the name of the field you would like to reflect,
* use `<this mirror>.symbol.typeSignature.member(newTermName(<name of the field>)).asTerm.accessed`.
* For further information about member lookup refer to `Symbol.typeSignature`.
*
* The input symbol can be either private or non-private (Scala reflection transparently deals with visibility).
* It must be a member (declared or inherited) of the class of the instance underlying this mirror.
*
* The input symbol can represent either a field itself or one of the corresponding accessors
* (in all cases the resulting mirror will refer to the field symbol).
*
* If a field symbol doesn't correspond to a reflectable entity of the underlying platform,
* a `ScalaReflectionException` exception will be thrown. This might happen, for example, for primary constructor parameters.
* Typically they produce class fields, however, private parameters that aren't used outside the constructor
* remain plain parameters of a constructor method of the class.
*/
def reflectField(field: TermSymbol): FieldMirror
/** Reflects against a method symbol and returns a mirror
* that can be used to invoke the method provided.
*
* To get a method symbol by the name of the method you would like to reflect,
* use `<this mirror>.symbol.typeSignature.member(newTermName(<name of the method>)).asMethod`.
* For further information about member lookup refer to `Symbol.typeSignature`.
*
* The input symbol can be either private or non-private (Scala reflection transparently deals with visibility).
* It must be a member (declared or inherited) of the instance underlying this mirror.
*/
def reflectMethod(method: MethodSymbol): MethodMirror
/** Reflects against an inner class symbol and returns a mirror
* that can be used to create instances of the class, inspect its companion object or perform further reflections.
*
* To get a class symbol by the name of the class you would like to reflect,
* use `<this mirror>.symbol.typeSignature.member(newTypeName(<name of the class>)).asClass`.
* For further information about member lookup refer to `Symbol.typeSignature`.
*
* The input symbol can be either private or non-private (Scala reflection transparently deals with visibility).
* It must be a member (declared or inherited) of the instance underlying this mirror.
*/
def reflectClass(cls: ClassSymbol): ClassMirror
/** Reflects against an inner module symbol and returns a mirror
* that can be used to get the instance of the object or inspect its companion class.
*
* To get a module symbol by the name of the object you would like to reflect,
* use `<this mirror>.symbol.typeSignature.member(newTermName(<name of the object>)).asModule`.
* For further information about member lookup refer to `Symbol.typeSignature`.
*
* The input symbol can be either private or non-private (Scala reflection transparently deals with visibility).
* It must be a member (declared or inherited) of the instance underlying this mirror.
*/
def reflectModule(mod: ModuleSymbol): ModuleMirror
}
/** A mirror that reflects a field */
trait FieldMirror {
/** The object containing the field */
def receiver: AnyRef
/** The field symbol representing the field.
*
* In Scala `val` and `var` declarations are usually compiled down to a pair of
* a backing field and corresponding accessor/accessors, which means that a single
* declaration might correspond to up to three different symbols. Nevertheless
* the `FieldMirror.symbol` field always points to a backing field symbol.
*/
def symbol: TermSymbol
/** Retrieves the value stored in the field.
*
* Scala reflection uses reflection capabilities of the underlying platform,
* so `FieldMirror.get` might throw platform-specific exceptions associated
* with getting a field or invoking a getter method of the field.
*/
def get: Any
/** Updates the value stored in the field.
*
* If a field is immutable, a `ScalaReflectionException` will be thrown.
*
* Scala reflection uses reflection capabilities of the underlying platform,
* so `FieldMirror.get` might throw platform-specific exceptions associated
* with setting a field or invoking a setter method of the field.
*/
def set(value: Any): Unit
}
/** A mirror that reflects a method handle */
trait MethodMirror {
/** The receiver object of the method */
def receiver: AnyRef
/** The method symbol representing the method */
def symbol: MethodSymbol
/** The result of applying the method to the given arguments
*
* Scala reflection uses reflection capabilities of the underlying platform,
* so `FieldMirror.get` might throw platform-specific exceptions associated
* with invoking the corresponding method or constructor.
*/
def apply(args: Any*): Any
}
/** A mirror that reflects the instance or static parts of a runtime class */
trait TemplateMirror {
/** The runtime class reflected by this mirror */
def runtimeClass: RuntimeClass
/** True if the mirror represents the static part
* if a runtime class or the companion object of a Scala class.
* One has:
*
* this.isStatic == this.isInstanceOf[ModuleMirror]
* !this.isStatic == this.isInstanceOf[ClassMirror]
*/
def isStatic: Boolean
/** The Scala symbol corresponding to the reflected runtime class or object */
def symbol: Symbol
/** Optionally, the mirror of the companion reflected by this mirror.
* If this mirror reflects a Scala object, the mirror for the companion class, or None
* if the mirror represents a Scala object that comes without a class.
* Otherwise, if the mirror represents the static part of a runtime class, the
* mirror representing the instance part of the same class.
* Otherwise, if the mirror represents a Scala instance class, the mirror for the companion
* object of that class, or None if no such object exists.
* Otherwise, if the mirror represents a runtime instance class, a mirror representing the static
* part of the same class.
*/
def companion: Option[TemplateMirror]
}
/** A mirror that reflects a Scala object definition or the static parts of a runtime class */
trait ModuleMirror extends TemplateMirror {
/** The Scala module symbol corresponding to the reflected object */
override def symbol: ModuleSymbol
/** If the reflected runtime class corresponds to a Scala object definition,
* returns the single instance representing that object.
* If this mirror reflects the static part of a runtime class, returns `null`.
*/
def instance: Any
/** Optionally, the mirror of the companion class if the object reflected by this mirror.
* If this mirror reflects a Scala object, the mirror for the companion class, or None
* if the mirror represents a Scala object that comes without a class.
* Otherwise, if the mirror represents the static part of a runtime class, the
* mirror representing the instance part of the same class.
*/
def companion: Option[ClassMirror]
}
/** A mirror that reflects the instance parts of a runtime class */
trait ClassMirror extends TemplateMirror {
/** The Scala class symbol corresponding to the reflected class */
override def symbol: ClassSymbol
/** Reflects against a constructor symbol and returns a mirror
* that can be used to invoke it and construct instances of this mirror's symbols.
*
* To get a constructor symbol you would like to reflect,
* use `<this mirror>.symbol.typeSignature.member(nme.CONSTRUCTOR).asMethod`.
* For further information about member lookup refer to `Symbol.typeSignature`.
*
* The input symbol can be either private or non-private (Scala reflection transparently deals with visibility).
* It must be a member (declared or inherited) of the class underlying this mirror.
*/
def reflectConstructor(constructor: MethodSymbol): MethodMirror
/** Optionally, the mirror of the companion object of the class reflected by this mirror.
* If this mirror represents a Scala instance class, the mirror for the companion
* object of that class, or None if no such object exists.
* Otherwise, if the mirror represents a runtime instance class, a mirror representing the static
* part of the same class.
*/
def companion: Option[ModuleMirror]
}
/** A mirror that reflects instances and static classes */
trait ReflectiveMirror extends MirrorOf[Mirrors.this.type] {
/** A reflective mirror for the given object.
*
* Such a mirror can be used to further reflect against the members of the object
* to get/set fields, invoke methods and inspect inner classes and objects.
*/
def reflect(obj: Any): InstanceMirror
/** Reflects against a static class symbol and returns a mirror
* that can be used to create instances of the class, inspect its companion object or perform further reflections.
*
* To get a class symbol by the name of the class you would like to reflect,
* use `<this mirror>.classSymbol(<runtime class loaded by its name>)`.
*
* The input symbol can be either private or non-private (Scala reflection transparently deals with visibility).
* It must be static, i.e. either top-level or nested within one or several static objects.
*/
def reflectClass(cls: ClassSymbol): ClassMirror
/** Reflects against a static module symbol and returns a mirror
* that can be used to get the instance of the object or inspect its companion class.
*
* To get a module symbol by the name of its companion class you would like to reflect,
* use `<this mirror>.classSymbol(<runtime class loaded by its name>).companion.get`.
*
* The input symbol can be either private or non-private (Scala reflection transparently deals with visibility).
* It must be static, i.e. either top-level or nested within one or several static objects.
*/
def reflectModule(mod: ModuleSymbol): ModuleMirror
}
/** The API of a mirror for a reflective universe */
trait RuntimeMirror extends ReflectiveMirror { self =>
/** Maps a Scala type to the corresponding Java class object */
def runtimeClass(tpe: Type): RuntimeClass
/** Maps a Scala class symbol to the corresponding Java class object
* @throws ClassNotFoundException if there is no Java class
* corresponding to the given Scala class symbol.
* Note: If the Scala symbol is ArrayClass, a ClassNotFound exception is thrown
* because there is no unique Java class corresponding to a Scala generic array
*/
def runtimeClass(cls: ClassSymbol): RuntimeClass
/** A class symbol for the specified runtime class.
* @return The class symbol for the runtime class in the current class loader.
* @throws java.lang.ClassNotFoundException if no class with that name exists
* @throws scala.reflect.internal.MissingRequirementError if no corresponding symbol exists
* to do: throws anything else?
*/
def classSymbol(rtcls: RuntimeClass): ClassSymbol
/** A module symbol for the specified runtime class.
* @return The module symbol for the runtime class in the current class loader.
* @throws java.lang.ClassNotFoundException if no class with that name exists
* @throws scala.reflect.internal.MissingRequirementError if no corresponding symbol exists
* to do: throws anything else?
*/
def moduleSymbol(rtcls: RuntimeClass): ModuleSymbol
}
}
|
