Changes to mirrors in support of metadata access at runtime. Assumes VM changes in flight.…

sdk/lib/mirrors/mirrors.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 // For the purposes of the mirrors library, we adopt a naming
 // convention with respect to getters and setters.  Specifically, for
 // some variable or field...
 //
 //   var myField;
 //
@@ skipping 94 matching lines @@
 
 /**
  * Creates a [MirrorSystem] for the isolate which is listening on
  * the [SendPort].
  */
 external Future<MirrorSystem> mirrorSystemOf(SendPort port);
 
 /**
  * Returns an [InstanceMirror] for some Dart language object.
  *
- * This only works if this mirror system is associated with the
- * current running isolate.
+ * This only works with objects local to the current isolate.
  */
 external InstanceMirror reflect(Object reflectee);
 
 /**
  * Returns a [ClassMirror] for the class represented by a Dart
  * Type object.
  *
  * This only works with objects local to the current isolate.
  */
 external ClassMirror reflectClass(Type key);
@@ skipping 91 matching lines @@
    */
   bool get isTopLevel;
 
   /**
    * The source location of this Dart language entity.
    */
   SourceLocation get location;
 
   /**
    * A list of the metadata associated with this declaration.
+   *
+   * Let *D* be the declaration this mirror reflects.
+   * If *D* is decorated with annotations *A1, ..., An*
+   * where *n > 0*, then for each annotation *Ai* associated 
+   * with *D, 1 <= i <= n*, let *ci* be the constant object 
+   * specified by *Ai*. Then this method returns a list whose 
+   * members are instance mirrors on *c1, ..., cn*.
+   * If no annotations are associated with *D*, then 
+   * an empty list is returned.
    */
   List<InstanceMirror> get metadata;
 }
 
 /**
  * An [ObjectMirror] is a common superinterface of [InstanceMirror],
  * [ClassMirror], and [LibraryMirror] that represents their shared
  * functionality.
  *
  * For the purposes of the mirrors library, these types are all
@@ skipping 64 matching lines @@
    * *o.f = a*
    * in a scope that has access to the private members
    * of *o* (if *o* is a class or library) or the private members of the
    * class of *o* (otherwise).
    * If the invocation returns a result *r*, this method returns
    * the result of calling [reflect]([value]).
    * If the invocation throws an exception *e* (that it does not catch)
    * the the result is a [MirrorError] wrapping *e*.
    */
   /* TODO(turnidge): Handle ambiguous names.*/
-  InstanceMirror setField(Symbol fieldName, Object arg);
+  InstanceMirror setField(Symbol fieldName, Object value);
 
   /**
    * Invokes the named function and returns a mirror on the result.
    * The arguments must be instances of [InstanceMirror], or of
    * a type that is serializable across isolates (currently [num],
    * [String], or [bool]).
    *
    * Let *o* be the object reflected by this mirror, let
    * *f* be the simple name of the member denoted by [memberName],
    * let *a1, ..., an* be the elements of [positionalArguments]
@@ skipping 15 matching lines @@
    * If the invocation returns a result *r*, *k* will be completed
    * with the result of calling [reflect](*r*).
    * If the invocation throws an exception *e* (that it does not catch)
    * then *k* is completed with a [MirrorError] wrapping *e*.
    */
   /*
    * TODO(turnidge): Handle ambiguous names.
    * TODO(turnidge): Handle optional & named arguments.
    */
   Future<InstanceMirror> invokeAsync(Symbol memberName,
-                                     List<Object> positionalArguments,
-                                     [Map<Symbol, Object> namedArguments]);
+                                     List positionalArguments,
+                                     [Map<Symbol, dynamic> namedArguments]);
 
   /**
    * Invokes a getter and returns a mirror on the result. The getter
    * can be the implicit getter for a field or a user-defined getter
    * method.
    *
    * Let *o* be the object reflected by this mirror, let
    * *f* be the simple name of the getter denoted by [fieldName],
    * Then this method will perform the getter invocation
    *  *o.f*
    * in a scope that has access to the private members
    * of *o* (if *o* is a class or library) or the private members of the
    * class of *o*(otherwise).
    * The method returns a future *k*.
    * If the invocation returns a result *r*, *k* will be completed
    * with the result of calling [reflect](*r*).
    * If the invocation throws an exception *e* (that it does not catch)
    * then *k* is completed with a [MirrorError] wrapping *e*.
    */
   /* TODO(turnidge): Handle ambiguous names.*/
   Future<InstanceMirror> getFieldAsync(Symbol fieldName);
 
   /**
    * Invokes a setter and returns a mirror on the result. The setter
    * may be either the implicit setter for a non-final field or a
    * user-defined setter method.
-   * The argument must be an instance of [InstanceMirror], or of
+   * The second argument must be an instance of [InstanceMirror], or of
    * a type that is serializable across isolates (currently [num],
    * [String], or [bool]).
    *
    * Let *o* be the object reflected by this mirror, let
    * *f* be the simple name of the getter denoted by [fieldName],
    * and let a be the object bound to [value]. If *a* is an instance of
    * [InstanceMirror]  let *p* be the object
    * reflected by *a*, otherwise let *p =a*.
    * If *p* is not an instance of [InstanceMirror], *p* must be
    * serializable across isolates or an exception is thrown.
@@ skipping 87 matching lines @@
    * let *k1, ..., km* be the identifiers denoted by the elements of
    * [namedArguments.keys]
    * and let *v1, ..., vm* be the elements of [namedArguments.values].
    * Then this method will perform the method invocation
    *  *f(a1, ..., an, k1: v1, ..., km: vm)*
    * If the invocation returns a result *r*, this method returns
    * the result of calling [reflect](*r*).
    * If the invocation throws an exception *e* (that it does not catch)
    * the the result is a [MirrorError] wrapping *e*.
    */
