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

lib/mirrors/mirrors.dart

Index: lib/mirrors/mirrors.dart
===================================================================
--- lib/mirrors/mirrors.dart	(revision 10864)
+++ lib/mirrors/mirrors.dart	(working copy)
@@ -2,8 +2,6 @@
 // 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
@@ -15,9 +13,9 @@
 // ...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.
@@ -32,29 +30,26 @@
  */
 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;
 }
 
 /**
@@ -73,13 +68,23 @@
 }
 
 /**
+ * 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;
 }
@@ -97,12 +102,16 @@
    * 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
@@ -110,28 +119,35 @@
  * 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);
 }
@@ -141,15 +157,15 @@
  */
 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
@@ -160,8 +176,9 @@
   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.
@@ -170,35 +187,42 @@
 }
 
 /**
- * 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);
 }
 
 /**
@@ -213,9 +237,9 @@
 }
 
 /**
- * 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.
    */
@@ -231,18 +255,18 @@
    *
    * 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
@@ -253,19 +277,19 @@
    *
    * 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.
@@ -303,25 +327,25 @@
    * 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;
 }
 
 /**
@@ -340,16 +364,16 @@
    *
    * 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?
@@ -357,7 +381,7 @@
    * For the purposes of the mirrors library, a top-level function is
    * considered static.
    */
-  bool isStatic;
+  final bool isStatic;
 
   // Method kind
 
@@ -366,49 +390,49 @@
    *
    * 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.
@@ -433,12 +457,12 @@
   /**
    * 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;
 }
 
 /**
@@ -455,14 +479,14 @@
    * 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?
@@ -470,12 +494,12 @@
    * 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;
 }