[Boost-commit] svn:boost r47613 - sandbox/boost/reflection

From: oryol_at_[hidden]
Date: 2008-07-19 22:24:52

Author: jeremypack
Date: 2008-07-19 22:24:51 EDT (Sat, 19 Jul 2008)
New Revision: 47613
URL: http://svn.boost.org/trac/boost/changeset/47613

Log:
Modifications to reflection/ headers.

Text files modified: 
   sandbox/boost/reflection/adapter.hpp          |    39 ++++++++++                              
   sandbox/boost/reflection/common.hpp           |     3                                         
   sandbox/boost/reflection/constructor_info.hpp |    16 ++-                                     
   sandbox/boost/reflection/parameter_map.hpp    |    73 ++++++++++++++++++-                     
   sandbox/boost/reflection/reflection.hpp       |   149 ++++++++++++++++++++++++++++++++++++++++
   5 files changed, 269 insertions(+), 11 deletions(-)

Modified: sandbox/boost/reflection/adapter.hpp
==============================================================================
--- sandbox/boost/reflection/adapter.hpp	(original)
+++ sandbox/boost/reflection/adapter.hpp	2008-07-19 22:24:51 EDT (Sat, 19 Jul 2008)
@@ -27,21 +27,43 @@
   }
 };
 
+/** \brief A container for generic_parameters.
+  *
+  * The basic_parameter_map is designed to hold arbitrary data indexed
+  * by the value of the Info parameter, and can return all items that
+  * match a certain type and Info parameter, ie all integers called "foobar".
+  */
 template <class Info = std::string,
           class TypeInfo = extensions::default_type_info>
 class basic_parameter_map
-  : public std::multimap<Info, generic_parameter<TypeInfo>*> {
+  : protected std::multimap<Info, generic_parameter<TypeInfo>*> {
 public:
+  /** The destructor deletes all of the parameters that it references.
+    */
   ~basic_parameter_map() {
     for (typename map_type::iterator it = begin(); it != end(); ++it) {
       delete it->second;
     }
   }
+
   typedef std::multimap<Info, generic_parameter<TypeInfo>*> map_type;
   using map_type::equal_range;
   using map_type::begin;
   using map_type::end;
   using map_type::insert;
+
+  /** \brief Return a vector of all parameters matching the given
+    * type and Info.
+    *
+    * Given an Info value and a type, this will return all parameters
+    * that either match the given type or are convertible to the given
+    * type.
+    * \return A vector of all parameters that match the given type and Info.
+    * \param info The index or name of the parameters to return.
+    * \tparam D The type of parameters to return.
+    * \pre None.
+    * \post None.
+    */
   template <class D>
   std::vector<generic_parameter<TypeInfo>*> get(Info info) {
     std::vector<generic_parameter<TypeInfo>*> parameters;
@@ -58,6 +80,18 @@
     return parameters;
   }
 
+  /** \brief Return a vector of all parameters matching the given
+    * type and Info.
+    *
+    * Given an Info value and a type, this will return all parameters
+    * that either match the given type or are convertible to the given
+    * type. This function is const.
+    * \return A vector of all parameters that match the given type and Info.
+    * \param info The index or name of the parameters to return.
+    * \tparam D The type of parameters to return.
+    * \pre None.
+    * \post None.
+    */
   template <class D>
   std::vector<const generic_parameter<TypeInfo>*> get(Info info) const {
     std::vector<generic_parameter<TypeInfo>*> parameters;
@@ -74,6 +108,9 @@
     return parameters;
   }
 };
+
+/** The most common version of basic_parameter_map.
+  */
 typedef basic_parameter_map<> parameter_map;
 }}
 

Modified: sandbox/boost/reflection/common.hpp
==============================================================================
--- sandbox/boost/reflection/common.hpp	(original)
+++ sandbox/boost/reflection/common.hpp	2008-07-19 22:24:51 EDT (Sat, 19 Jul 2008)
@@ -19,6 +19,9 @@
 #include <boost/preprocessor/repetition.hpp>
 #include <boost/concept_check.hpp>
 
+/** This determines the maximum number of parameters that a reflected
+  * function can have. 10 is the same default as Boost.Function.
+  */
 #ifndef BOOST_REFLECTION_MAX_FUNCTOR_PARAMS
 #define BOOST_REFLECTION_MAX_FUNCTOR_PARAMS 10
 #endif  // BOOST_REFLECTION_MAX_FUNCTOR_PARAMS

Modified: sandbox/boost/reflection/constructor_info.hpp
==============================================================================
--- sandbox/boost/reflection/constructor_info.hpp	(original)
+++ sandbox/boost/reflection/constructor_info.hpp	2008-07-19 22:24:51 EDT (Sat, 19 Jul 2008)
@@ -11,15 +11,19 @@
 
 // No header guards, as this header is intended to be included multiple times.
 
