|
|
Boost-Commit : |
From: eric_at_[hidden]
Date: 2008-02-21 15:12:03
Author: eric_niebler
Date: 2008-02-21 15:12:02 EST (Thu, 21 Feb 2008)
New Revision: 43362
URL: http://svn.boost.org/trac/boost/changeset/43362
Log:
doxygen comments for proto::when<>
Text files modified:
trunk/boost/xpressive/proto/literal.hpp | 2
trunk/boost/xpressive/proto/transform/bind.hpp | 36 ++++++------
trunk/boost/xpressive/proto/transform/when.hpp | 110 +++++++++++++++++++++++++++++++++++++--
3 files changed, 122 insertions(+), 26 deletions(-)
Modified: trunk/boost/xpressive/proto/literal.hpp
==============================================================================
--- trunk/boost/xpressive/proto/literal.hpp (original)
+++ trunk/boost/xpressive/proto/literal.hpp 2008-02-21 15:12:02 EST (Thu, 21 Feb 2008)
@@ -27,7 +27,7 @@
///
/// A simple wrapper for a terminal, provided for
/// ease of use. In all cases, <tt>literal\<X\> l(x);</tt>
- /// is equivalent to <tt>terminal\<X\>::type l = {x};</tt>.
+ /// is equivalent to <tt>terminal\<X\>::::type l = {x};</tt>.
///
/// The \c Domain template parameter defaults to
/// \c proto::default_domain.
Modified: trunk/boost/xpressive/proto/transform/bind.hpp
==============================================================================
--- trunk/boost/xpressive/proto/transform/bind.hpp (original)
+++ trunk/boost/xpressive/proto/transform/bind.hpp 2008-02-21 15:12:02 EST (Thu, 21 Feb 2008)
@@ -32,7 +32,7 @@
/// transformation. The invocation of the <tt>make\<\></tt> transform
/// evaluates any nested transforms, and the resulting type is treated
/// as a CallableTransform, which is evaluated with <tt>call\<\></tt>.
- template<typename Fun>
+ template<typename Object>
struct bind : proto::callable
{
template<typename Sig>
@@ -41,22 +41,23 @@
template<typename This, typename Expr, typename State, typename Visitor>
struct result<This(Expr, State, Visitor)>
{
- typedef typename make<Fun>::template result<void(Expr, State, Visitor)>::type make_;
- typedef call<make_> call_;
- typedef typename call_::template result<void(Expr, State, Visitor)>::type type;
+ typedef typename make<Object>::template result<void(Expr, State, Visitor)>::type fun;
+ typedef call<fun> impl;
+ typedef typename impl::template result<void(Expr, State, Visitor)>::type type;
};
- /// \brief Build a CallableTransform by applying <tt>make\<\></tt>
+ /// Build a CallableTransform by applying <tt>make\<\></tt>
/// and evaluate it with <tt>call\<\></tt>
+ ///
/// \param expr The current expression
/// \param state The current state
/// \param visitor An arbitrary visitor
- /// \return <tt>result\<void(Expr, State, Visitor)\>::::call_()(expr, state, visitor)</tt>
+ /// \return <tt>result\<void(Expr, State, Visitor)\>::::impl()(expr, state, visitor)</tt>
template<typename Expr, typename State, typename Visitor>
typename result<void(Expr, State, Visitor)>::type
operator ()(Expr const &expr, State const &state, Visitor &visitor) const
{
- return typename result<void(Expr, State, Visitor)>::call_()(expr, state, visitor);
+ return typename result<void(Expr, State, Visitor)>::impl()(expr, state, visitor);
}
};
@@ -67,8 +68,8 @@
/// INTERNAL ONLY
///
- template<typename Fun>
- struct is_callable<transform::bind<Fun> >
+ template<typename Object>
+ struct is_callable<transform::bind<Object> >
: mpl::true_
{};
@@ -88,8 +89,8 @@
/// transformation. The invocation of the <tt>make\<\></tt> transform
/// evaluates any nested transforms, and the resulting type is treated
/// as a CallableTransform, which is evaluated with <tt>call\<\></tt>.
- template<typename Return BOOST_PP_ENUM_TRAILING_PARAMS(N, typename A)>
- struct bind<Return(BOOST_PP_ENUM_PARAMS(N, A))> : proto::callable
+ template<typename Object BOOST_PP_ENUM_TRAILING_PARAMS(N, typename A)>
+ struct bind<Object(BOOST_PP_ENUM_PARAMS(N, A))> : proto::callable
{
template<typename Sig>
struct result;
@@ -97,22 +98,23 @@
template<typename This, typename Expr, typename State, typename Visitor>
struct result<This(Expr, State, Visitor)>
{
- typedef typename make<Return>::template result<void(Expr, State, Visitor)>::type make_;
- typedef call<make_(BOOST_PP_ENUM_PARAMS(N, A))> call_;
- typedef typename call_::template result<void(Expr, State, Visitor)>::type type;
+ typedef typename make<Object>::template result<void(Expr, State, Visitor)>::type fun;
+ typedef call<fun(BOOST_PP_ENUM_PARAMS(N, A))> impl;
+ typedef typename impl::template result<void(Expr, State, Visitor)>::type type;
};
- /// \brief Build a CallableTransform by applying <tt>make\<\></tt>
+ /// Build a CallableTransform by applying <tt>make\<\></tt>
/// and evaluate it with <tt>call\<\></tt>
+ ///
/// \param expr The current expression
/// \param state The current state
/// \param visitor An arbitrary visitor
- /// \return <tt>result\<void(Expr, State, Visitor)\>::::call_()(expr, state, visitor)</tt>
+ /// \return <tt>result\<void(Expr, State, Visitor)\>::::impl()(expr, state, visitor)</tt>
template<typename Expr, typename State, typename Visitor>
typename result<void(Expr, State, Visitor)>::type
operator ()(Expr const &expr, State const &state, Visitor &visitor) const
{
- return typename result<void(Expr, State, Visitor)>::call_()(expr, state, visitor);
+ return typename result<void(Expr, State, Visitor)>::impl()(expr, state, visitor);
}
};
Modified: trunk/boost/xpressive/proto/transform/when.hpp
==============================================================================
--- trunk/boost/xpressive/proto/transform/when.hpp (original)
+++ trunk/boost/xpressive/proto/transform/when.hpp 2008-02-21 15:12:02 EST (Thu, 21 Feb 2008)
@@ -24,8 +24,34 @@
namespace boost { namespace proto { namespace transform
{
- // Simple transform, takes a raw transform and
- // applies it directly.
+ /// \brief A grammar element and a PrimitiveTransform that associates
+ /// a transform with the grammar.
+ ///
+ /// Use <tt>when\<\></tt> to override a grammar's default transform
+ /// with a custom transform. It is for used when composing larger
+ /// transforms by associating smaller transforms with individual
+ /// rules in your grammar, as in the following transform which
+ /// counts the number of terminals in an expression.
+ ///
+ /// \code
+ /// // Count the terminals in an expression tree.
+ /// // Must be invoked with initial state == mpl::int_<0>().
+ /// struct CountLeaves
+ /// : or_<
+ /// when<terminal<_>, mpl::next<_state>()>
+ /// , otherwise<fold<_, _state, CountLeaves> >
+ /// >
+ /// {};
+ /// \endcode
+ ///
+ /// In <tt>when\<G, T\></tt>, when \c T is a class type it is a
+ /// PrimitiveTransform and the following equivalencies hold:
+ ///
+ /// <tt>when\<G,T\>::::result\<void(E,S,V)\>::::type</tt> is the same as
+ /// <tt>T::result\<void(E,S,V)\>::::type</tt>.
+ ///
+ /// <tt>when\<G,T\>()(e,s,v)</tt> is the same as
+ /// <tt>T()(e,s,v)</tt>.
template<typename Grammar, typename PrimitiveTransform BOOST_PROTO_FOR_DOXYGEN_ONLY(= Grammar)>
struct when
: PrimitiveTransform
@@ -33,11 +59,40 @@
typedef typename Grammar::proto_base_expr proto_base_expr;
};
+ /// \brief A specialization that treats function pointer Transforms as
+ /// if they were function type Transforms.
+ ///
+ /// This specialization requires that \c Fun is actually a function type.
+ ///
+ /// This specialization is required for nested transforms such as
+ /// <tt>when\<G, T0(T1(_))\></tt>. In C++, functions that are used as
+ /// parameters to other functions automatically decay to funtion
+ /// pointer types. In other words, the type <tt>T0(T1(_))</tt> is
+ /// indistinguishable from <tt>T0(T1(*)(_))</tt>. This specialization
+ /// is required to handle these nested function pointer type transforms
+ /// properly.
template<typename Grammar, typename Fun>
struct when<Grammar, Fun *>
: when<Grammar, Fun>
{};
+ /// \brief Syntactic sugar for <tt>when\<_, Fun\></tt>, for use
+ /// in grammars to handle all the cases not yet handled.
+ ///
+ /// Use <tt>otherwise\<T\></tt> in your grammars as a synonym for
+ /// <tt>when\<_, T\></tt> as in the following transform which
+ /// counts the number of terminals in an expression.
+ ///
+ /// \code
+ /// // Count the terminals in an expression tree.
+ /// // Must be invoked with initial state == mpl::int_<0>().
+ /// struct CountLeaves
+ /// : or_<
+ /// when<terminal<_>, mpl::next<_state>()>
+ /// , otherwise<fold<_, _state, CountLeaves> >
+ /// >
+ /// {};
+ /// \endcode
template<typename Fun>
struct otherwise
: when<_, Fun>
@@ -54,29 +109,68 @@
#define N BOOST_PP_ITERATION()
- template<typename Grammar, typename Return BOOST_PP_ENUM_TRAILING_PARAMS(N, typename A)>
- struct when<Grammar, Return(BOOST_PP_ENUM_PARAMS(N, A))>
+ /// \brief A grammar element and a PrimitiveTransform that associates
+ /// a transform with the grammar.
+ ///
+ /// Use <tt>when\<\></tt> to override a grammar's default transform
+ /// with a custom transform. It is for used when composing larger
+ /// transforms by associating smaller transforms with individual
+ /// rules in your grammar, as in the following transform which
+ /// counts the number of terminals in an expression.
+ ///
+ /// \code
+ /// // Count the terminals in an expression tree.
+ /// // Must be invoked with initial state == mpl::int_<0>().
+ /// struct CountLeaves
+ /// : or_<
+ /// when<terminal<_>, mpl::next<_state>()>
+ /// , otherwise<fold<_, _state, CountLeaves> >
+ /// >
+ /// {};
+ /// \endcode
+ ///
+ /// The <tt>when\<G, R(A0,A1,...)\></tt> form accepts either a
+ /// CallableTransform or an ObjectTransform as its second parameter.
+ /// <tt>when\<\></tt> uses <tt>is_callable\<R\>::::value</tt> to
+ /// distinguish between the two, and uses <tt>call\<\></tt> to
+ /// evaluate CallableTransforms and <tt>make\<\></tt> to evaluate
+ /// ObjectTransforms.
+ template<typename Grammar, typename R BOOST_PP_ENUM_TRAILING_PARAMS(N, typename A)>
+ struct when<Grammar, R(BOOST_PP_ENUM_PARAMS(N, A))>
: proto::callable
{
typedef typename Grammar::proto_base_expr proto_base_expr;
+ // Note: do not evaluate is_callable<R> in this scope.
+ // R may be an incomplete type at this point.
+
template<typename Sig>
struct result;
template<typename This, typename Expr, typename State, typename Visitor>
struct result<This(Expr, State, Visitor)>
{
+ typedef call<R(BOOST_PP_ENUM_PARAMS(N, A))> call_;
+ typedef make<R(BOOST_PP_ENUM_PARAMS(N, A))> make_;
+
typedef
- typename mpl::if_<
- is_callable<Return>
- , call<Return(BOOST_PP_ENUM_PARAMS(N, A))> // "Return" is a function to call
- , make<Return(BOOST_PP_ENUM_PARAMS(N, A))> // "Return" is an object to construct
+ typename mpl::if_c<
+ // OK to evaluate is_callable<R> here.
+ // R should be compete by now.
+ is_callable<R>::value
+ , call_ // "R" is a function to call
+ , make_ // "R" is an object to construct
>::type
impl;
typedef typename impl::template result<void(Expr, State, Visitor)>::type type;
};
+ /// Evaluate <tt>R(A0,A1,...)</tt> as a transform either with
+ /// <tt>call\<\></tt> or with <tt>make\<\></tt> depending on
+ /// whether <tt>is_callable\<R\>::::value</tt> is \c true or
+ /// \c false.
+ ///
/// \param expr The current expression
/// \param state The current state
/// \param visitor An arbitrary visitor
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