|
|
Boost-Commit : |
From: chochlik_at_[hidden]
Date: 2008-07-14 14:47:25
Author: matus.chochlik
Date: 2008-07-14 14:47:24 EDT (Mon, 14 Jul 2008)
New Revision: 47426
URL: http://svn.boost.org/trac/boost/changeset/47426
Log:
[mirror 0.2.x]
- Added documentation for meta_namespace
- Updated the documentation for meta_type
- Added simple documentation for meta_class
- Added several new samples into the documentation
Added:
sandbox/mirror/libs/mirror/doc/reference/meta_class.xml (contents, props changed)
sandbox/mirror/libs/mirror/doc/reference/meta_namespace.xml (contents, props changed)
sandbox/mirror/libs/mirror/doc/samples/usage_meta_type_01.xml (contents, props changed)
sandbox/mirror/libs/mirror/doc/samples/usage_meta_type_02.xml (contents, props changed)
Text files modified:
sandbox/mirror/libs/mirror/doc/mirror.xml | 1
sandbox/mirror/libs/mirror/doc/reference.xml | 2 +
sandbox/mirror/libs/mirror/doc/reference/meta_type.xml | 67 +++++++++++++++++++++++++++++----------
sandbox/mirror/libs/mirror/example/special/std_pair.cpp | 4 +-
4 files changed, 55 insertions(+), 19 deletions(-)
Modified: sandbox/mirror/libs/mirror/doc/mirror.xml
==============================================================================
--- sandbox/mirror/libs/mirror/doc/mirror.xml (original)
+++ sandbox/mirror/libs/mirror/doc/mirror.xml 2008-07-14 14:47:24 EDT (Mon, 14 Jul 2008)
@@ -12,6 +12,7 @@
<firstname>Matúš</firstname>
<surname>ChochlÃk</surname>
<email>chochlik -at- gmail.com</email>
+ <email>Matus.Chochlik -at- fri.uniza.sk</email>
</author>
<copyright>
Modified: sandbox/mirror/libs/mirror/doc/reference.xml
==============================================================================
--- sandbox/mirror/libs/mirror/doc/reference.xml (original)
+++ sandbox/mirror/libs/mirror/doc/reference.xml 2008-07-14 14:47:24 EDT (Mon, 14 Jul 2008)
@@ -6,6 +6,8 @@
<para>
</para>
+ <xi:include href="reference/meta_namespace.xml"/>
<xi:include href="reference/meta_type.xml"/>
+ <xi:include href="reference/meta_class.xml"/>
</library-reference>
Added: sandbox/mirror/libs/mirror/doc/reference/meta_class.xml
==============================================================================
--- (empty file)
+++ sandbox/mirror/libs/mirror/doc/reference/meta_class.xml 2008-07-14 14:47:24 EDT (Mon, 14 Jul 2008)
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<header name="boost/mirror/meta_class.hpp">
+ <namespace name="boost">
+ <namespace name="mirror">
+ <class name="meta_class">
+ <template>
+ <template-type-parameter name="Class"/>
+ <!--
+ <template-type-parameter name="VariantTag"/>
+ -->
+ </template>
+ <purpose>
+ <para>
+ This class template is to provides meta-data
+ about the reflected class.
+ </para>
+ <para>
+ Although the specializations of <code><classname>meta_class</classname></code>
+ template can be used directly to get the meta data about a particular class (or type),
+ it is recomended to use the reflection macro
+ <code><macroname>BOOST_MIRRORED_CLASS</macroname>(CLASS)</code>
+ instead, to get the proper specializations of
+ <code><classname>meta_class</classname></code>.
+ </para>
+ </purpose>
+ <inherit access="public">
+ <type><classname>meta_type</classname><Class></type>
+ <purpose>
+ <para>The basic type meta-information about the reflected class.
+ </para>
+ </purpose>
+ </inherit>
+
+ <access name="public">
+ <typedef name="base_classes">
+ <type><emphasis>unspecified</emphasis></type>
+ <purpose>The list of base classes</purpose>
+ <description>
+ <para>
+ </para>
+ </description>
+ </typedef>
+ <typedef name="attributes">
+ <type><emphasis>unspecified</emphasis></type>
+ <purpose>The own attributes of the class</purpose>
+ <description>
+ <para>
+ </para>
+ </description>
+ </typedef>
+ <typedef name="all_attributes">
+ <type><emphasis>unspecified</emphasis></type>
+ <purpose>All attributes of the class including the inherited ones</purpose>
+ <description>
+ <para>
+ </para>
+ </description>
+ </typedef>
+ </access>
+ </class>
+ </namespace><!-- mirror -->
+ </namespace><!-- boost -->
+</header>
Added: sandbox/mirror/libs/mirror/doc/reference/meta_namespace.xml
==============================================================================
--- (empty file)
+++ sandbox/mirror/libs/mirror/doc/reference/meta_namespace.xml 2008-07-14 14:47:24 EDT (Mon, 14 Jul 2008)
@@ -0,0 +1,173 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<header name="boost/mirror/meta_namespace.hpp">
+ <namespace name="boost">
+ <namespace name="mirror">
+ <class name="meta_namespace">
+ <template>
+ <template-type-parameter name="NamespacePlaceholder"/>
+ </template>
+ <purpose>
+ <para>
+ This class template provides meta-data
+ about the reflected namespace, especially allows to get the
+ base and full namespace name and to
+ get information about the scope inside of which this namespace
+ has been defined.
+ </para>
+ <para>
+ To obtain a <code><classname>meta_namespace</classname></code> for a particular
+ namespace (with the exception of the global scope) use the reflection
+ macro <code><macroname>BOOST_MIRRORED_NAMESPACE</macroname>(FULL_NAMESPACE_NAME)</code>. To
+ get the <code><classname>meta_namespace</classname></code> specialization for
+ the global scope use the <code><macroname>BOOST_MIRRORED_NAMESPACE</macroname>()</code>
+ macro.
+ </para>
+ </purpose>
+
+ <access name="public">
+ <typedef name="scope">
+ <type><emphasis>unspecified</emphasis></type>
+ <purpose>Meta-namespace describing the scope where the reflected namespace is defined</purpose>
+ <description>
+ <para>A meta-object describing the scope in which the reflected namespace
+ is defined. It is a specialization of <code><classname>meta_namespace</classname></code>
+ with the exception of the meta-namespace reflecting the global scope where
+ this type is not defined.
+ </para>
+ <para>To find out whether a meta-namespace reflects the global scope
+ use the <code><classname>reflects_global_scope</classname></code> template meta-function.
+ </para>
+ </description>
+ </typedef>
+ <typedef name="ancestors">
+ <type><emphasis>unspecified</emphasis></type>
+ <purpose>mpl::vector containing the whole path to the reflected namespace</purpose>
+ <description>
+ <para>An <code>mpl::vector</code> containing the <code><classname>meta_namespace</classname></code>
+ specializations for all the namespaces in which the reflected namespace is
+ directly or indirectly nested (not-containing the <code><classname>meta_namespace</classname></code>
+ for the reflected namespace). The elements of this <code>mpl::vector</code> are
+ ordered from the <code><classname>meta_namespace</classname></code> reflecting
+ the global scope to the <code><classname>meta_namespace</classname></code>
+ reflecting the parent namespace. The following holds
+ for <code><classname>meta_namespace</classname></code>s
+ reflecting any namespace with the exception of the global scope:
+ </para>
+ <programlisting>
+using namespace ::boost;
+using namespace ::boost::mirror;
+
+BOOST_MPL_ASSERT((
+ reflects_global_scope <
+ mpl::front <
+ BOOST_MIRRORED_NAMESPACE(::std)::ancestors
+ >
+ >
+));
+
+BOOST_MPL_ASSERT((
+ reflects_global_scope <
+ mpl::front <
+ BOOST_MIRRORED_NAMESPACE(::boost::mirror)::ancestors
+ >
+ >
+));
+
+BOOST_MPL_ASSERT((
+ is_same <
+ mpl::back <
+ BOOST_MIRRORED_NAMESPACE(::boost::mirror)::ancestors
+ >,
+ BOOST_MIRRORED_NAMESPACE(::boost::mirror)::scope
+ >
+));
+ </programlisting>
+ <para>For the <code><classname>meta_namespace</classname></code>
+ reflecting the global scope the following holds true.
+ </para>
+
+ <programlisting>
+BOOST_MPL_ASSERT((
+ mpl::empty <
+ BOOST_MIRRORED_GLOBAL_SCOPE()::ancestors
+ >
+));
+ </programlisting>
+ <para>To find out whether a meta-namespace reflects the global scope
+ use the <code><classname>reflects_global_scope</classname></code> template meta-function.
+ </para>
+ </description>
+ </typedef>
+ <method name="base_name">
+ <type>const <classname>bstring</classname>&</type>
+ <purpose>
+ <para>This static member function returns the base name of the
+ namespace reflected by a <code><classname>meta_namespace</classname></code>.
+ For example the base namespace name "returned" by the invocation of
+ <programlisting><macroname>BOOST_MIRRORED_NAMESPACE</macroname>(::boost::mirror) :: base_name()
+ </programlisting>
+ is <code>"mirror"</code>. When a full namespace name
+ <emphasis role="bold">with</emphasis> the nested name specifier
+ is needed use the <methodname>full_name</methodname> member function
+ instead.</para>
+ </purpose>
+ </method>
+ <method name="full_name">
+ <type>const <classname>bstring</classname>&</type>
+ <purpose>
+ <para>This static member function returns the full name of the
+ namespace reflected by a <code><classname>meta_namespace</classname></code>
+ with the nested name specifier. For example:
+ <programlisting><classname>BOOST_MIRRORED_NAMESPACE</classname>(::boost::mirror) :: full_name()
+ </programlisting>
+ returns <code>"::boost::mirror"</code>. When the base namespace name
+ <emphasis role="bold">without</emphasis> the nested name specifier
+ is needed use the <methodname>base_name</methodname> member function
+ instead.</para>
+ </purpose>
+ <notes>
+ <para>The first call to this function can be expensive
+ for deeply nested namespaces, because the name needs to be properly composed from
+ the base namespace names, which may
+ lead to multiple string concatenations. Subsequent calls to this member function
+ for a concrete specialization of <classname>meta_namespace</classname>
+ are usually much faster.
+ </para>
+ </notes>
+ </method>
+ <method name="get_name">
+ <template>
+ <template-nontype-parameter name="FullName">
+ <type>bool</type>
+ </template-nontype-parameter>
+ </template>
+ <type>const <classname>bstring</classname>&</type>
+ <parameter name="full">
+ <paramtype>::boost::mpl::bool_<FullName></paramtype>
+ </parameter>
+ <purpose>
+ <para>This static member template function returns either the base name
+ <emphasis role="bold">without</emphasis> the nested name specifier
+ or the full name <emphasis role="bold">with</emphasis> the
+ nested name specifier of the namespace reflected by this
+ <code><classname>meta_namespace</classname></code>,
+ depending on the value of the template argument <code>FullName</code>.
+ For example:
+ <programlisting><classname>BOOST_MIRRORED_NAMESPACE</classname>(::boost::mirror) :: get_name(::boost::mpl::false_())
+ </programlisting> is equivalent to calling the
+ <code><methodname>base_name</methodname></code> member function and
+ returns simply <code>"mirror"</code> and calling
+ <programlisting><classname>BOOST_MIRRORED_NAMESPACE</classname>(::boost::mirror) :: get_name(::boost::mpl::true_())
+ </programlisting> is equivalent to calling the
+ <code><methodname>full_name</methodname></code> method which
+ returns <code>"::boost::mirror"</code>.
+ </para>
+ </purpose>
+ </method>
+ </access>
+ </class>
+ </namespace><!-- mirror -->
+ </namespace><!-- boost -->
+</header>
Modified: sandbox/mirror/libs/mirror/doc/reference/meta_type.xml
==============================================================================
--- sandbox/mirror/libs/mirror/doc/reference/meta_type.xml (original)
+++ sandbox/mirror/libs/mirror/doc/reference/meta_type.xml 2008-07-14 14:47:24 EDT (Mon, 14 Jul 2008)
@@ -9,15 +9,13 @@
<template-type-parameter name="Type"/>
</template>
<purpose>
- <para>
- The purpose of this class template is to provide meta-data
+ <para>The purpose of this class template is to provide meta-data
about the reflected type, especially to allow to get the
base and full type name, of the reflected type and to
get information about the scope inside of which this type
has been declared.
</para>
- <para>
- Although the specializations of <code><classname>meta_type</classname></code>
+ <para>Although the specializations of <code><classname>meta_type</classname></code>
template can be used directly to get the meta data about a particular type,
it is recomended to use the reflection macros like
<code><macroname>BOOST_MIRRORED_TYPE</macroname>(TYPE)</code> or
@@ -26,6 +24,34 @@
<code><classname>meta_type</classname></code>.
</para>
</purpose>
+ <description>
+ <para>The specializations of <code><classname>meta_type</classname></code> can
+ be used to get meta-information about the reflected types at both compile-time and run-time.
+ The following examples show type reflection and basic
+ <code><classname>meta_type</classname></code> usage. Mirror works with the native C++ types
+ and some of the very common types like <code>::std::string</code>, etc. out of the box.
+ Meta-types for many other types from the standard library and <libraryname>Boost</libraryname>
+ are also provided and can be <code>#include</code>d when necessary.
+ </para>
+ <section id="mirror.meta_type.reference.samples">
+ <section id="mirror.meta_type.reference.sample01">
+ <title>Example - Basic usage</title>
+ <para>This sample code shows how to reflect a type and how to get its full type name.
+ Since various specializations of <code>::std::pair</code> are reflected,
+ the <code><classname>meta_type</classname></code>s for this template need to be
+ included.
+ </para>
+ <xi:include href="../samples/usage_meta_type_01.xml"/>
+ </section>
+ <section id="mirror.meta_type.reference.sample02">
+ <title>Example - Using with typeof and getting scope-related information</title>
+ <para>The following example shows cooperation with the <libraryname>Typeof</libraryname>
+ library and scope-related operations.
+ </para>
+ <xi:include href="../samples/usage_meta_type_02.xml"/>
+ </section>
+ </section>
+ </description>
<access name="public">
<typedef name="reflected_type">
@@ -53,16 +79,19 @@
<para>This static member function returns the base name of the
type reflected by <code><classname>meta_type</classname></code>
without the nested name specifier. For example:
- <code><classname>meta_type</classname> < ::std::string > :: base_name()</code>
+ <programlisting><macroname>BOOST_MIRRORED_TYPE</macroname>(::std::string) :: base_name()
+ </programlisting> or
+ <programlisting><classname>meta_type</classname> < ::std::string > :: base_name()
+ </programlisting>
returns simply <code>"string"</code>. When a full type name
- <emphasis role="bold">with</emphasis> nested name specifier
- is needed use the <functionname>full_name</functionname> member function
+ <emphasis role="bold">with</emphasis> the nested name specifier
+ is needed use the <methodname>full_name</methodname> member function
instead.</para>
</purpose>
<notes>
<para>The first call to this function can be expensive
for derived types like pointers, references, cv-qualified
- types etc. because the type name needs to be properly composed from
+ types, arrays etc. because the type name needs to be properly composed from
the base type name, which may depending on the complexity of the type
lead to multiple string concatenations. Subsequent calls to this member function
for a concrete specialization of <classname>meta_type</classname>
@@ -76,16 +105,19 @@
<para>This static member function returns the full name of the
type reflected by <code><classname>meta_type</classname></code>
with the nested name specifier. For example:
- <code><classname>meta_type</classname> < ::std::string > :: full_name()</code>
+ <programlisting><macroname>BOOST_MIRRORED_TYPE</macroname>(::std::string) :: full_name()
+ </programlisting> or
+ <programlisting><classname>meta_type</classname> < ::std::string > :: full_name()
+ </programlisting>
returns <code>"::std::string"</code>. When the base type name
<emphasis role="bold">without</emphasis> the nested name specifier
- is needed use the <functionname>base_name</functionname> member function
+ is needed use the <methodname>base_name</methodname> member function
instead.</para>
</purpose>
<notes>
<para>The first call to this function can be expensive
for derived types like pointers, references, cv-qualified
- types etc. because the type name needs to be properly composed from
+ types, arrays etc. because the type name needs to be properly composed from
the base type name, which may depending on the complexity of the type
lead to multiple string concatenations. Subsequent calls to this member function
for a concrete specialization of <classname>meta_type</classname>
@@ -111,13 +143,14 @@
<code><classname>meta_type</classname></code>,
depending on the value of the template argument <code>FullName</code>.
For example:
- <code><classname>meta_type</classname> < ::std::string > :: get_name(
- ::boost::mpl::false_())</code> is equivalent to calling the
- <code><functionname>base_name</functionname></code> member function and
+ <programlisting><macroname>meta_type</macroname>(::std::string) :: get_name(::boost::mpl::false_())</programlisting> or
+ <programlisting><classname>meta_type</classname> < ::std::string > :: get_name(::boost::mpl::false_())</programlisting>
+ is equivalent to calling the
+ <code><methodname>base_name</methodname></code> member function and
returns simply <code>"string"</code> and
- <code><classname>meta_type</classname> < ::std::string > :: get_name(
- ::boost::mpl::true_())</code> is equivalent to calling the
- <code><functionname>full_name</functionname></code> method which
+ <programlisting><macroname>meta_type</macroname>(::std::string) :: get_name(::boost::mpl::true_())</programlisting> or
+ <programlisting><classname>meta_type</classname> < ::std::string > :: get_name( ::boost::mpl::true_())</programlisting> is equivalent to calling the
+ <code><methodname>full_name</methodname></code> method which
returns <code>"::std::string"</code>.
</para>
</purpose>
Added: sandbox/mirror/libs/mirror/doc/samples/usage_meta_type_01.xml
==============================================================================
--- (empty file)
+++ sandbox/mirror/libs/mirror/doc/samples/usage_meta_type_01.xml 2008-07-14 14:47:24 EDT (Mon, 14 Jul 2008)
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<programlisting id="mirror.reference.sample.meta_type.usage01">
+
+#include <iostream>
+#include <boost/mirror/meta_type.hpp>
+#include <boost/mirror/meta_types/std_pair.hpp>
+
+int main(void)
+{
+ using namespace ::std;
+ using namespace ::boost;
+ using namespace ::boost::mirror;
+
+ // define a little more complex type
+ typedef pair<const int*, double [654][321]> T1;
+ typedef pair<float, const ::std::string&> T2;
+ typedef pair<T1 const volatile, T2 volatile const> T3;
+ typedef pair<T2, T1 volatile> T4;
+ typedef T4 (T)(const T1&, T2, volatile T3*);
+
+ // reflect it using mirror
+ typedef BOOST_MIRRORED_TYPE(T) meta_T;
+
+ // print out the full type name
+ wcout << "The full type name is: "<< meta_T::full_name() << endl;
+
+ return 0;
+}
+</programlisting>
+
Added: sandbox/mirror/libs/mirror/doc/samples/usage_meta_type_02.xml
==============================================================================
--- (empty file)
+++ sandbox/mirror/libs/mirror/doc/samples/usage_meta_type_02.xml 2008-07-14 14:47:24 EDT (Mon, 14 Jul 2008)
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<programlisting id="mirror.reference.sample.meta_type.usage02">
+
+#include <iostream>
+#include <string>
+#include <boost/typeof/typeof.hpp>
+#include <boost/mirror/meta_type.hpp>
+#include <boost/mirror/meta_types/std_pair.hpp>
+#include <boost/mirror/traits/reflects_global_scope.hpp>
+
+template <class MetaType>
+void print_meta_data(void)
+{
+ using namespace ::std;
+ using namespace ::boost;
+ using namespace ::boost::mirror;
+
+ // print out the base type name
+ wcout << "The type name is: "<< MetaType::base_name() << endl;
+ //
+ if(reflects_global_scope<MetaType::scope>::value)
+ wcout << "It's defined on the global scope" << endl;
+ else wcout <<
+ "It's defined in the " <<
+ MetaType::scope::full_name() <<
+ " namespace" << endl;
+ wcout << "--------------------------------------" << endl;
+}
+
+int main(void)
+{
+ using namespace ::std;
+ using namespace ::boost;
+ using namespace ::boost::mirror;
+
+ // reflect the type of an expression
+ // and print the meta-data
+ print_meta_data< BOOST_MIRRORED_TYPEOF(1+2) >();
+ print_meta_data< BOOST_MIRRORED_TYPEOF(1.0+2.0) >();
+ print_meta_data< BOOST_MIRRORED_TYPEOF("1" "+" "2") >();
+ print_meta_data< BOOST_MIRRORED_TYPEOF(string("1")+string("2")) >();
+
+ // another possibility
+ print_meta_data< BOOST_MIRRORED_TYPE(
+ BOOST_TYPEOF(L"1" L"+" L"2")
+ ) >();
+ print_meta_data< BOOST_MIRRORED_TYPE(
+ BOOST_TYPEOF(wstring(L"1")+wstring(L"2"))
+ ) >();
+
+ return 0;
+}
+</programlisting>
+
Modified: sandbox/mirror/libs/mirror/example/special/std_pair.cpp
==============================================================================
--- sandbox/mirror/libs/mirror/example/special/std_pair.cpp (original)
+++ sandbox/mirror/libs/mirror/example/special/std_pair.cpp 2008-07-14 14:47:24 EDT (Mon, 14 Jul 2008)
@@ -27,11 +27,11 @@
using namespace ::boost::mirror;
//
//
- typedef pair<const int*, double [321]> T1;
+ typedef pair<const int*, double [654][321]> T1;
typedef pair<float, const ::std::string&> T2;
typedef pair<T1 const volatile, T2 volatile const> T3;
typedef pair<T2, T1 volatile> T4;
- typedef pair<T3 const * volatile *, const T4&> T;
+ typedef T4 (T)(const T1&, T2, volatile T3*);
//
typedef BOOST_MIRRORED_CLASS(T) meta_T;
//
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk