Implement more of the mirrors library, primarily stuff to do with types.

runtime/include/dart_api.h

 // 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.
 
 #ifndef INCLUDE_DART_API_H_
 #define INCLUDE_DART_API_H_
 
 /** \mainpage Dart Embedding API Reference
  *
  * Dart is a class-based programming language for creating structured
@@ skipping 1934 matching lines @@
 // --- Closures ---
 
 /**
  * Is this object a Closure?
  */
 DART_EXPORT bool Dart_IsClosure(Dart_Handle object);
 
 /**
  * Retrieves the function of a closure.
  *
- * \return A handle on the function of the closure, or an error handle if the
+ * \return A handle to the function of the closure, or an error handle if the
  *   argument is not a closure.
  */
 DART_EXPORT Dart_Handle Dart_ClosureFunction(Dart_Handle closure);
 
 /**
  * Invokes a Closure with the given arguments.
  *
  * May generate an unhandled exception error.
  *
  * \return If no error occurs during execution, then the result of
@@ skipping 67 matching lines @@
 
 /**
  * Returns the interface at some index in the list of interfaces some
  * class or inteface.
  *
  * TODO(turnidge): Finish documentation.
  */
 DART_EXPORT Dart_Handle Dart_ClassGetInterfaceAt(Dart_Handle clazz,
                                                  intptr_t index);
 
+/**
+ * Is this class defined by a typedef?
+ *
+ * Typedef definitions from the main program are represented as a
+ * special kind of class handle.  These typedef classes allow the

[cshapiro, 2012/09/12 18:52:07]

typedef classes or typedef class handles?

[turnidge, 2012/09/12 21:39:30]

Done.

+ * embedder to find their referent by using
+ * Dart_ClassGetTypedefReferent.

[cshapiro, 2012/09/12 18:52:07]

Wordy.

"Dart_ClassGetTypedefReferent returns the class handle referent."

[turnidge, 2012/09/12 21:39:30]

Made less wordy.

+ *
+ * TODO(turnidge): Finish documentation.
+ */
+DART_EXPORT bool Dart_ClassIsTypedef(Dart_Handle handle);

[cshapiro, 2012/09/12 18:52:07]

Rename "handle" to "klass", "cls", or "clazz" ?

+
+/**
+ * Returns a handle to the type to which a typedef refers.
+ *
+ * This function should only be called when Dart_ClassIsTypedef returns
+ * true.

[cshapiro, 2012/09/12 18:52:07]

Why?  I would expect this function to return an error if a precondition is
violated.

[turnidge, 2012/09/12 21:39:30]

Just so.  I'm telling them how to avoid getting an error.  Changed the wording
to be more explicit:

 * It is an error to call this function on a handle for which
 * Dart_ClassIsTypedef is not true.

+ *
+ * TODO(turnidge): Finish documentation.
+ */
+DART_EXPORT Dart_Handle Dart_ClassGetTypedefReferent(Dart_Handle clazz);
+
+/**
+ * Does this class represent the type of a function?
+ */
+DART_EXPORT bool Dart_ClassIsFunctionType(Dart_Handle handle);

[cshapiro, 2012/09/12 18:52:07]

Rename "handle" to "klass", "cls", or "clazz" ?

[turnidge, 2012/09/12 21:39:30]

Done.

+
+/**
+ * Returns a signature function for a function type.

[cshapiro, 2012/09/12 18:52:07]

signature function or function signature?

[turnidge, 2012/09/12 21:39:30]

Um, rewrote comment entirely:


/**
 * Returns a function handle representing the signature associated
 * with a function type.
 *
 * The return value is a function handle (See Dart_IsFunction, etc.).
 *
 * TODO(turnidge): Finish documentation.
 */

