More mirrors changes to bring vm mirrors more in line with the

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.
 
 // 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...
 //
@@ skipping 92 matching lines @@
    */
   final bool isCurrent;
 
   /**
    * A mirror on the root library for this isolate.
    */
   final LibraryMirror rootLibrary;
 }
 
 /**
+ * A [DeclarationMirror] reflects some entity declared in a Dart program.
+ */
+interface DeclarationMirror extends Mirror {
+  /**
+   * The simple name for this Dart language entity.
+   *
+   * The simple name is in most cases the the identifier name of the
+   * entity, such as 'method' for a method [:void method() {...}:] or
+   * 'mylibrary' for a [:#library('mylibrary');:] declaration.
+   */
+  final String simpleName;
+
+  /**
+   * The fully-qualified name for this Dart language entity.
+   *
+   * This name is qualified by the name of the owner. For instance,
+   * the qualified name of a method 'method' in class 'Class' in
+   * library 'library' is 'library.Class.method'.
+   *
+   * TODO(turnidge): Specify whether this name is unique.  Currently
+   * this is a gray area due to lack of clarity over whether library
+   * names are unique.
+   */
+  final String qualifiedName;
+
+  /**
+   * A mirror on the owner of this function.  This is the declaration
+   * immediately surrounding the reflectee.
+   *
+   * Note that for libraries, the owner will be [:null:].
+   */
+  final DeclarationMirror owner;
+
+  /**
+   * Is this declaration private?
+   *
+   * Note that for libraries, this will be [:false:].
+   */
+  final bool isPrivate;
+
+  /**
+   * Is this declaration top-level?
+   *
+   * This is defined to be equivalent to:
+   *    [:mirror.owner !== null && mirror.owner is LibraryMirror:]
+   */
+  final bool isTopLevel;
+
+  /**
+   * The source location of this Dart language entity.
+   */
+  final SourceLocation location;
+}
+
+/**
  * 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
  * object-like, in that they support method invocation and field
  * access.  Real Dart objects are represented by the [InstanceMirror]
  * type.
  *
  * See [InstanceMirror], [ClassMirror], and [LibraryMirror].
@@ skipping 100 matching lines @@
    * result is a mirror on that value.
    */
   Future<InstanceMirror> findInContext(String name);
 }
 
 /**
  * A [LibraryMirror] reflects a Dart language library, providing
  * access to the variables, functions, classes, and interfaces of the
  * library.
  */
