Mirrors prototype added to dartdoc.

lib/dartdoc/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');
+
+#import('dart:uri');
+#import('dart2js_mirror.dart');
+
+/**
+ * [Compilation] encapsulates the compilation of a program.
+ */
+class Compilation {
+  /**
+   * Creates a new compilation which has [script] as its entry point.
+   */
+  factory Compilation(String script, String libraryRoot,
+                      [String packageRoot, List<String> opts = const []])
+  {
+    return new Dart2jsCompilation(script, libraryRoot, packageRoot, opts);
+  }
+
+  /**
+   * Returns the mirror system for this compilation.
+   */
+  abstract MirrorSystem mirrors();
+}
+
+/**
+ * The main interface for the whole mirror system.
+ */
+interface MirrorSystem {
+  /**
+   * Returns an unmodifiable map of all libraries in this mirror system.
+   */
+  Map<Object,LibraryMirror> libraries();
+}
+
+
+/**
+ * An entity in the mirror system.
+ */
+interface Mirror {
+  /**
+   * The simple name of the entity. The simple name is in most cases the
+   * the declared single identifier name of the entity, such as 'method' for
+   * a method [:void method() {...}:].
+   */
+  String simpleName();
+
+  /**
+   * Returns the name of this entity qualified by is enclosing context. For
+   * instance, the qualified name of a method 'method' in class 'Class' in
+   * library 'library' is 'library.Class.method'.
+   */
+  String qualifiedName();
+}
+
+/**
+ * Common interface for a type and library.

[Lasse Reichstein Nielsen, 2012/07/02 11:48:53]

... "for types, instances and libraries."

[Johnni Winther, 2012/07/03 07:38:50]

Done.

+ */
+interface ObjectMirror extends Mirror {
+
+  /**
+   * Returns an unmodifiable map of the members of declared in this type or
+   * library.
+   */
+  Map<Object,MemberMirror> declaredMembers();
+}
+
+/**
+ * A library.
+ */
+interface LibraryMirror extends ObjectMirror {
+  /**
+   * The name of the library, as given in #library().
+   */
+  String simpleName();
+
+  /**
+   * Returns an iterable over all types in the library.
+   */
+  Map<Object,InterfaceMirror> types();
+
+  /**
+   * Returns the source location for this library.
+   */
+  Location location();
+}
+
+/**
+ * Common interface for classes, interfaces, typedefs and type variables.
+ */
+interface TypeMirror extends Mirror {

[Lasse Reichstein Nielsen, 2012/07/02 11:48:53]

Make a comment that not all TypeMirrors are ObjectMirrors, which one would think
from the comment in line 60.

[Johnni Winther, 2012/07/03 07:38:50]

Done.

+  /**
+   * Returns the source location for this type.
+   */
+  Location location();
+
+  /**
+   * Returns the library in which this member resides.
+   */
+  LibraryMirror library();
+
+  /**
+   * Returns [:true:] iff this type is the [:Object:] type.
+   */
+  final bool isObject;
+
+  /**
+   * Returns [:true:] iff this type is the [:Dynamic:] type.
+   */
+  final bool isDynamic;
+
+  /**
+   * Returns [:true:] iff this type is the void type.
+   */
+  final bool isVoid;
+
+  /**
+   * Returns [:true:] iff this type is a type variable.
+   */
+  final bool isTypeVariable;
+
+  /**
+   * Returns [:true:] iff this type is a typedef.
+   */
+  final bool isTypedef;
+
+  /**
+   * Returns [:true:] iff this type is a function type.
+   */
+  final bool isFunction;
+}
+
+/**
+ * A class or interface type.
+ */
+interface InterfaceMirror extends TypeMirror, ObjectMirror {
+  /**
+   * Returns the defining type, i.e. declaration of a type.
+   */
+  final InterfaceMirror declaration;
+
+  /**
+   * Returns the super class of this type, or null if this type is [Object] or a
+   * typedef.
+   */
+  InterfaceMirror superclass();
+
+  /**
+   * Returns an iterable over the interfaces directly implemented by this type.
+   */
+  // TODO(johnniwinther): Semantics is unclear. Should List<String> return
+  // Collection<String> (that is, perform substitution) or Collection<E>
+  // (the declaration)? And for [:interface NumList<num> extends List<num>:]
+  // should List<num> or List<E> be returned?
+  Map<Object,InterfaceMirror> interfaces();
+
+  /**
+   * Returns an iterable over the type declarations directly inheriting from
+   * this type.
+   */
+  // An iterable is returned because this information should probably be
+  // computed on the fly.
+  Iterable<InterfaceMirror> computeSubdeclarations();
+
+  /**
+   * Returns [:true:] iff this type is a class.
+   */
+  final bool isClass;
+
+  /**
+   * Returns [:true:] iff this type is an interface.
+   */
+  final bool isInterface;
+
+  /**
+   * Returns [:true:] if this type is private.
+   */
+  final bool isPrivate;
+
+  /**
+   * Returns [:true:] if this type is the declaration of a type.
+   */
+  final bool isDeclaration;
+
+  /**
+   * Returns a list of the type arguments for this type.
+   */
+  // Return a list instead of a map since the order of type arguments matters.
+  // Also, there is no clear candidate for the keys, other than the indices,
+  // which again is an argument for returning a list.
+  List<TypeMirror> typeArguments();
+
+  /**
+   * Returns the list of type variables for this type.
+   */
+  // Return a list instead of a map since the order of type variable matters.
+  // Even though the type variable name is a candidate for the key, the index
+  // of a type variable has a more stable semantics, which is an argument for
+  // returning a list instead of a map.
+  List<TypeVariableMirror> typeVariables();
+
+  /**
+   * Returns an immutable map of the constructors in this interface.
+   */
+  Map<Object,MethodMirror> constructors();
+
+  /**
+   * Returns the default type for this interface.
+   */
+  InterfaceMirror defaultType();
+}
+
+/**
+ * A type parameter as declared on a generic type.
+ */
+interface TypeVariableMirror extends TypeMirror {
+  /**
+   * Return a mirror on the class, interface, or typedef that declared the
+   * type variable.
+   */
+  // Should not be called [declaration] as we then would have two [TypeMirror]
+  // subtypes ([InterfaceMirror] and [TypeVariableMirror]) which have
+  // [declaration()] methods but with different semantics.
+  InterfaceMirror declarer();
+
+  /**
+   * Returns the bound of the type parameter.
+   */
+  TypeMirror bound();
+}
+
+/**
+ * A function type.
+ */
+interface FunctionTypeMirror extends InterfaceMirror {
+  /**
+   * Returns the return type of this function type.
+   */
+  TypeMirror returnType();
+
+  /**
+   * Returns the parameters for this function type.
+   */
+  List<ParameterMirror> parameters();
+
+  /**
+   * Returns the call method for this function type.
+   */
+  MethodMirror callMethod();
+}
+
+/**
+ * A typedef.
+ */
+interface TypedefMirror extends InterfaceMirror {
+  /**
+   * Returns the defining type for this typedef. For instance [:void f(int):]
+   * for a [:typedef void f(int):].
+   */
+  TypeMirror definition();
+}
+
+/**
+ * A member of a type, i.e. a field, method or constructor.
+ */
+interface MemberMirror extends Mirror {
+  /**
+   * Returns the source location for this member.
+   */
+  Location location();
+
+  /**
+   * Returns a mirror on the declaration immediately surrounding the reflectee.
+   * This could be a class, interface, library or another method or function.
+   */
+  ObjectMirror surroundingDeclaration();
+
+  /**
+   * Returns true if this is a top level member, i.e. a member not within a

[Lasse Reichstein Nielsen, 2012/07/02 11:48:53]

I'd say "Is true if ..." since this is a property, not a function, or,
preferably, "Whether this is a ...".

[Johnni Winther, 2012/07/03 07:38:50]

Done.

+   * type.
+   */
+  final bool isTopLevel;
+
+  /**
+   * Returns true if this member is a constructor.
+   */
+  final bool isConstructor;
+
+  /**
+   * Returns true if this member is a field.
+   */
+  final bool isField;
+
+  /**
+   * Returns true if this member is a method.
+   */
+  final bool isMethod;
+
+  /**
+   * Returns true if this member is private.
+   */
+  final bool isPrivate;
+
+  /**
+   * Returns true if this member is static.
+   */
+  final bool isStatic;
+}
+
+/**
+ * A field.
+ */
+interface FieldMirror extends MemberMirror {
+
+  /**
+   * Returns true if this field is final.
+   */
+  final bool isFinal;
+
+  /**
+   * Returns the type of this field.
+   */
+  TypeMirror type();
+}
+
+/**
+ * A constructor or method.

[Lasse Reichstein Nielsen, 2012/07/02 11:48:53]

State that it includes getters and setters as methods.

[Johnni Winther, 2012/07/03 07:38:50]

Done.

+ */
+interface MethodMirror extends MemberMirror {
+  /**
+   * Returns the list of parameters for this method.
+   */
+  List<ParameterMirror> parameters();
+
+  /**
+   * Returns the return type of this method.
+   */
+  TypeMirror returnType();
+
+  /**
+   * Returns [:true:] if this method is a constant constructor.
+   */
+  final bool isConst;
+
+  /**
+   * Returns [:true:] if this method is a factory method.
+   */
+  final bool isFactory;
+
+  /**
+   * Returns the constructor name for named constructors and factory methods,
+   * e.g. [:'bar':] for constructor [:Foo.bar:] of type [:Foo:].
+   */
+  final String constructorName;
+
+  /**
+   * Returns [:true:] if this method is a getter method.
+   */
+  final bool isGetter;
+
+  /**
+   * Returns [:true:] if this method is a setter method.
+   */
+  final bool isSetter;
+
+  /**
+   * Returns [:true:] if this method is an operator method.
+   */
+  final bool isOperator;
+
+  /**
+   * Returns the operator name for operator methods, e.g. [:'<':] for
+   * [:operator <:]
+   */
+  final String operatorName;
+}
+
+/**
+ * A formal parameter.
+ */
+interface ParameterMirror extends Mirror {
+  /**
+   * Returns the type of this parameter.
+   */
+  TypeMirror type();
+
+  /**
+   * Returns the default value for this parameter.
+   */
+  String defaultValue();
+
+  /**
+   * Returns true if this parameter has a default value.
+   */
+  bool hasDefaultValue();
+
+  /**
+   * Returns true if this parameter is optional.
+   */
+  bool isOptional();
+}
+
+/**
+ * A [Location] describes the span of an entity in Dart source code.
+ * A [Location] should be the minimum span that encloses the declaration of the
+ * mirrored entity.
+ */
+interface Location {
+  /**
+   * The character index where the location begins.
+   */
+  int start();

[Lasse Reichstein Nielsen, 2012/07/04 10:58:59]

Make start and end getters too.
Yes, I like getters better than nullary functions.

+
+  /**
+   * The character index where the location ends.
+   */
+  int end();
+
+  /**
+   * Returns the [Source] in which this [Location] indexes.
+   * If [:loc:] is a location, [:loc.source().text()[loc.start()] is where it
+   * starts, and [:loc.source().text()[loc.end()] is where it ends.

[Lasse Reichstein Nielsen, 2012/07/02 11:48:53]

The "end" part seems odd. I don't consider the following *character* to be where
something ends (a character is not a position). The position itself makes more
sense.

[Johnni Winther, 2012/07/03 07:38:50]

I don't understand. [start] and [end] both return character positions.

[Lasse Reichstein Nielsen, 2012/07/04 10:58:59]

Then [:end.loc():] is where it ends (and [:start.loc():] where it starts), but
[:loc.source().text()[loc.end()]:] is the *character* *after* it ends - which
may not even exist, if it can end at the end of the source!

+   */
+  Source source();
+
+  /**
+   * The text of the location span.
+   */
+  String text();
+}
+
+/**
+ * A [Source] describes the source code of a compilation unit in Dart source
+ * code.
+ */
+interface Source {
+  /**
+   * Returns the URI where the source originated.
+   */
+  Uri uri();
+
+  /**
+   * Returns the text of this source.
+   */
+  String text();
+}