+ */
+DART_EXPORT Dart_Handle Dart_ClassGetFunctionTypeSignature(Dart_Handle clazz);
+
+
 // --- Function and Variable Declarations ---
 
 /**
  * Returns a list of the names of all functions or methods declared in
  * a library or class.
  *
  * \param target A library or class.
  *
  * \return If no error occurs, a list of strings is returned.
- *   Otherwise an erorr handle is returned.
+ *   Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_GetFunctionNames(Dart_Handle target);
 
 /**
  * Looks up a function or method declaration by name from a library or
  * class.
  *
  * \param target The library or class containing the function.
  * \param function_name The name of the function.
  *
  * \return If an error is encountered, returns an error handle.
  *   Otherwise returns a function handle if the function is found of
  *   Dart_Null() if the function is not found.
  */
 DART_EXPORT Dart_Handle Dart_LookupFunction(Dart_Handle target,
                                             Dart_Handle function_name);
 
 /**
  * Is this a function or method declaration handle?
  */
 DART_EXPORT bool Dart_IsFunction(Dart_Handle handle);
 
 /**
  * Returns the name for the provided function or method.
  *
  * \return A valid string handle if no error occurs during the
- * operation.
+ *   operation.
  */
 DART_EXPORT Dart_Handle Dart_FunctionName(Dart_Handle function);
 
 /**
- * Returns a handle to the owner of a function. The owner of an instance method
- * or a static method is its defining class. The owner of a top-level function
- * is its defining library. The owner of the function of a non-implicit closure
- * is the function of the method or closure that defines the non-implicit
+ * Returns a handle to the owner of a function.
+ *
+ * The owner of an instance method or a static method is its defining
+ * class. The owner of a top-level function is its defining
+ * library. The owner of the function of a non-implicit closure is the
+ * function of the method or closure that defines the non-implicit
  * closure.
  *
- * \return A valid handle on the owner of the function, or an error handle if
- * the argument is not a valid handle to a function.
+ * \return A valid handle to the owner of the function, or an error
+ *   handle if the argument is not a valid handle to a function.
  */
 DART_EXPORT Dart_Handle Dart_FunctionOwner(Dart_Handle function);
 
 /**
  * Determines whether a function handle refers to an abstract method.
  *
  * \param function A handle to a function or method declaration.
  * \param is_static Returns whether the handle refers to an abstract method.
  *
  * \return A valid handle if no error occurs during the operation.
@@ skipping 44 matching lines @@
  *
  * \param function A handle to a function or method declaration.
  * \param is_static Returns whether the function or method is a setter.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_FunctionIsSetter(Dart_Handle function,
                                               bool* is_setter);
 
 /**
+ * Returns a handle to the return type of a function.

[cshapiro, 2012/09/12 18:52:07]

I am confused about the pervasive use of handle in this documentation.  The
handle seems implied.

[turnidge, 2012/09/12 21:39:30]

Right.  I am torn about this.  I could start dropping the handles all over the
documentation which might make it all read easier.  I take it you think this is
a good idea?

[cshapiro, 2012/09/13 04:29:58]

I think the handle is superfluous, after all what else could it be?  Also, the
inconsistent usage is a little bit confusing in the context of a reflection API
given the indirection inherent in many of these operations.

[turnidge, 2012/09/13 17:02:57]

Fixed this use.  Will fix the more pervasive problem in a follow-up CL.

+ *
+ * \return A valid handle to a type or an error handle if the argument
+ *   is not valid.
+ */
+DART_EXPORT Dart_Handle Dart_FunctionReturnType(Dart_Handle function);
+
+/**
  * Determines the number of required and optional parameters.
  *
  * \param function A handle to a function or method declaration.
  * \param fixed_param_count Returns the number of required parameters.
  * \param opt_param_count Returns the number of optional parameters.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_FunctionParameterCounts(
   Dart_Handle function,
   int64_t* fixed_param_count,
   int64_t* opt_param_count);
 
 /**
+ * Returns a handle to the type of a function parameter.
+ *
+ * \return A valid handle to a type or an error handle if the argument
+ *   is not valid.
+ */
+DART_EXPORT Dart_Handle Dart_FunctionParameterType(Dart_Handle function,
+                                                   int parameter_index);
+
+/**
  * Returns a list of the names of all variables declared in a library
  * or class.
  *
  * \param target A library or class.
  *
  * \return If no error occurs, a list of strings is returned.
- *   Otherwise an erorr handle is returned.
+ *   Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_GetVariableNames(Dart_Handle target);
 
 /**
  * Looks up a variable declaration by name from a library or class.
  *
- * \param library The library or class containing the variable.
+ * \param target The library or class containing the variable.
  * \param variable_name The name of the variable.
  *
  * \return If an error is encountered, returns an error handle.
  *   Otherwise returns a variable handle if the variable is found or
  *   Dart_Null() if the variable is not found.
  */
 DART_EXPORT Dart_Handle Dart_LookupVariable(Dart_Handle target,
                                             Dart_Handle variable_name);
 
 /**
@@ skipping 24 matching lines @@
  * Determines whether a variable is declared final.
  *
  * \param variable A handle to a variable declaration.
  * \param is_final Returns whether the variable is declared final.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_VariableIsFinal(Dart_Handle variable,
                                              bool* is_final);
 
+/**
+ * Returns a handle to the type of a variable.
+ *
+ * \return A valid handle to a type of or an error handle if the
+ *   argument is not valid.
+ */
+DART_EXPORT Dart_Handle Dart_VariableType(Dart_Handle function);
+
+/**
+ * Returns a list of the names of all type variables declared in a class.
+ *
+ * The type variables list preserves the original declaration order.
+ *
+ * \param clazz A class.
+ *
+ * \return If no error occurs, a list of strings is returned.
+ *   Otherwise an error handle is returned.
+ */
+DART_EXPORT Dart_Handle Dart_GetTypeVariableNames(Dart_Handle clazz);
+
+/**
+ * Looks up a type variable declaration by name from a class.
+ *
+ * \param clazz The class containing the type variable.
+ * \param variable_name The name of the type variable.
+ *
+ * \return If an error is encountered, returns an error handle.
+ *   Otherwise returns a type variable handle if the type variable is
+ *   found or Dart_Null() if the type variable is not found.
+ */
+DART_EXPORT Dart_Handle Dart_LookupTypeVariable(Dart_Handle clazz,
+                                                Dart_Handle type_variable_name);
+
+/**
+ * Is this a type variable handle?
+ */
+DART_EXPORT bool Dart_IsTypeVariable(Dart_Handle handle);
+
+/**
+ * Returns the name for the provided type variable.
+ */
+DART_EXPORT Dart_Handle Dart_TypeVariableName(Dart_Handle type_variable);
+
+/**
+ * Returns a handle to the owner of a function.
+ *
+ * The owner of a type variable is its defining class.
+ *
+ * \return A valid handle to the owner of the type variable, or an error
+ *   handle if the argument is not a valid handle to a type variable.
+ */
+DART_EXPORT Dart_Handle Dart_TypeVariableOwner(Dart_Handle type_variable);
+
+/**
+ * Returns a handle to the upper bound of a type variable.
+ *
+ * The upper bound of a type variable is ...
+ *
+ * \return A valid handle to a type, or an error handle if the
+ *   argument is not a valid handle.
+ */
+DART_EXPORT Dart_Handle Dart_TypeVariableUpperBound(Dart_Handle type_variable);
+// TODO(turnidge): Finish documentation.
+
 // --- Constructors, Methods, and Fields ---
 
 /**
  * Invokes a constructor, creating a new object.
  *
  * This function allows hidden constructors (constructors with leading
  * underscores) to be called.
  *
  * \param clazz A class or an interface.
  * \param constructor_name The name of the constructor to invoke.  Use
@@ skipping 297 matching lines @@
 /**
  * Returns the url from which a library was loaded.
  */
 DART_EXPORT Dart_Handle Dart_LibraryUrl(Dart_Handle library);
 
 /**
  * Returns a list of the names of all classes and interfaces declared
  * in a library.
  *
  * \return If no error occurs, a list of strings is returned.
- *   Otherwise an erorr handle is returned.
+ *   Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_LibraryGetClassNames(Dart_Handle library);
 
 DART_EXPORT Dart_Handle Dart_LookupLibrary(Dart_Handle url);
 // TODO(turnidge): Consider returning Dart_Null() when the library is
 // not found to distinguish that from a true error case.
 
 DART_EXPORT Dart_Handle Dart_LoadLibrary(Dart_Handle url,
                                          Dart_Handle source);
 
@@ skipping 49 matching lines @@
 
 typedef void (*Dart_FileWriterFunction)(const char* buffer, int64_t num_bytes);
 
 // Support for generating symbol maps for use by the Linux perf tool.
 DART_EXPORT void Dart_InitPerfEventsSupport(Dart_FileWriterFunction function);
 
 // Support for generating flow graph compiler debugging output into a file.
 DART_EXPORT void Dart_InitFlowGraphPrinting(Dart_FileWriterFunction function);
 
 #endif  // INCLUDE_DART_API_H_