-interface LibraryMirror extends ObjectMirror {
-  /**
-   * The name of this library, as provided in the [#library] declaration.
-   */
-  final String simpleName;
-
+interface LibraryMirror extends DeclarationMirror, ObjectMirror {
   /**
    * The url of the library.
    *
    * TODO(turnidge): Document where this url comes from.  Will this
    * value be sensible?
    */
   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.
    */
   final Map<String, Mirror> members;
 
   /**
    * An immutable map from names to mirrors for all class and
    * interface declarations in this library.
    */
   final Map<String, ClassMirror> classes;
 
   /**
-   * An immutable map from names to mirrors for all function
+   * An immutable map from names to mirrors for all function, getter,
+   * and setter declarations in this library.
+   */
+  final Map<String, MethodMirror> functions;
+
+  /**
+   * An immutable map from names to mirrors for all getter
    * declarations in this library.
    */
-  final Map<String, MethodMirror> functions;
+  final Map<String, MethodMirror> getters;
+
+  /**
+   * An immutable map from names to mirrors for all setter

[cshapiro, 2012/08/21 03:16:05]

could call this (and above) mapping to get rid of implementation details your
call.

[turnidge, 2012/08/21 18:00:49]

Since the type is listed below, I'm not sure if the distinction between map and
mapping is important to me here.

+   * declarations in this library.
+   */
+  final Map<String, MethodMirror> setters;
 
   /**
    * An immutable map from names to mirrors for all variable
    * declarations in this library.
    */
   final Map<String, VariableMirror> variables;
 }
 
 /**
  * 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;
+interface TypeMirror extends DeclarationMirror {
 }
 
 /**
  * A [ClassMirror] reflects a Dart language class or interface.
  */
 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.
+   * A mirror on the superclass on the reflectee.
    *
-   * For interfaces, the superclass is Object.
+   * If this type is [:Object:] or a typedef, the superClass will be
+   * null.  For interfaces, the superclass is Object.
    */
   final ClassMirror superclass;
 
   /**
-   * Returns a list of mirrors on the superinterfaces for the reflectee.
+   * A list of mirrors on the superinterfaces of the reflectee.
    */
   final List<ClassMirror> superinterfaces;
 
   /**
-   * Returns a mirror on the default factory class or null if there is
-   * none.
-   */
-  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.
    */
   final Map<String, Mirror> members;
 
   /**
    * An immutable map from names to mirrors for all method,
-   * constructor, getter, and setter declarations in this library.
+   * constructor, getter, and setter declarations for this type.
    */
   final Map<String, MethodMirror> methods;
 
   /**
+   * An immutable map from names to mirrors for all constructor
+   * declarations for this type.
+   */
+  final Map<String, MethodMirror> constructors;
+
+  /**
+   * An immutable map from names to mirrors for all getter
+   * declarations for this type.
+   */
+  final Map<String, MethodMirror> getters;
+
+  /**
+   * An immutable map from names to mirrors for all setter
+   * declarations for this type.
+   */
+  final Map<String, MethodMirror> setters;
+
+  /**
    * An immutable map from names to mirrors for all variable
-   * declarations in this library.
+   * declarations for this type.
    */
   final Map<String, VariableMirror> variables;
 
   /**
+   * A list of type variables for this type.
+   */
+  final List<TypeVariableMirror> typeVariables;
+
+  /**
+   * A list of the type arguments for this type.
+   */
+  final List<TypeMirror> typeArguments;
+
+  /**
+   * Are the generic type variables for this type unbound?
+   */
+  final bool isUnboundType;

[cshapiro, 2012/08/21 03:16:05]

isGenericDeclaration

or

isDefinition

[turnidge, 2012/08/21 18:00:49]

Choosing isGenericDeclaration for now.

+
+  /**
+   * A mirror on this type but with unbound type variables.
+   *
+   * This allows us to go from a particular parametrization of a type
+   * to its generic declaration.
+   *
+   * TODO(turnidge): Is a non-generic class its own unboundType?
+   */
+  final ClassMirror unboundType;

[cshapiro, 2012/08/21 03:16:05]

The verbiage in the comments seems better than the variable name.  We have
talked about

genericDeclaration

and

definition

for this particular member.

[turnidge, 2012/08/21 18:00:49]

I'm changing it to genericDeclaration for now.

+
+  /**
    * 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]);
+                                     List<Object> positionalArguments,
+                                     [Map<String,Object> namedArguments]);
+
+  /**
+   * Does this mirror represent a class?
+   *
+   * TODO(turnidge): This functions goes away after the
+   * class/interface changes.
+   */
+  final bool isClass;
+
+  /**
+   * A mirror on the default factory class or null if there is none.
+   *
+   * TODO(turnidge): This functions goes away after the
+   * class/interface changes.
+   */
+  final ClassMirror defaultFactory;
+}
+
+/**
+ * A [TypeVariableMirror] represents a type parameter of a generic
+ * type.
+ */
+interface TypeVariableMirror extends TypeMirror {
+  /**
+   * The bound of the reflectee.

[cshapiro, 2012/08/21 03:16:05]

I am not sure what this means from the comment.  It seems ambiguous.

[turnidge, 2012/08/21 18:00:49]

Changed to upperBound and improved comment.

+   */
+  final TypeMirror bound;
+}
+
+/**
+ * A [FunctionTypeMirror] represents the type of a function in the
+ * Dart language.
+ */
+interface FunctionTypeMirror extends TypeMirror {
+  /**
+   * The return type of the reflectee.
+   */
+  final TypeMirror returnType;
+
+  /**
+   * A list of the parameter types of the reflectee.
+   */
+  final List<ParameterMirror> parameters;
+
+  /**
+   * A mirror on the [:call:] method for the reflectee.
+   *
+   * TODO(turnidge): What is this and what is it for?
+   */
+  final MethodMirror callMethod;
+}
+
+/**
+ * A [TypedefMirror] represents a typedef in a Dart language program.
+ */
+interface TypedefMirror extends ClassMirror {
+  /**
+   * The defining type for this typedef.
+   *
+   * For instance [:void f(int):] is the value for [:typedef void f(int):].
+   */
+  final TypeMirror value;
 }
 
 /**
  * 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
-   * [ClassMirror].
-   */
-  final Mirror owner;
-
-  /**
-   * Returns the list of parameters for this method.
+interface MethodMirror extends DeclarationMirror {
+  /**
+   * A mirror on the return type for the reflectee.
+   */
+  final TypeMirror returnType;
+
+  /**
+   * A list of mirrors on the parameters for the reflectee.
    */
   final List<ParameterMirror> parameters;
 
