OLD | NEW |
---|---|
(Empty) | |
1 #library("introspection"); | |
ahe
2012/01/02 16:21:14
According to merriam-webster, "introspection" mean
| |
2 #import("corelib_mirrors.dart"); | |
3 #import("debug"); | |
4 | |
5 /** | |
6 The root of the mirror hierarchy. | |
7 | |
8 Should Mirror implement Hashable? | |
ahe
2012/01/02 16:21:14
Yes :-)
| |
9 | |
10 Throughout the mirror API, we use maps to | |
11 Maps allow random access to mirrors, looked up by name. | |
12 One can always go through their values to look for mirrors with specific prope rties. | |
mattsh
2012/01/03 20:00:15
line too long here and a couple other places
| |
13 The keys will often by strings, but this is not required. All we require is th at a key | |
ahe
2012/01/02 16:21:14
by -> be
| |
14 has a toString() method (which all objects have) that yields a string that ide ntifies the desired mirror. | |
15 | |
16 The reason we do not insist on strings is that: | |
17 a. Efficient implementations may use customized representations of source code strings | |
18 (e.g., indices into a single source stream), and yet | |
19 b. The string interface cannot be implemented by user code. | |
20 | |
21 */ | |
22 interface Mirror { | |
23 | |
24 // final reflectee; | |
25 // in principle, everything being reflected has some reified representation, b ut this does not hold at the | |
26 // Dart language level | |
ahe
2012/01/02 16:21:14
A concrete example: a compiler may provide a mirro
| |
27 | |
28 /** We need a way of distinguishing different kinds of mirrors for purposes su ch as | |
29 equality, as illustrated by the proposed equality method: | |
30 | |
31 operator == (other) { return (kind == other.kind) && (reflectee == other.refle ctee);} | |
32 | |
33 */ | |
34 final String kind; | |
ahe
2012/01/02 16:21:14
I'd prefer having a MirrorKind interface.
| |
35 } | |
36 | |
37 | |
38 /** | |
39 Return an isolate mirror on the isolate of the argument port p. | |
40 This is how we start reflecting on another isolate. | |
41 | |
42 This is a synchronous wrapper around an asynchronous message send. I would like to | |
43 define it as an async function if we have language support for that. Or, we coul d | |
44 have it return a future. | |
45 */ | |
46 IsolateMirror isolateMirrorOf(Port p); | |
47 | |
48 | |
49 /** | |
50 The main gateway into the mirror system. | |
51 Given a mirror on an isolate, one can obtain mirrors on its ports and libraries, | |
52 and in particular on its root library. One can also suspend it and get a mirror | |
53 on its stack. | |
54 */ | |
55 interface IsolateMirror extends Mirror { | |
56 | |
57 /** Return a mirror on the root library of the reflectee */ | |
58 final LibraryMirror rootLibrary; | |
59 | |
60 /** Return true unless the reflectee is suspended */ | |
61 bool isActive(); | |
mattsh
2012/01/03 20:00:15
Might be better to reverse this to be isSuspended
| |
62 | |
63 /** Suspend the reflectee and return a mirror on its stack. | |
64 Do we want to separate this into two calls: suspend and stack? | |
65 | |
66 This call is a synchronous wrapper around an async message send. If we support | |
67 async, it could be an async method instead. | |
68 */ | |
69 StackMirror stack(); | |
ahe
2012/01/02 16:21:14
I think this name is problematic. The name should
| |
70 | |
71 /** Return an immutable map from library names to mirrors on all libraries loade d | |
72 by the reflectee. | |
73 */ | |
74 Map<Object, LibraryMirror> libraries(); | |
75 | |
76 /* Return a list of (mirrors for) all ports of the reflectee */ | |
ahe
2012/01/02 16:21:14
Which end of the ports?
| |
77 List<ObjectMirror> ports(); | |
78 } | |
79 | |
80 | |
81 | |
82 | |
83 /** A library mirror reflects a library instance, which includes actual classes and interfaces, | |
84 distinct from their declarations. | |
85 This also leaves an opening for making libraries first class. | |
86 | |
87 By extending ObjectMirror, we get the ability to access a library's state and ca ll its functions. | |
88 | |
89 A library itself has a declaration with access to the interface declarations. | |
90 | |
91 One question is how what class does a generic class declaration G<T1 .. Tn> indu ce | |
92 in the library? | |
93 I'd say G<Dynamic, ..., Dynamic> but I admit it seems weird. TBD. | |
ahe
2012/01/02 16:21:14
I'm not sure I understand this. A declaration of t
| |
94 | |
95 There is no constructor in this interface. One would obtain | |
96 LibraryMirrors from the IsolateMirror. | |
97 */ | |
98 interface LibraryMirror extends ObjectMirror { | |
99 | |
100 /** Returns an immutable map from simple top level class names to mirrors on the classes | |
101 of the library. | |
102 */ | |
103 Map<Object, InterfaceMirror> classes(); | |
mattsh
2012/01/03 20:00:15
Why do these methods return a Map, rather than sim
| |
104 | |
105 /** Returns an immutable map from simple top level interface names to mirrors on | |
106 the interfaces of the library. | |
107 */ | |
108 Map<Object, InterfaceMirror> interfaces(); | |
109 | |
110 /** Returns an immutable map from simple top level names to mirrors for | |
111 all top level declarations in the library. | |
112 */ | |
113 Map<Object, Mirror> members(); | |
114 | |
115 /** The declaration of this library */ | |
116 LibraryDeclarationMirror declaration(); | |
117 | |
118 //? Map<Object, LibraryMirror> imports | |
119 | |
120 /** | |
121 Lookup s in the scope of the library. Finds top level names and imported ones. | |
122 */ | |
123 Mirror lookupName(String s); | |
ahe
2012/01/02 16:21:14
Doesn't this method lookup a mirror? Using a Strin
| |
124 } | |
125 | |
126 /** | |
127 A library declaration represents the logical source of a library. | |
128 | |
129 There is no constructor in this interface. | |
130 One would obtain LibraryDeclarationMirrors from a LibraryMirror. | |
131 */ | |
132 interface LibraryDeclarationMirror extends Mirror { | |
133 | |
134 /** The name of the library, as given in #library(). | |
135 */ | |
136 String simpleName(); | |
ahe
2012/01/02 16:21:14
Object may be better here.
| |
137 | |
138 /** Returns an immutable map from simple top level class names to mirrors on the | |
139 class declarations of the library. | |
140 */ | |
141 Map<Object, InterfaceDeclarationMirror> classes(); | |
142 | |
143 /** Returns an immutable map from simple top level interface names to mirrors on the | |
144 interface declarations of the library. | |
145 */ | |
146 Map<Object, InterfaceDeclarationMirror> interfaces(); | |
hausner
2011/12/21 21:53:19
Why do you use Object as the first type argument o
gbracha
2011/12/22 18:29:59
Because in some cases, the key should not be a sta
zundel
2012/01/03 19:31:22
IMHO, I don't think using Object as a key is very
| |
147 | |
148 /** Returns an immutable map from simple top level function names to mirrors on the | |
149 function declarations of the library. | |
150 */ | |
151 Map<Object, MethodMirror> functions(); | |
152 | |
153 /** Returns a map from simple top level variable names to mirrors on the | |
154 variable declarations of the library. | |
155 */ | |
156 Map<Object, VariableMirror> variables(); | |
157 | |
158 /** Returns an immutable map from simple top level names to mirrors on the top l evel | |
159 declarations of the library. | |
160 */ | |
161 Map<Object, Mirror> declarations(); | |
ahe
2012/01/02 16:21:14
I think this method is important. Preferably, you'
| |
162 | |
163 /** Returns a list of all import clauses */ | |
164 List<String> imports(); | |
165 | |
166 /** Returns the source code for the library (if available). | |
167 If it isn't. what should it throw? | |
168 */ | |
169 String source();// multiple files | |
170 | |
171 // Includes? Not semantically meaningful, let's skip for now | |
ahe
2012/01/02 16:21:14
Everything in source code is important. Also, I'd
| |
172 } | |
173 | |
174 | |
175 /** A common supertype for interfaces and type variables */ | |
176 interface TypeMirror extends Mirror{ | |
177 | |
178 } | |
179 | |
180 /** | |
181 Represents a type variable, which has a name and a bound. | |
182 */ | |
183 | |
184 interface TypeVariableMirror extends TypeMirror { | |
185 | |
186 final String simpleName; | |
187 String qualifiedName(); // => '{declaration().qualifiedName()}.{simpleName}'; | |
188 String source(); // {return vmMirror.sourceFor(declaringClass.reflectee, simp leName);} | |
189 // type variables in same space as anything else | |
190 | |
191 /** Return a mirror on the class, interface, or typedef that declared the | |
192 reflectee. */ | |
193 Mirror declaration(); | |
194 | |
195 /** Returns a mirror on the bound of the reflectee */ | |
196 TypeMirror bound(); | |
197 } | |
198 | |
199 /** | |
200 Represents a class or interface. There is no separate ClassMirror, because a | |
201 ClassMirror would add very little to this interface (we could elide superclass p erhaps). | |
202 | |
203 An interface mirror represents an actual type. This is distinct from an interfac e | |
204 declaration, which may have formal type parameters (and in the future, may repr esent | |
205 a mixin). | |
206 | |
207 We extend ObjectMirror because we must provide a way to call static methods and access | |
208 static fields. Not very satisfying. What happens if you ask for the class | |
209 of these things? Do we raise an exception? Or provide a class (such as DartClass , DartInterface or DartLibrary)? | |
ahe
2012/01/02 16:21:14
Return null :-)
| |
210 */ | |
211 interface InterfaceMirror extends ObjectMirror, TypeMirror { | |
ahe
2012/01/02 16:21:14
From the perspective of using this library for sta
ahe
2012/01/02 16:21:14
An InterfaceMirror is not a TypeMirror. See commen
| |
212 | |
213 /** Return a mirror on the library that declared this interface */ | |
214 LibraryMirror library(); | |
215 | |
216 /** Return a mirror on the declaration of this interface */ | |
217 InterfaceDeclarationMirror declaration(); | |
218 | |
219 /** Returns an immutable map from interface names to mirrors on the superinterfa ces | |
220 of the reflectee. | |
221 */ | |
222 Map<Object, InterfaceMirror> superinterfaces(); | |
ahe
2012/01/02 16:21:14
See above comments about how to separate applicati
| |
223 | |
224 /** If the reflectee is a class, return a mirror on its superclass. | |
225 If the reflectee is an interface, return a mirror on class Object*/ | |
226 InterfaceMirror superclass(); | |
ahe
2012/01/02 16:21:14
This should return a TypeMirror.
| |
227 | |
228 /** Returns an immutable map from the names of the formal type parameters of t he | |
229 reflectee's declaration to the actual type arguments of the reflectee. | |
230 | |
231 In contrast, the declaration gives type parameters */ | |
232 Map<Object, TypeMirror> typeArguments(); | |
ahe
2012/01/02 16:21:14
This does not belong here.
| |
233 | |
234 /** Return true iff this mirror reflects a class */ | |
235 bool isClass; | |
236 | |
237 /** Returns an immutable map from member names to mirrors on | |
238 all members of this type - including inherited ones */ | |
239 Map<Object, Mirror> members(); | |
240 | |
241 /** Return a mirror on the default implementation; returns null if there is none . */ | |
242 InterfaceMirror defaultFactory(); | |
243 } | |
244 | |
245 | |
246 // Once we have proper aliases, we would add this: | |
247 // typedef ClassMirror = InterfaceMirror; | |
248 | |
249 /** | |
250 An interface declaration is distinct from an interface; the latter describes an actual | |
251 type. Many interfaces may correspond to the same interface declaration. | |
252 For example, List<String> and List<int> both correspond to the same declaration | |
253 List<T>. | |
254 | |
255 There is no ClassDeclarationMirror, because the only difference would be the sup erclass clause. | |
256 */ | |
257 interface InterfaceDeclarationMirror extends Mirror { | |
258 | |
259 /** Returns the simple name of this interface */ | |
260 final String simpleName; | |
261 | |
262 /** Returns the fully qualified name of this interface. | |
263 //{return '{library.name}{simpleName}';} | |
zundel
2012/01/03 19:31:22
{libraryPrefix}.{simpleName}? Surely there is som
| |
264 */ | |
265 String qualifiedName(); | |
266 | |
267 /** Returns a mirror on the declaration of the library in which this type is | |
268 declared. | |
269 */ | |
270 final LibraryDeclarationMirror library; | |
271 | |
272 /** | |
273 Return an immutable map from method names to mirrors on the methods | |
274 declared locally within the reflectee. | |
275 Inherited ones are a convenience supplied in InterfaceMirror | |
276 (though there is a subtlety wrt generics). | |
277 We make no distinction between static and instance members here. | |
278 Staticness is a property of the mirrors being returned. | |
279 Currently no distinction between class and mixin. | |
280 */ | |
281 Map<Object, MethodMirror> methods(); | |
282 | |
283 /** Returns an immutable map from field names to mirrors on any actual fields | |
284 declared within this interface. Empty unless this is a class. | |
285 */ | |
286 Map<Object, VariableMirror> fields(); | |
287 | |
288 /** | |
289 Returns an immutable map from names to mirrors on explicitly declared getters th at are | |
290 defined locally by the reflectee. Does not return implicitly defined getters. | |
291 Reflection shows you what is there, exposing structure hidden at the base level. | |
292 */ | |
293 Map<Object, MethodMirror> getters(); | |
294 | |
295 /** | |
296 Returns an immutable map from names to mirrors on explicitly declared setters th at are | |
297 defined locally by the reflectee. Does not return implicitly defined setters. | |
298 */ | |
299 Map<Object, MethodMirror> setters(); | |
300 | |
301 /** | |
302 Returns an immutable map from constructor names to mirrors on the constructors | |
303 of the reflectee. | |
304 This includes generative, redirecting and factory constructors. | |
305 */ | |
306 Map<Object, MethodMirror> constructors(); | |
307 | |
308 | |
309 /** Returns an immutable map from interface names to mirrors on the direct | |
310 superinterfaces of the reflectee. | |
311 */ | |
312 Map<Object, InterfaceMirror> superinterfaces(); | |
313 | |
314 /** If the reflectee is a class, return a mirror on the superclass given in th e | |
315 superclass clause. | |
316 If the reflectee is an interface, return a mirror on class Object. | |
317 */ | |
318 InterfaceMirror superclass(); | |
319 | |
320 /** Returns an immutable map from the names to the type parameters of the reflec tee. | |
321 If the reflectee is not generic, the map is empty. | |
322 */ | |
323 Map<Object, TypeMirror> typeParameters(); | |
324 | |
325 /** Returns an immutable list of members and constructors. | |
326 Includes getters and setters (which is why it cannot be a map) | |
327 Does it include implicit ones? | |
328 */ | |
329 List<Mirror> declarations(); | |
330 | |
331 | |
332 | |
333 } | |
334 | |
335 /** | |
336 A mirror representing a method (or function?) | |
337 */ | |
338 interface MethodMirror extends Mirror { | |
339 | |
340 /** Return the method name */ | |
341 final String simpleName; | |
342 | |
343 /** Return the name of the method, prefixed by the fully qualified name of its | |
344 immediately enclosing class, interface or library */ | |
345 String qualifiedName(); //{return declaringClass.fullyQualifiedName + "." + s impleName;} | |
346 | |
347 /** Return the source code for the reflectee. If unavailable, throw? Or return | |
348 empty string? | |
349 */ | |
350 String source(); //{return vmMirror.sourceFor(declaringClass.reflectee, simpl eName);} | |
hausner
2011/12/21 21:53:19
What's the rationale to have access to the source
gbracha
2011/12/22 18:29:59
IDEs
| |
351 | |
352 bool isStatic(); | |
353 bool isMethod(); | |
354 bool isGetter(); | |
355 bool isSetter(); | |
356 bool isToplevel(); | |
357 bool isConstructor(); | |
358 | |
359 /** only true if a const constructor */ | |
360 bool isConst(); | |
361 /** only true if redirecting constructor */ | |
362 bool isRedirecting(); | |
363 /** only true if generative constructor */ | |
364 bool isGenerative(); | |
365 /** only true if a factory constructor */ | |
366 bool isFactory(); | |
zundel
2012/01/03 19:31:22
This may be evident from the naming convention, bu
| |
367 | |
368 /** Return a mirror on the declaration immediately surrounding the reflectee. | |
369 This could be a class, interface, library or another method or function */ | |
370 */ | |
371 Mirror surroundingDeclaration(); | |
372 | |
373 } | |
374 | |
375 | |
376 | |
377 /** ObjectMirrors provide reflective access to live objects, and through them, t o their classes. | |
378 | |
379 If we supported an async construct in the language, I'd make the methods of this class | |
380 all be async methods. | |
381 As it stands, they are synchronous wrappers around asynchronous message sends. | |
382 | |
383 Should this type be removed from introspection and placed in a separate library? | |
384 Its presence makes it impossible to | |
385 tree shake code. | |
386 */ | |
387 interface ObjectMirror extends Mirror { | |
388 /** | |
389 Get a mirror on the actual class of the reflectee of this mirror. | |
390 At this point, there is no setClass, but ideally there should be one. | |
391 */ | |
392 InterfaceMirror getClass(); | |
ahe
2012/01/02 16:21:14
This should return a TypeMirror.
| |
393 | |
394 | |
395 /** Invoke the named method/getter/setter, or get the value of a local variabl e with | |
396 the supplied arguments. Returns a mirror on the result. | |
397 The arguments must be object mirrors or values, because we do not support serial ization | |
398 of objects across isolates. I'm not sure how workable that is. | |
399 We distinguish getetr and setter calls based on the number of arguments (0/1). | |
zundel
2012/01/03 19:31:22
getetr -> getter
| |
400 */ | |
401 ObjectMirror invoke(String memberName, List<Object> positionalArguments, Map<S tring, Object> namedArguments); | |
402 | |
403 /** Extract the closure for the function namde as an argument. | |
404 The optional argument allows us to distingusih between getters and setters. It d efaults | |
405 to false, so that a getter will be returned unless it is set to true. | |
406 Otherwise, it is ignored. | |
407 */ | |
408 ObjectMirror getProperty(String memberName, [bool setter]); | |
409 | |
410 /** Set the value of a field, bypassing setters. Lets us (re)set final fields | |
411 reflectively. The argument must be either a value or an ObjectMirror. | |
412 */ | |
413 void setField(String fieldName, Object value); | |
414 } | |
415 | |
416 | |
417 /** Fields look to be the same as variables, except that the surrounding declara tion | |
418 can be a library, so we can dispense with FieldMirror | |
419 */ | |
420 interface VariableDeclarationMirror extends Mirror { | |
421 | |
422 /** Return the variable name */ | |
423 final String simpleName; | |
424 | |
425 /** Return the name of the variable, prefixed by the fully qualified name of its | |
426 immediately enclosing class or library */ | |
427 String qualifiedName();//{return surroundingDeclaration.fullyQualifiedName + "." + simpleName;} | |
428 | |
429 /** Return the source code for the variable declaration. | |
430 The source would include modifiers, type and initializer */ | |
431 String source(); //{return vmMirror.sourceFor(surroundingDeclaration.reflecte e, simpleName);} | |
432 | |
433 /** True for static variables */ | |
434 bool isStatic; | |
435 bool isFinal; | |
436 | |
437 // add isLocal? isParameter? | |
438 | |
439 /** Return a mirror on the declaration immediately surrounding the reflectee. | |
440 This could be a class, interface, library or another method or function */ | |
441 */ | |
442 Mirror surroundingDeclaration; | |
443 | |
444 } | |
445 | |
446 /** | |
447 A closure mirror reflects a closure. Closures are special, because we do not w ish | |
448 to reflect the internals of a particular closure implementation. And yet, we nee d | |
449 access to details of the closure internals - for example, its enclosing context and | |
450 its source code. | |
451 */ | |
452 interface ClosureMirror { | |
453 | |
454 /** Return the source code for the closure, if available. | |
455 */ | |
456 String source(); | |
457 | |
458 /** Call the closure. The arguments given in the descriptor need to be ObjectMir rors | |
459 or values. | |
460 */ | |
461 ObjectMirror apply(ArgumentDescriptor arguments); | |
462 | |
463 /** Look up the value of name in the scope of the closure. | |
464 The result is a mirror on that value. | |
465 */ | |
466 ObjectMirror findInContext(String name); | |
467 | |
468 // As it stands, I cannot get at the activation it came from. | |
469 } | |
OLD | NEW |