libs/parameter_python/doc/html/index.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
   7 <title>The Boost Parameter Library Python Binding Documentation</title>
   8 <meta name="authors" content="David Abrahams  Daniel Wallin" />
   9 <meta name="organization" content="BoostPro Computing" />
  10 <meta name="date" content="$Date$" />
  11 <meta name="copyright" content="Copyright David Abrahams, Daniel Wallin 2005-2009. 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)" />
  12 <link rel="stylesheet" href="rst.css" type="text/css" />
  13 </head>
  14 <body>
  15 <div class="document" id="the-boost-parameter-library-python-binding-documentation">
  16 <h1 class="title">The Boost Parameter Library Python Binding Documentation</h1>
  17 <table class="docinfo" frame="void" rules="none">
  18 <col class="docinfo-name" />
  19 <col class="docinfo-content" />
  20 <tbody valign="top">
  21 <tr><th class="docinfo-name">Authors:</th>
  22 <td>David Abrahams
  23 <br />Daniel Wallin</td></tr>
  24 <tr><th class="docinfo-name">Contact:</th>
  25 <td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="last reference external" href="mailto:daniel&#64;boostpro.com">daniel&#64;boostpro.com</a></td></tr>
  26 <tr><th class="docinfo-name">Organization:</th>
  27 <td><a class="first last reference external" href="http://www.boostpro.com">BoostPro Computing</a></td></tr>
  28 <tr><th class="docinfo-name">Date:</th>
  29 <td>$Date$</td></tr>
  30 <tr><th class="docinfo-name">Copyright:</th>
  31 <td>Copyright David Abrahams, Daniel Wallin
  32 2005-2009. Distributed under the Boost Software License,
  33 Version 1.0. (See accompanying file LICENSE_1_0.txt
  34 or copy at <a class="reference external" href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</td></tr>
  35 </tbody>
  36 </table>
  37 <div class="abstract topic">
  38 <p class="topic-title first">Abstract</p>
  39 <p>Makes it possible to bind Boost.Parameter-enabled
  40 functions, operators and constructors to Python.</p>
  41 </div>
  42 <p><a class="reference external" href="../../../../index.htm"><img alt="Boost" src="../../../../boost.png" /></a></p>
  43 <div class="contents topic" id="contents">
  44 <p class="topic-title first">Contents</p>
  45 <ul class="simple">
  46 <li><a class="reference internal" href="#introduction" id="id7">Introduction</a></li>
  47 <li><a class="reference internal" href="#tutorial" id="id8">Tutorial</a></li>
  48 <li><a class="reference internal" href="#concept-parameterspec" id="id9">concept <span class="concept">ParameterSpec</span></a></li>
  49 <li><a class="reference internal" href="#special-keywords" id="id10"><em>special</em> keywords</a></li>
  50 <li><a class="reference internal" href="#class-template-init" id="id11">class template <tt class="docutils literal">init</tt></a></li>
  51 <li><a class="reference internal" href="#class-template-call" id="id12">class template <tt class="docutils literal">call</tt></a></li>
  52 <li><a class="reference internal" href="#class-template-function" id="id13">class template <tt class="docutils literal">function</tt></a></li>
  53 <li><a class="reference internal" href="#function-template-def" id="id14">function template <tt class="docutils literal">def</tt></a></li>
  54 <li><a class="reference internal" href="#portability" id="id15">Portability</a></li>
  55 </ul>
  56 </div>
  57 <div class="section" id="introduction">
  58 <h1><a class="toc-backref" href="#id7">Introduction</a></h1>
  59 <p><tt class="docutils literal">boost/parameter/python.hpp</tt> introduces a group of <a class="reference external" href="../../../python/doc/v2/def_visitor.html"><tt class="docutils literal">def_visitors</tt></a> that can
  60 be used to easily expose Boost.Parameter-enabled member functions to Python with
  61 Boost.Python. It also provides a function template <tt class="docutils literal">def()</tt> that can be used
  62 to expose Boost.Parameter-enabled free functions.</p>
  63 <p>When binding a Boost.Parameter enabled function, the keyword tags
  64 must be specified.  Additionally, because Boost.Parameter enabled
  65 functions are templates, the desired function signature must be
  66 specified.</p>
  67 <!-- The keyword tags are specified as an `MPL Sequence`_, using the
  68 pointer qualifications described in |ParameterSpec|_ below.  The
  69 signature is also specifid as an `MPL sequence`_ of parameter
  70 types. Additionally, ``boost::parameter::python::function`` and
  71 ``boost::parameter::python::def`` requires a class with forwarding
  72 overloads. We will take a closer look at how this is done in the
  73 tutorial section below. -->
  74 <p>The keyword tags and associated argument types are specified as an <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL
  75 Sequence</a>, using the function type syntax described in <a class="reference internal" href="#concept-parameterspec"><span class="concept">ParameterSpec</span></a>
  76 below. Additionally, <tt class="docutils literal"><span class="pre">boost::parameter::python::function</span></tt> and
  77 <tt class="docutils literal"><span class="pre">boost::parameter::python::def</span></tt> requires a class with forwarding overloads.
  78 We will take a closer look at how this is done in the tutorial section below.</p>
  79 <!-- The last two sentences are terribly vague.  Which namespace is -->
  80 <!-- ``function`` in?  Isn't the return type always needed?  What -->
  81 <!-- else are we going to do other than pass these sequences to -->
  82 <!-- function? -->
  83 </div>
  84 <div class="section" id="tutorial">
  85 <h1><a class="toc-backref" href="#id8">Tutorial</a></h1>
  86 <p>In this section we will outline the steps needed to bind a simple
  87 Boost.Parameter-enabled member function to Python. Knowledge of the
  88 Boost.Parameter <a class="reference external" href="index.html">macros</a> are required to understand this section.</p>
  89 <p>The class and member function we are interested in binding looks
  90 like this:</p>
  91 <pre class="literal-block">
  92 #include &lt;boost/parameter/keyword.hpp&gt;
  93 #include &lt;boost/parameter/preprocessor.hpp&gt;
  94 #include &lt;boost/parameter/python.hpp&gt;
  95 #include &lt;boost/python.hpp&gt;
  96
  97 // First the keywords
  98 BOOST_PARAMETER_KEYWORD(tag, title)
  99 BOOST_PARAMETER_KEYWORD(tag, width)
 100 BOOST_PARAMETER_KEYWORD(tag, height)
 101
 102 class window
 103 {
 104 public:
 105     BOOST_PARAMETER_MEMBER_FUNCTION(
 106       (void), open, tag,
 107       (required (title, (std::string)))
 108       (optional (width, (unsigned), 400)
 109                 (height, (unsigned), 400))
 110     )
 111     {
 112         <em>… function implementation …</em>
 113     }
 114 };
 115 </pre>
 116 <!-- @example.prepend('#include <cassert>') -->
 117 <!-- @example.replace_emphasis('''
 118 assert(title == "foo");
 119 assert(height == 20);
 120 assert(width == 400);
 121 ''') -->
 122 <p>It defines a set of overloaded member functions called <tt class="docutils literal">open</tt> with one
 123 required parameter and two optional ones. To bind this member function to
 124 Python we use the binding utility <tt class="docutils literal"><span class="pre">boost::parameter::python::function</span></tt>.
 125 <tt class="docutils literal"><span class="pre">boost::parameter::python::function</span></tt> is a <a class="reference external" href="../../../python/doc/v2/def_visitor.html"><tt class="docutils literal">def_visitor</tt></a> that we'll instantiate
 126 and pass to <tt class="docutils literal"><span class="pre">boost::python::class_::def()</span></tt>.</p>
 127 <p>To use <tt class="docutils literal"><span class="pre">boost::parameter::python::function</span></tt> we first need to define
 128 a class with forwarding overloads. This is needed because <tt class="docutils literal"><span class="pre">window::open()</span></tt>
 129 is a function template, so we can't refer to it in any other way.</p>
 130 <pre class="literal-block">
 131 struct open_fwd
 132 {
 133     template &lt;class A0, class A1, class A2&gt;
 134     void operator()(
 135         boost::type&lt;void&gt;, window&amp; self
 136       , A0 const&amp; a0, A1 const&amp; a1, A2 const&amp; a2
 137     )
 138     {
 139         self.open(a0, a1, a2);
 140     }
 141 };
 142 </pre>
 143 <p>The first parameter, <tt class="docutils literal"><span class="pre">boost::type&lt;void&gt;</span></tt>, tells the forwarding overload
 144 what the return type should be. In this case we know that it's always void
 145 but in some cases, when we are exporting several specializations of a
 146 Boost.Parameter-enabled template, we need to use that parameter to
 147 deduce the return type.</p>
 148 <p><tt class="docutils literal"><span class="pre">window::open()</span></tt> takes a total of 3 parameters, so the forwarding function
 149 needs to take three parameters as well.</p>
 150 <div class="note">
 151 <p class="first admonition-title">Note</p>
 152 <p class="last">We only need one overload in the forwarding class, despite the
 153 fact that there are two optional parameters. There are special
 154 circumstances when several overload are needed; see
 155 <a class="reference internal" href="#special-keywords">special keywords</a>.</p>
 156 </div>
 157 <p>Next we'll define the module and export the class:</p>
 158 <pre class="literal-block">
 159 BOOST_PYTHON_MODULE(my_module)
 160 {
 161     using namespace boost::python;
 162     namespace py = boost::parameter::python;
 163     namespace mpl = boost::mpl;
 164
 165     class_&lt;window&gt;(&quot;window&quot;)
 166         .def(
 167             &quot;open&quot;, py::function&lt;
 168                 open_fwd
 169               , mpl::vector&lt;
 170                     void
 171                   , tag::title(std::string)
 172                   , tag::width*(unsigned)
 173                   , tag::height*(unsigned)
 174                 &gt;
 175             &gt;()
 176         );
 177 }
 178 </pre>
 179 <!-- @jam_prefix.append('import python ;') -->
 180 <!-- @jam_prefix.append('stage . : my_module /boost/python//boost_python ;') -->
 181 <!-- @my_module = build(
 182     output = 'my_module'
 183   , target_rule = 'python-extension'
 184   , input = '/boost/python//boost_python'
 185   , howmany = 'all'
 186 ) -->
 187 <!-- @del jam_prefix[:] -->
 188 <p><tt class="docutils literal"><span class="pre">py::function</span></tt> is passed two parameters. The first one is the class with
 189 forwarding overloads that we defined earlier. The second one is an <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL
 190 Sequence</a> with the keyword tag types and argument types for the function
 191 specified as function types. The pointer syntax used in <tt class="docutils literal"><span class="pre">tag::width*</span></tt> and
 192 <tt class="docutils literal"><span class="pre">tag::height*</span></tt> means that the parameter is optional. The first element of
 193 the <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL Sequence</a> is the return type of the function, in this case <tt class="docutils literal">void</tt>,
 194 which is passed as the first argument to <tt class="docutils literal">operator()</tt> in the forwarding
 195 class.</p>
 196 <!-- The
 197 pointer syntax means that the parameter is optional, so in this case
 198 ``width`` and ``height`` are optional parameters. The third parameter
 199 is an `MPL Sequence`_ with the desired function signature. The return type comes first, and
 200 then the parameter types:
 201
 202 .. parsed-literal::
 203
 204     mpl::vector<void,        std::string, unsigned, unsigned>
 205                 *return type*  *title*        *width*     *height*
 206
 207 .. @ignore() -->
 208 <p>That's it! This class can now be used in Python with the expected syntax:</p>
 209 <pre class="literal-block">
 210 &gt;&gt;&gt; w = my_module.window()
 211 &gt;&gt;&gt; w.open(title = &quot;foo&quot;, height = 20)
 212 </pre>
 213 <!-- @example.prepend('import my_module') -->
 214 <!-- @run_python(module_path = my_module) -->
 215 <!-- Sorry to say this at such a late date, but this syntax really -->
 216 <!-- strikes me as cumbersome.  Couldn't we do something like:
 217
 218  class_<window>("window")
 219        .def(
 220            "open",
 221            (void (*)(
 222                tag::title(std::string),
 223                tag::width*(unsigned),
 224                tag::height*(unsigned))
 225            )0
 226        );
 227
 228 or at least:
 229
 230    class_<window>("window")
 231        .def(
 232            "open",
 233            mpl::vector<
 234                void,
 235                tag::title(std::string),
 236                tag::width*(unsigned),
 237                tag::height*(unsigned)
 238            >()
 239        );
 240
 241 assuming, that is, that we will have to repeat the tags (yes,
 242 users of broken compilers will have to give us function pointer
 243 types instead). -->
 244 </div>
 245 <hr class="docutils" />
 246 <div class="section" id="concept-parameterspec">
 247 <h1><a class="toc-backref" href="#id9">concept <span class="concept">ParameterSpec</span></a></h1>
 248 <p>A <span class="concept">ParameterSpec</span> is a function type <tt class="docutils literal">K(T)</tt> that describes both the keyword tag,
 249 <tt class="docutils literal">K</tt>, and the argument type, <tt class="docutils literal">T</tt>, for a parameter.</p>
 250 <p><tt class="docutils literal">K</tt> is either:</p>
 251 <ul class="simple">
 252 <li>A <em>required</em> keyword of the form <tt class="docutils literal">Tag</tt></li>
 253 <li><strong>or</strong>, an <em>optional</em> keyword of the form <tt class="docutils literal">Tag*</tt></li>
 254 <li><strong>or</strong>, a <em>special</em> keyword of the form <tt class="docutils literal">Tag**</tt></li>
 255 </ul>
 256 <p>where <tt class="docutils literal">Tag</tt> is a keyword tag type, as used in a specialization
 257 of <a class="reference external" href="../../../parameter/doc/html/reference.html#keyword"><tt class="docutils literal"><span class="pre">boost::parameter::keyword</span></tt></a>.</p>
 258 <p>The <strong>arity range</strong> for an <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL Sequence</a> of <span class="concept">ParameterSpec</span>'s is
 259 defined as the closed range:</p>
 260 <pre class="literal-block">
 261 [ mpl::size&lt;S&gt; - number of <em>special</em> keyword tags in <tt class="docutils literal">S</tt>, mpl::size&lt;S&gt; ]
 262 </pre>
 263 <p>For example, the <strong>arity range</strong> of <tt class="docutils literal"><span class="pre">mpl::vector2&lt;x(int),y(int)&gt;</span></tt> is <tt class="docutils literal">[2,2]</tt>,
 264 the <strong>arity range</strong> of <tt class="docutils literal"><span class="pre">mpl::vector2&lt;x(int),y*(int)&gt;</span></tt> is <tt class="docutils literal">[2,2]</tt> and the
 265 <strong>arity range</strong> of <tt class="docutils literal"><span class="pre">mpl::vector2&lt;x(int),y**(int)&gt;</span></tt> is <tt class="docutils literal">[1,2]</tt>.</p>
 266 </div>
 267 <div class="section" id="special-keywords">
 268 <h1><a class="toc-backref" href="#id10"><em>special</em> keywords</a></h1>
 269 <p>Sometimes it is desirable to have a default value for a parameter that differ
 270 in type from the parameter. This technique is useful for doing simple tag-dispatching
 271 based on the presence of a parameter. For example:</p>
 272 <!-- An example_ of this is given in the Boost.Parameter
 273 docs. The example uses a different technique, but could also have been written like this: -->
 274 <pre class="literal-block">
 275 namespace core
 276 {
 277   template &lt;class ArgumentPack&gt;
 278   void dfs_dispatch(ArgumentPack const&amp; args, mpl::false_)
 279   {
 280       <em>…compute and use default color map…</em>
 281   }
 282
 283   template &lt;class ArgumentPack, class ColorMap&gt;
 284   void dfs_dispatch(ArgumentPack const&amp; args, ColorMap colormap)
 285   {
 286       <em>…use colormap…</em>
 287   }
 288 }
 289
 290 template &lt;class ArgumentPack&gt;
 291 void depth_first_search(ArgumentPack const&amp; args)
 292 {
 293     core::dfs_dispatch(args, args[color | mpl::false_()]);
 294 }
 295 </pre>
 296 <!-- @example.prepend('''
 297 #include <boost/parameter/keyword.hpp>
 298 #include <boost/parameter/parameters.hpp>
 299 #include <boost/mpl/bool.hpp>
 300 #include <cassert>
 301
 302 BOOST_PARAMETER_KEYWORD(tag, color);
 303
 304 typedef boost::parameter::parameters<tag::color> params;
 305
 306 namespace mpl = boost::mpl;
 307 ''') -->
 308 <!-- @example.replace_emphasis('''
 309 assert(args[color | 1] == 1);
 310 ''') -->
 311 <!-- @example.replace_emphasis('''
 312 assert(args[color | 1] == 0);
 313 ''') -->
 314 <!-- @example.append('''
 315 int main()
 316 {
 317     depth_first_search(params()());
 318     depth_first_search(params()(color = 0));
 319 }''') -->
 320 <!-- @build() -->
 321 <!-- .. _example: index.html#dispatching-based-on-the-presence-of-a-default -->
 322 <p>In the above example the type of the default for <tt class="docutils literal">color</tt> is <tt class="docutils literal"><span class="pre">mpl::false_</span></tt>, a
 323 type that is distinct from any color map that the user might supply.</p>
 324 <p>When binding the case outlined above, the default type for <tt class="docutils literal">color</tt> will not
 325 be convertible to the parameter type. Therefore we need to tag the <tt class="docutils literal">color</tt>
 326 keyword as a <em>special</em> keyword. This is done by specifying the tag as
 327 <tt class="docutils literal"><span class="pre">tag::color**</span></tt> when binding the function (see <a class="reference internal" href="#concept-parameterspec">concept ParameterSpec</a> for
 328 more details on the tagging). By doing this we tell the binding functions that
 329 it needs to generate two overloads, one with the <tt class="docutils literal">color</tt> parameter present
 330 and one without. Had there been two <em>special</em> keywords, four overloads would
 331 need to be generated. The number of generated overloads is equal to 2<sup>N</sup>, where <tt class="docutils literal">N</tt> is the number of <em>special</em> keywords.</p>
 332 </div>
 333 <hr class="docutils" />
 334 <div class="section" id="class-template-init">
 335 <h1><a class="toc-backref" href="#id11">class template <tt class="docutils literal">init</tt></a></h1>
 336 <p>Defines a named parameter enabled constructor.</p>
 337 <pre class="literal-block">
 338 template &lt;class ParameterSpecs&gt;
 339 struct init : python::def_visitor&lt;init&lt;ParameterSpecs&gt; &gt;
 340 {
 341     template &lt;class Class&gt;
 342     void def(Class&amp; class_);
 343
 344     template &lt;class CallPolicies&gt;
 345     <em>def_visitor</em> operator[](CallPolicies const&amp; policies) const;
 346 };
 347 </pre>
 348 <!-- @ignore() -->
 349 <div class="section" id="init-requirements">
 350 <h2><tt class="docutils literal">init</tt> requirements</h2>
 351 <ul>
 352 <li><p class="first"><tt class="docutils literal">ParameterSpecs</tt> is an <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element is a
 353 model of <span class="concept">ParameterSpec</span>.</p>
 354 </li>
 355 <li><p class="first">For every <tt class="docutils literal">N</tt> in <tt class="docutils literal">[U,V]</tt>, where <tt class="docutils literal">[U,V]</tt> is the <strong>arity
 356 range</strong> of <tt class="docutils literal">ParameterSpecs</tt>, <tt class="docutils literal">Class</tt> must support these
 357 expressions:</p>
 358 <table border="1" class="docutils">
 359 <colgroup>
 360 <col width="30%" />
 361 <col width="17%" />
 362 <col width="53%" />
 363 </colgroup>
 364 <thead valign="bottom">
 365 <tr><th class="head">Expression</th>
 366 <th class="head">Return type</th>
 367 <th class="head">Requirements</th>
 368 </tr>
 369 </thead>
 370 <tbody valign="top">
 371 <tr><td><tt class="docutils literal">Class(a0, …, aN)</tt></td>
 372 <td>-</td>
 373 <td><tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt> are tagged arguments.</td>
 374 </tr>
 375 </tbody>
 376 </table>
 377 </li>
 378 </ul>
 379 </div>
 380 <div class="section" id="template-class-callpolicies-operator-callpolicies-const">
 381 <h2><tt class="docutils literal">template &lt;class CallPolicies&gt; <span class="pre">operator[](CallPolicies</span> const&amp;)</tt></h2>
 382 <p>Returns a <tt class="docutils literal">def_visitor</tt> equivalent to <tt class="docutils literal">*this</tt>, except that it
 383 uses CallPolicies when creating the binding.</p>
 384 </div>
 385 <div class="section" id="example">
 386 <h2>Example</h2>
 387 <pre class="literal-block">
 388 #include &lt;boost/parameter/keyword.hpp&gt;
 389 #include &lt;boost/parameter/preprocessor.hpp&gt;
 390 #include &lt;boost/parameter/python.hpp&gt;
 391 #include &lt;boost/python.hpp&gt;
 392 #include &lt;boost/mpl/vector.hpp&gt;
 393
 394 BOOST_PARAMETER_KEYWORD(tag, x)
 395 BOOST_PARAMETER_KEYWORD(tag, y)
 396
 397 struct base
 398 {
 399     template &lt;class ArgumentPack&gt;
 400     base(ArgumentPack const&amp; args)
 401     {
 402         <em>… use args …</em>
 403     }
 404 };
 405
 406 class X : base
 407 {
 408 public:
 409     BOOST_PARAMETER_CONSTRUCTOR(X, (base), tag,
 410         (required (x, *))
 411         (optional (y, *))
 412     )
 413 };
 414
 415 BOOST_PYTHON_MODULE(<em>module name</em>)
 416 {
 417     using namespace boost::python;
 418     namespace py = boost::parameter::python;
 419     namespace mpl = boost::mpl;
 420
 421     class_&lt;X&gt;(&quot;X&quot;, no_init)
 422         .def(
 423             py::init&lt;
 424                 mpl::vector&lt;tag::x(int), tag::y*(int)&gt;
 425             &gt;()
 426         );
 427 }
 428 </pre>
 429 <!-- @example.replace_emphasis('''
 430 assert(args[x] == 0);
 431 assert(args[y | 1] == 1);
 432 ''') -->
 433 <!-- @example.replace_emphasis('my_module') -->
 434 <!-- @jam_prefix.append('import python ;') -->
 435 <!-- @jam_prefix.append('stage . : my_module /boost/python//boost_python ;') -->
 436 <!-- @my_module = build(
 437     output = 'my_module'
 438   , target_rule = 'python-extension'
 439   , input = '/boost/python//boost_python'
 440 ) -->
 441 </div>
 442 </div>
 443 <hr class="docutils" />
 444 <div class="section" id="class-template-call">
 445 <h1><a class="toc-backref" href="#id12">class template <tt class="docutils literal">call</tt></a></h1>
 446 <p>Defines a <tt class="docutils literal">__call__</tt> operator, mapped to <tt class="docutils literal">operator()</tt> in C++.</p>
 447 <pre class="literal-block">
 448 template &lt;class ParameterSpecs&gt;
 449 struct call : python::def_visitor&lt;call&lt;ParameterSpecs&gt; &gt;
 450 {
 451     template &lt;class Class&gt;
 452     void def(Class&amp; class_);
 453
 454     template &lt;class CallPolicies&gt;
 455     <em>def_visitor</em> operator[](CallPolicies const&amp; policies) const;
 456 };
 457 </pre>
 458 <!-- @ignore() -->
 459 <div class="section" id="call-requirements">
 460 <h2><tt class="docutils literal">call</tt> requirements</h2>
 461 <ul>
 462 <li><p class="first"><tt class="docutils literal">ParameterSpecs</tt> is an <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element
 463 except the first models <span class="concept">ParameterSpec</span>. The first element
 464 is the result type of <tt class="docutils literal"><span class="pre">c(…)</span></tt>.</p>
 465 </li>
 466 <li><p class="first"><tt class="docutils literal">Class</tt> must support these expressions, where <tt class="docutils literal">c</tt> is an
 467 instance of <tt class="docutils literal">Class</tt>:</p>
 468 <table border="1" class="docutils">
 469 <colgroup>
 470 <col width="24%" />
 471 <col width="26%" />
 472 <col width="50%" />
 473 </colgroup>
 474 <thead valign="bottom">
 475 <tr><th class="head">Expression</th>
 476 <th class="head">Return type</th>
 477 <th class="head">Requirements</th>
 478 </tr>
 479 </thead>
 480 <tbody valign="top">
 481 <tr><td><tt class="docutils literal">c(a0, …, aN)</tt></td>
 482 <td>Convertible to <tt class="docutils literal">R</tt></td>
 483 <td><tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt> are tagged arguments.</td>
 484 </tr>
 485 </tbody>
 486 </table>
 487 <p>For every <tt class="docutils literal">N</tt> in <tt class="docutils literal">[U,V]</tt>, where <tt class="docutils literal">[U,V]</tt> is the <strong>arity range</strong> of <tt class="docutils literal">ParameterSpecs</tt>.</p>
 488 </li>
 489 </ul>
 490 </div>
 491 <div class="section" id="id3">
 492 <h2><tt class="docutils literal">template &lt;class CallPolicies&gt; <span class="pre">operator[](CallPolicies</span> const&amp;)</tt></h2>
 493 <p>Returns a <tt class="docutils literal">def_visitor</tt> equivalent to <tt class="docutils literal">*this</tt>, except that it
 494 uses CallPolicies when creating the binding.</p>
 495 </div>
 496 <div class="section" id="id4">
 497 <h2>Example</h2>
 498 <pre class="literal-block">
 499 #include &lt;boost/parameter/keyword.hpp&gt;
 500 #include &lt;boost/parameter/preprocessor.hpp&gt;
 501 #include &lt;boost/parameter/python.hpp&gt;
 502 #include &lt;boost/python.hpp&gt;
 503 #include &lt;boost/mpl/vector.hpp&gt;
 504
 505 BOOST_PARAMETER_KEYWORD(tag, x)
 506 BOOST_PARAMETER_KEYWORD(tag, y)
 507
 508 namespace parameter = boost::parameter;
 509
 510 typedef parameter::parameters&lt;
 511     parameter::required&lt;tag::x&gt;
 512   , parameter::optional&lt;tag::y&gt;
 513 &gt; call_parameters;
 514
 515 class X
 516 {
 517 public:
 518     template &lt;class ArgumentPack&gt;
 519     int call_impl(ArgumentPack const&amp; args)
 520     {
 521         <em>… use args …</em>
 522     }
 523
 524     template &lt;class A0&gt;
 525     int operator()(A0 const&amp; a0)
 526     {
 527         return call_impl(call_parameters()(a0));
 528     }
 529
 530     template &lt;class A0, class A1&gt;
 531     int operator()(A0 const&amp; a0, A1 const&amp; a1)
 532     {
 533         return call_impl(call_parameters()(a0,a1));
 534     }
 535 };
 536
 537 BOOST_PYTHON_MODULE(<em>module name</em>)
 538 {
 539     using namespace boost::python;
 540     namespace py = parameter::python;
 541     namespace mpl = boost::mpl;
 542
 543     class_&lt;X&gt;(&quot;X&quot;)
 544         .def(
 545             py::call&lt;
 546                 mpl::vector&lt;int, tag::x(int), tag::y*(int)&gt;
 547             &gt;()
 548         );
 549 }
 550 </pre>
 551 <!-- @example.replace_emphasis('''
 552 assert(args[x] == 0);
 553 assert(args[y | 1] == 1);
 554 return 0;
 555 ''') -->
 556 <!-- @example.replace_emphasis('my_module') -->
 557 <!-- @my_module = build(
 558     output = 'my_module'
 559   , target_rule = 'python-extension'
 560   , input = '/boost/python//boost_python'
 561 ) -->
 562 </div>
 563 </div>
 564 <hr class="docutils" />
 565 <div class="section" id="class-template-function">
 566 <h1><a class="toc-backref" href="#id13">class template <tt class="docutils literal">function</tt></a></h1>
 567 <p>Defines a named parameter enabled member function.</p>
 568 <pre class="literal-block">
 569 template &lt;class Fwd, class ParameterSpecs&gt;
 570 struct function : python::def_visitor&lt;function&lt;Fwd, ParameterSpecs&gt; &gt;
 571 {
 572     template &lt;class Class, class Options&gt;
 573     void def(Class&amp; class_, char const* name, Options const&amp; options);
 574 };
 575 </pre>
 576 <!-- @ignore() -->
 577 <div class="section" id="function-requirements">
 578 <h2><tt class="docutils literal">function</tt> requirements</h2>
 579 <ul>
 580 <li><p class="first"><tt class="docutils literal">ParameterSpecs</tt> is an <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element
 581 except the first models <span class="concept">ParameterSpec</span>. The first element
 582 is the result type of <tt class="docutils literal"><span class="pre">c.f(…)</span></tt>, where <tt class="docutils literal">f</tt> is the member
 583 function.</p>
 584 </li>
 585 <li><p class="first">An instance of <tt class="docutils literal">Fwd</tt> must support this expression:</p>
 586 <table border="1" class="docutils">
 587 <colgroup>
 588 <col width="39%" />
 589 <col width="18%" />
 590 <col width="43%" />
 591 </colgroup>
 592 <thead valign="bottom">
 593 <tr><th class="head">Expression</th>
 594 <th class="head">Return type</th>
 595 <th class="head">Requirements</th>
 596 </tr>
 597 </thead>
 598 <tbody valign="top">
 599 <tr><td><tt class="docutils literal"><span class="pre">fwd(boost::type&lt;R&gt;(),</span> self, a0, …, aN)</tt></td>
 600 <td>Convertible to <tt class="docutils literal">R</tt></td>
 601 <td><tt class="docutils literal">self</tt> is a reference to the object on which
 602 the function should be invoked. <tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt>
 603 are tagged arguments.</td>
 604 </tr>
 605 </tbody>
 606 </table>
 607 <p>For every <tt class="docutils literal">N</tt> in <tt class="docutils literal">[U,V]</tt>, where <tt class="docutils literal">[U,V]</tt> is the <strong>arity range</strong> of <tt class="docutils literal">ParameterSpecs</tt>.</p>
 608 </li>
 609 </ul>
 610 </div>
 611 <div class="section" id="id5">
 612 <h2>Example</h2>
 613 <p>This example exports a member function <tt class="docutils literal">f(int x, int y = …)</tt> to Python. The
 614 sequence of <span class="concept">ParameterSpec</span>'s <tt class="docutils literal"><span class="pre">mpl::vector2&lt;tag::x(int),</span> <span class="pre">tag::y*(int)&gt;</span></tt> has
 615 an <strong>arity range</strong> of [2,2], so we only need one forwarding overload.</p>
 616 <pre class="literal-block">
 617 #include &lt;boost/parameter/keyword.hpp&gt;
 618 #include &lt;boost/parameter/preprocessor.hpp&gt;
 619 #include &lt;boost/parameter/python.hpp&gt;
 620 #include &lt;boost/python.hpp&gt;
 621 #include &lt;boost/mpl/vector.hpp&gt;
 622
 623 BOOST_PARAMETER_KEYWORD(tag, x)
 624 BOOST_PARAMETER_KEYWORD(tag, y)
 625
 626 class X
 627 {
 628 public:
 629     BOOST_PARAMETER_MEMBER_FUNCTION((void), f, tag,
 630         (required (x, *))
 631         (optional (y, *, 1))
 632     )
 633     {
 634         <em>…</em>
 635     }
 636 };
 637
 638 struct f_fwd
 639 {
 640     template &lt;class A0, class A1&gt;
 641     void operator()(boost::type&lt;void&gt;, X&amp; self, A0 const&amp; a0, A1 const&amp; a1)
 642     {
 643         self.f(a0, a1);
 644     }
 645 };
 646
 647 BOOST_PYTHON_MODULE(<em>module name</em>)
 648 {
 649     using namespace boost::python;
 650     namespace py = boost::parameter::python;
 651     namespace mpl = boost::mpl;
 652
 653     class_&lt;X&gt;(&quot;X&quot;)
 654         .def(&quot;f&quot;,
 655             py::function&lt;
 656                 f_fwd
 657               , mpl::vector&lt;void, tag::x(int), tag::y*(int)&gt;
 658             &gt;()
 659         );
 660 }
 661 </pre>
 662 <!-- @example.replace_emphasis('''
 663 assert(x == 0);
 664 assert(y == 1);
 665 ''') -->
 666 <!-- @example.replace_emphasis('my_module') -->
 667 <!-- @my_module = build(
 668     output = 'my_module'
 669   , target_rule = 'python-extension'
 670   , input = '/boost/python//boost_python'
 671 ) -->
 672 </div>
 673 </div>
 674 <hr class="docutils" />
 675 <div class="section" id="function-template-def">
 676 <h1><a class="toc-backref" href="#id14">function template <tt class="docutils literal">def</tt></a></h1>
 677 <p>Defines a named parameter enabled free function in the current Python scope.</p>
 678 <pre class="literal-block">
 679 template &lt;class Fwd, class ParameterSpecs&gt;
 680 void def(char const* name);
 681 </pre>
 682 <!-- @ignore() -->
 683 <div class="section" id="def-requirements">
 684 <h2><tt class="docutils literal">def</tt> requirements</h2>
 685 <ul>
 686 <li><p class="first"><tt class="docutils literal">ParameterSpecs</tt> is an <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element
 687 except the first models <span class="concept">ParameterSpec</span>. The first element
 688 is the result type of <tt class="docutils literal"><span class="pre">f(…)</span></tt>, where <tt class="docutils literal">f</tt> is the function.</p>
 689 </li>
 690 <li><p class="first">An instance of <tt class="docutils literal">Fwd</tt> must support this expression:</p>
 691 <table border="1" class="docutils">
 692 <colgroup>
 693 <col width="39%" />
 694 <col width="21%" />
 695 <col width="40%" />
 696 </colgroup>
 697 <thead valign="bottom">
 698 <tr><th class="head">Expression</th>
 699 <th class="head">Return type</th>
 700 <th class="head">Requirements</th>
 701 </tr>
 702 </thead>
 703 <tbody valign="top">
 704 <tr><td><tt class="docutils literal"><span class="pre">fwd(boost::type&lt;R&gt;(),</span> a0, …, aN)</tt></td>
 705 <td>Convertible to <tt class="docutils literal">R</tt></td>
 706 <td><tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt> are tagged arguments.</td>
 707 </tr>
 708 </tbody>
 709 </table>
 710 <p>For every <tt class="docutils literal">N</tt> in <tt class="docutils literal">[U,V]</tt>, where <tt class="docutils literal">[U,V]</tt> is the <strong>arity range</strong> of <tt class="docutils literal">ParameterSpecs</tt>.</p>
 711 </li>
 712 </ul>
 713 </div>
 714 <div class="section" id="id6">
 715 <h2>Example</h2>
 716 <p>This example exports a function <tt class="docutils literal">f(int x, int y = …)</tt> to Python. The
 717 sequence of <span class="concept">ParameterSpec</span>'s <tt class="docutils literal"><span class="pre">mpl::vector2&lt;tag::x(int),</span> <span class="pre">tag::y*(int)&gt;</span></tt> has
 718 an <strong>arity range</strong> of [2,2], so we only need one forwarding overload.</p>
 719 <pre class="literal-block">
 720 BOOST_PARAMETER_FUNCTION((void), f, tag,
 721     (required (x, *))
 722     (optional (y, *, 1))
 723 )
 724 {
 725     <em>…</em>
 726 }
 727
 728 struct f_fwd
 729 {
 730     template &lt;class A0, class A1&gt;
 731     void operator()(boost::type&lt;void&gt;, A0 const&amp; a0, A1 const&amp; a1)
 732     {
 733         f(a0, a1);
 734     }
 735 };
 736
 737 BOOST_PYTHON_MODULE(…)
 738 {
 739     def&lt;
 740         f_fwd
 741       , mpl::vector&lt;
 742             void, tag::x(int), tag::y*(int)
 743         &gt;
 744     &gt;(&quot;f&quot;);
 745 }
 746 </pre>
 747 <!-- @ignore() -->
 748 <!-- again, the undefined ``fwd`` identifier. -->
 749 </div>
 750 </div>
 751 <div class="section" id="portability">
 752 <h1><a class="toc-backref" href="#id15">Portability</a></h1>
 753 <p>The Boost.Parameter Python binding library requires <em>partial template
 754 specialization</em>.</p>
 755 </div>
 756 </div>
 757 <div class="footer">
 758 <hr class="footer" />
 759 Generated on: 2019-12-10 00:22 UTC.
 760 Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 761
 762 </div>
 763 </body>
 764 </html>