-  // Ownership
-
-  /**
-   * Does this mirror reflect a top-level function?
-   */
-  final bool isTopLevel;
-
-  /**
-   * Does this mirror reflect a static method?
+  /**
+   * Is the reflectee static?
    *
    * For the purposes of the mirrors library, a top-level function is
    * considered static.
    */
   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.
-   */
-  final bool isMethod;
-
-  /**
-   * Does this mirror reflect an abstract method?
+  /**
+   * Is the reflectee abstract?
    */
   final bool isAbstract;
 
   /**
-   * Does this mirror reflect a getter?
+   * Is the reflectee a regular function or method?
+   *
+   * A function or method is regular if it is not a getter, setter, or
+   * constructor.  Note that operators, by this definition, are
+   * regular methods.
+   */
+  final bool isRegularMethod;
+
+  /**
+   * Is the reflectee an operator?
+   */
+  final bool isOperator;
+
+  /**
+   * Is the reflectee a getter?
    */
   final bool isGetter;
 
   /**
-   * Does this mirror reflect a setter?
+   * Is the reflectee a setter?
    */
   final bool isSetter;
 
   /**
-   * Does this mirror reflect a constructor?
+   * Is the reflectee a constructor?
    */
   final bool isConstructor;
 
-  // Constructor kind
-
-  /**
-   * Does this mirror reflect a const constructor?
+  /**
+   * The constructor name for named constructors and factory methods.
+   *
+   * For unnamed constructors, this is the empty string.  For
+   * non-constructors, this is the empty string.
+   *
+   * For example, [:'bar':] is the constructor name for constructor
+   * [:Foo.bar:] of type [:Foo:].
+   */
+  Final String constructorName;
+
+  /**
+   * Is the reflectee a const constructor?
    */
   final bool isConstConstructor;
 
   /**
-   * Does this mirror reflect a generative constructor?
+   * Is the reflectee a generative constructor?
    */
   final bool isGenerativeConstructor;
 
   /**
-   * Does this mirror reflect a redirecting constructor?
+   * Is the reflectee a redirecting constructor?
    */
   final bool isRedirectingConstructor;
 
   /**
-   * Does this mirror reflect a factory constructor?
+   * Is the reflectee a factory constructor?
    */
   final bool isFactoryConstructor;
 }
 
 /**
  * A [VariableMirror] reflects a Dart language variable declaration.
  */
-interface VariableMirror {
+interface VariableMirror extends DeclarationMirror {
   /**
-   * The name of this variable
+   * A mirror on the type of the reflectee.
    */
-  final String simpleName;
+  final TypeMirror type;
 
   /**
-   * 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 a [ClassMirror].
-   */
-  final Mirror owner;
-
-  /**
-   * Does this mirror reflect a top-level variable?
-   */
-  final bool isTopLevel;
-
-  /**
-   * Does this mirror reflect a static variable?
+   * Is the reflectee a static variable?
    *
    * For the purposes of the mirror library, top-level variables are
    * implicitly declared static.
    */
   final bool isStatic;
 
   /**
-   * Does this mirror reflect a final variable?
+   * Is the reflectee a final variable?
    */
   final bool isFinal;
 }
 
 /**
  * A [ParameterMirror] reflects a Dart formal parameter declaration.
  */
 interface ParameterMirror extends VariableMirror {
   /**
-   * Returns the type of this parameter.
+   * A mirror on the type of this parameter.
    */
   final TypeMirror type;
 
   /**
-   * Returns the default value for this parameter.
+   * Is this parameter optional?
    */
-  final String defaultValue;
+  final bool isOptional;
 
   /**
-   * Returns true if this parameter has a default value.
+   * Is this parameter named?
+   */
+  final bool isNamed;
+
+  /**
+   * Does this parameter have a default value?
    */
   final bool hasDefaultValue;
 
   /**
-   * Returns true if this parameter is optional.
+   * A mirror on the default value for this parameter, if it exists.
+   *
+   * TODO(turnidge): String may not be a good representation of this
+   * at runtime.
    */
-  final bool isOptional;
+  final String defaultValue;
+}
+
+/**
+ * A [SourceLocation] describes the span of an entity in Dart source code.
+ */
+interface 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
@@ skipping 63 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;
 }