ceph/src/boost/libs/proto/doc/reference/transform/env.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3   Copyright 2012 Eric Niebler
   4
   5   Distributed under the Boost
   6   Software License, Version 1.0. (See accompanying
   7   file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   8   -->
   9 <header name="boost/proto/transform/env.hpp">
  10   <namespace name="boost">
  11     <namespace name="proto">
  12
  13       <struct name="key_not_found">
  14         <purpose>
  15           The type of objects returned when a key-based lookup fails in a
  16           transform environment.
  17         </purpose>
  18       </struct>
  19
  20       <!-- empty_env -->
  21       <struct name="empty_env">
  22         <purpose>
  23           The type of an object that represents a transform environment
  24           with no key/value pairs in it.
  25         </purpose>
  26
  27         <method-group name="public member functions">
  28           <method name="operator[]" cv="const">
  29             <type><classname>proto::key_not_found</classname></type>
  30             <parameter name="">
  31               <paramtype><replaceable>unspecified</replaceable></paramtype>
  32             </parameter>
  33             <description>
  34               <para>The type of the argument to this function has a
  35               user-defined implicit conversion from any type.</para>
  36             </description>
  37           </method>
  38         </method-group>
  39       </struct>
  40
  41       <!-- env -->
  42       <struct name="env">
  43         <template>
  44           <template-type-parameter name="Key"/>
  45           <template-type-parameter name="Value"/>
  46           <template-type-parameter name="Env">
  47             <default><classname>proto::empty_env</classname></default>
  48           </template-type-parameter>
  49         </template>
  50
  51         <constructor specifiers="explicit">
  52           <parameter name="value">
  53             <paramtype>Value const &amp;</paramtype>
  54             <description>
  55               <para>
  56                 The value to be associated with the <code>Key</code>.
  57               </para>
  58             </description>
  59           </parameter>
  60           <parameter name="other">
  61             <paramtype>Env const &amp;</paramtype>
  62             <default>Env()</default>
  63             <description>
  64               <para>
  65                 Another key/value store.
  66               </para>
  67             </description>
  68           </parameter>
  69         </constructor>
  70
  71         <method-group name="public member functions">
  72           <method name="operator[]" cv="const">
  73             <type><replaceable>see-below</replaceable></type>
  74             <parameter name="">
  75               <paramtype><replaceable>see-below</replaceable></paramtype>
  76             </parameter>
  77             <description>
  78               <para>
  79                 If called with an object that is implicitly convertible to type <code>Key</code>,
  80                 this function returns the <code>Value</code> passed to the constructor. Otherwise, it returns
  81                 the result of calling <code>operator[]</code> on the <code>Env</code> passed to
  82                 the constructor.
  83               </para>
  84             </description>
  85           </method>
  86         </method-group>
  87       </struct>
  88
  89       <!-- is_env -->
  90       <struct name="is_env">
  91         <template>
  92           <template-type-parameter name="T"/>
  93         </template>
  94         <inherit><type>mpl::bool_&lt;<replaceable>true-or-false</replaceable>&gt;</type></inherit>
  95         <purpose>
  96           <para>A Boolean metafuntion for determining whether or not a type is a Proto
  97           transform environment.</para>
  98         </purpose>
  99         <description>
 100           <para><code>is_env&lt;T&gt;</code> inherits from <code>mpl::true_</code> under the following
 101           conditions:
 102             <itemizedlist>
 103               <listitem>If <code>T</code> is <classname>proto::empty_env</classname>.</listitem>
 104               <listitem>If <code>T</code> is a specialization of <classname>proto::env&lt;&gt;</classname>.</listitem>
 105               <listitem>If <code>T</code> is derived from any of the above.</listitem>
 106               <listitem>If <code>T</code> is a cv-qualified variant of any of the above.</listitem>
 107               <listitem>If <code>T</code> is a reference to any of the above.</listitem>
 108             </itemizedlist>
 109           </para>
 110           <para>Otherwise, <code>is_env&lt;T&gt;</code> inherits from <code>mpl::false_</code>.
 111         </para>
 112         </description>
 113       </struct>
 114
 115       <struct name="data_type">
 116         <purpose>
 117           The type of <code><globalname>proto::data</globalname></code>, a key for use when creating
 118           a transform environment that associates a piece of data with this type.
 119         </purpose>
 120         <description>
 121           <para>
 122             The <code>proto::data_type</code> type, along with the <code><globalname>proto::data</globalname></code>
 123             global, are declared using the <code><macroname>BOOST_PROTO_DEFINE_ENV_VAR</macroname>()</code> macro.
 124           </para>
 125         </description>
 126         <method-group name="public member functions">
 127           <overloaded-method name="operator=">
 128             <signature cv="const">
 129               <template>
 130                 <template-type-parameter name="Value"/>
 131               </template>
 132               <type><classname>env</classname>&lt;data_type, <replaceable>see-below</replaceable>&gt;</type>
 133               <parameter name="value">
 134                 <paramtype>Value &amp;</paramtype>
 135               </parameter>
 136             </signature>
 137             <signature cv="const">
 138               <template>
 139                 <template-type-parameter name="Value"/>
 140               </template>
 141               <type><classname>env</classname>&lt;data_type, <replaceable>see-below</replaceable>&gt;</type>
 142               <parameter name="value">
 143                 <paramtype>Value const &amp;</paramtype>
 144               </parameter>
 145             </signature>
 146             <description>
 147               <para>
 148                 If <code>Value</code> is a specialization <code>boost::reference_wrapper&lt;T&gt;</code>,
 149                 this function returns <code><classname>env</classname>&lt;data_type, T &amp;&gt;(value.get())</code>.
 150               </para>
 151               <para>
 152                 Else, if the type <code>Value</code> is non-copyable (i.e., a function, an array, abstract, or an ostream),
 153                 this function returns <code><classname>env</classname>&lt;data_type, Value <replaceable>cv</replaceable> &amp;&gt;(value)</code>,
 154                 where <code><replaceable>cv</replaceable></code> is <code>const</code> for the second overload, and empty
 155                 for the first.
 156               </para>
 157               <para>
 158                 Otherwise, this function returns <code><classname>env</classname>&lt;data_type, Value&gt;(value)</code>.
 159               </para>
 160             </description>
 161           </overloaded-method>
 162         </method-group>
 163       </struct>
 164
 165       <data-member name="data">
 166         <description>
 167           <para>A key used for creating a transform environment.</para>
 168         </description>
 169         <type><classname>proto::data_type</classname> const</type>
 170       </data-member>
 171
 172       <namespace name="functional">
 173
 174         <!-- functional::as_env -->
 175         <struct name="as_env">
 176           <inherit><classname>proto::callable</classname></inherit>
 177           <purpose>
 178             A unary <conceptname>PolymorphicFunctionObject</conceptname> for ensuring that an object
 179             is a transform environment. If it isn't already, it is turned into one such that the
 180             object is associated with the <classname>proto::data_type</classname> key.
 181           </purpose>
 182           <struct name="result">
 183             <template>
 184               <template-type-parameter name="Sig"/>
 185             </template>
 186             <typedef name="type">
 187               <type><replaceable>see-below</replaceable></type>
 188               <description>
 189                 <para>See <code><methodname>proto::functional::as_env::operator()</methodname></code>.</para>
 190               </description>
 191             </typedef>
 192             <description>
 193               <para>
 194                 Encodes the return type of <code><methodname>proto::functional::as_env::operator()</methodname></code>.
 195                 The presence of this member template makes <code><classname>proto::functional::as_env</classname></code>
 196                 a valid TR1-style function object type usable with <code>boost::result_of&lt;&gt;</code>.
 197               </para>
 198             </description>
 199           </struct>
 200           <method-group name="public member functions">
 201             <overloaded-method name="operator()">
 202               <signature cv="const">
 203                 <template>
 204                   <template-type-parameter name="T"/>
 205                 </template>
 206                 <type><replaceable>see-below</replaceable></type>
 207                 <parameter name="t">
 208                   <paramtype>T &amp;</paramtype>
 209                 </parameter>
 210               </signature>
 211               <signature cv="const">
 212                 <template>
 213                   <template-type-parameter name="T"/>
 214                 </template>
 215                 <type><replaceable>see-below</replaceable></type>
 216                 <parameter name="t">
 217                   <paramtype>T const &amp;</paramtype>
 218                 </parameter>
 219               </signature>
 220               <description>
 221                 <para>
 222                   If <code><classname>proto::is_env</classname>&lt;T&gt;::value</code> is <code>false</code>,
 223                   this function returns the result of <code>(<globalname>proto::data</globalname> = t)</code>.
 224                   See <code><methodname>proto::data_type::operator=</methodname></code> for details.
 225                 </para>
 226                 <para>
 227                   Otherwise, this function returns <code>t</code> by reference.
 228                 </para>
 229               </description>
 230             </overloaded-method>
 231           </method-group>
 232         </struct>
 233
 234         <!-- functional::has_env_var -->
 235         <struct name="has_env_var">
 236           <inherit><classname>proto::callable</classname></inherit>
 237           <template>
 238             <template-type-parameter name="Key"/>
 239           </template>
 240           <purpose>
 241             A unary boolean <conceptname>PolymorphicFunctionObject</conceptname> used for determining whether a particular
 242             transform environment has a value associated with a particular key.
 243           </purpose>
 244           <struct name="result">
 245             <template>
 246               <template-type-parameter name="Sig"/>
 247             </template>
 248             <typedef name="type">
 249               <type><replaceable>see-below</replaceable></type>
 250               <description>
 251                 <para>See <code><methodname>proto::functional::has_env_var::operator()</methodname></code>.</para>
 252               </description>
 253             </typedef>
 254             <description>
 255               <para>
 256                 Encodes the return type of <code><methodname>proto::functional::has_env_var::operator()</methodname></code>.
 257                 The presence of this member template makes <code><classname>proto::functional::has_env_var</classname></code>
 258                 a valid TR1-style function object type usable with <code>boost::result_of&lt;&gt;</code>.
 259               </para>
 260             </description>
 261           </struct>
 262           <method-group name="public member functions">
 263             <method name="operator()" cv="const">
 264               <template>
 265                 <template-type-parameter name="Env"/>
 266               </template>
 267               <type><replaceable>see-below</replaceable></type>
 268               <parameter name="e">
 269                 <paramtype>Env const &amp;</paramtype>
 270               </parameter>
 271               <description>
 272                 <para>
 273                   This function behaves as follows:
 274                   <itemizedlist>
 275                     <listitem>
 276                       If <code><classname>proto::is_env</classname>&lt;Env&gt;::value</code> is <code>true</code>:
 277                       <itemizedlist>
 278                         <listitem>
 279                           If <code>e[Key()]</code> returns an instance of
 280                           <code><classname>proto::key_not_found</classname></code>, return
 281                           <code>mpl::false_</code>. See <code><methodname>proto::env::operator[]</methodname></code>
 282                           for more information.
 283                         </listitem>
 284                         <listitem>
 285                           Otherwise, return <code>mpl::true_</code>.
 286                         </listitem>
 287                       </itemizedlist>
 288                     </listitem>
 289                     <listitem>
 290                       Otherwise:
 291                       <itemizedlist>
 292                         <listitem>
 293                           If <code>Key</code> is <code><classname>proto::data_type</classname></code>,
 294                           return <code>mpl::true_</code>.
 295                         </listitem>
 296                         <listitem>
 297                           Otherwise, return <code>mpl::false_</code>.
 298                         </listitem>
 299                       </itemizedlist>
 300                     </listitem>
 301                   </itemizedlist>
 302                 </para>
 303               </description>
 304             </method>
 305           </method-group>
 306         </struct>
 307
 308         <!-- functional::env_var -->
 309         <struct name="env_var">
 310           <inherit><classname>proto::callable</classname></inherit>
 311           <template>
 312             <template-type-parameter name="Key"/>
 313           </template>
 314           <purpose>
 315             A unary <conceptname>PolymorphicFunctionObject</conceptname> used for fetching the value
 316             associated with a particular key in a transform environment.
 317           </purpose>
 318           <struct name="result">
 319             <template>
 320               <template-type-parameter name="Sig"/>
 321             </template>
 322             <typedef name="type">
 323               <type><replaceable>see-below</replaceable></type>
 324               <description>
 325                 <para>See <code><methodname>proto::functional::env_var::operator()</methodname></code>.</para>
 326               </description>
 327             </typedef>
 328             <description>
 329               <para>
 330                 Encodes the return type of <code><methodname>proto::functional::env_var::operator()</methodname></code>.
 331                 The presence of this member template makes <code><classname>proto::functional::env_var</classname></code>
 332                 a valid TR1-style function object type usable with <code>boost::result_of&lt;&gt;</code>.
 333               </para>
 334             </description>
 335           </struct>
 336           <method-group name="public member functions">
 337             <method name="operator()" cv="const">
 338               <template>
 339                 <template-type-parameter name="Env"/>
 340               </template>
 341               <type><replaceable>see-below</replaceable></type>
 342               <parameter name="e">
 343                 <paramtype>Env const &amp;</paramtype>
 344               </parameter>
 345               <description>
 346                 <para>
 347                   This function behaves as follows:
 348                   <itemizedlist>
 349                     <listitem>
 350                       If <code>Key</code> is <code><classname>proto::data_type</classname></code>:
 351                       <itemizedlist>
 352                         <listitem>
 353                           If <code><classname>proto::is_env</classname>&lt;Env&gt;::value</code> is <code>true</code>,
 354                           return <code>e[<globalname>proto::data</globalname>]</code>.
 355                         </listitem>
 356                         <listitem>
 357                           Otherwise, return <code>e</code>.
 358                         </listitem>
 359                       </itemizedlist>
 360                     </listitem>
 361                     <listitem>
 362                       Otherwise, return <code>e[Key()]</code>.
 363                     </listitem>
 364                   </itemizedlist>
 365                 </para>
 366                 <para>
 367                   See <code><methodname>proto::env::operator[]</methodname></code> for additional information.
 368                 </para>
 369               </description>
 370             </method>
 371           </method-group>
 372         </struct>
 373
 374       </namespace>
 375
 376       <namespace name="result_of">
 377         <struct name="as_env">
 378           <template>
 379             <template-type-parameter name="T"/>
 380           </template>
 381           <inherit><type>boost::result_of&lt;<classname>proto::functional::as_env</classname>(T)&gt;</type></inherit>
 382           <purpose>
 383             Metafunction for computing the return type of <code><functionname>proto::as_env()</functionname></code>.
 384           </purpose>
 385         </struct>
 386         <struct name="has_env_var">
 387           <template>
 388             <template-type-parameter name="Env"/>
 389             <template-type-parameter name="Key"/>
 390           </template>
 391           <inherit><type>boost::result_of&lt;<classname>proto::functional::has_env_var</classname>&lt;Key&gt;(Env)&gt;::type</type></inherit>
 392           <purpose>
 393             Metafunction for computing the return type of <code><functionname>proto::has_env_var()</functionname></code>.
 394           </purpose>
 395         </struct>
 396         <struct name="env_var">
 397           <template>
 398             <template-type-parameter name="Env"/>
 399             <template-type-parameter name="Key"/>
 400           </template>
 401           <inherit><type>boost::result_of&lt;<classname>proto::functional::env_var</classname>&lt;Key&gt;(Env)&gt;</type></inherit>
 402           <purpose>
 403             Metafunction for computing the return type of <code><functionname>proto::env_var()</functionname></code>.
 404           </purpose>
 405         </struct>
 406       </namespace>
 407
 408       <!-- proto::as_env -->
 409       <overloaded-function name="as_env">
 410         <signature>
 411           <template>
 412             <template-type-parameter name="T"/>
 413           </template>
 414           <type>typename <classname>proto::result_of::as_env</classname>&lt;T &amp;&gt;::type</type>
 415           <parameter name="t">
 416             <paramtype>T &amp;</paramtype>
 417           </parameter>
 418         </signature>
 419         <signature>
 420           <template>
 421             <template-type-parameter name="T"/>
 422           </template>
 423           <type>typename <classname>proto::result_of::as_env</classname>&lt;T const &amp;&gt;::type</type>
 424           <parameter name="t">
 425             <paramtype>T const &amp;</paramtype>
 426           </parameter>
 427         </signature>
 428         <purpose>
 429           For ensuring that the given argument is a transform environment. If it is not already,
 430           it is made one as if by <code>(<globalname>proto::data</globalname> = t)</code>.
 431         </purpose>
 432         <description>
 433           <para>
 434             See also:
 435             <itemizedlist>
 436               <listitem>
 437                 <code><methodname>proto::data_type::operator=</methodname></code>
 438               </listitem>
 439               <listitem>
 440                 <code><methodname>proto::functional::as_env::operator()</methodname></code>
 441               </listitem>
 442             </itemizedlist>
 443           </para>
 444         </description>
 445         <returns><code><classname>proto::functional::as_env</classname>()(t)</code></returns>
 446       </overloaded-function>
 447
 448       <!-- proto::has_env_var -->
 449       <overloaded-function name="has_env_var">
 450         <signature>
 451           <template>
 452             <template-type-parameter name="Key"/>
 453             <template-type-parameter name="Env"/>
 454           </template>
 455           <type>typename <classname>proto::result_of::has_env_var</classname>&lt;Env &amp;, Key&gt;::type</type>
 456           <parameter name="e">
 457             <paramtype>Env &amp;</paramtype>
 458           </parameter>
 459         </signature>
 460         <signature>
 461           <template>
 462             <template-type-parameter name="Key"/>
 463             <template-type-parameter name="Env"/>
 464           </template>
 465           <type>typename <classname>proto::result_of::has_env_var</classname>&lt;Env const &amp;, Key&gt;::type</type>
 466           <parameter name="e">
 467             <paramtype>Env const &amp;</paramtype>
 468           </parameter>
 469         </signature>
 470         <purpose>
 471           For testing to see whether a value exists in a transform environment corresponding to the
 472           specified <code>Key</code>.
 473         </purpose>
 474         <description>
 475           <para>
 476             See also:
 477             <itemizedlist>
 478               <listitem>
 479                 <code><methodname>proto::functional::has_env_var::operator()</methodname></code>
 480               </listitem>
 481             </itemizedlist>
 482           </para>
 483         </description>
 484         <returns><code><classname>proto::functional::has_env_var&lt;Key&gt;</classname>()(e)</code></returns>
 485       </overloaded-function>
 486
 487       <!-- proto::env_var -->
 488       <overloaded-function name="env_var">
 489         <signature>
 490           <template>
 491             <template-type-parameter name="Key"/>
 492             <template-type-parameter name="Env"/>
 493           </template>
 494           <type>typename <classname>proto::result_of::env_var</classname>&lt;Env &amp;, Key&gt;::type</type>
 495           <parameter name="e">
 496             <paramtype>Env &amp;</paramtype>
 497           </parameter>
 498         </signature>
 499         <signature>
 500           <template>
 501             <template-type-parameter name="Key"/>
 502             <template-type-parameter name="Env"/>
 503           </template>
 504           <type>typename <classname>proto::result_of::env_var</classname>&lt;Env const &amp;, Key&gt;::type</type>
 505           <parameter name="e">
 506             <paramtype>Env const &amp;</paramtype>
 507           </parameter>
 508         </signature>
 509         <purpose>
 510           For fetching the value from a transform environment corresponding to the
 511           specified <code>Key</code>.
 512         </purpose>
 513         <description>
 514           <para>
 515             See also:
 516             <itemizedlist>
 517               <listitem>
 518                 <code><methodname>proto::functional::env_var::operator()</methodname></code>
 519               </listitem>
 520             </itemizedlist>
 521           </para>
 522         </description>
 523         <returns><code><classname>proto::functional::env_var&lt;Key&gt;</classname>()(e)</code></returns>
 524       </overloaded-function>
 525
 526       <!-- proto::operator, -->
 527       <overloaded-function name="operator,">
 528         <signature>
 529           <template>
 530             <template-type-parameter name="Env"/>
 531             <template-type-parameter name="Key"/>
 532             <template-type-parameter name="Value"/>
 533           </template>
 534           <type><classname>proto::env</classname>&lt;Key, Value, <replaceable>UNCVREF</replaceable>(typename <classname>proto::result_of::as_env</classname>&lt;Env &amp;&gt;::type)&gt;</type>
 535           <parameter name="other">
 536             <paramtype>Env &amp;</paramtype>
 537           </parameter>
 538           <parameter name="head">
 539             <paramtype><classname>proto::env</classname>&lt;Key, Value&gt; const &amp;</paramtype>
 540           </parameter>
 541         </signature>
 542         <signature>
 543           <template>
 544             <template-type-parameter name="Env"/>
 545             <template-type-parameter name="Key"/>
 546             <template-type-parameter name="Value"/>
 547           </template>
 548           <type><classname>proto::env</classname>&lt;Key, Value, <replaceable>UNCVREF</replaceable>(typename <classname>proto::result_of::as_env</classname>&lt;Env const &amp;&gt;::type)&gt;</type>
 549           <parameter name="other">
 550             <paramtype>Env const &amp;</paramtype>
 551           </parameter>
 552           <parameter name="head">
 553             <paramtype><classname>proto::env</classname>&lt;Key, Value&gt; const &amp;</paramtype>
 554           </parameter>
 555         </signature>
 556         <purpose>
 557           For composing a larger transform environment from two smaller ones.
 558         </purpose>
 559         <description>
 560           <para>
 561             The effect of this function is to take two transform environments and compose them into
 562             a larger environment that contains the key/values pairs of the two. The first argument
 563             is allowed to not be a transform environment, in which case it is turned into one with
 564             the <functionname>proto::as_env()</functionname> function before composition with the
 565             second argument. The second argument is required to be a transform environment with exactly
 566             one key/value pair.
 567           </para>
 568           <para>
 569             <emphasis role="bold">Example:</emphasis>
 570           </para>
 571           <para>
 572             Given user-defined keys <code>key0</code> and <code>key1</code> of types <code>key0_type</code>
 573             and <code>key1_type</code>, the following code demonstrates how the chained use of <code>operator,</code>
 574             can build a composite transform environment containing a number of key/value pairs:
 575             <programlisting><classname>proto::env</classname>&lt;
 576     key1_type
 577   , int
 578   , <classname>proto::env</classname>&lt;
 579         key0_type
 580       , char const (&amp;)[6]
 581       , <classname>proto::env</classname>&lt;<classname>proto::data_type</classname>, int&gt;
 582     &gt;
 583 &gt; myenv = (<globalname>proto::data</globalname> = 1, key0 = "hello", key1 = 42);
 584 // NOTE: operator, here --^    and here --^
 585
 586 // Check the results:
 587 assert(1 == myenv[proto::data]);
 588 assert(0 == std::strcmp(myenv[key0], "hello"));
 589 assert(42 == myenv[key1]);</programlisting>
 590           </para>
 591           <para>
 592             <emphasis role="bold">Note:</emphasis> In the return type and the "Returns" clause, <code><replaceable>UNCVREF</replaceable>(X)</code> is
 593             the type <code>X</code> stripped of top-level reference and cv-qualifiers.
 594           </para>
 595           <para>
 596             <emphasis role="bold">Note:</emphasis> In the "Returns" clause, <code><replaceable>cv</replaceable></code> is replaced with <code>const</code>
 597             for the second overload, and nothing for the first.
 598           </para>
 599           <para>
 600             <emphasis role="bold">See also:</emphasis>
 601             <itemizedlist>
 602               <listitem>
 603                 <code><methodname>proto::env::operator[]</methodname></code>
 604               </listitem>
 605             </itemizedlist>
 606           </para>
 607         </description>
 608         <returns><code><classname>proto::env</classname>&lt;Key, Value, <replaceable>UNCVREF</replaceable>(typename <classname>proto::result_of::as_env</classname>&lt;Env <replaceable>cv</replaceable> &amp;&gt;::type)&gt;(head[Key()], <functionname>proto::as_env</functionname>(other))</code></returns>
 609       </overloaded-function>
 610
 611       <!-- struct _env_var -->
 612       <struct name="_env_var">
 613         <template>
 614           <template-type-parameter name="Key"/>
 615         </template>
 616         <purpose>
 617           A primitive transform that returns the value associated with a particular <code>Key</code>
 618           in the current transform environment.
 619         </purpose>
 620         <inherit>
 621           <type><classname>proto::transform</classname>&lt;_env_var&lt;Key&gt; &gt;</type>
 622         </inherit>
 623         <struct name="impl">
 624           <template>
 625             <template-type-name name="Expr"/>
 626             <template-type-name name="State"/>
 627             <template-type-name name="Data"/>
 628           </template>
 629           <inherit>
 630             <type><classname>proto::transform_impl</classname>&lt;Expr, State, Data&gt; &gt;</type>
 631           </inherit>
 632           <typedef name="result_type">
 633             <type>typename <classname>proto::result_of::env_var</classname>&lt;Data, Key&gt;::type</type>
 634           </typedef>
 635           <method-group name="public member functions">
 636             <method name="operator()" cv="const">
 637               <type>result_type</type>
 638               <parameter name="">
 639                 <paramtype>typename impl::expr_param</paramtype>
 640               </parameter>
 641               <parameter name="">
 642                 <paramtype>typename impl::state_param</paramtype>
 643               </parameter>
 644               <parameter name="data">
 645                 <paramtype>typename impl::data_param</paramtype>
 646                 <description>
 647                   <para>The current transform environment</para>
 648                 </description>
 649               </parameter>
 650               <description>
 651                 <para>
 652                   Fetches the value associated with <code>Key</code> from the transform environment
 653                   passed in the data (third) parameter.
 654                 </para>
 655               </description>
 656               <requires>
 657                 <para>
 658                   <code><classname>proto::is_env</classname>&lt;Data&gt;::value</code>
 659                   is <code>true</code>.
 660                 </para>
 661               </requires>
 662               <returns>
 663                 <para>
 664                   <code><functionname>proto::env_var</functionname>(data)</code>
 665                 </para>
 666               </returns>
 667             </method>
 668           </method-group>
 669         </struct>
 670         <description>
 671           <para>
 672             See <code><classname>proto::_env_var::impl</classname></code> for the full details.
 673           </para>
 674         </description>
 675       </struct>
 676
 677       <!-- struct _env -->
 678       <struct name="_env">
 679         <purpose>
 680           A primitive transform that returns the current transform environment unmodified.
 681         </purpose>
 682         <inherit>
 683           <type><classname>proto::transform</classname>&lt;_env&gt;</type>
 684         </inherit>
 685         <struct name="impl">
 686           <template>
 687             <template-type-name name="Expr"/>
 688             <template-type-name name="State"/>
 689             <template-type-name name="Data"/>
 690           </template>
 691           <inherit>
 692             <type><classname>proto::transform_impl</classname>&lt;Expr, State, Data&gt;</type>
 693           </inherit>
 694           <typedef name="result_type">
 695             <type>Data</type>
 696           </typedef>
 697           <method-group name="public member functions">
 698             <method name="operator()" cv="const">
 699               <type>result_type</type>
 700               <parameter name="">
 701                 <paramtype>typename impl::expr_param</paramtype>
 702               </parameter>
 703               <parameter name="">
 704                 <paramtype>typename impl::state_param</paramtype>
 705               </parameter>
 706               <parameter name="data">
 707                 <paramtype>typename impl::data_param</paramtype>
 708                 <description>
 709                   <para>The current transform environment </para>
 710                 </description>
 711               </parameter>
 712               <description>
 713                 <para>
 714                   Returns the current transform environment
 715                   passed in the data (third) parameter.
 716                 </para>
 717               </description>
 718               <returns>
 719                 <para>
 720                   <code>data</code>
 721                 </para>
 722               </returns>
 723             </method>
 724           </method-group>
 725         </struct>
 726         <description>
 727           <para>
 728             See <code><classname>proto::_env::impl</classname></code> for the full details.
 729           </para>
 730         </description>
 731       </struct>
 732     </namespace>
 733   </namespace>
 734
 735   <!-- BOOST_PROTO_DEFINE_ENV_VAR() -->
 736   <macro name="BOOST_PROTO_DEFINE_ENV_VAR" kind="functionlike">
 737     <macro-parameter name="Type"/>
 738     <macro-parameter name="Name"/>
 739     <purpose>
 740       Define a type and a global variable of that type that can be used
 741       to initialize a slot in a Proto transform environment.
 742     </purpose>
 743     <description>
 744       <para>
 745         Proto primitive transforms can optionally accept an environment in
 746         their third parameter which is a key/value store of environment
 747         variables. Use the <code>BOOST_PROTO_DEFINE_ENV_VAR()</code> macro
 748         to define the keys.
 749       </para>
 750       <para>
 751         See the description for <code><classname alt="boost::proto::data_type">proto::data_type</classname></code>
 752         for an example of the class interface created by this macro.
 753       </para>
 754       <para>
 755         <emphasis role="bold">Example:</emphasis>
 756       </para>
 757       <para>
 758         <programlisting>BOOST_PROTO_DEFINE_ENV_VAR(mykey_type, mykey);
 759
 760 struct FetchMyKey
 761   : <classname alt="boost::proto::when">proto::when</classname>&lt; <classname alt="boost::proto::_">_</classname>, <classname alt="boost::proto::_env_var">proto::_env_var</classname>&lt;mykey_type&gt; &gt;
 762 {};
 763
 764 int main()
 765 {
 766     <classname alt="boost::proto::terminal">proto::terminal</classname>&lt;int&gt;::type i = {42};
 767     char const * sz = FetchMyKey()(i, 0, (mykey = "hello!"));
 768     assert(0 == std::strcmp(sz, "hello!");
 769 }</programlisting>
 770       </para>
 771     </description>
 772
 773   </macro>
 774
 775 </header>