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 // | 18 // |
19 // TODO(turnidge): Finish implementing this api. | 19 // TODO(turnidge): Finish implementing this api. |
20 | 20 |
21 /** | 21 /** |
22 * Returns an [IsolateMirror] for the current isolate. | 22 * A [MirrorSystem] is the main interface used to reflect on a set of |
| 23 * associated libraries. |
| 24 * |
| 25 * At runtime each running isolate has a distinct [MirrorSystem]. |
| 26 * |
| 27 * It is also possible to have a [MirrorSystem] which represents a set |
| 28 * of libraries which are not running -- perhaps at compile-time. In |
| 29 * this case, all available reflective functionality would be |
| 30 * supported, but runtime functionality (such as invoking a function |
| 31 * or inspecting the contents of a variable) would fail dynamically. |
23 */ | 32 */ |
24 IsolateMirror currentIsolateMirror() { | 33 interface MirrorSystem { |
25 return _Mirrors.currentIsolateMirror(); | 34 /** |
| 35 * A mirror on the root library of the mirror system. |
| 36 */ |
| 37 final LibraryMirror rootLibrary; |
| 38 |
| 39 /** |
| 40 * An immutable map from from library names to mirrors for all |
| 41 * libraries known to this mirror system. |
| 42 */ |
| 43 Map<String, LibraryMirror> libraries(); |
| 44 |
| 45 /** |
| 46 * A mirror on the isolate associated with this [MirrorSystem]. |
| 47 * This may be null if this mirror system is not running. |
| 48 */ |
| 49 IsolateMirror isolate; |
| 50 |
| 51 /** |
| 52 * Returns an [InstanceMirror] for some Dart language object. |
| 53 * |
| 54 * This only works if this mirror system is associated with the |
| 55 * current running isolate. |
| 56 */ |
| 57 InstanceMirror mirrorOf(Object reflectee); |
26 } | 58 } |
27 | 59 |
28 /** | 60 /** |
29 * Returns an [InstanceMirror] for some Dart language object. | 61 * Returns a [MirrorSystem] for the current isolate. |
30 */ | 62 */ |
31 InstanceMirror mirrorOf(Object reflectee) { | 63 MirrorSystem currentMirrorSystem() { |
32 return _Mirrors.mirrorOf(reflectee); | 64 return _Mirrors.currentMirrorSystem(); |
33 } | 65 } |
34 | 66 |
35 /** | 67 /** |
36 * Creates an [IsolateMirror] on the isolate which is listening on | 68 * Creates a [MirrorSystem] for the isolate which is listening on |
37 * the [SendPort]. | 69 * the [SendPort]. |
38 */ | 70 */ |
39 Future<IsolateMirror> isolateMirrorOf(SendPort port) { | 71 Future<MirrorSystem> mirrorSystemOf(SendPort port) { |
40 return _Mirrors.isolateMirrorOf(port); | 72 return _Mirrors.mirrorSystemOf(port); |
41 } | 73 } |
42 | 74 |
43 /** | 75 /** |
44 * A [Mirror] reflects some Dart language entity. | 76 * A [Mirror] reflects some Dart language entity. |
45 * | 77 * |
46 * Every [Mirror] originates from some [IsolateMirror]. | 78 * Every [Mirror] originates from some [MirrorSystem]. |
47 */ | 79 */ |
48 interface Mirror { | 80 interface Mirror { |
49 /** | 81 /** |
50 * A mirror on the originating isolate for this [Mirror]. | 82 * The originating [MirrorSystem] for this mirror. |
51 */ | 83 */ |
52 final IsolateMirror isolate; | 84 final MirrorSystem mirrors; |
53 } | 85 } |
54 | 86 |
55 /** | 87 /** |
56 * An [IsolateMirror] reflects an isolate. | 88 * An [IsolateMirror] reflects an isolate. |
57 */ | 89 */ |
58 interface IsolateMirror extends Mirror { | 90 interface IsolateMirror extends Mirror { |
59 /** | 91 /** |
60 * A unique name used to refer to an isolate in debugging messages. | 92 * A unique name used to refer to an isolate in debugging messages. |
61 */ | 93 */ |
62 final String debugName; | 94 final String debugName; |
63 | 95 |
64 /** | 96 /** |
65 * A mirror on the root library of the reflectee. | 97 * Does this mirror reflect the currently running isolate? |
66 */ | 98 */ |
67 final LibraryMirror rootLibrary; | 99 final bool isCurrent; |
68 | |
69 /** | |
70 * An immutable map from from library names to mirrors for all | |
71 * libraries loaded in the reflectee. | |
72 */ | |
73 Map<String, LibraryMirror> libraries(); | |
74 } | 100 } |
75 | 101 |
76 | 102 |
77 /** | 103 /** |
78 * An [ObjectMirror] is a common superinterface of [InstanceMirror], | 104 * An [ObjectMirror] is a common superinterface of [InstanceMirror], |
79 * [InterfaceMirror], and [LibraryMirror] that represents their shared | 105 * [InterfaceMirror], and [LibraryMirror] that represents their shared |
80 * functionality. | 106 * functionality. |
81 * | 107 * |
82 * For the purposes of the mirrors library, these types are all | 108 * For the purposes of the mirrors library, these types are all |
83 * object-like, in that they support method invocation and field | 109 * object-like, in that they support method invocation and field |
(...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
121 * - the value is of type [bool] | 147 * - the value is of type [bool] |
122 * - the value is of type [String] | 148 * - the value is of type [String] |
123 * | 149 * |
124 * If you access [simpleValue] when [hasSimpleValue] is false an | 150 * If you access [simpleValue] when [hasSimpleValue] is false an |
125 * exception is thrown. | 151 * exception is thrown. |
126 */ | 152 */ |
127 final simpleValue; | 153 final simpleValue; |
128 } | 154 } |
129 | 155 |
130 /** | 156 /** |
| 157 * A [TypeMirror] reflects a Dart language class, interface, typedef |
| 158 * or type variable. |
| 159 */ |
| 160 interface TypeMirror extends Mirror { |
| 161 /** |
| 162 * The library in which this interface is declared. |
| 163 */ |
| 164 final LibraryMirror library; |
| 165 } |
| 166 |
| 167 /** |
131 * An [InterfaceMirror] reflects a Dart language class or interface. | 168 * An [InterfaceMirror] reflects a Dart language class or interface. |
132 */ | 169 */ |
133 interface InterfaceMirror extends ObjectMirror { | 170 interface InterfaceMirror extends TypeMirror, ObjectMirror { |
134 /** | 171 /** |
135 * The name of this interface. | 172 * The name of this interface. |
136 */ | 173 */ |
137 final String simpleName; | 174 final String simpleName; |
138 | 175 |
139 /** | 176 /** |
140 * The library in which this interface is declared. | |
141 */ | |
142 final LibraryMirror library; | |
143 | |
144 /** | |
145 * Does this mirror represent a class? | 177 * Does this mirror represent a class? |
146 */ | 178 */ |
147 final bool isClass; | 179 final bool isClass; |
148 | 180 |
149 /** | 181 /** |
150 * Returns a mirror on the superclass on the reflectee. | 182 * Returns a mirror on the superclass on the reflectee. |
151 * | 183 * |
152 * For interfaces, the superclass is Object. | 184 * For interfaces, the superclass is Object. |
153 */ | 185 */ |
154 InterfaceMirror superclass(); | 186 InterfaceMirror superclass(); |
(...skipping 280 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
435 | 467 |
436 /** | 468 /** |
437 * A [MirrorException] is used to indicate errors within the mirrors | 469 * A [MirrorException] is used to indicate errors within the mirrors |
438 * framework. | 470 * framework. |
439 */ | 471 */ |
440 class MirrorException implements Exception { | 472 class MirrorException implements Exception { |
441 const MirrorException(String this._message); | 473 const MirrorException(String this._message); |
442 String toString() => "MirrorException: '$_message'"; | 474 String toString() => "MirrorException: '$_message'"; |
443 final String _message; | 475 final String _message; |
444 } | 476 } |
OLD | NEW |