OLD | NEW |
---|---|
1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2013, 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 // For the purposes of the mirrors library, we adopt a naming | 5 // For the purposes of the mirrors library, we adopt a naming |
6 // convention with respect to getters and setters. Specifically, for | 6 // convention with respect to getters and setters. Specifically, for |
7 // some variable or field... | 7 // some variable or field... |
8 // | 8 // |
9 // var myField; | 9 // var myField; |
10 // | 10 // |
(...skipping 52 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
63 * | 63 * |
64 * At runtime each running isolate has a distinct [MirrorSystem]. | 64 * At runtime each running isolate has a distinct [MirrorSystem]. |
65 * | 65 * |
66 * It is also possible to have a [MirrorSystem] which represents a set | 66 * It is also possible to have a [MirrorSystem] which represents a set |
67 * of libraries which are not running -- perhaps at compile-time. In | 67 * of libraries which are not running -- perhaps at compile-time. In |
68 * this case, all available reflective functionality would be | 68 * this case, all available reflective functionality would be |
69 * supported, but runtime functionality (such as invoking a function | 69 * supported, but runtime functionality (such as invoking a function |
70 * or inspecting the contents of a variable) would fail dynamically. | 70 * or inspecting the contents of a variable) would fail dynamically. |
71 */ | 71 */ |
72 abstract class MirrorSystem { | 72 abstract class MirrorSystem { |
73 /** | 73 /// Returns an immutable map from URIs to mirrors for all libraries known |
Lasse Reichstein Nielsen
2015/10/07 08:32:25
Why change this doc-comment's format, but not the
srawlins
2015/10/07 10:26:29
Sorry, in some other libraries I've been changing
| |
74 * Returns an immutable map from URIs to mirrors for all libraries known | 74 /// to this mirror system. |
Lasse Reichstein Nielsen
2015/10/07 09:09:03
This is better described as a property:
/// All l
srawlins
2015/10/07 10:26:30
Done.
| |
75 * to this mirror system. For a runtime mirror system, only libraries which | 75 /// |
76 * are currently loaded are included, and repeated calls of this method may | 76 /// For a runtime mirror system, only libraries which are currently loaded |
77 * return different maps as libraries are loaded. | 77 /// are included, and repeated calls of this method may return different maps |
78 */ | 78 /// as libraries are loaded. |
79 Map<Uri, LibraryMirror> get libraries; | 79 Map<Uri, LibraryMirror> get libraries; |
80 | 80 |
81 /** | 81 /** |
82 * Returns the unique library named [libraryName] if it exists. | 82 * Returns the unique library named [libraryName] if it exists. |
83 * | 83 * |
84 * If no unique library exists, an error is thrown. | 84 * If no unique library exists, an error is thrown. |
85 */ | 85 */ |
86 LibraryMirror findLibrary(Symbol libraryName) { | 86 LibraryMirror findLibrary(Symbol libraryName) { |
87 return libraries.values.singleWhere( | 87 return libraries.values.singleWhere( |
88 (library) => library.simpleName == libraryName); | 88 (library) => library.simpleName == libraryName); |
89 } | 89 } |
90 | 90 |
91 /** | 91 /// A mirror on the isolate associated with this [MirrorSystem]. |
92 * A mirror on the isolate associated with this [MirrorSystem]. | 92 /// |
93 * This may be null if this mirror system is not running. | 93 /// This may be null if this mirror system is not running. |
94 */ | |
95 IsolateMirror get isolate; | 94 IsolateMirror get isolate; |
96 | 95 |
97 /** | 96 /** |
98 * A mirror on the [:dynamic:] type. | 97 * A mirror on the [:dynamic:] type. |
99 */ | 98 */ |
100 TypeMirror get dynamicType; | 99 TypeMirror get dynamicType; |
101 | 100 |
102 /** | 101 /** |
103 * A mirror on the [:void:] type. | 102 * A mirror on the [:void:] type. |
104 */ | 103 */ |
105 TypeMirror get voidType; | 104 TypeMirror get voidType; |
106 | 105 |
107 /** | 106 /** |
108 * Returns the name of [symbol]. | 107 * Returns the name of [symbol]. |
109 * | 108 * |
110 * The following text is non-normative: | 109 * The following text is non-normative: |
111 * | 110 * |
112 * Using this method may result in larger output. If possible, use | 111 * Using this method may result in larger output. If possible, use |
113 * [MirrorsUsed] to specify which symbols must be retained in clear text. | 112 * [MirrorsUsed] to specify which symbols must be retained in clear text. |
114 */ | 113 */ |
115 external static String getName(Symbol symbol); | 114 external static String getName(Symbol symbol); |
116 | 115 |
117 /** | 116 /// Returns a symbol for [name]. |
118 * Returns a symbol for [name]. If [library] is not a [LibraryMirror] or if | 117 /// |
119 * [name] is a private identifier and [library] is [:null:], throws an | 118 /// If [library] is not a [LibraryMirror] or if [name] is a private identifier |
120 * [ArgumentError]. If [name] is a private identifier, the symbol returned is | 119 /// and [library] is [:null:], throws an [ArgumentError]. If [name] is a |
Lasse Reichstein Nielsen
2015/10/07 09:09:02
Cosider changing [:...:] to `...`.
srawlins
2015/10/07 10:26:29
Done.
| |
121 * with respect to [library]. | 120 /// private identifier, the symbol returned is with respect to [library]. |
122 * | 121 /// |
123 * The following text is non-normative: | 122 /// The following text is non-normative: |
124 * | 123 /// |
125 * Using this method may result in larger output. If possible, use | 124 /// Using this method may result in larger output. If possible, use |
126 * the const constructor of Symbol or symbol literals. | 125 /// the const constructor of Symbol or symbol literals. |
Lasse Reichstein Nielsen
2015/10/07 09:09:02
maybe: Symbol -> [Symbol]
srawlins
2015/10/07 10:26:30
Done.
| |
127 */ | |
128 external static Symbol getSymbol(String name, [LibraryMirror library]); | 126 external static Symbol getSymbol(String name, [LibraryMirror library]); |
129 } | 127 } |
130 | 128 |
131 /** | 129 /** |
132 * Returns a [MirrorSystem] for the current isolate. | 130 * Returns a [MirrorSystem] for the current isolate. |
133 */ | 131 */ |
134 external MirrorSystem currentMirrorSystem(); | 132 external MirrorSystem currentMirrorSystem(); |
135 | 133 |
136 /** | 134 /// Reflects an instance. |
137 * Reflects an instance. | 135 /// |
138 * Returns an [InstanceMirror] reflecting [reflectee]. | 136 /// Returns an [InstanceMirror] reflecting [reflectee]. If [reflectee] is a |
139 * If [reflectee] is a function or an instance of a class | 137 /// function or an instance of a class that has a [:call:] method, the returned |
140 * that has a [:call:] method, the returned instance mirror | 138 /// instance mirror will be a [ClosureMirror]. |
141 * will be a [ClosureMirror]. | 139 /// |
142 * | 140 /// Note that since one cannot obtain an object from another isolate, this |
143 * Note that since one cannot obtain an object from | 141 /// function can only be used to obtain mirrors on objects of the current |
144 * another isolate, this function can only be used to | 142 /// isolate. |
145 * obtain mirrors on objects of the current isolate. | |
146 */ | |
147 external InstanceMirror reflect(Object reflectee); | 143 external InstanceMirror reflect(Object reflectee); |
148 | 144 |
149 /** | 145 /// Reflects a class declaration. |
150 * Reflects a class declaration. | 146 /// |
151 * Let *C* be the original class declaration of the class | 147 /// Let *C* be the original class declaration of the class represented by [key]. |
152 * represented by [key]. | 148 /// This function returns a [ClassMirror] reflecting *C*. |
153 * This function returns a [ClassMirror] reflecting *C*. | 149 /// |
154 * | 150 /// If [key] is not an instance of [Type] then this function throws an |
155 * If [key] is not an instance of [Type] then this function | 151 /// [ArgumentError]. If [key] is the Type for dynamic or a function typedef, |
156 * throws an [ArgumentError]. If [key] is the Type for dynamic | 152 /// throws an [ArgumentError]. |
157 * or a function typedef, throws an [ArgumentError]. | 153 /// |
158 * | 154 /// Note that since one cannot obtain a [Type] object from another isolate, this |
159 * Note that since one cannot obtain a [Type] object from | 155 /// function can only be used to obtain class mirrors on classes of the current |
160 * another isolate, this function can only be used to | 156 /// isolate. |
161 * obtain class mirrors on classes of the current isolate. | |
162 */ | |
163 external ClassMirror reflectClass(Type key); | 157 external ClassMirror reflectClass(Type key); |
164 | 158 |
165 /** | 159 /// Returns a [TypeMirror] reflecting the type represented by [key]. |
Lasse Reichstein Nielsen
2015/10/07 09:09:03
Inconsistent wording with the methods above.
Maybe
srawlins
2015/10/07 10:26:30
Done.
| |
166 * This function returns a [TypeMirror] reflecting the type | 160 /// |
167 * represented by [key]. | 161 /// If [key] is not an instance of [Type] then this function throws an |
168 * | 162 /// [ArgumentError]. |
169 * If [key] is not an instance of [Type] then this function | 163 /// |
170 * throws an [ArgumentError]. | 164 /// Note that since one cannot obtain a [Type] object from another isolate, this |
171 * | 165 /// function can only be used to obtain type mirrors on types of the current |
172 * Note that since one cannot obtain a [Type] object from | 166 /// isolate. |
173 * another isolate, this function can only be used to | |
174 * obtain type mirrors on types of the current isolate. | |
175 */ | |
176 external TypeMirror reflectType(Type key); | 167 external TypeMirror reflectType(Type key); |
177 | 168 |
178 /** | 169 /** |
179 * A [Mirror] reflects some Dart language entity. | 170 * A [Mirror] reflects some Dart language entity. |
180 * | 171 * |
181 * Every [Mirror] originates from some [MirrorSystem]. | 172 * Every [Mirror] originates from some [MirrorSystem]. |
182 */ | 173 */ |
183 abstract class Mirror {} | 174 abstract class Mirror {} |
184 | 175 |
185 /** | 176 /** |
186 * An [IsolateMirror] reflects an isolate. | 177 * An [IsolateMirror] reflects an isolate. |
187 */ | 178 */ |
188 abstract class IsolateMirror implements Mirror { | 179 abstract class IsolateMirror implements Mirror { |
189 /** | 180 /// Returns a unique name used to refer to an isolate in debugging messages. |
Lasse Reichstein Nielsen
2015/10/07 09:09:02
Describe a getter as a property:
/// A unique name
srawlins
2015/10/07 10:26:29
Done.
| |
190 * Returns a unique name used to refer to an isolate | |
191 * in debugging messages. | |
192 */ | |
193 String get debugName; | 181 String get debugName; |
194 | 182 |
195 /** | 183 /// Returns [:true:] if and only if this mirror reflects the currently running |
196 * Returns [:true:] if and only if this mirror reflects | 184 /// isolate. Otherwise returns [:false:]. |
Lasse Reichstein Nielsen
2015/10/07 09:09:02
/// Whether this mirror reflects the currently run
srawlins
2015/10/07 10:26:30
Done.
| |
197 * the currently running isolate. Otherwise returns | |
198 * [:false:]. | |
199 */ | |
200 bool get isCurrent; | 185 bool get isCurrent; |
201 | 186 |
202 /** | 187 /// Returns a [LibraryMirror] on the root library for this isolate. |
Lasse Reichstein Nielsen
2015/10/07 09:09:02
/// The root library for the reflected isolate.
//
srawlins
2015/10/07 10:26:29
I'm probably not qualified to spell out the defini
| |
203 * Returns a [LibraryMirror] on the root library for this | |
204 * isolate. | |
205 */ | |
206 LibraryMirror get rootLibrary; | 188 LibraryMirror get rootLibrary; |
207 | 189 |
208 /** | 190 /// Returns [:true:] if this mirror is equal to [other]. |
209 * Returns [:true:] if this mirror is equal to [other]. | 191 /// |
210 * Otherwise returns [:false:]. | 192 /// Otherwise returns [:false:]. The equality holds if and only if |
Lasse Reichstein Nielsen
2015/10/07 09:09:03
/// Whether [other] is an [IsolateMirror] on the s
srawlins
2015/10/07 10:26:29
Done.
| |
211 * The equality holds if and only if | 193 /// |
212 * (1) [other] is a mirror of the same kind | 194 /// 1. [other] is a mirror of the same kind, and |
213 * and | 195 /// 2. the isolate being reflected by this mirror is the same isolate being |
214 * (2) the isolate being reflected by this mirror is the same | 196 /// reflected by [other]. |
215 * isolate being reflected by [other]. | |
216 */ | |
217 bool operator == (other); | 197 bool operator == (other); |
218 } | 198 } |
219 | 199 |
220 /** | 200 /** |
221 * A [DeclarationMirror] reflects some entity declared in a Dart program. | 201 * A [DeclarationMirror] reflects some entity declared in a Dart program. |
222 */ | 202 */ |
223 abstract class DeclarationMirror implements Mirror { | 203 abstract class DeclarationMirror implements Mirror { |
224 /** | 204 /// The simple name for this Dart language entity. |
225 * The simple name for this Dart language entity. | 205 /// |
226 * | 206 /// The simple name is in most cases the the identifier name of the entity, |
227 * The simple name is in most cases the the identifier name of the | 207 /// such as 'method' for a method, [:void method() {...}:] or 'mylibrary' for |
Lasse Reichstein Nielsen
2015/10/07 09:09:02
Confusing to use "method". Maybe change to "method
srawlins
2015/10/07 10:26:29
Done.
| |
228 * entity, such as 'method' for a method [:void method() {...}:] or | 208 /// a [:library 'mylibrary';:] declaration. |
229 * 'mylibrary' for a [:library 'mylibrary';:] declaration. | |
230 */ | |
231 Symbol get simpleName; | 209 Symbol get simpleName; |
232 | 210 |
233 /** | 211 /** |
234 * The fully-qualified name for this Dart language entity. | 212 * The fully-qualified name for this Dart language entity. |
235 * | 213 * |
236 * This name is qualified by the name of the owner. For instance, | 214 * This name is qualified by the name of the owner. For instance, |
237 * the qualified name of a method 'method' in class 'Class' in | 215 * the qualified name of a method 'method' in class 'Class' in |
238 * library 'library' is 'library.Class.method'. | 216 * library 'library' is 'library.Class.method'. |
239 * | 217 * |
240 * Returns a [Symbol] constructed from a string representing the | 218 * Returns a [Symbol] constructed from a string representing the |
241 * fully qualified name of the reflectee. | 219 * fully qualified name of the reflectee. |
242 * Let *o* be the [owner] of this mirror, let *r* be the reflectee of | 220 * Let *o* be the [owner] of this mirror, let *r* be the reflectee of |
243 * this mirror, let *p* be the fully qualified | 221 * this mirror, let *p* be the fully qualified |
244 * name of the reflectee of *o*, and let *s* be the simple name of *r* | 222 * name of the reflectee of *o*, and let *s* be the simple name of *r* |
245 * computed by [simpleName]. | 223 * computed by [simpleName]. |
246 * The fully qualified name of *r* is the | 224 * The fully qualified name of *r* is the |
247 * concatenation of *p*, '.', and *s*. | 225 * concatenation of *p*, '.', and *s*. |
248 * | 226 * |
249 * Because an isolate can contain more than one library with the same name (at | 227 * Because an isolate can contain more than one library with the same name (at |
250 * different URIs), a fully-qualified name does not uniquely identify any | 228 * different URIs), a fully-qualified name does not uniquely identify any |
251 * language entity. | 229 * language entity. |
252 */ | 230 */ |
253 Symbol get qualifiedName; | 231 Symbol get qualifiedName; |
254 | 232 |
255 /** | 233 /// A mirror on the owner of this Dart language entity. This is the |
Lasse Reichstein Nielsen
2015/10/07 09:09:02
Newlines before "This". And change "This" to "The
srawlins
2015/10/07 10:26:30
Done.
| |
256 * A mirror on the owner of this Dart language entity. This is the declaration | 234 /// declaration immediately surrounding the reflectee. |
Lasse Reichstein Nielsen
2015/10/07 09:09:02
Consider changing the final '.' to ':'.
srawlins
2015/10/07 10:26:29
Done.
| |
257 * immediately surrounding the reflectee. | 235 /// |
258 * | 236 /// * For a library, the owner is [:null:]. |
Lasse Reichstein Nielsen
2015/10/07 09:09:02
These should probably be list items, so add "* " i
srawlins
2015/10/07 10:26:29
Done.
| |
259 * For a library, the owner is [:null:]. | 237 /// * For a class declaration, typedef or top level function or variable, the |
260 * For a class declaration, typedef or top level function | 238 /// owner is the enclosing library. |
261 * or variable, the owner is the enclosing library. | 239 /// * For a mixin application *S with M*, the owner is the owner of *M*. |
Lasse Reichstein Nielsen
2015/10/07 09:09:03
*S with M* -> `S with M`
dittos below
srawlins
2015/10/07 10:26:30
Done.
| |
262 * For a mixin application *S with M*, the owner is the owner | 240 /// * For a constructor, the owner is the immediately enclosing class. |
263 * of *M*. | 241 /// * For a method, instance variable or a static variable, the owner is the |
264 * For a constructor, the owner is the immediately enclosing class. | 242 /// immediately enclosing class, unless the class is a mixin application |
265 * For a method, instance variable or | 243 /// *S with M*, in which case the owner is *M*. Note that *M* may be an |
266 * a static variable, the owner is the immediately enclosing class, | 244 /// invocation of a generic. |
267 * unless the class is a mixin application *S with M*, in which case | 245 /// * For a parameter, local variable or local function the owner is the |
268 * the owner is *M*. Note that *M* may be an invocation of a generic. | 246 /// immediately enclosing function. |
269 * For a parameter, local variable or local function the owner is the | |
270 * immediately enclosing function. | |
271 */ | |
272 DeclarationMirror get owner; | 247 DeclarationMirror get owner; |
273 | 248 |
274 /** | 249 /// Returns [:true:] if this declaration is considered private according to |
Lasse Reichstein Nielsen
2015/10/07 09:09:03
/// Whether this declaration is library private.
/
srawlins
2015/10/07 10:26:29
Done.
| |
275 * Returns [:true:] if this declaration is considered private | 250 /// the Dart language specification. |
276 * according to the Dart language specification. | 251 /// |
277 * Always returns [: false :] if this declaration | 252 /// Always returns [: false :] if this declaration is a library. Otherwise |
278 * is a library. | 253 /// return [:false:]. |
279 * Otherwise return [:false:]. | |
280 * | |
281 */ | |
282 bool get isPrivate; | 254 bool get isPrivate; |
283 | 255 |
284 /** | 256 /// Is this declaration top-level? |
Lasse Reichstein Nielsen
2015/10/07 09:09:02
/// Whether this declaration is top-level.
///
///
srawlins
2015/10/07 10:26:29
Done.
| |
285 * Is this declaration top-level? | 257 /// |
286 * | 258 /// This is defined to be equivalent to: |
287 * This is defined to be equivalent to: | 259 /// [:mirror.owner != null && mirror.owner is LibraryMirror:]. |
288 * [:mirror.owner != null && mirror.owner is LibraryMirror:] | |
289 */ | |
290 bool get isTopLevel; | 260 bool get isTopLevel; |
291 | 261 |
292 /** | 262 /// The source location of this Dart language entity, or [:null:] if the |
293 * The source location of this Dart language entity, or [:null:] if the | 263 /// entity is synthetic. |
294 * entity is synthetic. | 264 /// |
295 * | 265 /// If the reflectee is a variable, the returned location gives the position |
296 * If the reflectee is a variable, the returned location gives the position of * the variable name at its point of declaration. | 266 /// of the variable name at its point of declaration. |
297 * | 267 /// |
298 * If the reflectee is a library, class, typedef, function or type variable | 268 /// If the reflectee is a library, class, typedef, function or type variable |
299 * with associated metadata, the returned location gives the position of the | 269 /// with associated metadata, the returned location gives the position of the |
300 * first metadata declaration associated with the reflectee. | 270 /// first metadata declaration associated with the reflectee. |
301 * | 271 /// |
302 * Otherwise: | 272 /// Otherwise: |
303 * If the reflectee is a library, the returned location gives the position of | 273 /// |
304 * the keyword 'library' at the reflectee's point of declaration, if the | 274 /// If the reflectee is a library, the returned location gives the position of |
305 * reflectee is a named library, or the first character of the first line in | 275 /// the keyword 'library' at the reflectee's point of declaration, if the |
306 * the compilation unit defining the reflectee if the reflectee is anonymous. | 276 /// reflectee is a named library, or the first character of the first line in |
307 * | 277 /// the compilation unit defining the reflectee if the reflectee is anonymous. |
308 * If the reflectee is an abstract class, the returned location gives the | 278 /// |
309 * position of the keyword 'abstract' at the reflectee's point of declaration. * Otherwise, if the reflectee is a class, the returned location gives the | 279 /// If the reflectee is an abstract class, the returned location gives the |
310 * position of the keyword 'class' at the reflectee's point of declaration. | 280 /// position of the keyword 'abstract' at the reflectee's point of declaration . |
311 * | 281 /// Otherwise, if the reflectee is a class, the returned location gives the |
312 * If the reflectee is a typedef the returned location gives the position of | 282 /// position of the keyword 'class' at the reflectee's point of declaration. |
313 * the of the keyword 'typedef' at the reflectee's point of declaration. | 283 /// |
314 * | 284 /// If the reflectee is a typedef the returned location gives the position of |
315 * If the reflectee is a function with a declared return type, the returned | 285 /// the of the keyword 'typedef' at the reflectee's point of declaration. |
316 * location gives the position of the function's return type at the | 286 /// |
317 * reflectee's point of declaration. Otherwise. the returned location gives | 287 /// If the reflectee is a function with a declared return type, the returned |
318 * the position of the function's name at the reflectee's point of | 288 /// location gives the position of the function's return type at the |
319 * declaration. | 289 /// reflectee's point of declaration. Otherwise. the returned location gives |
320 * | 290 /// the position of the function's name at the reflectee's point of |
321 * This operation is optional and may throw an [UnsupportedError]. | 291 /// declaration. |
Lasse Reichstein Nielsen
2015/10/07 09:09:02
Interesting ... it does not include "static" or "e
srawlins
2015/10/07 10:26:29
Acknowledged.
| |
322 */ | 292 /// |
293 /// This operation is optional and may throw an [UnsupportedError]. | |
323 SourceLocation get location; | 294 SourceLocation get location; |
324 | 295 |
325 /** | 296 /** |
326 * A list of the metadata associated with this declaration. | 297 * A list of the metadata associated with this declaration. |
327 * | 298 * |
328 * Let *D* be the declaration this mirror reflects. | 299 * Let *D* be the declaration this mirror reflects. |
329 * If *D* is decorated with annotations *A1, ..., An* | 300 * If *D* is decorated with annotations *A1, ..., An* |
330 * where *n > 0*, then for each annotation *Ai* associated | 301 * where *n > 0*, then for each annotation *Ai* associated |
331 * with *D, 1 <= i <= n*, let *ci* be the constant object | 302 * with *D, 1 <= i <= n*, let *ci* be the constant object |
332 * specified by *Ai*. Then this method returns a list whose | 303 * specified by *Ai*. Then this method returns a list whose |
(...skipping 16 matching lines...) Expand all Loading... | |
349 * | 320 * |
350 * For the purposes of the mirrors library, these types are all | 321 * For the purposes of the mirrors library, these types are all |
351 * object-like, in that they support method invocation and field | 322 * object-like, in that they support method invocation and field |
352 * access. Real Dart objects are represented by the [InstanceMirror] | 323 * access. Real Dart objects are represented by the [InstanceMirror] |
353 * type. | 324 * type. |
354 * | 325 * |
355 * See [InstanceMirror], [ClassMirror], and [LibraryMirror]. | 326 * See [InstanceMirror], [ClassMirror], and [LibraryMirror]. |
356 */ | 327 */ |
357 abstract class ObjectMirror implements Mirror { | 328 abstract class ObjectMirror implements Mirror { |
358 | 329 |
359 /** | 330 /// Invokes the named function and returns a mirror on the result. |
360 * Invokes the named function and returns a mirror on the result. | 331 /// |
361 * | 332 /// Let *o* be the object reflected by this mirror, let *f* be the simple name |
362 * Let *o* be the object reflected by this mirror, let | 333 /// of the member denoted by [memberName], let *a1, ..., an* be the elements |
363 * *f* be the simple name of the member denoted by [memberName], | 334 /// of [positionalArguments], let *k1, ..., km* be the identifiers denoted by |
364 * let *a1, ..., an* be the elements of [positionalArguments] | 335 /// the elements of [namedArguments.keys], and let *v1, ..., vm* be the |
365 * let *k1, ..., km* be the identifiers denoted by the elements of | 336 /// elements of [namedArguments.values]. Then this method will perform the |
366 * [namedArguments.keys] | 337 /// method invocation *o.f(a1, ..., an, k1: v1, ..., km: vm)* in a scope that |
367 * and let *v1, ..., vm* be the elements of [namedArguments.values]. | 338 /// has access to the private members of *o* (if *o* is a class or library) or |
368 * Then this method will perform the method invocation | 339 /// the private members of the class of *o* (otherwise). |
Lasse Reichstein Nielsen
2015/10/07 09:09:03
Reflow reduces the readability/editability of the
srawlins
2015/10/07 10:26:29
This means it is equally not readable online:
htt
Lasse Reichstein Nielsen
2015/10/07 18:05:56
I think bulleted would be better, maybe reworded a
Lasse Reichstein Nielsen
2015/10/07 18:06:39
I prefer to make it readable in one case rather th
| |
369 * *o.f(a1, ..., an, k1: v1, ..., km: vm)* | 340 /// |
370 * in a scope that has access to the private members | 341 /// If the invocation returns a result *r*, this method returns the result of |
371 * of *o* (if *o* is a class or library) or the private members of the | 342 /// calling [reflect]\(*r*\). |
372 * class of *o* (otherwise). | 343 /// |
373 * If the invocation returns a result *r*, this method returns | 344 /// If the invocation causes a compilation error the effect is the same as if |
374 * the result of calling [reflect]\(*r*\). | 345 /// a non-reflective compilation error had been encountered. |
375 * If the invocation causes a compilation error | 346 /// |
376 * the effect is the same as if a non-reflective compilation error | 347 /// If the invocation throws an exception *e* (that it does not catch), this |
377 * had been encountered. | 348 /// method throws *e*. |
378 * If the invocation throws an exception *e* (that it does not catch) | |
379 * this method throws *e*. | |
380 */ | |
381 /* | 349 /* |
382 * TODO(turnidge): Handle ambiguous names. | 350 * TODO(turnidge): Handle ambiguous names. |
383 * TODO(turnidge): Handle optional & named arguments. | 351 * TODO(turnidge): Handle optional & named arguments. |
384 */ | 352 */ |
385 InstanceMirror invoke(Symbol memberName, | 353 InstanceMirror invoke(Symbol memberName, |
386 List positionalArguments, | 354 List positionalArguments, |
387 [Map<Symbol,dynamic> namedArguments]); | 355 [Map<Symbol,dynamic> namedArguments]); |
388 | 356 |
389 /** | 357 /// Invokes a getter and returns a mirror on the result. |
390 * Invokes a getter and returns a mirror on the result. The getter | 358 /// |
391 * can be the implicit getter for a field or a user-defined getter | 359 /// The getter can be the implicit getter for a field or a user-defined getter |
392 * method. | 360 /// method. |
393 * | 361 /// |
394 * Let *o* be the object reflected by this mirror, let | 362 /// Let *o* be the object reflected by this mirror, let *f* be the simple name |
Lasse Reichstein Nielsen
2015/10/07 09:09:03
*f* -> `f`
More below.
srawlins
2015/10/07 10:26:29
This *f* format is everywhere in this file. Maybe
| |
395 * *f* be the simple name of the getter denoted by [fieldName], | 363 /// of the getter denoted by [fieldName]. Then this method will perform the |
396 * Then this method will perform the getter invocation | 364 /// getter invocation *o.f* in a scope that has access to the private members |
397 * *o.f* | 365 /// of *o* (if *o* is a class or library) or the private members of the class |
398 * in a scope that has access to the private members | 366 /// of *o* (otherwise). |
399 * of *o* (if *o* is a class or library) or the private members of the | 367 /// |
400 * class of *o* (otherwise). | 368 /// If this mirror is an [InstanceMirror], and [fieldName] denotes an instance |
401 * | 369 /// method on its reflectee, the result of the invocation is an instance |
402 * If this mirror is an [InstanceMirror], and [fieldName] denotes an instance | 370 /// mirror on a closure corresponding to that method. |
403 * method on its reflectee, the result of the invocation is an instance | 371 /// |
404 * mirror on a closure corresponding to that method. | 372 /// If this mirror is a [LibraryMirror], and [fieldName] denotes a top-level |
405 * | 373 /// method in the corresponding library, the result of the invocation is an |
406 * If this mirror is a [LibraryMirror], and [fieldName] denotes a top-level | 374 /// instance mirror on a closure corresponding to that method. |
407 * method in the corresponding library, the result of the invocation is an | 375 /// |
408 * instance mirror on a closure corresponding to that method. | 376 /// If this mirror is a [ClassMirror], and [fieldName] denotes a static method |
409 * | 377 /// in the corresponding class, the result of the invocation is an instance |
410 * If this mirror is a [ClassMirror], and [fieldName] denotes a static method | 378 /// mirror on a closure corresponding to that method. |
411 * in the corresponding class, the result of the invocation is an instance | 379 /// |
412 * mirror on a closure corresponding to that method. | 380 /// If the invocation returns a result *r*, this method returns the result of |
413 * | 381 /// calling [reflect]\(*r*\). |
414 * If the invocation returns a result *r*, this method returns | 382 /// |
415 * the result of calling [reflect]\(*r*\). | 383 /// If the invocation causes a compilation error, the effect is the same as if |
416 * If the invocation causes a compilation error | 384 /// a non-reflective compilation error had been encountered. |
417 * the effect is the same as if a non-reflective compilation error | 385 /// |
418 * had been encountered. | 386 /// If the invocation throws an exception *e* (that it does not catch), this |
419 * If the invocation throws an exception *e* (that it does not catch) | 387 /// method throws *e*. |
420 * this method throws *e*. | |
421 */ | |
422 // TODO(ahe): Remove stuff about scope and private members. [fieldName] is a | 388 // TODO(ahe): Remove stuff about scope and private members. [fieldName] is a |
423 // capability giving access to private members. | 389 // capability giving access to private members. |
424 InstanceMirror getField(Symbol fieldName); | 390 InstanceMirror getField(Symbol fieldName); |
425 | 391 |
426 /** | 392 /// Invokes a setter and returns a mirror on the result. |
427 * Invokes a setter and returns a mirror on the result. The setter | 393 /// |
428 * may be either the implicit setter for a non-final field or a | 394 /// The setter may be either the implicit setter for a non-final field or a |
429 * user-defined setter method. | 395 /// user-defined setter method. |
430 * | 396 /// |
431 * Let *o* be the object reflected by this mirror, let | 397 /// Let *o* be the object reflected by this mirror, let *f* be the simple name |
432 * *f* be the simple name of the getter denoted by [fieldName], | 398 /// of the getter denoted by [fieldName], and let *a* be the object bound to |
433 * and let *a* be the object bound to [value]. | 399 /// [value]. Then this method will perform the setter invocation *o.f = a* in |
434 * Then this method will perform the setter invocation | 400 /// a scope that has access to the private members of *o* (if *o* is a class |
435 * *o.f = a* | 401 /// or library) or the private members of the class of *o* (otherwise). |
436 * in a scope that has access to the private members | 402 /// |
437 * of *o* (if *o* is a class or library) or the private members of the | 403 /// If the invocation returns a result *r*, this method returns the result of |
438 * class of *o* (otherwise). | 404 /// calling [reflect]\([value]\). |
439 * If the invocation returns a result *r*, this method returns | 405 /// |
440 * the result of calling [reflect]\([value]\). | 406 /// If the invocation causes a compilation error, the effect is the same as if |
441 * If the invocation causes a compilation error | 407 /// a non-reflective compilation error had been encountered. |
442 * the effect is the same as if a non-reflective compilation error | 408 /// |
443 * had been encountered. | 409 /// If the invocation throws an exception *e* (that it does not catch) this |
444 * If the invocation throws an exception *e* (that it does not catch) | 410 /// method throws *e*. |
445 * this method throws *e*. | |
446 */ | |
447 /* TODO(turnidge): Handle ambiguous names.*/ | 411 /* TODO(turnidge): Handle ambiguous names.*/ |
448 InstanceMirror setField(Symbol fieldName, Object value); | 412 InstanceMirror setField(Symbol fieldName, Object value); |
449 | 413 |
450 /** | 414 /// Perform [invocation] on [reflectee]. |
451 * Perform [invocation] on [reflectee]. | 415 /// |
452 * Equivalent to | 416 /// Equivalent to |
453 * | 417 /// |
454 * if (invocation.isGetter) { | 418 /// if (invocation.isGetter) { |
455 * return this.getField(invocation.memberName).reflectee; | 419 /// return this.getField(invocation.memberName).reflectee; |
456 * } else if (invocation.isSetter) { | 420 /// } else if (invocation.isSetter) { |
457 * return this.setField(invocation.memberName, | 421 /// return this.setField(invocation.memberName, |
458 * invocation.positionArguments[0]).reflectee; | 422 /// invocation.positionArguments[0]).reflectee; |
459 * } else { | 423 /// } else { |
460 * return this.invoke(invocation.memberName, | 424 /// return this.invoke(invocation.memberName, |
461 * invocation.positionalArguments, | 425 /// invocation.positionalArguments, |
462 * invocation.namedArguments).reflectee; | 426 /// invocation.namedArguments).reflectee; |
463 * } | 427 /// } |
464 */ | |
465 delegate(Invocation invocation); | 428 delegate(Invocation invocation); |
466 } | 429 } |
467 | 430 |
468 /** | 431 /** |
469 * An [InstanceMirror] reflects an instance of a Dart language object. | 432 * An [InstanceMirror] reflects an instance of a Dart language object. |
470 */ | 433 */ |
471 abstract class InstanceMirror implements ObjectMirror { | 434 abstract class InstanceMirror implements ObjectMirror { |
472 /** | 435 /** |
473 * A mirror on the type of the reflectee. | 436 * A mirror on the type of the reflectee. |
474 * | 437 * |
(...skipping 955 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
1430 final override; | 1393 final override; |
1431 | 1394 |
1432 /** | 1395 /** |
1433 * See the documentation for [MirrorsUsed.symbols], [MirrorsUsed.targets], | 1396 * See the documentation for [MirrorsUsed.symbols], [MirrorsUsed.targets], |
1434 * [MirrorsUsed.metaTargets] and [MirrorsUsed.override] for documentation | 1397 * [MirrorsUsed.metaTargets] and [MirrorsUsed.override] for documentation |
1435 * of the parameters. | 1398 * of the parameters. |
1436 */ | 1399 */ |
1437 const MirrorsUsed( | 1400 const MirrorsUsed( |
1438 {this.symbols, this.targets, this.metaTargets, this.override}); | 1401 {this.symbols, this.targets, this.metaTargets, this.override}); |
1439 } | 1402 } |
OLD | NEW |