Mirrors overhaul.

dart/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 53 matching lines @@
  * or inspecting the contents of a variable) would fail dynamically.
  */
 abstract class MirrorSystem {
   /**
    * Returns an immutable map from URIs to mirrors for all
    * libraries known to this mirror system.
    */
   Map<Uri, LibraryMirror> get libraries;
 
   /**
-   * Returns an iterable of all libraries in the mirror system whose library
-   * name is [libraryName].
+   * Returns the unique library named [libraryName] if it exists.
+   *
+   * If no unique library exists, an error is thrown.
    */
-  Iterable<LibraryMirror> findLibrary(Symbol libraryName) {
-    return libraries.values.where(
+  LibraryMirror findLibrary(Symbol libraryName) {
+    return libraries.values.singleWhere(
         (library) => library.simpleName == libraryName);
   }
 
   /**
    * A mirror on the isolate associated with this [MirrorSystem].
    * This may be null if this mirror system is not running.
    */
   IsolateMirror get isolate;
 
   /**
@@ skipping 33 matching lines @@
 /**
  * Returns a [MirrorSystem] for the current isolate.
  */
 external MirrorSystem currentMirrorSystem();
 
 /**
  * Reflects an instance.
  * Returns an [InstanceMirror] reflecting [reflectee].
  * If [reflectee] is a function or an instance of a class
  * that has a [:call:] method, the returned instance mirror
- * will be a [ClosureMirror].  
+ * will be a [ClosureMirror].
  *
  * Note that since one cannot obtain an object from
  * another isolate, this function can only be used to
  * obtain  mirrors on objects of the current isolate.
  */
 external InstanceMirror reflect(Object reflectee);
 
 /**
  * Reflects a class declaration.
  * Let *C* be the original class declaration of the class
@@ skipping 132 matching lines @@
   /**
    * Is this declaration top-level?
    *
    * This is defined to be equivalent to:
    *    [:mirror.owner != null && mirror.owner is LibraryMirror:]
    */
   bool get isTopLevel;
 
   /**
    * The source location of this Dart language entity.
+   *
+   * This operation is optional and may return [:null:].
    */
   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.
    *
-   * If evaluating any of *c1, ..., cn* would cause a 
+   * If evaluating any of *c1, ..., cn* would cause a
    * compilation error
-   * the effect is the same as if a non-reflective compilation error 
+   * the effect is the same as if a non-reflective compilation error
    * had been encountered.
    */
   List<InstanceMirror> get metadata;
 }
 
 /**
  * An [ObjectMirror] is a common superinterface of [InstanceMirror],
  * [ClassMirror], and [LibraryMirror] that represents their shared
  * functionality.
  *
@@ skipping 16 matching lines @@
    * [namedArguments.keys]
    * and let *v1, ..., vm* be the elements of [namedArguments.values].
    * Then this method will perform the method invocation
    *  *o.f(a1, ..., an, k1: v1, ..., km: vm)*
    * 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](*r*).
    * If the invocation causes a compilation error
-   * the effect is the same as if a non-reflective compilation error 
+   * the effect is the same as if a non-reflective compilation error
    * had been encountered.
    * If the invocation throws an exception *e* (that it does not catch)
    * this method throws *e*.
    */
   /*
    * TODO(turnidge): Handle ambiguous names.
    * TODO(turnidge): Handle optional & named arguments.
    */
   InstanceMirror invoke(Symbol memberName,
                         List positionalArguments,
@@ skipping 20 matching lines @@
    * method in the corresponding library, the result of the invocation is an
    * instance mirror on a closure corresponding to that method.
    *
    * If this mirror is a [ClassMirror], and [fieldName] denotes a static method
    * in the corresponding class, the result of the invocation is an instance
    * mirror on a closure corresponding to that method.
    *
    * If the invocation returns a result *r*, this method returns
    * the result of calling [reflect](*r*).
    * If the invocation causes a compilation error
-   * the effect is the same as if a non-reflective compilation error 
+   * the effect is the same as if a non-reflective compilation error
    * had been encountered.
    * If the invocation throws an exception *e* (that it does not catch)
    * this method throws *e*.
    */
-  /* TODO(turnidge): Handle ambiguous names.*/
+  // TODO(ahe): Remove stuff about scope and private members. [fieldName] is a
+  // capability giving access to private members.
   InstanceMirror getField(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.
    *
    * 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].
    * Then this method will perform the setter invocation
    * *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 causes a compilation error
-   * the effect is the same as if a non-reflective compilation error 
+   * the effect is the same as if a non-reflective compilation error
    * had been encountered.
    * If the invocation throws an exception *e* (that it does not catch)
    * this method throws *e*.
    */
   /* TODO(turnidge): Handle ambiguous names.*/
   InstanceMirror setField(Symbol fieldName, Object value);
 }
 
 /**
  * An [InstanceMirror] reflects an instance of a Dart language object.
@@ skipping 60 matching lines @@
 
 /**
  * A [ClosureMirror] reflects a closure.
  *
  * A [ClosureMirror] provides access to its captured variables and
  * provides the ability to execute its reflectee.
  */
 abstract class ClosureMirror implements InstanceMirror {
   /**
    * A mirror on the function associated with this closure.
+   *
+   * The function associated with an implicit closure of a function is that
+   * function.
+   *
+   * The function associated with an instance of a class that has a [:call:]
+   * method is that [:call:] method.
    */
   MethodMirror get function;
 
   /**
    * 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].
@@ skipping 34 matching lines @@
  * library.
  */
 abstract class LibraryMirror implements DeclarationMirror, ObjectMirror {
   /**
    * The absolute uri of the library.
    */
   Uri get uri;
 
   /**
    * Returns an immutable map of the declarations actually given in the library.
-   * 
+   *
    * This map includes all regular methods, getters, setters, fields, classes
    * and typedefs actually declared in the library. The map is keyed by the
    * simple names of the declarations.
    */
   Map<Symbol, DeclarationMirror> get declarations;
 
   /**
-   * An immutable map from from names to mirrors for all members in
-   * this library.
-   *
-   * The members of a library are its top-level classes,
-   * functions, variables, getters, and setters.
-   */
-  Map<Symbol, Mirror> get members;
-
-  /**
-   * An immutable map from names to mirrors for all class
-   * declarations in this library.
-   */
-  Map<Symbol, ClassMirror> get classes;
-
-  /**
-   * An immutable map from names to mirrors for all type
-   * declarations in this library.
-   */
-  Map<Symbol, TypeMirror> get types;
-
-  /**
-   * An immutable map from names to mirrors for all function, getter,
-   * and setter declarations in this library.
-   */
-  Map<Symbol, MethodMirror> get functions;
-
-  /**
-   * An immutable map from names to mirrors for all getter
-   * declarations in this library.
-   */
-  Map<Symbol, MethodMirror> get getters;
-
-  /**
-   * An immutable map from names to mirrors for all setter
-   * declarations in this library.
-   */
-  Map<Symbol, MethodMirror> get setters;
-
-  /**
-   * An immutable map from names to mirrors for all variable
-   * declarations in this library.
-   */
-  Map<Symbol, VariableMirror> get variables;
-
-  /**
    * Returns [:true:] if this mirror is equal to [other].
    * Otherwise returns [:false:].
    *
    * The equality holds if and only if
    * (1) [other] is a mirror of the same kind
    * and
    * (2)  The library being reflected by this mirror
    * and the library being reflected by [other]
    * are
    * the same library in the same isolate.
@@ skipping 77 matching lines @@
    *
    * If this type is [:Object:], the superclass will be null.
    */
   ClassMirror get superclass;
 
   /**
    * A list of mirrors on the superinterfaces of the reflectee.
    */
   List<ClassMirror> get superinterfaces;
 
-  /** 
+  /**
    * Returns an immutable map of the declarations actually given in the class
    * declaration.
    *
    * This map includes all regular methods, getters, setters, fields,
    * constructors and type variables actually declared in the class. Both
    * static and instance members are included, but no inherited members are
    * included. The map is keyed by the simple names of the declarations.
+   *
+   * This does not include inherited members.
    */
   Map<Symbol, DeclarationMirror> get declarations;
 
   /**
    * The mixin of this class.
    * If this class is the result of a mixin application of the
    * form S with M, returns a class mirror on M.
    * Otherwise returns a class mirror on [reflectee].
    */
   ClassMirror get mixin;
 
-  /**
-   * An immutable map from names to mirrors for all members of
-   * this type.
-   *
-   * The members of a type are its methods, fields, getters, and
-   * setters.  Note that constructors and type variables are not
-   * considered to be members of a type.
-   *
-   * This does not include inherited members.
-   */
-  Map<Symbol, Mirror> get members;
-
-  /**
-   * An immutable map from names to mirrors for all method,
-   * declarations for this type.  This does not include getters and
-   * setters.
-   */
-  Map<Symbol, MethodMirror> get methods;
-
-  /**
-   * An immutable map from names to mirrors for all getter
-   * declarations for this type.
-   */
-  Map<Symbol, MethodMirror> get getters;
-
-  /**
-   * An immutable map from names to mirrors for all setter
-   * declarations for this type.
-   */
-  Map<Symbol, MethodMirror> get setters;
-
-  /**
-   * An immutable map from names to mirrors for all variable
-   * declarations for this type.
-   */
-  Map<Symbol, VariableMirror> get variables;
-
-  /**
-   * An immutable map from names to mirrors for all constructor
-   * declarations for this type.
-   */
-  Map<Symbol, MethodMirror> get constructors;
+  // TODO(ahe): What about:
+  // /// Finds the instance member named [name] declared or inherited in the
+  // /// reflected class.
+  // DeclarationMirror instanceLookup(Symbol name);
 
    /**
    * Invokes the named constructor and returns a mirror on the result.
    *
    * Let *c* be the class 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].
    * If [constructorName] was created from the empty string
    * Then this method will execute the instance creation expression
    * *new c(a1, ..., an, k1: v1, ..., km: vm)*
    * in a scope that has access to the private members
    * of *c*. Otherwise, let
    * *f* be the simple name of the constructor denoted by [constructorName]
    * Then this method will execute the instance creation expression
    *  *new c.f(a1, ..., an, k1: v1, ..., km: vm)*
    * in a scope that has access to the private members
    * of *c*.
    * In either case:
    * If the expression evaluates to a result *r*, this method returns
    * the result of calling [reflect](*r*).
    * If evaluating the expression causes a compilation error
-   * the effect is the same as if a non-reflective compilation error 
+   * the effect is the same as if a non-reflective compilation error
    * had been encountered.
    * If evaluating the expression throws an exception *e*
    * (that it does not catch)
    * this method throws *e*.
    */
   InstanceMirror newInstance(Symbol constructorName,
                              List positionalArguments,
                              [Map<Symbol,dynamic> namedArguments]);
 
   /**
@@ skipping 251 matching lines @@
   InstanceMirror get defaultValue;
 }
 
 /**
  * A [SourceLocation] describes the span of an entity in Dart source code.
  */
 abstract class SourceLocation {
 }
 
 /**
- * When an error occurs during the mirrored execution of code, a
- * [MirroredError] is thrown.
- *
- * In general, there are three main classes of failure that can happen
- * during mirrored execution of code in some isolate:
- *
- * - An exception is thrown but not caught.  This is caught by the
- *   mirrors framework and a [MirroredUncaughtExceptionError] is
- *   created and thrown.
- *
- * - A compile-time error occurs, such as a syntax error.  This is
- *   suppressed by the mirrors framework and a
- *   [MirroredCompilationError] is created and thrown.
- *
- * - A truly fatal error occurs, causing the isolate to be exited.  If
- *   the reflector and reflectee share the same isolate, then they
- *   will both suffer.  If the reflector and reflectee are in distinct
- *   isolates, then we hope to provide some information about the
- *   isolate death, but this has yet to be implemented.
- *
- * TODO(turnidge): Specify the behavior for remote fatal errors.
- */
-abstract class MirroredError implements Exception {
-}
-
-/**
- * When an uncaught exception occurs during the mirrored execution
- * of code, a [MirroredUncaughtExceptionError] is thrown.
- *
- * This exception contains a mirror on the original exception object.
- * It also contains an object which can be used to recover the
- * stacktrace.
- */
-class MirroredUncaughtExceptionError extends MirroredError {
-  MirroredUncaughtExceptionError(this.exception_mirror,
-                                 this.exception_string,
-                                 this.stacktrace) {}
-
-  /** A mirror on the exception object. */
-  final InstanceMirror exception_mirror;
-
-  /** The result of toString() for the exception object. */
-  final String exception_string;
-
-  /** A stacktrace object for the uncaught exception. */
-  final Object stacktrace;
-
-  String toString() {
-    return
-        "Uncaught exception during mirrored execution: <${exception_string}>";
-  }
-}
-
-/**
- * When a compile-time error occurs during the mirrored execution
- * of code, a [MirroredCompilationError] is thrown.
- *
- * This exception includes the compile-time error message that would
- * have been displayed to the user, if the function had not been
- * invoked via mirror.
- */
-class MirroredCompilationError extends MirroredError {
-  MirroredCompilationError(this.message) {}
-
-  final String message;
-
-  String toString() {
-    return "Compile-time error during mirrored execution: <$message>";
-  }
-}
-
-/**
- * A [MirrorException] is used to indicate errors within the mirrors
- * framework.
- */
-class MirrorException implements Exception {
-  const MirrorException(String this._message);
-  String toString() => "MirrorException: '$_message'";
-  final String _message;
-}
-
-/**
  * Class used for encoding comments as metadata annotations.
  */
 class Comment {
   /**
    * The comment text as written in the source text.
    */
   final String text;
 
   /**
    * The comment text without the start, end, and padding text.
@@ skipping 105 matching lines @@
    *
    * When used as metadata on an import of "dart:mirrors", this metadata does
    * not apply to the library in which the annotation is used, but instead
    * applies to the other libraries (all libraries if "*" is used).
    */
   final override;
 
   const MirrorsUsed(
       {this.symbols, this.targets, this.metaTargets, this.override});
 }