ceph/src/boost/libs/proto/doc/reference/domain.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/domain.hpp">
  10   <para>
  11     Contains definition of the <computeroutput><classname alt="boost::proto::domain">proto::domain&lt;&gt;</classname>
  12     </computeroutput> class template and helpers for defining domains with a generator for customizing expression
  13     construction and a grammar for controlling operator overloading.
  14   </para>
  15   <namespace name="boost">
  16     <namespace name="proto">
  17
  18       <!-- proto::domain<> -->
  19       <struct name="domain">
  20         <template>
  21           <template-type-parameter name="Generator">
  22             <default><classname>proto::default_generator</classname></default>
  23           </template-type-parameter>
  24           <template-type-parameter name="Grammar">
  25             <default><classname>proto::_</classname></default>
  26           </template-type-parameter>
  27           <template-type-parameter name="Super">
  28             <default><replaceable>unspecified</replaceable></default>
  29           </template-type-parameter>
  30         </template>
  31         <inherit><type>Generator</type></inherit>
  32         <purpose>For use in defining domain tags to be used with <computeroutput>
  33           <classname alt="proto::extends">proto::extends&lt;&gt;</classname></computeroutput>,
  34           <computeroutput><macroname>BOOST_PROTO_EXTENDS</macroname>()</computeroutput> and
  35           <computeroutput><macroname>BOOST_PROTO_DEFINE_OPERATORS</macroname>()</computeroutput>.
  36           A <emphasis>domain</emphasis> associates an expression type with a <emphasis>generator</emphasis>,
  37           and optionally a <emphasis>grammar</emphasis>. It may also have a super-domain. Expressions
  38           in a sub-domain are interoperable (i.e. can be combined freely with) expressions in a
  39           super-domain. Finally, domains control how non-Proto objects are turned into Proto
  40           expressions and how they are combined to form larger Proto expressions.
  41         </purpose>
  42         <description>
  43           <para>
  44             The Generator parameter determines how new expressions in the domain are post-processed. Typically, a generator
  45             wraps all new expressions in a wrapper that imparts domain-specific behaviors to expressions within
  46             its domain. (See <computeroutput><classname alt="proto::extends">proto::extends&lt;&gt;</classname></computeroutput>.)
  47           </para>
  48           <para>
  49             The Grammar parameter determines whether a given expression is valid within the domain, and automatically
  50             disables any operator overloads which would cause an invalid expression to be created. By default,
  51             the Grammar parameter defaults to the wildcard, <computeroutput><classname>proto::_</classname>
  52             </computeroutput>, which makes all expressions valid within the domain.
  53           </para>
  54           <para>
  55             The Super parameter declares the domain currently being defined to be a sub-domain of Super. An expression in
  56             a sub-domain can be freely combined with expressions in its super-domain (and <emphasis>its</emphasis>
  57             super-domain, etc.).
  58           </para>
  59           <para>
  60             Example: <programlisting> template&lt;typename Expr&gt;
  61  struct MyExpr;
  62
  63  struct MyGrammar
  64    : <classname>proto::or_</classname>&lt; <classname>proto::terminal</classname>&lt;_&gt;, <classname>proto::plus</classname>&lt;MyGrammar, MyGrammar&gt; &gt;
  65  {};
  66
  67  // Define MyDomain, in which all expressions are
  68  // wrapped in MyExpr&lt;&gt; and only expressions that
  69  // conform to MyGrammar are allowed.
  70  struct MyDomain
  71    : <classname>proto::domain</classname>&lt;<classname>proto::generator</classname>&lt;MyExpr&gt;, MyGrammar&gt;
  72  {};
  73
  74  // Use MyDomain to define MyExpr
  75  template&lt;typename Expr&gt;
  76  struct MyExpr
  77    : <classname>proto::extends</classname>&lt;Expr, MyExpr&lt;Expr&gt;, MyDomain&gt;
  78  {
  79      // ...
  80  };
  81             </programlisting>
  82           </para>
  83           <para>
  84             The <computeroutput><classname>domain::as_expr</classname>&lt;&gt;</computeroutput> and
  85             <computeroutput><classname>domain::as_child</classname>&lt;&gt;</computeroutput> member
  86             templates define how non-Proto objects are turned into Proto terminals and how Proto
  87             expressions should be processed before they are combined to form larger expressions.
  88             They can be overridden in a derived domain for customization. See their descriptions to
  89             understand how Proto uses these two templates and what their default behavior is.
  90           </para>
  91         </description>
  92         <typedef name="proto_grammar">
  93           <type>Grammar</type>
  94         </typedef>
  95         <typedef name="proto_generator">
  96           <type>Generator</type>
  97         </typedef>
  98         <typedef name="proto_super_domain">
  99           <type>Super</type>
 100         </typedef>
 101
 102         <struct name="as_expr">
 103           <template>
 104             <template-type-parameter name="T"/>
 105           </template>
 106           <inherit><type><classname>proto::callable</classname></type></inherit>
 107           <purpose>
 108             A callable unary MonomorphicFunctionObject that specifies how objects are turned into
 109             Proto expressions in this domain. The resulting expression object is suitable for storage
 110             in a local variable.
 111           </purpose>
 112           <description>
 113             <para>
 114               A unary MonomorphicFunctionObject that specifies how objects are turned into Proto
 115               expressions in this domain. The resulting expression object is suitable for storage
 116               in a local variable. In that scenario, it is usually preferable to return
 117               expressions by value; and, in the case of objects that are not yet Proto expressions,
 118               to wrap them by value (if possible) in a new Proto terminal expression. (Contrast
 119               this description with the description for
 120               <computeroutput><classname>proto::domain::as_child</classname></computeroutput>.)
 121             </para>
 122             <para>
 123               The <computeroutput>as_expr</computeroutput> function object turns objects into
 124               Proto expressions, if  they are not already, by making them Proto terminals held by
 125               value if possible. Objects that are already Proto expressions are simply returned
 126               by value. If
 127               <computeroutput>wants_basic_expr&lt;Generator&gt;::value</computeroutput> is true,
 128               then let <emphasis>E</emphasis> be
 129               <computeroutput><classname>proto::basic_expr</classname></computeroutput>;
 130               otherwise, let <emphasis>E</emphasis> be
 131               <computeroutput><classname>proto::expr</classname></computeroutput>.
 132               Given an lvalue <computeroutput>t</computeroutput> of type
 133               <computeroutput>T</computeroutput>:
 134               <itemizedlist>
 135                 <listitem>
 136                   If <computeroutput>T</computeroutput> is not a Proto expression type, the resulting
 137                   terminal is calculated as follows:
 138                   <itemizedlist>
 139                     <listitem>
 140                       If <computeroutput>T</computeroutput> is a function type, an abstract type, or
 141                       a type derived from <computeroutput>std::ios_base</computeroutput>, let
 142                       <replaceable>A</replaceable> be <computeroutput>T &amp;</computeroutput>.
 143                     </listitem>
 144                     <listitem>
 145                       Otherwise, let <replaceable>A</replaceable> be the type
 146                       <computeroutput>T</computeroutput> stripped of cv-qualifiers.
 147                     </listitem>
 148                   </itemizedlist>
 149                   Then, the result of <computeroutput>as_expr&lt;T&gt;()(t)</computeroutput> is
 150                   <computeroutput>Generator()(<replaceable>E</replaceable>&lt;tag::terminal,
 151                   term&lt; <replaceable>A</replaceable> &gt; &gt;::make(t))</computeroutput>.
 152                 </listitem>
 153                 <listitem>
 154                   Otherwise, the result is <computeroutput>t</computeroutput> converted to an
 155                   (un-const) rvalue.
 156                 </listitem>
 157               </itemizedlist>
 158             </para>
 159           </description>
 160           <typedef name="result_type">
 161             <type><replaceable>see-below</replaceable></type>
 162           </typedef>
 163           <method-group name="public member functions">
 164             <method name="operator()" cv="const">
 165               <type>result_type</type>
 166               <parameter name="t">
 167                 <paramtype>T &amp;</paramtype>
 168                 <description>
 169                   <para>The object to wrap.</para>
 170                 </description>
 171               </parameter>
 172             </method>
 173           </method-group>
 174         </struct>
 175
 176         <struct name="as_child">
 177           <template>
 178             <template-type-parameter name="T"/>
 179           </template>
 180           <inherit><type><classname>proto::callable</classname></type></inherit>
 181           <purpose>
 182             A callable unary MonomorphicFunctionObject that specifies how objects are turned into
 183             Proto expressions in this domain, for use in scenarios where the resulting expression is
 184             intended to be made a child of another expression.
 185           </purpose>
 186           <description>
 187             <para>
 188               A unary MonomorphicFunctionObject that specifies how objects are turned into Proto
 189               expressions in this domain. The resulting expression object is suitable for storage
 190               as a child of another expression. In that scenario, it is usually
 191               preferable to store child expressions by reference; or, in the case of objects that
 192               are not yet Proto expressions, to wrap them by reference in a new Proto terminal
 193               expression. (Contrast this description with the description for
 194               <computeroutput><classname>proto::domain::as_expr</classname></computeroutput>.)
 195             </para>
 196             <para>
 197               The <computeroutput>as_child</computeroutput> function object turns objects into
 198               Proto expressions, if  they are not already, by making them Proto terminals held by
 199               reference. Objects that are already Proto expressions are simply returned by
 200               reference. If
 201               <computeroutput>wants_basic_expr&lt;Generator&gt;::value</computeroutput> is true,
 202               then let <emphasis>E</emphasis> be
 203               <computeroutput><classname>proto::basic_expr</classname></computeroutput>;
 204               otherwise, let <emphasis>E</emphasis> be
 205               <computeroutput><classname>proto::expr</classname></computeroutput>.
 206               Given an lvalue <computeroutput>t</computeroutput> of type
 207               <computeroutput>T</computeroutput>:
 208               <itemizedlist>
 209                 <listitem>
 210                   If <computeroutput>T</computeroutput> is not a Proto expression type, the resulting
 211                   terminal is
 212                   <computeroutput>Generator()(<replaceable>E</replaceable>&lt;tag::terminal,
 213                   term&lt; <computeroutput>T &amp;</computeroutput> &gt; &gt;::make(t))</computeroutput>.
 214                 </listitem>
 215                 <listitem>
 216                   Otherwise, the result is the lvalue <computeroutput>t</computeroutput>.
 217                 </listitem>
 218               </itemizedlist>
 219             </para>
 220           </description>
 221           <typedef name="result_type">
 222             <type><replaceable>see-below</replaceable></type>
 223           </typedef>
 224           <method-group name="public member functions">
 225             <method name="operator()" cv="const">
 226               <type>result_type</type>
 227               <parameter name="t">
 228                 <paramtype>T &amp;</paramtype>
 229                 <description>
 230                   <para>The object to wrap.</para>
 231                 </description>
 232               </parameter>
 233             </method>
 234           </method-group>
 235         </struct>
 236       </struct>
 237
 238       <!-- proto::default_domain -->
 239       <struct name="default_domain">
 240         <inherit><classname>proto::domain</classname>&lt;&gt;</inherit>
 241         <purpose>The domain expressions have by default, if <computeroutput>
 242           <classname alt="proto::extends">proto::extends&lt;&gt;</classname></computeroutput> has not been used
 243           to associate a domain with an expression.</purpose>
 244       </struct>
 245
 246       <!-- proto::basic_default_domain -->
 247       <struct name="basic_default_domain">
 248         <inherit><classname>proto::domain</classname>&lt; <classname>proto::basic_default_generator</classname> &gt;</inherit>
 249         <purpose>A domain similiar in purpose to <classname>proto::default_domain</classname>, except stating
 250         a preference for <classname>proto::basic_expr</classname>&lt;&gt; over <classname>proto::expr</classname>&lt;&gt;.</purpose>
 251       </struct>
 252
 253       <!-- proto::deduce_domain -->
 254       <struct name="deduce_domain">
 255         <purpose>A pseudo-domain for use in functions and metafunctions that require a domain parameter.
 256           It indicates that the domain of the parent node should be inferred from the domains of the child nodes.</purpose>
 257         <description>
 258           <para>
 259             When <computeroutput>proto::deduce_domain</computeroutput> is used as a domain &#x2014; either
 260             explicitly or implicitly by
 261             <computeroutput><functionname>proto::make_expr</functionname>()</computeroutput>,
 262             <computeroutput><functionname>proto::unpack_expr</functionname>()</computeroutput>,
 263             or Proto's operator overloads &#x2014; Proto will use the domains of the child expressions to
 264             compute the domain of the parent. It is done in such a way that (A) expressions in domains
 265             that share a common super-domain are interoperable, and (B) expressions that are in
 266             the default domain (or a sub-domain thereof) are interoperable with <emphasis>all</emphasis>
 267             expressions. The rules are as follows:
 268             <itemizedlist>
 269               <listitem>
 270                 A sub-domain is <emphasis>stronger</emphasis> than its super-domain.
 271               </listitem>
 272               <listitem>
 273                 <computeroutput><classname>proto::default_domain</classname></computeroutput>,
 274                 <computeroutput><classname>proto::basic_default_domain</classname></computeroutput>
 275                 and all their sub-domains are <emphasis>weaker</emphasis> than all other domains.
 276               </listitem>
 277               <listitem>
 278                 <computeroutput><classname>proto::basic_default_domain</classname></computeroutput>
 279                 is weaker than
 280                 <computeroutput><classname>proto::default_domain</classname></computeroutput>.
 281               </listitem>
 282               <listitem>
 283                 For each child, define a set of domains <emphasis>S<subscript>N</subscript></emphasis>
 284                 that includes the child's domain and all its super-domains.
 285               </listitem>
 286               <listitem>
 287                 Define a set <emphasis>I<subscript>S</subscript></emphasis> that is the intersection of
 288                 all the individual sets <emphasis>S<subscript>N</subscript></emphasis> that don't contain
 289                 <computeroutput><classname>proto::default_domain</classname></computeroutput> or
 290                 <computeroutput><classname>proto::basic_default_domain</classname></computeroutput>.
 291               </listitem>
 292               <listitem>
 293                 Define a set <emphasis>I<subscript>W</subscript></emphasis> that is the intersection of
 294                 all the individual sets <emphasis>S<subscript>N</subscript></emphasis> that contain
 295                 <computeroutput><classname>proto::default_domain</classname></computeroutput> or
 296                 <computeroutput><classname>proto::basic_default_domain</classname></computeroutput>.
 297               </listitem>
 298               <listitem>
 299                 Define a set <emphasis>P</emphasis> that is the union of
 300                 <emphasis>I<subscript>S</subscript></emphasis> and
 301                 <emphasis>I<subscript>W</subscript></emphasis>.
 302               </listitem>
 303               <listitem>
 304                 The common domain is the strongest domain in set <emphasis>P</emphasis>, with the
 305                 following caveats.
 306               </listitem>
 307               <listitem>
 308                 Let <emphasis>U</emphasis> be the union of all sets
 309                 <emphasis>S<subscript>N</subscript></emphasis>. If the result is
 310                 <computeroutput><classname>proto::default_domain</classname></computeroutput> or
 311                 <computeroutput><classname>proto::basic_default_domain</classname></computeroutput>
 312                 and <emphasis>U</emphasis> contains an element that is <emphasis>not </emphasis>
 313                 <computeroutput><classname>proto::default_domain</classname></computeroutput> or
 314                 <computeroutput><classname>proto::basic_default_domain</classname></computeroutput>,
 315                 it is an error.
 316               </listitem>
 317             </itemizedlist>
 318           </para>
 319           <para>
 320             Note: the above description sounds like it would be expensive to compute at compile time.
 321             In fact, it can all be done using C++ function overloading.
 322           </para>
 323         </description>
 324       </struct>
 325
 326       <!-- proto::is_domain -->
 327       <struct name="is_domain">
 328         <template>
 329           <template-type-parameter name="T"/>
 330         </template>
 331         <inherit>
 332           <type>mpl::bool_&lt; <replaceable>true-or-false</replaceable> &gt;</type>
 333         </inherit>
 334         <description>
 335           <para>
 336             A metafunction that returns <computeroutput>mpl::true_</computeroutput> if the type
 337             <computeroutput>T</computeroutput> is the type of a Proto domain;
 338             <computeroutput>mpl::false_</computeroutput> otherwise. If <computeroutput>T</computeroutput>
 339             inherits from <computeroutput><classname alt="proto::domain">proto::domain&lt;&gt;</classname></computeroutput>,
 340             <computeroutput>is_domain&lt;T&gt;</computeroutput> is <computeroutput>mpl::true_</computeroutput>.
 341           </para>
 342         </description>
 343       </struct>
 344
 345       <!-- proto::domain_of -->
 346       <struct name="domain_of">
 347         <template>
 348           <template-type-parameter name="T"/>
 349         </template>
 350         <description>
 351           <para>
 352             A metafunction that returns the domain of a given type. If <computeroutput>T</computeroutput> is a Proto
 353             expression type, it returns that expression's associated domain. If not, it returns
 354             <computeroutput><classname>proto::default_domain</classname></computeroutput>.
 355           </para>
 356         </description>
 357         <typedef name="type">
 358           <type><replaceable>domain-of-T</replaceable></type>
 359         </typedef>
 360       </struct>
 361
 362       <!-- proto::base_expr --><!--
 363       <struct name="base_expr">
 364         <template>
 365           <template-type-parameter name="Domain"/>
 366           <template-type-parameter name="Tag"/>
 367           <template-type-parameter name="Args"/>
 368         </template>
 369         <description>
 370           <para>
 371             Given a domain, a tag type and an argument list,
 372             compute the type of the expression to generate. This is
 373             either an instance of
 374             <computeroutput><classname>proto::basic_expr</classname>&lt;&gt;</computeroutput> or
 375             <computeroutput><classname>proto::expr</classname>&lt;&gt;</computeroutput>.
 376             </para>
 377         </description>
 378         <typedef name="A">
 379           <purpose>For exposition only</purpose>
 380           <type><classname>proto::basic_expr</classname>&lt; Tag, Args &gt;</type>
 381         </typedef>
 382         <typedef name="B">
 383           <purpose>For exposition only</purpose>
 384           <type><classname>proto::expr</classname>&lt; Tag, Args &gt;</type>
 385         </typedef>
 386         <typedef name="type">
 387           <type>typename mpl::if_&lt;<classname>proto::wants_basic_expr</classname>&lt; Domain &gt;, A, B&gt;::type</type>
 388         </typedef>
 389       </struct>-->
 390
 391     </namespace>
 392   </namespace>
 393 </header>