|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r79678 - in trunk/libs/proto/doc: . reference/transform
From: eric_at_[hidden]
Date: 2012-07-22 16:03:42
Author: eric_niebler
Date: 2012-07-22 16:03:41 EDT (Sun, 22 Jul 2012)
New Revision: 79678
URL: http://svn.boost.org/trac/boost/changeset/79678
Log:
add reference section for new transform environment functionality
Added:
trunk/libs/proto/doc/reference/transform/env.xml (contents, props changed)
Text files modified:
trunk/libs/proto/doc/reference.xml | 86 ++++++++++++++++++++++++++++++++++++++++
trunk/libs/proto/doc/reference/transform/arg.xml | 61 ++++++++++-----------------
trunk/libs/proto/doc/reference/transform/when.xml | 86 +++++++++++++++++++++++++++++++++++++++
3 files changed, 193 insertions(+), 40 deletions(-)
Modified: trunk/libs/proto/doc/reference.xml
==============================================================================
--- trunk/libs/proto/doc/reference.xml (original)
+++ trunk/libs/proto/doc/reference.xml 2012-07-22 16:03:41 EDT (Sun, 22 Jul 2012)
@@ -44,6 +44,16 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::_env">proto::_env</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
+ <classname alt="boost::proto::_env_var">proto::_env_var</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::_expr">proto::_expr</classname>
</computeroutput>
</listitem>
@@ -204,6 +214,11 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::data_type">proto::data_type</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::deduce_domain">proto::deduce_domain</classname>
</computeroutput>
</listitem>
@@ -254,6 +269,16 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::empty_env">proto::empty_env</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
+ <classname alt="boost::proto::env">proto::env</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::equal_to">proto::equal_to</classname>
</computeroutput>
</listitem>
@@ -304,6 +329,11 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::functional::as_env">proto::functional::as_env</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::functional::as_expr">proto::functional::as_expr</classname>
</computeroutput>
</listitem>
@@ -334,6 +364,11 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::functional::env_var">proto::functional::env_var</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::functional::eval">proto::functional::eval</classname>
</computeroutput>
</listitem>
@@ -349,6 +384,11 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::functional::has_env_var">proto::functional::has_env_var</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::functional::left">proto::functional::left</classname>
</computeroutput>
</listitem>
@@ -459,6 +499,11 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::is_env">proto::is_env</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::is_expr">proto::is_expr</classname>
</computeroutput>
</listitem>
@@ -479,6 +524,11 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::key_not_found">proto::key_not_found</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::lazy">proto::lazy</classname>
</computeroutput>
</listitem>
@@ -664,6 +714,11 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::result_of::as_env">proto::result_of::as_env</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::result_of::as_expr">proto::result_of::as_expr</classname>
</computeroutput>
</listitem>
@@ -684,6 +739,11 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::result_of::env_var">proto::result_of::env_var</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::result_of::eval">proto::result_of::eval</classname>
</computeroutput>
</listitem>
@@ -694,6 +754,11 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::result_of::has_env_var">proto::result_of::has_env_var</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::result_of::left">proto::result_of::left</classname>
</computeroutput>
</listitem>
@@ -1009,6 +1074,11 @@
</listitem>
<listitem>
<computeroutput>
+ <classname alt="boost::proto::transforms_type">proto::transforms_type</classname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<classname alt="boost::proto::transform_impl">proto::transform_impl</classname>
</computeroutput>
</listitem>
@@ -1060,6 +1130,11 @@
</listitem>
<listitem>
<computeroutput>
+ <functionname alt="boost::proto::as_env">proto::as_env()</functionname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<functionname alt="boost::proto::as_expr">proto::as_expr()</functionname>
</computeroutput>
</listitem>
@@ -1095,6 +1170,11 @@
</listitem>
<listitem>
<computeroutput>
+ <functionname alt="boost::proto::env_var">proto::env_var()</functionname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<functionname alt="boost::proto::eval">proto::eval()</functionname>
</computeroutput>
</listitem>
@@ -1105,6 +1185,11 @@
</listitem>
<listitem>
<computeroutput>
+ <functionname alt="boost::proto::has_env_var">proto::has_env_var()</functionname>
+ </computeroutput>
+ </listitem>
+ <listitem>
+ <computeroutput>
<functionname alt="boost::proto::if_else">proto::if_else()</functionname>
</computeroutput>
</listitem>
@@ -1176,6 +1261,7 @@
<xi:include href="reference/transform/arg.xml"/>
<xi:include href="reference/transform/call.xml"/>
<xi:include href="reference/transform/default.xml"/>
+ <xi:include href="reference/transform/env.xml"/>
<xi:include href="reference/transform/fold.xml"/>
<xi:include href="reference/transform/fold_tree.xml"/>
<xi:include href="reference/transform/impl.xml"/>
Modified: trunk/libs/proto/doc/reference/transform/arg.xml
==============================================================================
--- trunk/libs/proto/doc/reference/transform/arg.xml (original)
+++ trunk/libs/proto/doc/reference/transform/arg.xml 2012-07-22 16:03:41 EDT (Sun, 22 Jul 2012)
@@ -120,14 +120,27 @@
<struct name="_data">
<inherit><classname>proto::transform</classname>< _data ></inherit>
- <purpose>A <conceptname>PrimitiveTransform</conceptname> that returns the current data unmodified. </purpose>
+ <purpose>
+ A <conceptname>PrimitiveTransform</conceptname> that returns the current data unmodified.
+ If the data (third) parameter is a transform environment, it returns the value associated
+ with the <code><classname>proto::data_type</classname></code> key. Otherwise, it returns
+ the data parameter unmodified.
+ </purpose>
<description>
<para>
- Example:
+ If the data (third) parameter is a transform environment, it returns the value associated
+ with the <code><classname>proto::data_type</classname></code> key. Otherwise, it returns
+ the data parameter unmodified.
+ </para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
<programlisting><classname>proto::terminal</classname><int>::type i = {42};
std::string str("hello");
-std::string & data = proto::_data()(i, 'a', str);
-assert( &str == &data );</programlisting>
+std::string & d1 = proto::_data()(i, 'a', str);
+assert( &str == &d1 );
+
+std::string & d2 = proto::_data()(i, 'a', (<globalname>proto::data</globalname> = boost::ref(str)));
+assert( &str == &d2 );</programlisting>
</para>
</description>
<struct name="impl">
@@ -136,40 +149,12 @@
<template-type-parameter name="State"/>
<template-type-parameter name="Data"/>
</template>
- <inherit><classname>proto::transform_impl</classname>< Expr, State, Data ></inherit>
- <typedef name="result_type">
- <type>Data</type>
- </typedef>
- <method-group name="public member functions">
- <method name="operator()" cv="const">
- <type>Data</type>
- <parameter name="">
- <paramtype>typename impl::expr_param</paramtype>
- </parameter>
- <parameter name="">
- <paramtype>typename impl::state_param</paramtype>
- </parameter>
- <parameter name="data">
- <paramtype>typename impl::data_param</paramtype>
- <description>
- <para>The current data. </para>
- </description>
- </parameter>
- <description>
- <para>
- Returns the current data.
- </para>
- </description>
- <returns>
- <para>
- <computeroutput>data</computeroutput>
- </para>
- </returns>
- <throws>
- <simpara>Will not throw.</simpara>
- </throws>
- </method>
- </method-group>
+ <inherit><type>
+ mpl::if_c<
+ <classname>proto::is_env</classname><Data>::value,
+ <classname>proto::_env_var</classname><<classname>proto::data_type</classname>>,
+ <classname>proto::_env</classname>
+ >::type::template impl<Expr, State, Data></type></inherit>
</struct>
</struct>
Added: trunk/libs/proto/doc/reference/transform/env.xml
==============================================================================
--- (empty file)
+++ trunk/libs/proto/doc/reference/transform/env.xml 2012-07-22 16:03:41 EDT (Sun, 22 Jul 2012)
@@ -0,0 +1,775 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ Copyright 2012 Eric Niebler
+
+ Distributed under the Boost
+ Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ -->
+<header name="boost/proto/transform/env.hpp">
+ <namespace name="boost">
+ <namespace name="proto">
+
+ <struct name="key_not_found">
+ <purpose>
+ The type of objects returned when a key-based lookup fails in a
+ transform environment.
+ </purpose>
+ </struct>
+
+ <!-- empty_env -->
+ <struct name="empty_env">
+ <purpose>
+ The type of an object that represents a transform environment
+ with no key/value pairs in it.
+ </purpose>
+
+ <method-group name="public member functions">
+ <method name="operator[]" cv="const">
+ <type><classname>proto::key_not_found</classname></type>
+ <parameter name="">
+ <paramtype><replaceable>unspecified</replaceable></paramtype>
+ </parameter>
+ <description>
+ <para>The type of the argument to this function has a
+ user-defined implicit conversion from any type.</para>
+ </description>
+ </method>
+ </method-group>
+ </struct>
+
+ <!-- env -->
+ <struct name="env">
+ <template>
+ <template-type-parameter name="Key"/>
+ <template-type-parameter name="Value"/>
+ <template-type-parameter name="Env">
+ <default><classname>proto::empty_env</classname></default>
+ </template-type-parameter>
+ </template>
+
+ <constructor specifiers="explicit">
+ <parameter name="value">
+ <paramtype>Value const &</paramtype>
+ <description>
+ <para>
+ The value to be associated with the <code>Key</code>.
+ </para>
+ </description>
+ </parameter>
+ <parameter name="other">
+ <paramtype>Env const &</paramtype>
+ <default>Env()</default>
+ <description>
+ <para>
+ Another key/value store.
+ </para>
+ </description>
+ </parameter>
+ </constructor>
+
+ <method-group name="public member functions">
+ <method name="operator[]" cv="const">
+ <type><replaceable>see-below</replaceable></type>
+ <parameter name="">
+ <paramtype><replaceable>see-below</replaceable></paramtype>
+ </parameter>
+ <description>
+ <para>
+ If called with an object that is implicitly convertible to type <code>Key</code>,
+ this function returns the <code>Value</code> passed to the constructor. Otherwise, it returns
+ the result of calling <code>operator[]</code> on the <code>Env</code> passed to
+ the constructor.
+ </para>
+ </description>
+ </method>
+ </method-group>
+ </struct>
+
+ <!-- is_env -->
+ <struct name="is_env">
+ <template>
+ <template-type-parameter name="T"/>
+ </template>
+ <inherit><type>mpl::bool_<<replaceable>true-or-false</replaceable>></type></inherit>
+ <purpose>
+ <para>A Boolean metafuntion for determining whether or not a type is a Proto
+ transform environment.</para>
+ </purpose>
+ <description>
+ <para><code>is_env<T></code> inherits from <code>mpl::true_</code> under the following
+ conditions:
+ <itemizedlist>
+ <listitem>If <code>T</code> is <classname>proto::empty_env</classname>.</listitem>
+ <listitem>If <code>T</code> is a specialization of <classname>proto::env<></classname>.</listitem>
+ <listitem>If <code>T</code> is derived from any of the above.</listitem>
+ <listitem>If <code>T</code> is a cv-qualified variant of any of the above.</listitem>
+ <listitem>If <code>T</code> is a reference to any of the above.</listitem>
+ </itemizedlist>
+ </para>
+ <para>Otherwise, <code>is_env<T></code> inherits from <code>mpl::false_</code>.
+ </para>
+ </description>
+ </struct>
+
+ <struct name="data_type">
+ <purpose>
+ The type of <code><globalname>proto::data</globalname></code>, a key for use when creating
+ a transform environment that associates a piece of data with this type.
+ </purpose>
+ <description>
+ <para>
+ The <code>proto::data_type</code> type, along with the <code><globalname>proto::data</globalname></code>
+ global, are declared using the <code><macroname>BOOST_PROTO_DEFINE_ENV_VAR</macroname>()</code> macro.
+ </para>
+ </description>
+ <method-group name="public member functions">
+ <overloaded-method name="operator=">
+ <signature cv="const">
+ <template>
+ <template-type-parameter name="Value"/>
+ </template>
+ <type><classname>env</classname><data_type, <replaceable>see-below</replaceable>></type>
+ <parameter name="value">
+ <paramtype>Value &</paramtype>
+ </parameter>
+ </signature>
+ <signature cv="const">
+ <template>
+ <template-type-parameter name="Value"/>
+ </template>
+ <type><classname>env</classname><data_type, <replaceable>see-below</replaceable>></type>
+ <parameter name="value">
+ <paramtype>Value const &</paramtype>
+ </parameter>
+ </signature>
+ <description>
+ <para>
+ If <code>Value</code> is a specialization <code>boost::reference_wrapper<T></code>,
+ this function returns <code><classname>env</classname><data_type, T &>(value.get())</code>.
+ </para>
+ <para>
+ Else, if the type <code>Value</code> is non-copyable (i.e., a function, an array, abstract, or an ostream),
+ this function returns <code><classname>env</classname><data_type, Value <replaceable>cv</replaceable> &>(value)</code>,
+ where <code><replaceable>cv</replaceable></code> is <code>const</code> for the second overload, and empty
+ for the first.
+ </para>
+ <para>
+ Otherwise, this function returns <code><classname>env</classname><data_type, Value>(value)</code>.
+ </para>
+ </description>
+ </overloaded-method>
+ </method-group>
+ </struct>
+
+ <data-member name="data">
+ <description>
+ <para>A key used for creating a transform environment.</para>
+ </description>
+ <type><classname>proto::data_type</classname> const</type>
+ </data-member>
+
+ <namespace name="functional">
+
+ <!-- functional::as_env -->
+ <struct name="as_env">
+ <inherit><classname>proto::callable</classname></inherit>
+ <purpose>
+ A unary <conceptname>PolymorphicFunctionObject</conceptname> for ensuring that an object
+ is a transform environment. If it isn't already, it is turned into one such that the
+ object is associated with the <classname>proto::data_type</classname> key.
+ </purpose>
+ <struct name="result">
+ <template>
+ <template-type-parameter name="Sig"/>
+ </template>
+ <typedef name="type">
+ <type><replaceable>see-below</replaceable></type>
+ <description>
+ <para>See <code><methodname>proto::functional::as_env::operator()</methodname></code>.</para>
+ </description>
+ </typedef>
+ <description>
+ <para>
+ Encodes the return type of <code><methodname>proto::functional::as_env::operator()</methodname></code>.
+ The presence of this member template makes <code><classname>proto::functional::as_env</classname></code>
+ a valid TR1-style function object type usable with <code>boost::result_of<></code>.
+ </para>
+ </description>
+ </struct>
+ <method-group name="public member functions">
+ <overloaded-method name="operator()">
+ <signature cv="const">
+ <template>
+ <template-type-parameter name="T"/>
+ </template>
+ <type><replaceable>see-below</replaceable></type>
+ <parameter name="t">
+ <paramtype>T &</paramtype>
+ </parameter>
+ </signature>
+ <signature cv="const">
+ <template>
+ <template-type-parameter name="T"/>
+ </template>
+ <type><replaceable>see-below</replaceable></type>
+ <parameter name="t">
+ <paramtype>T const &</paramtype>
+ </parameter>
+ </signature>
+ <description>
+ <para>
+ If <code><classname>proto::is_env</classname><T>::value</code> is <code>false</code>,
+ this function returns the result of <code>(<globalname>proto::data</globalname> = t)</code>.
+ See <code><methodname>proto::data_type::operator=</methodname></code> for details.
+ </para>
+ <para>
+ Otherwise, this function returns <code>t</code> by reference.
+ </para>
+ </description>
+ </overloaded-method>
+ </method-group>
+ </struct>
+
+ <!-- functional::has_env_var -->
+ <struct name="has_env_var">
+ <inherit><classname>proto::callable</classname></inherit>
+ <template>
+ <template-type-parameter name="Key"/>
+ </template>
+ <purpose>
+ A unary boolean <conceptname>PolymorphicFunctionObject</conceptname> used for determining whether a particular
+ transform environment has a value associated with a particular key.
+ </purpose>
+ <struct name="result">
+ <template>
+ <template-type-parameter name="Sig"/>
+ </template>
+ <typedef name="type">
+ <type><replaceable>see-below</replaceable></type>
+ <description>
+ <para>See <code><methodname>proto::functional::has_env_var::operator()</methodname></code>.</para>
+ </description>
+ </typedef>
+ <description>
+ <para>
+ Encodes the return type of <code><methodname>proto::functional::has_env_var::operator()</methodname></code>.
+ The presence of this member template makes <code><classname>proto::functional::has_env_var</classname></code>
+ a valid TR1-style function object type usable with <code>boost::result_of<></code>.
+ </para>
+ </description>
+ </struct>
+ <method-group name="public member functions">
+ <method name="operator()" cv="const">
+ <template>
+ <template-type-parameter name="Env"/>
+ </template>
+ <type><replaceable>see-below</replaceable></type>
+ <parameter name="e">
+ <paramtype>Env const &</paramtype>
+ </parameter>
+ <description>
+ <para>
+ This function behaves as follows:
+ <itemizedlist>
+ <listitem>
+ If <code><classname>proto::is_env</classname><Env>::value</code> is <code>true</code>:
+ <itemizedlist>
+ <listitem>
+ If <code>e[Key()]</code> returns an instance of
+ <code><classname>proto::key_not_found</classname></code>, return
+ <code>mpl::false_</code>. See <code><methodname>proto::env::operator[]</methodname></code>
+ for more information.
+ </listitem>
+ <listitem>
+ Otherwise, return <code>mpl::true_</code>.
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ Otherwise:
+ <itemizedlist>
+ <listitem>
+ If <code>Key</code> is <code><classname>proto::data_type</classname></code>,
+ return <code>mpl::true_</code>.
+ </listitem>
+ <listitem>
+ Otherwise, return <code>mpl::false_</code>.
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </description>
+ </method>
+ </method-group>
+ </struct>
+
+ <!-- functional::env_var -->
+ <struct name="env_var">
+ <inherit><classname>proto::callable</classname></inherit>
+ <template>
+ <template-type-parameter name="Key"/>
+ </template>
+ <purpose>
+ A unary <conceptname>PolymorphicFunctionObject</conceptname> used for fetching the value
+ associated with a particular key in a transform environment.
+ </purpose>
+ <struct name="result">
+ <template>
+ <template-type-parameter name="Sig"/>
+ </template>
+ <typedef name="type">
+ <type><replaceable>see-below</replaceable></type>
+ <description>
+ <para>See <code><methodname>proto::functional::env_var::operator()</methodname></code>.</para>
+ </description>
+ </typedef>
+ <description>
+ <para>
+ Encodes the return type of <code><methodname>proto::functional::env_var::operator()</methodname></code>.
+ The presence of this member template makes <code><classname>proto::functional::env_var</classname></code>
+ a valid TR1-style function object type usable with <code>boost::result_of<></code>.
+ </para>
+ </description>
+ </struct>
+ <method-group name="public member functions">
+ <method name="operator()" cv="const">
+ <template>
+ <template-type-parameter name="Env"/>
+ </template>
+ <type><replaceable>see-below</replaceable></type>
+ <parameter name="e">
+ <paramtype>Env const &</paramtype>
+ </parameter>
+ <description>
+ <para>
+ This function behaves as follows:
+ <itemizedlist>
+ <listitem>
+ If <code>Key</code> is <code><classname>proto::data_type</classname></code>:
+ <itemizedlist>
+ <listitem>
+ If <code><classname>proto::is_env</classname><Env>::value</code> is <code>true</code>,
+ return <code>e[<globalname>proto::data</globalname>]</code>.
+ </listitem>
+ <listitem>
+ Otherwise, return <code>e</code>.
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ Otherwise, return <code>e[Key()]</code>.
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ See <code><methodname>proto::env::operator[]</methodname></code> for additional information.
+ </para>
+ </description>
+ </method>
+ </method-group>
+ </struct>
+
+ </namespace>
+
+ <namespace name="result_of">
+ <struct name="as_env">
+ <template>
+ <template-type-parameter name="T"/>
+ </template>
+ <inherit><type>boost::result_of<<classname>proto::functional::as_env</classname>(T)></type></inherit>
+ <purpose>
+ Metafunction for computing the return type of <code><functionname>proto::as_env()</functionname></code>.
+ </purpose>
+ </struct>
+ <struct name="has_env_var">
+ <template>
+ <template-type-parameter name="Env"/>
+ <template-type-parameter name="Key"/>
+ </template>
+ <inherit><type>boost::result_of<<classname>proto::functional::has_env_var</classname><Key>(Env)>::type</type></inherit>
+ <purpose>
+ Metafunction for computing the return type of <code><functionname>proto::has_env_var()</functionname></code>.
+ </purpose>
+ </struct>
+ <struct name="env_var">
+ <template>
+ <template-type-parameter name="Env"/>
+ <template-type-parameter name="Key"/>
+ </template>
+ <inherit><type>boost::result_of<<classname>proto::functional::env_var</classname><Key>(Env)></type></inherit>
+ <purpose>
+ Metafunction for computing the return type of <code><functionname>proto::env_var()</functionname></code>.
+ </purpose>
+ </struct>
+ </namespace>
+
+ <!-- proto::as_env -->
+ <overloaded-function name="as_env">
+ <signature>
+ <template>
+ <template-type-parameter name="T"/>
+ </template>
+ <type>typename <classname>proto::result_of::as_env</classname><T &>::type</type>
+ <parameter name="t">
+ <paramtype>T &</paramtype>
+ </parameter>
+ </signature>
+ <signature>
+ <template>
+ <template-type-parameter name="T"/>
+ </template>
+ <type>typename <classname>proto::result_of::as_env</classname><T const &>::type</type>
+ <parameter name="t">
+ <paramtype>T const &</paramtype>
+ </parameter>
+ </signature>
+ <purpose>
+ For ensuring that the given argument is a transform environment. If it is not already,
+ it is made one as if by <code>(<globalname>proto::data</globalname> = t)</code>.
+ </purpose>
+ <description>
+ <para>
+ See also:
+ <itemizedlist>
+ <listitem>
+ <code><methodname>proto::data_type::operator=</methodname></code>
+ </listitem>
+ <listitem>
+ <code><methodname>proto::functional::as_env::operator()</methodname></code>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </description>
+ <returns><code><classname>proto::functional::as_env</classname>()(t)</code></returns>
+ </overloaded-function>
+
+ <!-- proto::has_env_var -->
+ <overloaded-function name="has_env_var">
+ <signature>
+ <template>
+ <template-type-parameter name="Key"/>
+ <template-type-parameter name="Env"/>
+ </template>
+ <type>typename <classname>proto::result_of::has_env_var</classname><Env &, Key>::type</type>
+ <parameter name="e">
+ <paramtype>Env &</paramtype>
+ </parameter>
+ </signature>
+ <signature>
+ <template>
+ <template-type-parameter name="Key"/>
+ <template-type-parameter name="Env"/>
+ </template>
+ <type>typename <classname>proto::result_of::has_env_var</classname><Env const &, Key>::type</type>
+ <parameter name="e">
+ <paramtype>Env const &</paramtype>
+ </parameter>
+ </signature>
+ <purpose>
+ For testing to see whether a value exists in a transform environment corresponding to the
+ specified <code>Key</code>.
+ </purpose>
+ <description>
+ <para>
+ See also:
+ <itemizedlist>
+ <listitem>
+ <code><methodname>proto::functional::has_env_var::operator()</methodname></code>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </description>
+ <returns><code><classname>proto::functional::has_env_var<Key></classname>()(e)</code></returns>
+ </overloaded-function>
+
+ <!-- proto::env_var -->
+ <overloaded-function name="env_var">
+ <signature>
+ <template>
+ <template-type-parameter name="Key"/>
+ <template-type-parameter name="Env"/>
+ </template>
+ <type>typename <classname>proto::result_of::env_var</classname><Env &, Key>::type</type>
+ <parameter name="e">
+ <paramtype>Env &</paramtype>
+ </parameter>
+ </signature>
+ <signature>
+ <template>
+ <template-type-parameter name="Key"/>
+ <template-type-parameter name="Env"/>
+ </template>
+ <type>typename <classname>proto::result_of::env_var</classname><Env const &, Key>::type</type>
+ <parameter name="e">
+ <paramtype>Env const &</paramtype>
+ </parameter>
+ </signature>
+ <purpose>
+ For fetching the value from a transform environment corresponding to the
+ specified <code>Key</code>.
+ </purpose>
+ <description>
+ <para>
+ See also:
+ <itemizedlist>
+ <listitem>
+ <code><methodname>proto::functional::env_var::operator()</methodname></code>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </description>
+ <returns><code><classname>proto::functional::env_var<Key></classname>()(e)</code></returns>
+ </overloaded-function>
+
+ <!-- proto::operator, -->
+ <overloaded-function name="operator,">
+ <signature>
+ <template>
+ <template-type-parameter name="Env"/>
+ <template-type-parameter name="Key"/>
+ <template-type-parameter name="Value"/>
+ </template>
+ <type><classname>proto::env</classname><Key, Value, <replaceable>UNCVREF</replaceable>(typename <classname>proto::result_of::as_env</classname><Env &>::type)></type>
+ <parameter name="other">
+ <paramtype>Env &</paramtype>
+ </parameter>
+ <parameter name="head">
+ <paramtype><classname>proto::env</classname><Key, Value> const &</paramtype>
+ </parameter>
+ </signature>
+ <signature>
+ <template>
+ <template-type-parameter name="Env"/>
+ <template-type-parameter name="Key"/>
+ <template-type-parameter name="Value"/>
+ </template>
+ <type><classname>proto::env</classname><Key, Value, <replaceable>UNCVREF</replaceable>(typename <classname>proto::result_of::as_env</classname><Env const &>::type)></type>
+ <parameter name="other">
+ <paramtype>Env const &</paramtype>
+ </parameter>
+ <parameter name="head">
+ <paramtype><classname>proto::env</classname><Key, Value> const &</paramtype>
+ </parameter>
+ </signature>
+ <purpose>
+ For composing a larger transform environment from two smaller ones.
+ </purpose>
+ <description>
+ <para>
+ The effect of this function is to take two transform environments and compose them into
+ a larger environment that contains the key/values pairs of the two. The first argument
+ is allowed to not be a transform environment, in which case it is turned into one with
+ the <functionname>proto::as_env()</functionname> function before composition with the
+ second argument. The second argument is required to be a transform environment with exactly
+ one key/value pair.
+ </para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <para>
+ Given user-defined keys <code>key0</code> and <code>key1</code> of types <code>key0_type</code>
+ and <code>key1_type</code>, the following code demonstrates how the chained use of <code>operator,</code>
+ can build a composite transform environment containing a number of key/value pairs:
+ <programlisting><classname>proto::env</classname><
+ key1_type
+ , int
+ , <classname>proto::env</classname><
+ key0_type
+ , char const (&)[6]
+ , <classname>proto::env</classname><<classname>proto::data_type</classname>, int>
+ >
+> myenv = (<globalname>proto::data</globalname> = 1, key0 = "hello", key1 = 42);
+// NOTE: operator, here --^ and here --^
+
+// Check the results:
+assert(1 == myenv[proto::data]);
+assert(0 == std::strcmp(myenv[key0], "hello"));
+assert(42 == myenv[key1]);</programlisting>
+ </para>
+ <para>
+ <emphasis role="bold">Note:</emphasis> In the return type and the "Returns" clause, <code><replaceable>UNCVREF</replaceable>(X)</code> is
+ the type <code>X</code> stripped of top-level reference and cv-qualifiers.
+ </para>
+ <para>
+ <emphasis role="bold">Note:</emphasis> In the "Returns" clause, <code><replaceable>cv</replaceable></code> is replaced with <code>const</code>
+ for the second overload, and nothing for the first.
+ </para>
+ <para>
+ <emphasis role="bold">See also:</emphasis>
+ <itemizedlist>
+ <listitem>
+ <code><methodname>proto::env::operator[]</methodname></code>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </description>
+ <returns><code><classname>proto::env</classname><Key, Value, <replaceable>UNCVREF</replaceable>(typename <classname>proto::result_of::as_env</classname><Env <replaceable>cv</replaceable> &>::type)>(head[Key()], <functionname>proto::as_env</functionname>(other))</code></returns>
+ </overloaded-function>
+
+ <!-- struct _env_var -->
+ <struct name="_env_var">
+ <template>
+ <template-type-parameter name="Key"/>
+ </template>
+ <purpose>
+ A primitive transform that returns the value associated with a particular <code>Key</code>
+ in the current transform environment.
+ </purpose>
+ <inherit>
+ <type><classname>proto::transform</classname><_env_var<Key> ></type>
+ </inherit>
+ <struct name="impl">
+ <template>
+ <template-type-name name="Expr"/>
+ <template-type-name name="State"/>
+ <template-type-name name="Data"/>
+ </template>
+ <inherit>
+ <type><classname>proto::transform_impl</classname><Expr, State, Data> ></type>
+ </inherit>
+ <typedef name="result_type">
+ <type>typename <classname>proto::result_of::env_var</classname><Data, Key>::type</type>
+ </typedef>
+ <method-group name="public member functions">
+ <method name="operator()" cv="const">
+ <type>result_type</type>
+ <parameter name="">
+ <paramtype>typename impl::expr_param</paramtype>
+ </parameter>
+ <parameter name="">
+ <paramtype>typename impl::state_param</paramtype>
+ </parameter>
+ <parameter name="data">
+ <paramtype>typename impl::data_param</paramtype>
+ <description>
+ <para>The current transform environment</para>
+ </description>
+ </parameter>
+ <description>
+ <para>
+ Fetches the value associated with <code>Key</code> from the transform environment
+ passed in the data (third) parameter.
+ </para>
+ </description>
+ <requires>
+ <para>
+ <code><classname>proto::is_env</classname><Data>::value</code>
+ is <code>true</code>.
+ </para>
+ </requires>
+ <returns>
+ <para>
+ <code><functionname>proto::env_var</functionname>(data)</code>
+ </para>
+ </returns>
+ </method>
+ </method-group>
+ </struct>
+ <description>
+ <para>
+ See <code><classname>proto::_env_var::impl</classname></code> for the full details.
+ </para>
+ </description>
+ </struct>
+
+ <!-- struct _env -->
+ <struct name="_env">
+ <purpose>
+ A primitive transform that returns the current transform environment unmodified.
+ </purpose>
+ <inherit>
+ <type><classname>proto::transform</classname><_env></type>
+ </inherit>
+ <struct name="impl">
+ <template>
+ <template-type-name name="Expr"/>
+ <template-type-name name="State"/>
+ <template-type-name name="Data"/>
+ </template>
+ <inherit>
+ <type><classname>proto::transform_impl</classname><Expr, State, Data></type>
+ </inherit>
+ <typedef name="result_type">
+ <type>Data</type>
+ </typedef>
+ <method-group name="public member functions">
+ <method name="operator()" cv="const">
+ <type>result_type</type>
+ <parameter name="">
+ <paramtype>typename impl::expr_param</paramtype>
+ </parameter>
+ <parameter name="">
+ <paramtype>typename impl::state_param</paramtype>
+ </parameter>
+ <parameter name="data">
+ <paramtype>typename impl::data_param</paramtype>
+ <description>
+ <para>The current transform environment </para>
+ </description>
+ </parameter>
+ <description>
+ <para>
+ Returns the current transform environment
+ passed in the data (third) parameter.
+ </para>
+ </description>
+ <returns>
+ <para>
+ <code>data</code>
+ </para>
+ </returns>
+ </method>
+ </method-group>
+ </struct>
+ <description>
+ <para>
+ See <code><classname>proto::_env::impl</classname></code> for the full details.
+ </para>
+ </description>
+ </struct>
+ </namespace>
+ </namespace>
+
+ <!-- BOOST_PROTO_DEFINE_ENV_VAR() -->
+ <macro name="BOOST_PROTO_DEFINE_ENV_VAR" kind="functionlike">
+ <macro-parameter name="Type"/>
+ <macro-parameter name="Name"/>
+ <purpose>
+ Define a type and a global variable of that type that can be used
+ to initialize a slot in a Proto transform environment.
+ </purpose>
+ <description>
+ <para>
+ Proto primitive transforms can optionally accept an environment in
+ their third parameter which is a key/value store of environment
+ variables. Use the <code>BOOST_PROTO_DEFINE_ENV_VAR()</code> macro
+ to define the keys.
+ </para>
+ <para>
+ See the description for <code><classname alt="boost::proto::data_type">proto::data_type</classname></code>
+ for an example of the class interface created by this macro.
+ </para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <para>
+ <programlisting>BOOST_PROTO_DEFINE_ENV_VAR(mykey_type, mykey);
+
+struct FetchMyKey
+ : <classname alt="boost::proto::when">proto::when</classname>< <classname alt="boost::proto::_">_</classname>, <classname alt="boost::proto::_env_var">proto::_env_var</classname><mykey_type> >
+{};
+
+int main()
+{
+ <classname alt="boost::proto::terminal">proto::terminal</classname><int>::type i = {42};
+ char const * sz = FetchMyKey()(i, 0, (mykey = "hello!"));
+ assert(0 == std::strcmp(sz, "hello!");
+}</programlisting>
+ </para>
+ </description>
+
+ </macro>
+
+</header>
Modified: trunk/libs/proto/doc/reference/transform/when.xml
==============================================================================
--- trunk/libs/proto/doc/reference/transform/when.xml (original)
+++ trunk/libs/proto/doc/reference/transform/when.xml 2012-07-22 16:03:41 EDT (Sun, 22 Jul 2012)
@@ -18,6 +18,69 @@
</para>
<namespace name="boost">
<namespace name="proto">
+
+ <!-- struct transforms_type -->
+ <struct name="transforms_type">
+ <purpose>
+ The type used to define the global <code><globalname>proto::transforms</globalname></code>,
+ a key for use when creating and accessing a slot in a transform environment for
+ a set of external transforms.
+ </purpose>
+ <description>
+ <para>
+ The <code>proto::transforms_type</code> type, along with the <code><globalname>proto::transforms</globalname></code>
+ global, are declared using the <code><macroname>BOOST_PROTO_DEFINE_ENV_VAR</macroname>()</code> macro.
+ </para>
+ </description>
+ <method-group name="public member functions">
+ <overloaded-method name="operator=">
+ <signature cv="const">
+ <template>
+ <template-type-parameter name="Value"/>
+ </template>
+ <type><classname>env</classname><transforms_type, <replaceable>see-below</replaceable>></type>
+ <parameter name="value">
+ <paramtype>Value &</paramtype>
+ </parameter>
+ </signature>
+ <signature cv="const">
+ <template>
+ <template-type-parameter name="Value"/>
+ </template>
+ <type><classname>env</classname><transforms_type, <replaceable>see-below</replaceable>></type>
+ <parameter name="value">
+ <paramtype>Value const &</paramtype>
+ </parameter>
+ </signature>
+ <description>
+ <para>
+ If <code>Value</code> is a specialization <code>boost::reference_wrapper<T></code>,
+ this function returns <code><classname>env</classname><transforms_type, T &>(value.get())</code>.
+ </para>
+ <para>
+ Else, if the type <code>Value</code> is non-copyable (i.e., a function, an array, abstract, or an ostream),
+ this function returns <code><classname>env</classname><transforms_type, Value <replaceable>cv</replaceable> &>(value)</code>,
+ where <code><replaceable>cv</replaceable></code> is <code>const</code> for the second overload, and empty
+ for the first.
+ </para>
+ <para>
+ Otherwise, this function returns <code><classname>env</classname><transforms_type, Value>(value)</code>.
+ </para>
+ </description>
+ </overloaded-method>
+ </method-group>
+ </struct>
+
+ <data-member name="transforms">
+ <description>
+ <para>
+ A key key for use when creating and accessing a slot in a transform environment for
+ a set of external transforms.
+ </para>
+ </description>
+ <type><classname>proto::transforms_type</classname> const</type>
+ </data-member>
+
<struct name="when">
<template>
<template-type-parameter name="Grammar"/>
@@ -342,9 +405,24 @@
<template-type-parameter name="Data"/>
</template>
<inherit><type>
- boost::remove_reference< Data >::type
+ boost::remove_reference<
+ typename mpl::eval_if_c<
+ <classname>proto::result_of::has_env_var</classname><Data, <classname>proto::transforms_type</classname>>::value,
+ <classname>proto::result_of::env_var</classname><Data, <classname>proto::transforms_type</classname>>,
+ <classname>proto::result_of::env_var</classname><Data, <classname>proto::data_type</classname>>
+ >::type
+ >::type
::template when< Grammar >
::template impl< Expr, State, Data ></type></inherit>
+ <description>
+ <para>
+ The implementation of the <code>impl</code> struct depends on whether the <code>Data</code>
+ parameter is a transform environment that contains a value corresponding to the
+ <classname>proto::transforms_type</classname> key. If so, that value is treated as a
+ map from rules to transforms. Otherwise, the <code>Data</code> type itself is treated
+ as such a map.
+ </para>
+ </description>
</struct>
<typedef name="proto_grammar">
<type>typename Grammar::proto_grammar</type>
@@ -454,7 +532,11 @@
my_transforms trx;
// Evaluate "i+c" using my_grammar with the specified transforms:
-my_grammar()(i + c, 0, trx);</programlisting>
+my_grammar()(i + c, 0, trx);
+
+// If you would also like to pass arbitrary data along with the
+// transforms, you can use a transform environment, as so:
+my_grammar()(i + c, 0, (proto::data = 42, proto::transforms = trx));</programlisting>
</para>
</description>
</struct>
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