A round of edits to make mirrors.dart more like our current working

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.
 
-// #library("mirrors");
-
 // The dart:mirrors library provides reflective access for Dart program.
 //
 // 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;
 //
 // ...the getter is named 'myField' and the setter is named
 // 'myField='.  This allows us to assign unique names to getters and
 // setters for the purposes of member lookup.
-//
-// TODO(turnidge): Finish implementing this api.
+
+// #library("mirrors");

[cshapiro, 2012/08/17 19:06:09]

Any reason this is still commented out?

[turnidge, 2012/08/17 19:44:10]

For now we can't have these #directives in code built into the vm.  I hope this
will change.

 
 /**
  * A [MirrorSystem] is the main interface used to reflect on a set of
  * associated libraries.
  *
  * At runtime each running isolate has a distinct [MirrorSystem].
  *
  * It is also possible to have a [MirrorSystem] which represents a set
  * of libraries which are not running -- perhaps at compile-time.  In
  * this case, all available reflective functionality would be
  * supported, but runtime functionality (such as invoking a function
  * or inspecting the contents of a variable) would fail dynamically.
  */
 interface MirrorSystem {
   /**
-   * A mirror on the root library of the mirror system.
-   */
-  final LibraryMirror rootLibrary;
-
-  /**
    * An immutable map from from library names to mirrors for all
    * libraries known to this mirror system.
-  */
-  Map<String, LibraryMirror> libraries();
+   */
+  final Map<String, LibraryMirror> libraries;
 
   /**
    * A mirror on the isolate associated with this [MirrorSystem].
    * This may be null if this mirror system is not running.
    */
-  IsolateMirror isolate;
+  final IsolateMirror isolate;
 
   /**
-   * Returns an [InstanceMirror] for some Dart language object.
-   *
-   * This only works if this mirror system is associated with the
-   * current running isolate.
+   * A mirror on the [:Dynamic:] type.
    */
-  InstanceMirror mirrorOf(Object reflectee);
+  final TypeMirror dynamicType;
+
+  /**
+   * A mirror on the [:void:] type.
+   */
+  final TypeMirror voidType;
 }
 
 /**
  * Returns a [MirrorSystem] for the current isolate.
  */
 MirrorSystem currentMirrorSystem() {
   return _Mirrors.currentMirrorSystem();
 }
 
 /**
  * Creates a [MirrorSystem] for the isolate which is listening on
  * the [SendPort].
  */
 Future<MirrorSystem> mirrorSystemOf(SendPort port) {
   return _Mirrors.mirrorSystemOf(port);
 }
 
 /**
+ * Returns an [InstanceMirror] for some Dart language object.
+ *
+ * This only works if this mirror system is associated with the
+ * current running isolate.
+ */
+InstanceMirror reflect(Object reflectee) {
+  return _Mirrors.reflect(reflectee);
+}
+
+/**
  * A [Mirror] reflects some Dart language entity.
  *
  * Every [Mirror] originates from some [MirrorSystem].
  */
