OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 // #library("mirrors"); | 5 // #library("mirrors"); |
6 | 6 |
7 // The dart:mirrors library provides reflective access for Dart program. | 7 // The dart:mirrors library provides reflective access for Dart program. |
8 // | 8 // |
9 // For the purposes of the mirrors library, we adopt a naming | 9 // For the purposes of the mirrors library, we adopt a naming |
10 // convention with respect to getters and setters. Specifically, for | 10 // convention with respect to getters and setters. Specifically, for |
11 // some variable or field... | 11 // some variable or field... |
12 // | 12 // |
13 // var myField; | 13 // var myField; |
14 // | 14 // |
15 // ...the getter is named 'myField' and the setter is named | 15 // ...the getter is named 'myField' and the setter is named |
16 // 'myField='. This allows us to assign unique names to getters and | 16 // 'myField='. This allows us to assign unique names to getters and |
17 // setters for the purposes of member lookup. | 17 // setters for the purposes of member lookup. |
18 // TODO(turnidge): Implement getter/setter lookup. | |
19 // | 18 // |
20 // TODO(turnidge): Finish implementing this api. | 19 // TODO(turnidge): Finish implementing this api. |
21 | 20 |
22 /** | 21 /** |
23 * Returns an [IsolateMirror] for the current isolate. | 22 * Returns an [IsolateMirror] for the current isolate. |
24 */ | 23 */ |
25 IsolateMirror currentIsolateMirror() { | 24 IsolateMirror currentIsolateMirror() { |
26 return _Mirrors.currentIsolateMirror(); | 25 return _Mirrors.currentIsolateMirror(); |
27 } | 26 } |
28 | 27 |
(...skipping 12 matching lines...) Expand all Loading... |
41 return _Mirrors.isolateMirrorOf(port); | 40 return _Mirrors.isolateMirrorOf(port); |
42 } | 41 } |
43 | 42 |
44 /** | 43 /** |
45 * A [Mirror] reflects some Dart language entity. | 44 * A [Mirror] reflects some Dart language entity. |
46 * | 45 * |
47 * Every [Mirror] originates from some [IsolateMirror]. | 46 * Every [Mirror] originates from some [IsolateMirror]. |
48 */ | 47 */ |
49 interface Mirror { | 48 interface Mirror { |
50 /** | 49 /** |
51 * The isolate of orgin for this [Mirror]. | 50 * A mirror on the originating isolate for this [Mirror]. |
52 */ | 51 */ |
53 final IsolateMirror isolate; | 52 final IsolateMirror isolate; |
54 } | 53 } |
55 | 54 |
56 /** | 55 /** |
57 * An [IsolateMirror] reflects an isolate. | 56 * An [IsolateMirror] reflects an isolate. |
58 */ | 57 */ |
59 interface IsolateMirror extends Mirror { | 58 interface IsolateMirror extends Mirror { |
60 /** | 59 /** |
61 * A unique name used to refer to an isolate in debugging messages. | 60 * A unique name used to refer to an isolate in debugging messages. |
(...skipping 23 matching lines...) Expand all Loading... |
85 * access. Real Dart objects are represented by the [InstanceMirror] | 84 * access. Real Dart objects are represented by the [InstanceMirror] |
86 * type. | 85 * type. |
87 * | 86 * |
88 * See [InstanceMirror], [InterfaceMirror], and [LibraryMirror]. | 87 * See [InstanceMirror], [InterfaceMirror], and [LibraryMirror]. |
89 */ | 88 */ |
90 interface ObjectMirror extends Mirror { | 89 interface ObjectMirror extends Mirror { |
91 /** | 90 /** |
92 * Invokes the named function and returns a mirror on the result. | 91 * Invokes the named function and returns a mirror on the result. |
93 * | 92 * |
94 * TODO(turnidge): Properly document. | 93 * TODO(turnidge): Properly document. |
95 * | |
96 * TODO(turnidge): what to do if invoke causes the death of the reflectee? | |
97 */ | 94 */ |
98 Future<InstanceMirror> invoke(String memberName, | 95 Future<InstanceMirror> invoke(String memberName, |
99 List<Object> positionalArguments, | 96 List<Object> positionalArguments, |
100 [Map<String,Object> namedArguments]); | 97 [Map<String,Object> namedArguments]); |
101 } | 98 } |
102 | 99 |
103 /** | 100 /** |
104 * An [InstanceMirror] reflects an instance of a Dart language object. | 101 * An [InstanceMirror] reflects an instance of a Dart language object. |
105 */ | 102 */ |
106 interface InstanceMirror extends ObjectMirror { | 103 interface InstanceMirror extends ObjectMirror { |
107 /** | 104 /** |
108 * Returns a mirror on the class of the reflectee. | 105 * Returns a mirror on the class of the reflectee. |
109 */ | 106 */ |
110 InterfaceMirror getClass(); | 107 InterfaceMirror getClass(); |
111 | 108 |
112 /** | 109 /** |
113 * Does [simpleValue] contain the value of the reflectee? | 110 * Does [simpleValue] contain the value of the reflectee? |
114 */ | 111 */ |
115 bool hasSimpleValue; | 112 bool hasSimpleValue; |
116 | 113 |
117 /** | 114 /** |
118 * If the [InstanceMirror] refers to a simple value, we provide | 115 * If the [InstanceMirror] refers to a simple value, we provide |
119 * access to the actual value here. | 116 * access to the actual value here. |
120 * | 117 * |
121 * A value is simple if: | 118 * A value is simple if one of the following holds: |
122 * - it is null | 119 * - the value is null |
123 * - it is of type [num] | 120 * - the value is of type [num] |
124 * - it is of type [bool] | 121 * - the value is of type [bool] |
125 * - it is of type [String] | 122 * - the value is of type [String] |
126 * | 123 * |
127 * If you access [simpleValue] when [hasSimpleValue] is false an | 124 * If you access [simpleValue] when [hasSimpleValue] is false an |
128 * exception is thrown. | 125 * exception is thrown. |
129 */ | 126 */ |
130 final simpleValue; | 127 final simpleValue; |
131 | |
132 } | 128 } |
133 | 129 |
134 /** | 130 /** |
135 * An [InterfaceMirror] reflects a Dart language class or interface. | 131 * An [InterfaceMirror] reflects a Dart language class or interface. |
136 */ | 132 */ |
137 interface InterfaceMirror extends ObjectMirror { | 133 interface InterfaceMirror extends ObjectMirror { |
138 /** | 134 /** |
139 * The name of this interface. | 135 * The name of this interface. |
140 */ | 136 */ |
141 final String simpleName; | 137 final String simpleName; |
(...skipping 21 matching lines...) Expand all Loading... |
163 List<InterfaceMirror> superinterfaces(); | 159 List<InterfaceMirror> superinterfaces(); |
164 | 160 |
165 /** | 161 /** |
166 * Returns a mirror on the default factory class or null if there is | 162 * Returns a mirror on the default factory class or null if there is |
167 * none. | 163 * none. |
168 */ | 164 */ |
169 InterfaceMirror defaultFactory(); | 165 InterfaceMirror defaultFactory(); |
170 | 166 |
171 /** | 167 /** |
172 * An immutable map from from names to mirrors for all members of | 168 * An immutable map from from names to mirrors for all members of |
173 * this type, including inherited members. | 169 * this type. |
174 * | 170 * |
175 * The members of an interface are its constructors, methods, | 171 * The members of an interface are its constructors, methods, |
176 * fields, getters, and setters. | 172 * fields, getters, and setters. |
177 * | 173 * |
178 * TODO(turnidge): Currently empty. | 174 * This does not include inherited members. |
179 */ | 175 */ |
180 Map<String, Mirror> members(); | 176 Map<String, Mirror> members(); |
| 177 |
| 178 /** |
| 179 * An immutable map from names to mirrors for all method, |
| 180 * constructor, getter, and setter declarations in this library. |
| 181 */ |
| 182 Map<String, MethodMirror> methods(); |
| 183 |
| 184 /** |
| 185 * An immutable map from names to mirrors for all variable |
| 186 * declarations in this library. |
| 187 */ |
| 188 Map<String, VariableMirror> variables(); |
181 } | 189 } |
182 | 190 |
183 /** | 191 /** |
184 * A [LibraryMirror] reflects a Dart language library, providing | 192 * A [LibraryMirror] reflects a Dart language library, providing |
185 * access to the variables, functions, classes, and interfaces of the | 193 * access to the variables, functions, classes, and interfaces of the |
186 * library. | 194 * library. |
187 */ | 195 */ |
188 interface LibraryMirror extends ObjectMirror { | 196 interface LibraryMirror extends ObjectMirror { |
189 /** | 197 /** |
190 * The name of this library, as provided in the [#library] declaration. | 198 * The name of this library, as provided in the [#library] declaration. |
191 */ | 199 */ |
192 final String simpleName; | 200 final String simpleName; |
193 | 201 |
194 /** | 202 /** |
195 * The url of the library. | 203 * The url of the library. |
196 * | 204 * |
197 * TODO(turnidge): Document where this url comes from. Will this | 205 * TODO(turnidge): Document where this url comes from. Will this |
198 * value be sensible? | 206 * value be sensible? |
199 */ | 207 */ |
200 final String url; | 208 final String url; |
201 | 209 |
202 /** | 210 /** |
203 * An immutable map from from top-level names to mirrors for all | 211 * An immutable map from from names to mirrors for all members in |
204 * members in this library. | 212 * this library. |
205 * | 213 * |
206 * The members of a library are its top-level classes, interfaces, | 214 * The members of a library are its top-level classes, interfaces, |
207 * functions, variables, getters, and setters. | 215 * functions, variables, getters, and setters. |
208 * | |
209 * TODO(turnidge): Currently only contains classes and interfaces. | |
210 */ | 216 */ |
211 Map<String, Mirror> members(); | 217 Map<String, Mirror> members(); |
| 218 |
| 219 /** |
| 220 * An immutable map from names to mirrors for all class and |
| 221 * interface declarations in this library. |
| 222 */ |
| 223 Map<String, InterfaceMirror> classes(); |
| 224 |
| 225 /** |
| 226 * An immutable map from names to mirrors for all function |
| 227 * declarations in this library. |
| 228 */ |
| 229 Map<String, MethodMirror> functions(); |
| 230 |
| 231 /** |
| 232 * An immutable map from names to mirrors for all variable |
| 233 * declarations in this library. |
| 234 */ |
| 235 Map<String, VariableMirror> variables(); |
212 } | 236 } |
213 | 237 |
214 /** | 238 /** |
| 239 * A [MethodMirror] reflects a Dart language function, method, |
| 240 * constructor, getter, or setter. |
| 241 */ |
| 242 interface MethodMirror { |
| 243 /** |
| 244 * The name of this function. |
| 245 */ |
| 246 final String simpleName; |
| 247 |
| 248 /** |
| 249 * A mirror on the owner of this function. This is the declaration |
| 250 * immediately surrounding the reflectee. |
| 251 * |
| 252 * For top-level functions, this will be a [LibraryMirror] and for |
| 253 * methods, constructors, getters, and setters, this will be an |
| 254 * [InterfaceMirror]. |
| 255 */ |
| 256 Mirror owner; |
| 257 |
| 258 // Ownership |
| 259 |
| 260 /** |
| 261 * Does this mirror reflect a top-level function? |
| 262 */ |
| 263 bool isTopLevel; |
| 264 |
| 265 /** |
| 266 * Does this mirror reflect a static method? |
| 267 * |
| 268 * For the purposes of the mirrors library, a top-level function is |
| 269 * considered static. |
| 270 */ |
| 271 bool isStatic; |
| 272 |
| 273 // Method kind |
| 274 |
| 275 /** |
| 276 * Does this mirror reflect a regular function or method? |
| 277 * |
| 278 * A method is regular if it is not a getter, setter, or constructor. |
| 279 */ |
| 280 bool isMethod; |
| 281 |
| 282 /** |
| 283 * Does this mirror reflect an abstract method? |
| 284 */ |
| 285 bool isAbstract; |
| 286 |
| 287 /** |
| 288 * Does this mirror reflect a getter? |
| 289 */ |
| 290 bool isGetter; |
| 291 |
| 292 /** |
| 293 * Does this mirror reflect a setter? |
| 294 */ |
| 295 bool isSetter; |
| 296 |
| 297 /** |
| 298 * Does this mirror reflect a constructor? |
| 299 */ |
| 300 bool isConstructor; |
| 301 |
| 302 // Constructor kind |
| 303 |
| 304 /** |
| 305 * Does this mirror reflect a const constructor? |
| 306 */ |
| 307 bool isConstConstructor; |
| 308 |
| 309 /** |
| 310 * Does this mirror reflect a generative constructor? |
| 311 */ |
| 312 bool isGenerativeConstructor; |
| 313 |
| 314 /** |
| 315 * Does this mirror reflect a redirecting constructor? |
| 316 */ |
| 317 bool isRedirectingConstructor; |
| 318 |
| 319 /** |
| 320 * Does this mirror reflect a factory constructor? |
| 321 */ |
| 322 bool isFactoryConstructor; |
| 323 } |
| 324 |
| 325 |
| 326 /** |
| 327 * A [VariableMirror] reflects a Dart language variable. |
| 328 */ |
| 329 interface VariableMirror { |
| 330 /** |
| 331 * The name of this variable |
| 332 */ |
| 333 final String simpleName; |
| 334 |
| 335 /** |
| 336 * A mirror on the owner of this method. The owner is the |
| 337 * declaration immediately surrounding the reflectee. |
| 338 * |
| 339 * For top-level variables, this will be a [LibraryMirror] and for |
| 340 * class and interface variables, this will be an [InterfaceMirror]. |
| 341 */ |
| 342 Mirror owner; |
| 343 |
| 344 /** |
| 345 * Does this mirror reflect a top-level variable? |
| 346 */ |
| 347 bool isTopLevel; |
| 348 |
| 349 /** |
| 350 * Does this mirror reflect a static variable? |
| 351 * |
| 352 * For the purposes of the mirror library, top-level variables are |
| 353 * implicitly declared static. |
| 354 */ |
| 355 bool isStatic; |
| 356 |
| 357 /** |
| 358 * Does this mirror reflect a final variable? |
| 359 */ |
| 360 bool isFinal; |
| 361 } |
| 362 |
| 363 |
| 364 /** |
215 * When an error occurs during the mirrored execution of code, a | 365 * When an error occurs during the mirrored execution of code, a |
216 * [MirroredError] is thrown. | 366 * [MirroredError] is thrown. |
217 * | 367 * |
218 * In general, there are three main classes of failure that can happen | 368 * In general, there are three main classes of failure that can happen |
219 * during mirrored execution of code in some isolate: | 369 * during mirrored execution of code in some isolate: |
220 * | 370 * |
221 * - An exception is thrown but not caught. This is caught by the | 371 * - An exception is thrown but not caught. This is caught by the |
222 * mirrors framework and a [MirroredUncaughtExceptionError] is | 372 * mirrors framework and a [MirroredUncaughtExceptionError] is |
223 * created and thrown. | 373 * created and thrown. |
224 * | 374 * |
225 * - A compile-time error occurs, such as a syntax error. This is | 375 * - A compile-time error occurs, such as a syntax error. This is |
226 * suppressed by the mirrors framework and a | 376 * suppressed by the mirrors framework and a |
227 * [MirroredCompilationError] is created and thrown. | 377 * [MirroredCompilationError] is created and thrown. |
228 * | 378 * |
229 * - A truly fatal error occurs, causing the isolate to be exited. If | 379 * - A truly fatal error occurs, causing the isolate to be exited. If |
230 * the reflector and reflectee share the same isolate, then they | 380 * the reflector and reflectee share the same isolate, then they |
231 * will both suffer. If the reflector and reflectee are in distinct | 381 * will both suffer. If the reflector and reflectee are in distinct |
232 * isolates, then we hope to provide some information about the | 382 * isolates, then we hope to provide some information about the |
233 * isolate death, but this is yet to be implemented. | 383 * isolate death, but this has yet to be implemented. |
234 * | 384 * |
235 * TODO(turnidge): Specify the behavior for remote fatal errors. | 385 * TODO(turnidge): Specify the behavior for remote fatal errors. |
236 */ | 386 */ |
237 abstract class MirroredError implements Exception { | 387 abstract class MirroredError implements Exception { |
238 } | 388 } |
239 | 389 |
240 /** | 390 /** |
241 * When an uncaught exception occurs during the mirrored execution | 391 * When an uncaught exception occurs during the mirrored execution |
242 * of code, a [MirroredUncaughtExceptionError] is thrown. | 392 * of code, a [MirroredUncaughtExceptionError] is thrown. |
243 * | 393 * |
(...skipping 41 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
285 | 435 |
286 /** | 436 /** |
287 * A [MirrorException] is used to indicate errors within the mirrors | 437 * A [MirrorException] is used to indicate errors within the mirrors |
288 * framework. | 438 * framework. |
289 */ | 439 */ |
290 class MirrorException implements Exception { | 440 class MirrorException implements Exception { |
291 const MirrorException(String this._message); | 441 const MirrorException(String this._message); |
292 String toString() => "MirrorException: '$_message'"; | 442 String toString() => "MirrorException: '$_message'"; |
293 final String _message; | 443 final String _message; |
294 } | 444 } |
OLD | NEW |