Implement method and variable reflection in dart:mirrors.

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 1976 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);
 
+// --- 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.

[cshapiro, 2012/06/28 23:57:47]

I am confused about the conditions under which errors are returned.  Is any
object permitted as the target?  This applies to all of the new functions in
this header.

[turnidge, 2012/07/09 23:45:17]

This comment would apply to all dart api functions, so I think it's a separate
change.  Considering....

+ *   Otherwise an erorr 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

[cshapiro, 2012/06/28 23:57:47]

This does not read right specifically, "is found of Dart_Null()".  Perhaps you
meant something else?

[turnidge, 2012/07/09 23:45:17]

Done.

+ *   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.

[cshapiro, 2012/06/28 23:57:47]

Is there no possible error return?  Maybe provide a \return documentation string
here as well.

[turnidge, 2012/07/09 23:45:17]

Done.

+ */
+DART_EXPORT Dart_Handle Dart_FunctionName(Dart_Handle function);
+
+/**
+ * Determines whether a function or method is declared abstract.

[cshapiro, 2012/06/28 23:57:47]

Since there cannot be an abstract function, perhaps the documentation string
should say something like "Returns true if the handle refers to an abstract
method" rather than teasing the existence of an abstract function.

[turnidge, 2012/07/09 23:45:17]

Done.

+ *
+ * \param function A handle to a function or method declaration.
+ * \param is_static Returns whether the function or method is declared abstract.

[cshapiro, 2012/06/28 23:57:47]

Same here, "returns true if 'function' is an abstract method".

[turnidge, 2012/07/09 23:45:17]

Done.

+ *
+ * \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 or method is declared static.

[cshapiro, 2012/06/28 23:57:47]

Declaring static seems confusing.  I understand there is a comment below that
tries to reconcile with reality, but similarly, outside of the embedding api
functions are static even though they are not declared so.

[turnidge, 2012/07/09 23:45:17]

Done.

+ *
+ * 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 or method is a constructor.

[cshapiro, 2012/06/28 23:57:47]

Functions cannot be constructors.  What about factories?

[turnidge, 2012/07/09 23:45:17]

Done.

+ *
+ * \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);
+
+/**
+ * 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 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.
+ */
+DART_EXPORT Dart_Handle Dart_GetVariableNames(Dart_Handle target);

[cshapiro, 2012/06/28 23:57:47]

Why not call this "Field" instead of "Variable"?

[turnidge, 2012/07/09 23:45:17]

The spec calls them variables instead of fields, so I decided to follow that.

+
+/**
+ * Looks up a variable declaration by name from a library or class.
+ *
+ * \param library 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_LookupVariable(Dart_Handle target,

[cshapiro, 2012/06/28 23:57:47]

Likewise.

+                                            Dart_Handle variable_name);
+
+/**
+ * Is this a variable declaration handle?

[cshapiro, 2012/06/28 23:57:47]

What is a variable in this context?  Is this a local variable or a class field
or something else?

[turnidge, 2012/07/09 23:45:17]

For now, a variable is a top-level variable or a "field" from a class.  The spec
calls these variables.  Local variables are not included.

Currently the only place a variable handle can come from is a call to
Dart_LookupVariable, which looks up a variable in a library or a class.

+ */
+DART_EXPORT bool Dart_IsVariable(Dart_Handle handle);
+
+/**
+ * Returns the name for the provided variable.

[cshapiro, 2012/06/28 23:57:47]

Ditto.

+ */
+DART_EXPORT Dart_Handle Dart_VariableName(Dart_Handle variable);
+
+/**
+ * Determines whether a variable is declared static.

[cshapiro, 2012/06/28 23:57:47]

What kind of variable?  Local variable?

+ *
+ * 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.

[cshapiro, 2012/06/28 23:57:47]

Ditto.

+ *
+ * \param variable A handle to a variable declaration.
+ * \param is_static Returns whether the variable is declared final.

[cshapiro, 2012/06/28 23:57:47]

You have the wrong name for the \param, it should be is_final.

[turnidge, 2012/07/09 23:45:17]

Done.

+ *
+ * \return A valid handle if no error occurs during the operation.
+ */
+DART_EXPORT Dart_Handle Dart_VariableIsFinal(Dart_Handle variable,
+                                             bool* is_final);
+
 // --- 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 364 matching lines @@
 // information that can be used for better profile reports for
 // dynamically generated code.
 DART_EXPORT void Dart_InitPprofSupport();
 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size);
 
 // Support for generating flow graph compiler debugging output into a file.
 typedef void (*FileWriterFunction)(const char* buffer, int64_t num_bytes);
 DART_EXPORT void Dart_InitFlowGraphPrinting(FileWriterFunction function);
 
 #endif  // INCLUDE_DART_API_H_