-// The basic_constructor_info class is used as a key in the map
-// of constructors available for the current reflection.
-// There are two types - those with ParameterInfo defined, and
-// those without.
+/** The basic_constructor_info class is used as a key in the map
+  * of constructors available for the current reflection.
+  * There are two types - those with ParameterInfo defined, and
+  * those without.
+  */
 #ifdef BOOST_REFLECTION_WITH_PARAMETER_INFO
 template<class TypeInfo, class ParameterInfo = void>
 struct basic_constructor_info {
-  // A description for each parameter of the function.
-  // If ParameterInfo=void, this does not appear.
+/** A description for each parameter of the function.
+  * If ParameterInfo=void, this does not appear.
+  * This member variable only occurs for reflections with
+  * parameter info.
+  */
   std::vector<ParameterInfo> parameter_info_;
 #else
 template<class TypeInfo>

Modified: sandbox/boost/reflection/parameter_map.hpp
==============================================================================
--- sandbox/boost/reflection/parameter_map.hpp	(original)
+++ sandbox/boost/reflection/parameter_map.hpp	2008-07-19 22:24:51 EDT (Sat, 19 Jul 2008)
@@ -30,7 +30,7 @@
 template <class Info = std::string,
           class TypeInfo = extensions::default_type_info>
 class basic_parameter_map
-  : public std::multimap<Info, generic_parameter<TypeInfo>*> {
+  : protected std::multimap<Info, generic_parameter<TypeInfo>*> {
 public:
   ~basic_parameter_map() {
     for (typename map_type::iterator it = begin(); it != end(); ++it) {
@@ -42,13 +42,26 @@
   using map_type::begin;
   using map_type::end;
   using map_type::insert;
+
+  /** \brief Return all parameters matching the TypeInfo and Info.
+    *
+    * Given a type (D) and Info (ie, string describing the parameter),
+    * return a vector containing all generic_parameters that match,
+    * or can be converted to the given type.
+    *
+    * \return Matching parameters.
+    * \pre None.
+    * \post None.
+    * \param Info The Info (ie, name) describing the parameter needed.
+    * \tparam D The type of parameter to return.
+    */
   template <class D>
-  std::vector<generic_parameter<TypeInfo>*> get(Info info) const {
+  std::vector<generic_parameter<TypeInfo>*> get(Info info) {
     std::vector<generic_parameter<TypeInfo>*> parameters;
     std::pair<typename map_type::iterator, typename map_type::iterator> its
       = equal_range(info);
-    for (typename map_type::iterator current = its->first;
-         current != its->second; ++current) {
+    for (typename map_type::iterator current = its.first;
+         current != its.second; ++current) {
       generic_parameter<TypeInfo>& p = *current->second;
       if (p.template can_cast<D>()) {
         parameters.push_back(current->second);
@@ -56,6 +69,58 @@
     }
     return parameters;
   }
+
+  /** \brief Return true if the given parameter exists.
+    *
+    * Given a type (D) and Info (ie, string describing the parameter),
+    * return true if the element exists in the parameter_map.
+    *
+    * \return True if the parameter exists.
+    * \pre None.
+    * \post None.
+    * \param Info The Info (ie, name) describing the parameter needed.
+    * \tparam D The type of parameter to search for.
+    */
+  template <class D>
+  bool has(Info info) const {
+    std::pair<typename map_type::const_iterator,
+              typename map_type::const_iterator> its
+      = equal_range(info);
+    for (typename map_type::const_iterator current = its.first;
+         current != its.second; ++current) {
+      generic_parameter<TypeInfo>& p = *current->second;
+      if (p.template can_cast<D>()) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** \brief Return the first matching parameter.
+    *
+    * Given a type (D) and Info (ie, string describing the parameter),
+    * return first parameter matching, or that can be converted to that
+    * type.
+    *
+    * \return The first matching parameter.
+    * \pre None.
+    * \post None.
+    * \param Info The Info (ie, name) describing the parameter needed.
+    * \tparam D The type of parameter to search for.
+    */
+  template <class D>
+  generic_parameter<TypeInfo>* get_first(Info info) {
+    std::pair<typename map_type::iterator, typename map_type::iterator> its
+      = equal_range(info);
+    for (typename map_type::iterator current = its.first;
+         current != its.second; ++current) {
+      generic_parameter<TypeInfo>& p = *current->second;
+      if (p.template can_cast<D>()) {
+        return &p;
+      }
+    }
+    throw parameter_unavailable_exception();
+  }
 };
 typedef basic_parameter_map<> parameter_map;
 }}

Modified: sandbox/boost/reflection/reflection.hpp
==============================================================================
--- sandbox/boost/reflection/reflection.hpp	(original)
+++ sandbox/boost/reflection/reflection.hpp	2008-07-19 22:24:51 EDT (Sat, 19 Jul 2008)
@@ -25,6 +25,153 @@
 
 namespace boost {
 namespace reflections {
+
+// Provide a simplified version of the class for Doxygen, as
+// well as for human consumption.
+#ifdef BOOST_REFLECTION_DOXYGEN_INVOKED
+
+template <class Info = std::string, class ParameterInfo = void,
+          class TypeInfo = extensions::default_type_info>
+class basic_reflection {
+public:
+typedef void ParameterInfo;
+  /** \brief Internal class for reflecting constructors, functions etc.
+    *
+    * The reflector class is returned by the reflect method, and can
+    * then be used to reflect constructors, functions or data.
+    * It is normally used chained:
+    * \code
+    * reflection r;
+    * r.reflect<MyClass>()
+    *  .constructor()
+    *  .constructor<int, float>();
+    * \endcode
+    */
+  template <class T>
+  class reflector
+  {
+  public:
+    /** Initialize with a pointer to the reflection
+      * this reflector will be reflecting into.
+      * This is called by the reflection::reflect function.
+      * \param current_reflection The reflection to set to type T.
+      * \pre current_reflection has not already been reflected into.
+      * \post None.
+      */
+    reflector(basic_reflection<Info, ParameterInfo, TypeInfo>*
+              current_reflection)
+      : reflection_(current_reflection) {
+    }
+
+    // Typedefs for the specific instantiations used by this class.
+    typedef basic_function_info<Info, TypeInfo, ParameterInfo> function_info;
+    typedef basic_constructor_info<TypeInfo, ParameterInfo> constructor_info;
+
+    /** \brief Reflect a constructor with params (Params...)
+      * Reflects the constructor of T that takes the arguments listed
+      * in Params...
+      * \tparam Params... A variable length list of parameters the
+      *         constructor takes.
+      * \returns *this.
+      * \pre None.
+      * \post None.
+      */
+    template <class Params...>
+    reflector& constructor() {}
+
+    /** \brief Reflect a data member of the class.
+      * \param data_ptr The fully-qualified member address of the data member.
+      * \param info A description or other Info of this data member.
+      * \tparam Data The type of the data being reflected.
+      * Reflect a data member of the class, which will be referenceable
+      * by its type and the value of the Info parameter.
+      * \code
+      * reflection r;
+      * r.reflect<MyClass>().constructor()
+      *  .data(&MyClass:someData, "someDataDescription");
+      * \endcode
+      * \pre None.
+      * \post None.
+      */
+    template <class Data>
+    reflector& data(Data T::*data_ptr, Info info) {}
+
+    /** \brief Reflect a member function of the class.
+      * \param func The fully-qualified member address of the function.
+      * \param info A description or other Info of this function.
+      * \tparam Data The function's return type.
+      * \tparam Params... The parameters of the function.
+      * Reflect a member function of the class, which will be referenceable
+      * by its type and the value of the Info parameter. The template
+      * parameters only need to be included if the function is overloaded.
+      * \code
+      * reflection r;
+      * r.reflect<MyClass>().constructor()
+      *  .function(&MyClass:someFunction, "someFuncDescription");
+      * \endcode
+      * \pre None.
+      * \post None.
+      */
+    template <class ReturnValue = void, class Params...>
+    reflector& function(void (T::*func)(), Info info) {}
+  };
+
+  /** \brief Attempt to retrieve a constructor.
+    * \tparam Params... The parameters of the requested function.
+    * \returns A constructor reference (that must be checked for validity).
+    *
+    * Attempt to retrieve any constructor whose Params match the list in
+    * Params...
+    * For example:
+    * \code
+    * r.reflect<MyClass>()
+    *  .constructor() ;
+    * instance_constructor<> ic = r.get_constructor();
+    * if (i.valid()) {
+    *   instance i = ic();
+    * }
+    * \endcode
+    * \pre None.
+    * \post None.
+    */
+  template <class Params...>
+  instance_constructor<Params...> get_constructor() const {}
+
+  /** \brief Attempt to retrieve a data member.
+    * \tparam Data The type of the requested data.
+    * \returns A data reference (that must be checked for validity).
+    *
+    * Attempt to retrieve any data of type Data and the same Info.
+    * For example:
+    * \code
+    * r.reflect<MyClass>()
+    *  .constructor()
+    *  .data(&MyClass:someInt, "My Int");
+    * instance_constructor<> ic = r.get_constructor();
+    * instance i = ic();
+    * data<int> d = r.get_data<int>("My Int");
+    * int& myIntRef = d(i);
+    * \endcode
+    * \pre None.
+    * \post None.
+    */
+  template <class Data>
+  data<Data> get_data(Info info) const {}
+
+  /** \brief Set the type of this reflection.
+    * \tparam T The type to set the reflection to.
+    * Set the type of this reflection, and return a reflector
+    * which can be used to reflect constructors, data and functions
+    * of the class T.
+    * \returns A reflector instance.
+    * \pre reflect() has not been called.
+    * \post None.
+    */
+  template <class T>
+  reflector<T> reflect() {}
+};
+
+#else
 using extensions::type_info_handler;
 namespace impl {
 template <class T>
@@ -52,9 +199,11 @@
 #include <boost/reflection/constructor_info.hpp>
 #include <boost/reflection/impl/reflection.hpp>
 #undef BOOST_REFLECTION_WITH_PARAMETER_INFO
+
 #include <boost/reflection/function_info.hpp>
 #include <boost/reflection/constructor_info.hpp>
 #include <boost/reflection/impl/reflection.hpp>
+#endif  // BOOST_REFLECTION_DOXYGEN_INVOKED
 
 typedef basic_reflection<> reflection;
 }}