Split dart_api.h into multiple parts:

runtime/include/dart_mirrors_api.h

+/*
+ * Copyright (c) 2013, 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_MIRRORS_API_H_
+#define INCLUDE_DART_MIRRORS_API_H_
+
+#include "include/dart_api.h"
+
+/*
+ * =================================
+ * Classes and Interfaces Reflection
+ * =================================

[vsm, 2013/06/13 22:34:55]

You might consider moving Dart_GetSuperclass and similar from dart_debugger_api
to here.

[siva, 2013/06/13 22:53:17]

Yes, that would be the plan. I will do that in a different CL.

On 2013/06/13 22:34:55, vsm wrote:

+ */
+
+/**
+ * Returns the class name for the provided class or interface.
+ */
+DART_EXPORT Dart_Handle Dart_ClassName(Dart_Handle clazz);
+
+/**
+ * Returns the library for the provided class or interface.
+ */
+DART_EXPORT Dart_Handle Dart_ClassGetLibrary(Dart_Handle clazz);
+
+/**
+ * Returns the number of interfaces directly implemented by some class
+ * or interface.
+ *
+ * TODO(turnidge): Finish documentation.
+ */
+DART_EXPORT Dart_Handle Dart_ClassGetInterfaceCount(Dart_Handle clazz,
+                                                    intptr_t* count);
+
+/**
+ * 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.  See Dart_ClassGetTypedefReferent.
+ *
+ * TODO(turnidge): Finish documentation.
+ */
+DART_EXPORT bool Dart_ClassIsTypedef(Dart_Handle clazz);
+
+/**
+ * Returns a handle to the type to which a typedef refers.
+ *
+ * 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 clazz);
+
+/**
+ * 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 Variables Reflection
+ * =================================
+ */
+
+/**
+ * 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 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);
+
+/**
+ * Returns the name for the provided function or method.
+ *
+ * \return A valid string handle if no error occurs during the
+ *   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
+ * closure.
+ *
+ * \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.
+ */
+DART_EXPORT Dart_Handle Dart_FunctionIsAbstract(Dart_Handle function,
+                                                bool* is_abstract);
+
+/**
+ * Determines whether a function handle referes to a static function
+ * of method.
+ *
+ * For the purposes of the embedding API, a top-level function is
+ * implicitly declared static.
+ *
+ * \param function A handle to a function or method declaration.
+ * \param is_static Returns whether the function or method is declared static.
+ *
+ * \return A valid handle if no error occurs during the operation.
+ */
+DART_EXPORT Dart_Handle Dart_FunctionIsStatic(Dart_Handle function,
+                                              bool* is_static);
+
+/**
+ * Determines whether a function handle referes to a constructor.
+ *
+ * \param function A handle to a function or method declaration.
+ * \param is_static Returns whether the function or method is a constructor.
+ *
+ * \return A valid handle if no error occurs during the operation.
+ */
+DART_EXPORT Dart_Handle Dart_FunctionIsConstructor(Dart_Handle function,
+                                                   bool* is_constructor);
+/* TODO(turnidge): Document behavior for factory constructors too. */
+
+/**
+ * Determines whether a function or method is a getter.
+ *
+ * \param function A handle to a function or method declaration.
+ * \param is_static Returns whether the function or method is a getter.
+ *
+ * \return A valid handle if no error occurs during the operation.
+ */
+DART_EXPORT Dart_Handle Dart_FunctionIsGetter(Dart_Handle function,
+                                              bool* is_getter);
+
+/**
+ * Determines whether a function or method is a setter.
+ *
+ * \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 the return type of a function.
+ *
+ * \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 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 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);
+
+/**
+ * Returns the name for the provided variable.
+ */
+DART_EXPORT Dart_Handle Dart_VariableName(Dart_Handle variable);
+
+/**
+ * Determines whether a variable is declared static.
+ *
+ * For the purposes of the embedding API, a top-level variable is
+ * implicitly declared static.
+ *
+ * \param variable A handle to a variable declaration.
+ * \param is_static Returns whether the variable is declared static.
+ *
+ * \return A valid handle if no error occurs during the operation.
+ */
+DART_EXPORT Dart_Handle Dart_VariableIsStatic(Dart_Handle variable,
+                                              bool* is_static);
+
+/**
+ * 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 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);
+
+/**
+ * Returns the name for the provided type variable.
+ */
+DART_EXPORT Dart_Handle Dart_TypeVariableName(Dart_Handle type_variable);
+
+/**
+ * Returns 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 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. */
+
+
+/*
+ * ====================
+ * Libraries Reflection
+ * ====================
+ */
+
+/**
+ * Returns the name of a library as declared in the #library directive.
+ */
+DART_EXPORT Dart_Handle Dart_LibraryName(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 error handle is returned.
+ */
+DART_EXPORT Dart_Handle Dart_LibraryGetClassNames(Dart_Handle library);
+
+
+/*
+ * ===================
+ * Closures Reflection
+ * ===================
+ */
+
+/**
+ * Retrieves the function of a closure.
+ *
+ * \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);
+
+/*
+ * ===================
+ * Metadata Reflection
+ * ===================
+ */
+
+/**
+ * Get metadata associated with an object.
+ *
+ * \param obj Object for which the metadata is retrieved.
+ *
+ * \return If no error occurs, returns an array of metadata values.
+ *   Returns an empty array if there is no metadata for the object.
+ *   Returns an error if the evaluation of the metadata expressions fails.
+ *
+ */
+DART_EXPORT Dart_Handle Dart_GetMetadata(Dart_Handle obj);
+
+#endif  /* INCLUDE_DART_MIRRORS_API_H_ */  /* NOLINT */