1 <?xml version=
"1.0" encoding=
"utf-8"?>
3 Copyright 2012 Eric Niebler
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)
9 <header name=
"boost/proto/transform/env.hpp">
10 <namespace name=
"boost">
11 <namespace name=
"proto">
13 <struct name=
"key_not_found">
15 The type of objects returned when a key-based lookup fails in a
16 transform environment.
21 <struct name=
"empty_env">
23 The type of an object that represents a transform environment
24 with no key/value pairs in it.
27 <method-group name=
"public member functions">
28 <method name=
"operator[]" cv=
"const">
29 <type><classname>proto::key_not_found
</classname></type>
31 <paramtype><replaceable>unspecified
</replaceable></paramtype>
34 <para>The type of the argument to this function has a
35 user-defined implicit conversion from any type.
</para>
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>
51 <constructor specifiers=
"explicit">
52 <parameter name=
"value">
53 <paramtype>Value const
&</paramtype>
56 The value to be associated with the
<code>Key
</code>.
60 <parameter name=
"other">
61 <paramtype>Env const
&</paramtype>
62 <default>Env()
</default>
65 Another key/value store.
71 <method-group name=
"public member functions">
72 <method name=
"operator[]" cv=
"const">
73 <type><replaceable>see-below
</replaceable></type>
75 <paramtype><replaceable>see-below
</replaceable></paramtype>
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
90 <struct name=
"is_env">
92 <template-type-parameter name=
"T"/>
94 <inherit><type>mpl::bool_
<<replaceable>true-or-false
</replaceable>></type></inherit>
96 <para>A Boolean metafuntion for determining whether or not a type is a Proto
97 transform environment.
</para>
100 <para><code>is_env
<T
></code> inherits from
<code>mpl::true_
</code> under the following
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
<></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>
110 <para>Otherwise,
<code>is_env
<T
></code> inherits from
<code>mpl::false_
</code>.
115 <struct name=
"data_type">
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.
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.
126 <method-group name=
"public member functions">
127 <overloaded-method name=
"operator=">
128 <signature cv=
"const">
130 <template-type-parameter name=
"Value"/>
132 <type><classname>env
</classname><data_type,
<replaceable>see-below
</replaceable>></type>
133 <parameter name=
"value">
134 <paramtype>Value
&</paramtype>
137 <signature cv=
"const">
139 <template-type-parameter name=
"Value"/>
141 <type><classname>env
</classname><data_type,
<replaceable>see-below
</replaceable>></type>
142 <parameter name=
"value">
143 <paramtype>Value const
&</paramtype>
148 If
<code>Value
</code> is a specialization
<code>boost::reference_wrapper
<T
></code>,
149 this function returns
<code><classname>env
</classname><data_type, T
&>(value.get())
</code>.
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><data_type, Value
<replaceable>cv
</replaceable> &>(value)
</code>,
154 where
<code><replaceable>cv
</replaceable></code> is
<code>const
</code> for the second overload, and empty
158 Otherwise, this function returns
<code><classname>env
</classname><data_type, Value
>(value)
</code>.
165 <data-member name=
"data">
167 <para>A key used for creating a transform environment.
</para>
169 <type><classname>proto::data_type
</classname> const
</type>
172 <namespace name=
"functional">
174 <!-- functional::as_env -->
175 <struct name=
"as_env">
176 <inherit><classname>proto::callable
</classname></inherit>
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.
182 <struct name=
"result">
184 <template-type-parameter name=
"Sig"/>
186 <typedef name=
"type">
187 <type><replaceable>see-below
</replaceable></type>
189 <para>See
<code><methodname>proto::functional::as_env::operator()
</methodname></code>.
</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
<></code>.
200 <method-group name=
"public member functions">
201 <overloaded-method name=
"operator()">
202 <signature cv=
"const">
204 <template-type-parameter name=
"T"/>
206 <type><replaceable>see-below
</replaceable></type>
208 <paramtype>T
&</paramtype>
211 <signature cv=
"const">
213 <template-type-parameter name=
"T"/>
215 <type><replaceable>see-below
</replaceable></type>
217 <paramtype>T const
&</paramtype>
222 If
<code><classname>proto::is_env
</classname><T
>::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.
227 Otherwise, this function returns
<code>t
</code> by reference.
234 <!-- functional::has_env_var -->
235 <struct name=
"has_env_var">
236 <inherit><classname>proto::callable
</classname></inherit>
238 <template-type-parameter name=
"Key"/>
241 A unary boolean
<conceptname>PolymorphicFunctionObject
</conceptname> used for determining whether a particular
242 transform environment has a value associated with a particular key.
244 <struct name=
"result">
246 <template-type-parameter name=
"Sig"/>
248 <typedef name=
"type">
249 <type><replaceable>see-below
</replaceable></type>
251 <para>See
<code><methodname>proto::functional::has_env_var::operator()
</methodname></code>.
</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
<></code>.
262 <method-group name=
"public member functions">
263 <method name=
"operator()" cv=
"const">
265 <template-type-parameter name=
"Env"/>
267 <type><replaceable>see-below
</replaceable></type>
269 <paramtype>Env const
&</paramtype>
273 This function behaves as follows:
276 If
<code><classname>proto::is_env
</classname><Env
>::value
</code> is
<code>true
</code>:
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.
285 Otherwise, return
<code>mpl::true_
</code>.
293 If
<code>Key
</code> is
<code><classname>proto::data_type
</classname></code>,
294 return
<code>mpl::true_
</code>.
297 Otherwise, return
<code>mpl::false_
</code>.
308 <!-- functional::env_var -->
309 <struct name=
"env_var">
310 <inherit><classname>proto::callable
</classname></inherit>
312 <template-type-parameter name=
"Key"/>
315 A unary
<conceptname>PolymorphicFunctionObject
</conceptname> used for fetching the value
316 associated with a particular key in a transform environment.
318 <struct name=
"result">
320 <template-type-parameter name=
"Sig"/>
322 <typedef name=
"type">
323 <type><replaceable>see-below
</replaceable></type>
325 <para>See
<code><methodname>proto::functional::env_var::operator()
</methodname></code>.
</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
<></code>.
336 <method-group name=
"public member functions">
337 <method name=
"operator()" cv=
"const">
339 <template-type-parameter name=
"Env"/>
341 <type><replaceable>see-below
</replaceable></type>
343 <paramtype>Env const
&</paramtype>
347 This function behaves as follows:
350 If
<code>Key
</code> is
<code><classname>proto::data_type
</classname></code>:
353 If
<code><classname>proto::is_env
</classname><Env
>::value
</code> is
<code>true
</code>,
354 return
<code>e[
<globalname>proto::data
</globalname>]
</code>.
357 Otherwise, return
<code>e
</code>.
362 Otherwise, return
<code>e[Key()]
</code>.
367 See
<code><methodname>proto::env::operator[]
</methodname></code> for additional information.
376 <namespace name=
"result_of">
377 <struct name=
"as_env">
379 <template-type-parameter name=
"T"/>
381 <inherit><type>boost::result_of
<<classname>proto::functional::as_env
</classname>(T)
></type></inherit>
383 Metafunction for computing the return type of
<code><functionname>proto::as_env()
</functionname></code>.
386 <struct name=
"has_env_var">
388 <template-type-parameter name=
"Env"/>
389 <template-type-parameter name=
"Key"/>
391 <inherit><type>boost::result_of
<<classname>proto::functional::has_env_var
</classname><Key
>(Env)
>::type
</type></inherit>
393 Metafunction for computing the return type of
<code><functionname>proto::has_env_var()
</functionname></code>.
396 <struct name=
"env_var">
398 <template-type-parameter name=
"Env"/>
399 <template-type-parameter name=
"Key"/>
401 <inherit><type>boost::result_of
<<classname>proto::functional::env_var
</classname><Key
>(Env)
></type></inherit>
403 Metafunction for computing the return type of
<code><functionname>proto::env_var()
</functionname></code>.
408 <!-- proto::as_env -->
409 <overloaded-function name=
"as_env">
412 <template-type-parameter name=
"T"/>
414 <type>typename
<classname>proto::result_of::as_env
</classname><T
&>::type
</type>
416 <paramtype>T
&</paramtype>
421 <template-type-parameter name=
"T"/>
423 <type>typename
<classname>proto::result_of::as_env
</classname><T const
&>::type
</type>
425 <paramtype>T const
&</paramtype>
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>.
437 <code><methodname>proto::data_type::operator=
</methodname></code>
440 <code><methodname>proto::functional::as_env::operator()
</methodname></code>
445 <returns><code><classname>proto::functional::as_env
</classname>()(t)
</code></returns>
446 </overloaded-function>
448 <!-- proto::has_env_var -->
449 <overloaded-function name=
"has_env_var">
452 <template-type-parameter name=
"Key"/>
453 <template-type-parameter name=
"Env"/>
455 <type>typename
<classname>proto::result_of::has_env_var
</classname><Env
&, Key
>::type
</type>
457 <paramtype>Env
&</paramtype>
462 <template-type-parameter name=
"Key"/>
463 <template-type-parameter name=
"Env"/>
465 <type>typename
<classname>proto::result_of::has_env_var
</classname><Env const
&, Key
>::type
</type>
467 <paramtype>Env const
&</paramtype>
471 For testing to see whether a value exists in a transform environment corresponding to the
472 specified
<code>Key
</code>.
479 <code><methodname>proto::functional::has_env_var::operator()
</methodname></code>
484 <returns><code><classname>proto::functional::has_env_var
<Key
></classname>()(e)
</code></returns>
485 </overloaded-function>
487 <!-- proto::env_var -->
488 <overloaded-function name=
"env_var">
491 <template-type-parameter name=
"Key"/>
492 <template-type-parameter name=
"Env"/>
494 <type>typename
<classname>proto::result_of::env_var
</classname><Env
&, Key
>::type
</type>
496 <paramtype>Env
&</paramtype>
501 <template-type-parameter name=
"Key"/>
502 <template-type-parameter name=
"Env"/>
504 <type>typename
<classname>proto::result_of::env_var
</classname><Env const
&, Key
>::type
</type>
506 <paramtype>Env const
&</paramtype>
510 For fetching the value from a transform environment corresponding to the
511 specified
<code>Key
</code>.
518 <code><methodname>proto::functional::env_var::operator()
</methodname></code>
523 <returns><code><classname>proto::functional::env_var
<Key
></classname>()(e)
</code></returns>
524 </overloaded-function>
526 <!-- proto::operator, -->
527 <overloaded-function name=
"operator,">
530 <template-type-parameter name=
"Env"/>
531 <template-type-parameter name=
"Key"/>
532 <template-type-parameter name=
"Value"/>
534 <type><classname>proto::env
</classname><Key, Value,
<replaceable>UNCVREF
</replaceable>(typename
<classname>proto::result_of::as_env
</classname><Env
&>::type)
></type>
535 <parameter name=
"other">
536 <paramtype>Env
&</paramtype>
538 <parameter name=
"head">
539 <paramtype><classname>proto::env
</classname><Key, Value
> const
&</paramtype>
544 <template-type-parameter name=
"Env"/>
545 <template-type-parameter name=
"Key"/>
546 <template-type-parameter name=
"Value"/>
548 <type><classname>proto::env
</classname><Key, Value,
<replaceable>UNCVREF
</replaceable>(typename
<classname>proto::result_of::as_env
</classname><Env const
&>::type)
></type>
549 <parameter name=
"other">
550 <paramtype>Env const
&</paramtype>
552 <parameter name=
"head">
553 <paramtype><classname>proto::env
</classname><Key, Value
> const
&</paramtype>
557 For composing a larger transform environment from two smaller ones.
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
569 <emphasis role=
"bold">Example:
</emphasis>
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><
578 ,
<classname>proto::env
</classname><
580 , char const (
&)[
6]
581 ,
<classname>proto::env
</classname><<classname>proto::data_type
</classname>, int
>
583 > myenv = (
<globalname>proto::data
</globalname> =
1, key0 =
"hello", key1 =
42);
584 // NOTE: operator, here --^ and here --^
586 // Check the results:
587 assert(
1 == myenv[proto::data]);
588 assert(
0 == std::strcmp(myenv[key0],
"hello"));
589 assert(
42 == myenv[key1]);
</programlisting>
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.
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.
600 <emphasis role=
"bold">See also:
</emphasis>
603 <code><methodname>proto::env::operator[]
</methodname></code>
608 <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>
609 </overloaded-function>
611 <!-- struct _env_var -->
612 <struct name=
"_env_var">
614 <template-type-parameter name=
"Key"/>
617 A primitive transform that returns the value associated with a particular
<code>Key
</code>
618 in the current transform environment.
621 <type><classname>proto::transform
</classname><_env_var
<Key
> ></type>
625 <template-type-name name=
"Expr"/>
626 <template-type-name name=
"State"/>
627 <template-type-name name=
"Data"/>
630 <type><classname>proto::transform_impl
</classname><Expr, State, Data
> ></type>
632 <typedef name=
"result_type">
633 <type>typename
<classname>proto::result_of::env_var
</classname><Data, Key
>::type
</type>
635 <method-group name=
"public member functions">
636 <method name=
"operator()" cv=
"const">
637 <type>result_type
</type>
639 <paramtype>typename impl::expr_param
</paramtype>
642 <paramtype>typename impl::state_param
</paramtype>
644 <parameter name=
"data">
645 <paramtype>typename impl::data_param
</paramtype>
647 <para>The current transform environment
</para>
652 Fetches the value associated with
<code>Key
</code> from the transform environment
653 passed in the data (third) parameter.
658 <code><classname>proto::is_env
</classname><Data
>::value
</code>
659 is
<code>true
</code>.
664 <code><functionname>proto::env_var
</functionname>(data)
</code>
672 See
<code><classname>proto::_env_var::impl
</classname></code> for the full details.
680 A primitive transform that returns the current transform environment unmodified.
683 <type><classname>proto::transform
</classname><_env
></type>
687 <template-type-name name=
"Expr"/>
688 <template-type-name name=
"State"/>
689 <template-type-name name=
"Data"/>
692 <type><classname>proto::transform_impl
</classname><Expr, State, Data
></type>
694 <typedef name=
"result_type">
697 <method-group name=
"public member functions">
698 <method name=
"operator()" cv=
"const">
699 <type>result_type
</type>
701 <paramtype>typename impl::expr_param
</paramtype>
704 <paramtype>typename impl::state_param
</paramtype>
706 <parameter name=
"data">
707 <paramtype>typename impl::data_param
</paramtype>
709 <para>The current transform environment
</para>
714 Returns the current transform environment
715 passed in the data (third) parameter.
728 See
<code><classname>proto::_env::impl
</classname></code> for the full details.
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"/>
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.
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
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.
755 <emphasis role=
"bold">Example:
</emphasis>
758 <programlisting>BOOST_PROTO_DEFINE_ENV_VAR(mykey_type, mykey);
761 :
<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
> >
766 <classname alt=
"boost::proto::terminal">proto::terminal
</classname><int
>::type i = {
42};
767 char const * sz = FetchMyKey()(i,
0, (mykey =
"hello!"));
768 assert(
0 == std::strcmp(sz,
"hello!");