-  InstanceMirror apply(List<Object> positionalArguments,
-                       [Map<Symbol,Object> namedArguments]);
+  InstanceMirror apply(List positionalArguments,
+                       [Map<Symbol, dynamic> namedArguments]);
 
   /**
    * Executes the closure and returns a mirror on the result.
    *
    * Let *f* be the closure reflected by this mirror,
    * let *a1, ..., an* be the elements of [positionalArguments]
    * let *k1, ..., km* be the identifiers denoted by the elements of
    * [namedArguments.keys]
    * and let *v1, ..., vm* be the elements of [namedArguments.values].
    * For each *ai*, if *ai* is an instance of [InstanceMirror], let *pi*
    * be the object reflected by *ai*; otherwise let *pi = ai,  i in 1 ...n*.
    * Likewise, for each *vj*, if *vj* is an instance of [InstanceMirror], let
    * *qj*
    * be the object reflected by *vj*; otherwise let *qj = vj,  j in 1 ...m*.
    * If any of the *pi, qj* is not an instance of [InstanceMirror] and
    * is not serializable across isolates, an exception is thrown.
    * Then this method will perform the function invocation
    *  *f(p1, ..., pn, k1: q1, ..., km: qm)*
    * The method returns a future *k*.
    * If the invocation returns a result *r*, *k* will be completed
    * with the result of calling [reflect](*r*).
    * If the invocation throws an exception *e* (that it does not catch)
    * then *k* is completed with a [MirrorError] wrapping *e*.
    *
    * The arguments must be instances of [InstanceMirror], or of
    * a type that is serializable across isolates (currently [num],
    * [String], or [bool]).
    */
-  Future<InstanceMirror> applyAsync(List<Object> positionalArguments,
-                                    [Map<Symbol, Object> namedArguments]);
+  Future<InstanceMirror> applyAsync(List positionalArguments,
+                                    [Map<Symbol, dynamic> namedArguments]);
 
   /**
    * Looks up the value of a name in the scope of the closure. The
    * result is a mirror on that value.
    *
    * Let *s* be the contents of the string used to construct the symbol [name].
    *
    * If the expression *s* occurs within the source code of the reflectee,
    * and that any such occurrence refers to a declaration outside the reflectee,
    * then let *v* be the result of evaluating the expression *s* at such
@@ skipping 221 matching lines @@
    * in a scope that has access to the private members
    * of *c*.
    * In either case:
    * The method returns a future *k*.
    * If the invocation returns a result *r*, *k* will be completed
    * with the result of calling [reflect](*r*).
    * If the invocation throws an exception *e* (that it does not catch)
    * then *k* is completed with a [MirrorError] wrapping *e*.
 */
   Future<InstanceMirror> newInstanceAsync(Symbol constructorName,
-                                          List<Object> positionalArguments,
-                                          [Map<Symbol, Object> namedArguments]);
+                                          List positionalArguments,
+                                          [Map<Symbol, dynamic> namedArguments]);
 
   /**
    * Does this mirror represent a class?
    *
    * TODO(turnidge): This functions goes away after the
    * class/interface changes.
    */
   bool get isClass;
 
   /**
@@ skipping 302 matching lines @@
   /**
    * Is [:true:] if this comment is a documentation comment.
    *
    * That is, that the comment is either enclosed in [: /** ... */ :] or starts
    * with [: /// :].
    */
   final bool isDocComment;
 
   const Comment(this.text, this.trimmedText, this.isDocComment);
 }