|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r67974 - sandbox/tti/libs/tti/doc
From: eldiener_at_[hidden]
Date: 2011-01-11 15:47:56
Author: eldiener
Date: 2011-01-11 15:47:54 EST (Tue, 11 Jan 2011)
New Revision: 67974
URL: http://svn.boost.org/trac/boost/changeset/67974
Log:
Updated documentation
Added:
sandbox/tti/libs/tti/doc/TTITests.qbk (contents, props changed)
sandbox/tti/libs/tti/doc/TTIToDo.qbk (contents, props changed)
Text files modified:
sandbox/tti/libs/tti/doc/TTIAcknowledgements.qbk | 4
sandbox/tti/libs/tti/doc/TTIDetail.qbk | 8 +-
sandbox/tti/libs/tti/doc/TTIFunctionality.qbk | 18 ++--
sandbox/tti/libs/tti/doc/TTIIntroduction.qbk | 15 ++-
sandbox/tti/libs/tti/doc/TTIMetafunctions.qbk | 4
sandbox/tti/libs/tti/doc/TTINestedType.qbk | 131 ++++++++++++++++++++++++++++++++++++---
sandbox/tti/libs/tti/doc/TypeTraitsIntrospection.qbk | 2
7 files changed, 146 insertions(+), 36 deletions(-)
Modified: sandbox/tti/libs/tti/doc/TTIAcknowledgements.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TTIAcknowledgements.qbk (original)
+++ sandbox/tti/libs/tti/doc/TTIAcknowledgements.qbk 2011-01-11 15:47:54 EST (Tue, 11 Jan 2011)
@@ -13,9 +13,9 @@
Two of the introspection templates are taken from the MPL and
lifted into my library under a different name for the sake
-of orthoganality, so I would like to thank Aleksey Gurtovoy,
+of orthogonality, so I would like to thank Aleksey Gurtovoy and
David Abrahams for that library, and Daniel Walker for work on
-those introspection macros.
+those MPL introspection macros.
Finally thanks to Anthony Williams for supplying a workaround
for a Visual C++ bug which is needed for introspecting member
Modified: sandbox/tti/libs/tti/doc/TTIDetail.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TTIDetail.qbk (original)
+++ sandbox/tti/libs/tti/doc/TTIDetail.qbk 2011-01-11 15:47:54 EST (Tue, 11 Jan 2011)
@@ -5,10 +5,10 @@
element has two forms, the simple one where the first macro parameter designating the
'name' of the inner element is used to create the name of the metafunction, and the
complex one where the first macro parameter, called 'trait', designates
-the name of the metafunction and the second macro parameter designates the 'name' to be queried.
-Other than that difference, the two forms of the macro produce the exact same results.
-All of the introspecting macros create a metafunction whose boolean 'value' specifies
-whether or not the inner element exists.
+the name of the metafunction and the second macro parameter designates the 'name' to be
+introspected. Other than that difference, the two forms of the macro produce the exact same
+results. All of the introspecting macros create a metafunction whose boolean 'value'
+specifies whether or not the inner element exists.
To use these metafunctions you need to include the main header file 'TTIntrospection.hpp',
unless otherwise noted.
Modified: sandbox/tti/libs/tti/doc/TTIFunctionality.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TTIFunctionality.qbk (original)
+++ sandbox/tti/libs/tti/doc/TTIFunctionality.qbk 2011-01-11 15:47:54 EST (Tue, 11 Jan 2011)
@@ -1,7 +1,7 @@
[section:tti_functionality General Functionality]
-The elements which a template metaprogrammer might be interested in finding
-out about at compile time about a type are:
+The elements about which a template metaprogrammer might be interested in finding
+out at compile time about a type are:
* Does it have a nested type with a particular name ?
* Does it have a nested type with a particular name which is a typedef for a particular type ?
@@ -30,23 +30,23 @@
macro part of the name in lower case. As an example, for the macro TTI_HAS_TYPE(MyType) the
name of the metafunction is 'tti::has_type_MyType' and it will look for an inner type
called 'MyType'.
-# In the slightly more complicated form which I call the complex form, the macro starts with
+# In the slightly more complicated form, which I call the complex form, the macro starts with
TTI\_TRAIT\_ and a 'trait' name is passed as the first parameter, with the 'name' of the inner
element as the second parameter. The 'trait' serves only to completely name the metafunction in
the tti namespace. As an example, for the macro TTI_TRAIT_HAS_TYPE(MyTrait,MyType) the name of
the metafunction is 'tti::MyTrait' and it will look for an inner type called 'MyType'.
-[important Any given macro metafunction generated, when introspecting a particular inner element, can be reused
-for any combination of template parameters which involve the same type of inner element. Once a macro metafunction
-is generated, attempting to generate another macro metafunction of the same name will create ODR violations since
-two C++ constructs with the same name/type in the same namespace will have been created. This latter possibility
-has much less chance of occurence if you use the simple form of each macro and just reuse
+[important When introspecting a particular inner element any given macro metafunction generated can be reused
+with any combination of template parameters which involve the same type of inner element. Furthermore once a macro
+metafunction is generated, attempting to generate another macro metafunction of the same name will create ODR
+violations since two C++ constructs with the same name/type in the same namespace will have been created. This
+latter possibility has much less chance of occurence if you use the simple form of each macro and just reuse
the macro metafunction. You can even do this if you are introspecting for two entities of the same name in
different enclosing types, or in the same enclosing type but with different signatures,
as with overloaded member functions.]
Once either of these two macro forms are used for a particular type of inner element, the
corresponding macro metafunction has the exact same functionality. I refer to these two macros as
-a macro pair, and their are denoted in the documentation as 'SIMPLE_FORM ( COMPLEX_FORM )'.
+a macro pair, and they are denoted in the documentation as 'SIMPLE_FORM ( COMPLEX_FORM )'.
[endsect]
Modified: sandbox/tti/libs/tti/doc/TTIIntroduction.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TTIIntroduction.qbk (original)
+++ sandbox/tti/libs/tti/doc/TTIIntroduction.qbk 2011-01-11 15:47:54 EST (Tue, 11 Jan 2011)
@@ -13,7 +13,8 @@
a type about the existence of a specific element.
I use the word "introspect" in a very broad sense here. Normally language
-introspection means initially asking for information to be initially returned by name.
+introspection means initially asking for information to be initially returned by name,
+which can then further be used to introspect for more specific information.
In the TTI library one must always supply the name, and use the functionality
for the correct type of inner element to find out if the particular named entity exists.
You may prefer the term "query" instead of "introspection" to denote what this
@@ -22,20 +23,22 @@
The functionality of the library may be summed up as:
-# Provide the means to introspect a type at compile time
+* Provide the means to introspect a type at compile time
using a set of macros. Each macro takes the name of the
type's element and generates a metafunction which can be
subsequently invoked to determine whether or not the
element exists within the type. These metafunctions
will be called macro metafunctions in the documentation.
-# Provide corresponding metafunctions which can operate
+* Provide corresponding metafunctions which can operate
on each of the macro metafunctions generated.
- These secondary metafunctions provide
+ These secondary metafunctions provide nearly
the same set of introspection as the primary ones but
allow nested types, which do not actually have to exist,
to be passed in template parameters without producing
- a compiler error. These metafunctions will be called
- nested type metafunctions in the documentation.
+ a compiler error. They also work with individual types
+ when specifying function syntax rather than a composite
+ type. These metafunctions will be called nested type
+ metafunctions in the documentation.
The library is a header only library.
Modified: sandbox/tti/libs/tti/doc/TTIMetafunctions.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TTIMetafunctions.qbk (original)
+++ sandbox/tti/libs/tti/doc/TTIMetafunctions.qbk 2011-01-11 15:47:54 EST (Tue, 11 Jan 2011)
@@ -26,7 +26,7 @@
existence the metaprogrammer is introspecting. A more detailed explanation can be found
in the reference section. All of the metafunctions are in the top-level 'tti' namespace,
all have a particular name based on the type of its functionality, and all begin with the prefix
-'mf_' so as not to conflict with the macro metafunctions in the library.
+'mf_' so as not to conflict with the macro metafunction named generated by the library.
[table:tbmetafunctions TTI Metafunctions
[
@@ -158,6 +158,6 @@
information above is that the enclosing type is a nullary metafunction,
which means that the enclosing type can be specified as the result
of using TTI\_MEMBER\_TYPE (TTI\_TRAIT\_MEMBER\_TYPE) as well as the
-result of using itself.
+result of using mf\_member\_type itself.
[endsect]
Modified: sandbox/tti/libs/tti/doc/TTINestedType.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TTINestedType.qbk (original)
+++ sandbox/tti/libs/tti/doc/TTINestedType.qbk 2011-01-11 15:47:54 EST (Tue, 11 Jan 2011)
@@ -1,6 +1,6 @@
[section:tti_nested_type Nested Types]
-[heading The Problem]
+[heading The problem]
The goal of the TTI library is never to produce a compiler error by just
using the functionality in the library, whether it is invoking its function-like macros
@@ -13,7 +13,7 @@
The metafunctions generated by the TTI macros all work with types, whether in specifying
an enclosing type or in specifying the type of some inner element, which may also involve
-types in the signature of that element. The C++ notation for
+types in the signature of that element, such as a parameter or return type of a function. The C++ notation for
a nested type, given an enclosing type 'T' and an inner type 'InnerType', is 'T::InnerType'. If either
the enclosing type 'T' does not exist, or the inner type 'InnerType' does not exist within 'T',
the expression 'T::InnerType' will give a compiler error if we attempt to use it in our template
@@ -40,25 +40,130 @@
boost::mpl::eval_if type selection statements to get to some final condition where we know we
can generate the compile-time code which we want.
-[heading The Solution]
+[heading The solution]
The TTI library offers a better solution in the form of a set of constructs which work with
nested types without producing a compiler error if the nested type does not exist, but still
are able to do the introspecting for inner elements that our TTI macro metafunctions do.
-We have already seen one of those constructs, the macro TTI_MEMBER_TYPE
-( and equivalent TTI_TRAIT_MEMBER_TYPE ), which generates a metafunction based on the name
+We have already seen one of those constructs, the macro TTI\_MEMBER\_TYPE
+( TTI\_TRAIT\_MEMBER\_TYPE ), which generates a metafunction based on the name
of an inner type. But instead of telling us whether that inner type exists it instead returns
a typedef 'type' which is that inner type if it exists, else it is an unspecified type if it
does not. In this way we have created a metafunction, very similar in functionality to
-boost::mpl::identity, but which still returns some marker 'type' if our nested type is invalid.
+boost::mpl::identity, but which still returns some unspecified marker 'type' if our nested type is invalid.
-The remaining nested type metafunctions in the TTI library use this concept of a nested type which does
-not exist not producing a compiler error to introspect the same things that our macro metafunctions
-do, but without having to use the notation 'T::InnerType' to express a nested type. Because of this we
-can avoid a compiler error when attempting to introspect enclosing types, where they may be nested types,
-or specifying the signature of inner elements which may involve nested types.
-
-These nested type metafunctions,and how they work, are more fully explained in our next section.
+We can use the functionality of TTI\_MEMBER\_TYPE ( TTI\_TRAIT\_MEMBER\_TYPE ) to construct nested types
+for our other macro metafunctions, without having to use the T::InnerType syntax and produce a compiler
+error if no such type actually exists within our scope. We can even do this in deeply nested contexts
+by stringing together, so to speak, a series of these macro metafunction results.
+
+As an example, given a type T, let us create a metafunction where there is a nested type FindType
+whose enclosing type is CType, where CType's enclosing type is BType, where BType's enclosing type
+is AType, and where AType's enclosing type is our original T. We can represent this conventially as:
+
+struct T
+ {
+ struct AType
+ {
+ struct BType
+ {
+ struct CType
+ {
+ struct FindType
+ {
+ };
+ }
+ };
+ };
+ };
+
+
+We can represent this by first creating a series of member type macros for each of our nested
+types:
+
+TTI\_MEMBER\_TYPE(FindType)
+TTI\_MEMBER\_TYPE(AType)
+TTI\_MEMBER\_TYPE(BType)
+TTI\_MEMBER\_TYPE(CType)
+
+Next we can create a typedef to reflect a nested type called FindType which has the relationship
+as specified above by instantiating our macro metafunctions.
+
+typedef typename
+tti::member\_type\_FindType
+ <
+ typename
+ tti::member\_type\_CType
+ <
+ typename
+ tti::member\_type\_BType
+ <
+ typename
+ tti::member\_type\_AType
+ <
+ T
+ >::type
+ >::type
+ >::type
+ > MyFindType;
+
+We can use the above typedef to pass the type of FindType
+to one of our macro metafunctions. FindType may not actually exist but we will not generate
+a compiler error when we use it.
+
+As one example, let's ask whether FindType has a static member data called MyData of type 'int'. We add:
+
+TTI\_HAS\_STATIC\_MEMBER(MyData)
+
+Next we create our metafunction:
+
+tti::has\_static\_member\_MyData
+ <
+ MyFindType,
+ int
+ >
+
+and use this in our metaprogramming code. Our metafunction now tells us whether the nested type
+FindType has a static member data called MyData of type 'int', even if FindType does not actually
+exist as we have specified it as a type.
+
+We can also find out whether the deeply nested type 'FindType' actually exists in a similar manner.
+Our metafunction would be:
+
+TTI\_HAS\_TYPE(FindType)
+
+tti::has\_type\_FindType
+ <
+ typename
+ tti::member\_type\_CType
+ <
+ typename
+ tti::member\_type\_BType
+ <
+ typename
+ tti::member\_type\_AType
+ <
+ T
+ >::type
+ >::type
+ >::type
+ >
+
+Because this duplicates much of our code to create our nested type as a metafunction,
+TTI\_MEMBER\_TYPE also has, as a conveniende, a boolean compile-time constant value
+called 'valid' which returns 'true' if our nested type exists or 'false' if it does not.
+
+[heading A more elegant solution]
+
+Although using TTI\_MEMBER\_TYPE represents a good solution to creating a nested type
+without the possible compile-time error of the T::InnerType syntax, reaching in to
+specify all those ::type expressions does get syntactically tedious. Because of this
+the TTI library offers a parallel set of metafunctions to the macro metafunctions
+where the 'types' used are themselves nullary metafunctions. Furthermore, composite
+types are broken down into a notation of individual types so that nested types can be
+more easily passed to these metafunctions in the formation of data and function signatures.
+This parallel set of metafunctions, using nullary metafunctions to specify individual types,
+are called 'nested type metafunctions' and are fully explained in the next section.
[endsect]
Added: sandbox/tti/libs/tti/doc/TTITests.qbk
==============================================================================
--- (empty file)
+++ sandbox/tti/libs/tti/doc/TTITests.qbk 2011-01-11 15:47:54 EST (Tue, 11 Jan 2011)
@@ -0,0 +1,20 @@
+[section:tti_tests Testing TTI]
+
+In the libs/tti/test subdirectory there is a jamfile
+which can be used to test TTI functionality.
+
+Executing the jamfile without a target will run tests
+for both basic TTI and for the variadic macro
+portion of TTI. To successfully do that you need to
+get the variadic_macro_data library from the sandbox.
+You can run tests for only the basic TTI, which is the
+vast majority of TTI functionality, by specifying only
+the 'tti' target when executing the jamfile, and therefore
+you would not need the variadic_macro_data library. If you
+just want to run the tests for the variadic macro portion
+of TTI, specify the target as 'ttiVM'.
+
+The TTI library has been tested with VC++ 8, 9, 10 and with
+gcc 4.3.0, 4.4.0, and 4.5.0-1.
+
+[endsect]
Added: sandbox/tti/libs/tti/doc/TTIToDo.qbk
==============================================================================
--- (empty file)
+++ sandbox/tti/libs/tti/doc/TTIToDo.qbk 2011-01-11 15:47:54 EST (Tue, 11 Jan 2011)
@@ -0,0 +1,9 @@
+[section:tti_todo ToDo]
+
+* Use FunctionTypes tag type for the function nested metafunctions.
+* Create mtafunctions that work with mpl lambda expressions.
+* See if function templates can be introspected.
+* Put some examples in the documentation.
+* Find a workarounnd so that gcc3+ can compile TTI correctly.
+
+[endsect]
Modified: sandbox/tti/libs/tti/doc/TypeTraitsIntrospection.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TypeTraitsIntrospection.qbk (original)
+++ sandbox/tti/libs/tti/doc/TypeTraitsIntrospection.qbk 2011-01-11 15:47:54 EST (Tue, 11 Jan 2011)
@@ -18,5 +18,7 @@
[include TTINestedType.qbk]
[include TTIMetafunctions.qbk]
[include TTIReference.qbk]
+[include TTITests.qbk]
[include TTIHistory.qbk]
+[include TTIToDo.qbk]
[include TTIAcknowledgements.qbk]
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