Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/parameter/doc/html/python.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

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