-interface Mirror {
+interface Mirror extends Hashable {
   /**
-   * The originating [MirrorSystem] for this mirror.
+   * The [MirrorSystem] which contains this mirror.

[cshapiro, 2012/08/17 19:06:09]

that contains?

[turnidge, 2012/08/17 19:44:10]

Done.

    */
   final MirrorSystem mirrors;
 }
 
 /**
  * An [IsolateMirror] reflects an isolate.
  */
 interface IsolateMirror extends Mirror {
   /**
    * A unique name used to refer to an isolate in debugging messages.
    */
   final String debugName;
 
   /**
    * Does this mirror reflect the currently running isolate?
    */
   final bool isCurrent;
+
+  /**
+   * A mirror on the root library for this isolate.
+   */
+  final LibraryMirror rootLibrary;
 }
 
-
 /**
  * An [ObjectMirror] is a common superinterface of [InstanceMirror],
- * [InterfaceMirror], and [LibraryMirror] that represents their shared
+ * [ClassMirror], and [LibraryMirror] that represents their shared
  * functionality.
  *
  * For the purposes of the mirrors library, these types are all
  * object-like, in that they support method invocation and field
  * access.  Real Dart objects are represented by the [InstanceMirror]
  * type.
  *
- * See [InstanceMirror], [InterfaceMirror], and [LibraryMirror].
+ * See [InstanceMirror], [ClassMirror], and [LibraryMirror].
  */
 interface ObjectMirror extends Mirror {
   /**
    * Invokes the named function and returns a mirror on the result.
    *
    * TODO(turnidge): Properly document.
+   * TODO(turnidge): Handle ambiguous names.
+   * TODO(turnidge): Handle optional & named arguments.
    */
   Future<InstanceMirror> invoke(String memberName,
                                 List<Object> positionalArguments,
                                 [Map<String,Object> namedArguments]);
 
   /**
-   * Invokes a getter and returns a mirror on the result. The getter may be 
-   * either the implicit getter for a field or a user-defined getter method.
+   * Invokes a getter and returns a mirror on the result. The getter
+   * may be either the implicit getter for a field or a user-defined

[cshapiro, 2012/08/17 19:06:09]

can be the implicit...

[turnidge, 2012/08/17 19:44:10]

Done.

+   * getter method.
+   *
+   * TODO(turnidge): Handle ambiguous names.
    */
   Future<InstanceMirror> getField(String 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.
+   * 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.
+   *
+   * TODO(turnidge): Handle ambiguous names.
    */
   Future<InstanceMirror> setField(String fieldName, Object value);
 }
 
 /**
  * An [InstanceMirror] reflects an instance of a Dart language object.
  */
 interface InstanceMirror extends ObjectMirror {
   /**
-   * Returns a mirror on the class of the reflectee.
+   * A mirror on the type of the reflectee.
    */
-  InterfaceMirror getClass();
+  final ClassMirror type;
 
   /**
-   * Does [reflectee] contain the instance reflected by this mirror? This will
-   * always be true in the local case (reflecting instances in the same 
-   * isolate), but only true in the remote case if this mirror reflects a 
-   * simple value.
+   * Does [reflectee] contain the instance reflected by this mirror?
+   * This will always be true in the local case (reflecting instances
+   * in the same isolate), but only true in the remote case if this
+   * mirror reflects a simple value.

[cshapiro, 2012/08/17 19:06:09]

How about adding a top-level function called IsSimpleValue that returns true
when it is invoked with an object of one of the four simple types?

[turnidge, 2012/08/17 19:44:10]

Will do in a follow-up CL.

    *
    * A value is simple if one of the following holds:
    *  - the value is null
    *  - the value is of type [num]
    *  - the value is of type [bool]
    *  - the value is of type [String]
    */
   final bool hasReflectee;
 
   /**
-   * If the [InstanceMirror] reflects an instance it is meaningful to have a
-   * local reference to, we provide access to the actual instance here.
+   * If the [InstanceMirror] reflects an instance it is meaningful to
+   * have a local reference to, we provide access to the actual
+   * instance here.
    *
    * If you access [reflectee] when [hasReflectee] is false, an
    * exception is thrown.
    */
   final reflectee;
 }
 
 /**
- * A [ClosureMirror] reflects a closure. Closures are special, because we do not
- * wish to reflect the internals of a particular closure implementation. And
- * yet, we need access to details of the closure internals - for example, its
- * enclosing context and its source code.
+ * A [ClosureMirror] reflects a closure.
+ *
+ * A [ClosureMirror] provides access to it's captured variables and

[cshapiro, 2012/08/17 19:06:09]

its not it's.

[turnidge, 2012/08/17 19:44:10]

Done.

+ * provides the ability to execute it's reflectee.

[cshapiro, 2012/08/17 19:06:09]

its not it's.

[turnidge, 2012/08/17 19:44:10]

Done.  How embarrassing.

  */
 interface ClosureMirror extends InstanceMirror {
+  /**
+   * A mirror on the function for this closure.

[cshapiro, 2012/08/17 19:06:09]

of this closure

[turnidge, 2012/08/17 19:44:10]

Changed to "function associated with this closure".  "Function of" causes my
brain to misfire when I read it.

+   */
+  final MethodMirror function;
 
   /**
-   * Return the source code for the closure, if available.
-   */ 
-  String source();
-  
-  /**
-   * Call the closure. The arguments given in the descriptor need to be
-   * ObjectMirrors or values. Asynchronous.
-   */  
-  Future<ObjectMirror> apply(List<Object> positionalArguments,
-                             [Map<String,Object> namedArguments]); 
+   * The source code for this closure, if available.

[cshapiro, 2012/08/17 19:06:09]

And what if it's not available?  Null?

[turnidge, 2012/08/17 19:44:10]

Done.  This field will probably go away anyways, I think.

+   *
+   * TODO(turnidge): Would this just be available in function?
+   */
+  final String source;
 
   /**
-   * Look up the value of name in the scope of the closure. The result is a
-   * mirror on that value. Asynchronous.
+   * Executes the closure. The arguments given in the descriptor need to
+   * be InstanceMirrors or simple values.
+   *
+   * A value is simple if one of the following holds:
+   *  - the value is null
+   *  - the value is of type [num]
+   *  - the value is of type [bool]
+   *  - the value is of type [String]
    */
-  Future<ObjectMirror> findInContext(String name);
+  Future<InstanceMirror> apply(List<Object> positionalArguments,
+                               [Map<String,Object> namedArguments]);
 
   /**
-   * Return a mirror on the function of this closure.
+   * Looks up the value of a name in the scope of the closure. The
+   * result is a mirror on that value.
    */
-  MethodMirror function();
+  Future<InstanceMirror> findInContext(String name);
 }
 
 /**
  * A [TypeMirror] reflects a Dart language class, interface, typedef
  * or type variable.
  */
 interface TypeMirror extends Mirror {
   /**
    * The library in which this interface is declared.
    */
   final LibraryMirror library;
 }
 
 /**
- * An [InterfaceMirror] reflects a Dart language class or interface.
+ * A [ClassMirror] reflects a Dart language class or interface.
  */
-interface InterfaceMirror extends TypeMirror, ObjectMirror {
+interface ClassMirror extends TypeMirror, ObjectMirror {
   /**
    * The name of this interface.
    */
   final String simpleName;
 
   /**
    * Does this mirror represent a class?
    */
   final bool isClass;
 
   /**
    * Returns a mirror on the superclass on the reflectee.
    *
    * For interfaces, the superclass is Object.
    */
-  InterfaceMirror superclass();
+  final ClassMirror superclass;
 
   /**
    * Returns a list of mirrors on the superinterfaces for the reflectee.
    */
-  List<InterfaceMirror> superinterfaces();
+  final List<ClassMirror> superinterfaces;
 
   /**
    * Returns a mirror on the default factory class or null if there is
    * none.
    */
-  InterfaceMirror defaultFactory();
+  final ClassMirror defaultFactory;
 
   /**
    * An immutable map from from names to mirrors for all members of
    * this type.
    *
    * The members of an interface are its constructors, methods,
    * fields, getters, and setters.
    *
    * This does not include inherited members.
    */
-  Map<String, Mirror> members();
+  final Map<String, Mirror> members;
 
   /**
    * An immutable map from names to mirrors for all method,
    * constructor, getter, and setter declarations in this library.
    */
-  Map<String, MethodMirror> methods();
+  final Map<String, MethodMirror> methods;
 
   /**
    * An immutable map from names to mirrors for all variable
    * declarations in this library.
    */
-  Map<String, VariableMirror> variables();
+  final Map<String, VariableMirror> variables;
 
   /**
    * Invokes the named constructor and returns a mirror on the result.
    *
    * TODO(turnidge): Properly document.
    */
   Future<InstanceMirror> newInstance(String constructorName,
                                 List<Object> positionalArguments,
                                 [Map<String,Object> namedArguments]);
 }
@@ skipping 17 matching lines @@
    */
   final String url;
 
   /**
    * An immutable map from from names to mirrors for all members in
    * this library.
    *
    * The members of a library are its top-level classes, interfaces,
    * functions, variables, getters, and setters.
    */
-  Map<String, Mirror> members();
+  final Map<String, Mirror> members;
 
   /**
    * An immutable map from names to mirrors for all class and
    * interface declarations in this library.
    */
-  Map<String, InterfaceMirror> classes();
+  final Map<String, ClassMirror> classes;
 
   /**
    * An immutable map from names to mirrors for all function
    * declarations in this library.
    */
-  Map<String, MethodMirror> functions();
+  final Map<String, MethodMirror> functions;
 
   /**
    * An immutable map from names to mirrors for all variable
    * declarations in this library.
    */
-  Map<String, VariableMirror> variables();
+  final Map<String, VariableMirror> variables;
 }
 
 /**
  * A [MethodMirror] reflects a Dart language function, method,
  * constructor, getter, or setter.
  */
 interface MethodMirror {
   /**
    * The name of this function.
    */
   final String simpleName;
 
   /**
    * A mirror on the owner of this function.  This is the declaration
    * immediately surrounding the reflectee.
    *
    * For top-level functions, this will be a [LibraryMirror] and for
    * methods, constructors, getters, and setters, this will be an
-   * [InterfaceMirror].
+   * [ClassMirror].
    */
-  Mirror owner;
+  final Mirror owner;
 
   // Ownership
 
   /**
    * Does this mirror reflect a top-level function?
    */
-  bool isTopLevel;
+  final bool isTopLevel;
 
   /**
    * Does this mirror reflect a static method?
    *
    * For the purposes of the mirrors library, a top-level function is
    * considered static.
    */
-  bool isStatic;
+  final bool isStatic;
 
   // Method kind
 
   /**
    * Does this mirror reflect a regular function or method?
    *
    * A method is regular if it is not a getter, setter, or constructor.
    */
-  bool isMethod;
+  final bool isMethod;
 
   /**
    * Does this mirror reflect an abstract method?
    */
-  bool isAbstract;
+  final bool isAbstract;
 
   /**
    * Does this mirror reflect a getter?
    */
-  bool isGetter;
+  final bool isGetter;
 
   /**
    * Does this mirror reflect a setter?
    */
-  bool isSetter;
+  final bool isSetter;
 
   /**
    * Does this mirror reflect a constructor?
    */
-  bool isConstructor;
+  final bool isConstructor;
 
   // Constructor kind
 
   /**
    * Does this mirror reflect a const constructor?
    */
-  bool isConstConstructor;
+  final bool isConstConstructor;
 
   /**
    * Does this mirror reflect a generative constructor?
    */
-  bool isGenerativeConstructor;
+  final bool isGenerativeConstructor;
 
   /**
    * Does this mirror reflect a redirecting constructor?
    */
-  bool isRedirectingConstructor;
+  final bool isRedirectingConstructor;
 
   /**
    * Does this mirror reflect a factory constructor?
    */
-  bool isFactoryConstructor;
+  final bool isFactoryConstructor;
 
   /**
    * Returns the list of parameters for this method.
    */
   List<ParameterMirror> parameters();

[cshapiro, 2012/08/17 19:06:09]

This should be a final field (a getter).

[turnidge, 2012/08/17 19:44:10]

Done.

 }
 
 /**
  * A [ParameterMirror] reflects a Dart formal parameter declaration.
  */
 interface ParameterMirror extends VariableMirror {
   /**
    * Returns the type of this parameter.
    */
   TypeMirror type;

[cshapiro, 2012/08/17 19:06:09]

This should be final.

[turnidge, 2012/08/17 19:44:10]

Done.

 
   /**
    * Returns the default value for this parameter.
    */
   String defaultValue;

[cshapiro, 2012/08/17 19:06:09]

And this should be final too.

[turnidge, 2012/08/17 19:44:10]

Done.

 
   /**
    * Returns true if this parameter has a default value.
    */
-  bool hasDefaultValue;
+  final bool hasDefaultValue;
 
   /**
    * Returns true if this parameter is optional.
    */
-  bool isOptional;
+  final bool isOptional;
 }
 
 /**
  * A [VariableMirror] reflects a Dart language variable declaration.
  */
 interface VariableMirror {
   /**
    * The name of this variable
    */
   final String simpleName;
 
   /**
    * A mirror on the owner of this method.  The owner is the
    * declaration immediately surrounding the reflectee.
    *
    * For top-level variables, this will be a [LibraryMirror] and for
-   * class and interface variables, this will be an [InterfaceMirror].
+   * class and interface variables, this will be a [ClassMirror].
    */
-  Mirror owner;
+  final Mirror owner;
 
   /**
    * Does this mirror reflect a top-level variable?
    */
-  bool isTopLevel;
+  final bool isTopLevel;
 
   /**
    * Does this mirror reflect a static variable?
    *
    * For the purposes of the mirror library, top-level variables are
    * implicitly declared static.
    */
-  bool isStatic;
+  final bool isStatic;
 
   /**
    * Does this mirror reflect a final variable?
    */
-  bool isFinal;
+  final bool isFinal;
 }
 
 
 /**
  * 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:
  *
@@ skipping 64 matching lines @@
 
 /**
  * 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;
 }