]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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.7: 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="2009-01-29" /> | |
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@boost-consulting.com">dave@boost-consulting.com</a>, <a class="last reference external" href="mailto:daniel@boostpro.com">daniel@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>2009-01-29</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 <boost/parameter/keyword.hpp> | |
93 | #include <boost/parameter/preprocessor.hpp> | |
94 | #include <boost/parameter/python.hpp> | |
95 | #include <boost/python.hpp> | |
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 <class A0, class A1, class A2> | |
134 | void operator()( | |
135 | boost::type<void>, window& self | |
136 | , A0 const& a0, A1 const& a1, A2 const& 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<void></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_<window>("window") | |
166 | .def( | |
167 | "open", py::function< | |
168 | open_fwd | |
169 | , mpl::vector< | |
170 | void | |
171 | , tag::title(std::string) | |
172 | , tag::width*(unsigned) | |
173 | , tag::height*(unsigned) | |
174 | > | |
175 | >() | |
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 | >>> w = my_module.window() | |
211 | >>> w.open(title = "foo", 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<S> - number of <em>special</em> keyword tags in <tt class="docutils literal">S</tt>, mpl::size<S> ] | |
262 | </pre> | |
263 | <p>For example, the <strong>arity range</strong> of <tt class="docutils literal"><span class="pre">mpl::vector2<x(int),y(int)></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<x(int),y*(int)></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<x(int),y**(int)></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 <class ArgumentPack> | |
278 | void dfs_dispatch(ArgumentPack const& args, mpl::false_) | |
279 | { | |
280 | <em>…compute and use default color map…</em> | |
281 | } | |
282 | ||
283 | template <class ArgumentPack, class ColorMap> | |
284 | void dfs_dispatch(ArgumentPack const& args, ColorMap colormap) | |
285 | { | |
286 | <em>…use colormap…</em> | |
287 | } | |
288 | } | |
289 | ||
290 | template <class ArgumentPack> | |
291 | void depth_first_search(ArgumentPack const& 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 <class ParameterSpecs> | |
339 | struct init : python::def_visitor<init<ParameterSpecs> > | |
340 | { | |
341 | template <class Class> | |
342 | void def(Class& class_); | |
343 | ||
344 | template <class CallPolicies> | |
345 | <em>def_visitor</em> operator[](CallPolicies const& 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"><p class="first last">Expression</p> | |
366 | </th> | |
367 | <th class="head"><p class="first last">Return type</p> | |
368 | </th> | |
369 | <th class="head"><p class="first last">Requirements</p> | |
370 | </th> | |
371 | </tr> | |
372 | </thead> | |
373 | <tbody valign="top"> | |
374 | <tr><td><p class="first last"><tt class="docutils literal">Class(a0, …, aN)</tt></p> | |
375 | </td> | |
376 | <td><p class="first last">-</p> | |
377 | </td> | |
378 | <td><p class="first last"><tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt> are tagged arguments.</p> | |
379 | </td> | |
380 | </tr> | |
381 | </tbody> | |
382 | </table> | |
383 | </li> | |
384 | </ul> | |
385 | </div> | |
386 | <div class="section" id="template-class-callpolicies-operator-callpolicies-const"> | |
387 | <h2><tt class="docutils literal">template <class CallPolicies> <span class="pre">operator[](CallPolicies</span> const&)</tt></h2> | |
388 | <p>Returns a <tt class="docutils literal">def_visitor</tt> equivalent to <tt class="docutils literal">*this</tt>, except that it | |
389 | uses CallPolicies when creating the binding.</p> | |
390 | </div> | |
391 | <div class="section" id="example"> | |
392 | <h2>Example</h2> | |
393 | <pre class="literal-block"> | |
394 | #include <boost/parameter/keyword.hpp> | |
395 | #include <boost/parameter/preprocessor.hpp> | |
396 | #include <boost/parameter/python.hpp> | |
397 | #include <boost/python.hpp> | |
398 | #include <boost/mpl/vector.hpp> | |
399 | ||
400 | BOOST_PARAMETER_KEYWORD(tag, x) | |
401 | BOOST_PARAMETER_KEYWORD(tag, y) | |
402 | ||
403 | struct base | |
404 | { | |
405 | template <class ArgumentPack> | |
406 | base(ArgumentPack const& args) | |
407 | { | |
408 | <em>… use args …</em> | |
409 | } | |
410 | }; | |
411 | ||
412 | class X : base | |
413 | { | |
414 | public: | |
415 | BOOST_PARAMETER_CONSTRUCTOR(X, (base), tag, | |
416 | (required (x, *)) | |
417 | (optional (y, *)) | |
418 | ) | |
419 | }; | |
420 | ||
421 | BOOST_PYTHON_MODULE(<em>module name</em>) | |
422 | { | |
423 | using namespace boost::python; | |
424 | namespace py = boost::parameter::python; | |
425 | namespace mpl = boost::mpl; | |
426 | ||
427 | class_<X>("X", no_init) | |
428 | .def( | |
429 | py::init< | |
430 | mpl::vector<tag::x(int), tag::y*(int)> | |
431 | >() | |
432 | ); | |
433 | } | |
434 | </pre> | |
435 | <!-- @example.replace_emphasis(''' | |
436 | assert(args[x] == 0); | |
437 | assert(args[y | 1] == 1); | |
438 | ''') --> | |
439 | <!-- @example.replace_emphasis('my_module') --> | |
440 | <!-- @jam_prefix.append('import python ;') --> | |
441 | <!-- @jam_prefix.append('stage . : my_module /boost/python//boost_python ;') --> | |
442 | <!-- @my_module = build( | |
443 | output = 'my_module' | |
444 | , target_rule = 'python-extension' | |
445 | , input = '/boost/python//boost_python' | |
446 | ) --> | |
447 | </div> | |
448 | </div> | |
449 | <hr class="docutils" /> | |
450 | <div class="section" id="class-template-call"> | |
451 | <h1><a class="toc-backref" href="#id12">class template <tt class="docutils literal">call</tt></a></h1> | |
452 | <p>Defines a <tt class="docutils literal">__call__</tt> operator, mapped to <tt class="docutils literal">operator()</tt> in C++.</p> | |
453 | <pre class="literal-block"> | |
454 | template <class ParameterSpecs> | |
455 | struct call : python::def_visitor<call<ParameterSpecs> > | |
456 | { | |
457 | template <class Class> | |
458 | void def(Class& class_); | |
459 | ||
460 | template <class CallPolicies> | |
461 | <em>def_visitor</em> operator[](CallPolicies const& policies) const; | |
462 | }; | |
463 | </pre> | |
464 | <!-- @ignore() --> | |
465 | <div class="section" id="call-requirements"> | |
466 | <h2><tt class="docutils literal">call</tt> requirements</h2> | |
467 | <ul> | |
468 | <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 | |
469 | except the first models <span class="concept">ParameterSpec</span>. The first element | |
470 | is the result type of <tt class="docutils literal"><span class="pre">c(…)</span></tt>.</p> | |
471 | </li> | |
472 | <li><p class="first"><tt class="docutils literal">Class</tt> must support these expressions, where <tt class="docutils literal">c</tt> is an | |
473 | instance of <tt class="docutils literal">Class</tt>:</p> | |
474 | <table border="1" class="docutils"> | |
475 | <colgroup> | |
476 | <col width="24%" /> | |
477 | <col width="26%" /> | |
478 | <col width="50%" /> | |
479 | </colgroup> | |
480 | <thead valign="bottom"> | |
481 | <tr><th class="head"><p class="first last">Expression</p> | |
482 | </th> | |
483 | <th class="head"><p class="first last">Return type</p> | |
484 | </th> | |
485 | <th class="head"><p class="first last">Requirements</p> | |
486 | </th> | |
487 | </tr> | |
488 | </thead> | |
489 | <tbody valign="top"> | |
490 | <tr><td><p class="first last"><tt class="docutils literal">c(a0, …, aN)</tt></p> | |
491 | </td> | |
492 | <td><p class="first last">Convertible to <tt class="docutils literal">R</tt></p> | |
493 | </td> | |
494 | <td><p class="first last"><tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt> are tagged arguments.</p> | |
495 | </td> | |
496 | </tr> | |
497 | </tbody> | |
498 | </table> | |
499 | <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> | |
500 | </li> | |
501 | </ul> | |
502 | </div> | |
503 | <div class="section" id="id3"> | |
504 | <h2><tt class="docutils literal">template <class CallPolicies> <span class="pre">operator[](CallPolicies</span> const&)</tt></h2> | |
505 | <p>Returns a <tt class="docutils literal">def_visitor</tt> equivalent to <tt class="docutils literal">*this</tt>, except that it | |
506 | uses CallPolicies when creating the binding.</p> | |
507 | </div> | |
508 | <div class="section" id="id4"> | |
509 | <h2>Example</h2> | |
510 | <pre class="literal-block"> | |
511 | #include <boost/parameter/keyword.hpp> | |
512 | #include <boost/parameter/preprocessor.hpp> | |
513 | #include <boost/parameter/python.hpp> | |
514 | #include <boost/python.hpp> | |
515 | #include <boost/mpl/vector.hpp> | |
516 | ||
517 | BOOST_PARAMETER_KEYWORD(tag, x) | |
518 | BOOST_PARAMETER_KEYWORD(tag, y) | |
519 | ||
520 | namespace parameter = boost::parameter; | |
521 | ||
522 | typedef parameter::parameters< | |
523 | parameter::required<tag::x> | |
524 | , parameter::optional<tag::y> | |
525 | > call_parameters; | |
526 | ||
527 | class X | |
528 | { | |
529 | public: | |
530 | template <class ArgumentPack> | |
531 | int call_impl(ArgumentPack const& args) | |
532 | { | |
533 | <em>… use args …</em> | |
534 | } | |
535 | ||
536 | template <class A0> | |
537 | int operator()(A0 const& a0) | |
538 | { | |
539 | return call_impl(call_parameters()(a0)); | |
540 | } | |
541 | ||
542 | template <class A0, class A1> | |
543 | int operator()(A0 const& a0, A1 const& a1) | |
544 | { | |
545 | return call_impl(call_parameters()(a0,a1)); | |
546 | } | |
547 | }; | |
548 | ||
549 | BOOST_PYTHON_MODULE(<em>module name</em>) | |
550 | { | |
551 | using namespace boost::python; | |
552 | namespace py = parameter::python; | |
553 | namespace mpl = boost::mpl; | |
554 | ||
555 | class_<X>("X") | |
556 | .def( | |
557 | py::call< | |
558 | mpl::vector<int, tag::x(int), tag::y*(int)> | |
559 | >() | |
560 | ); | |
561 | } | |
562 | </pre> | |
563 | <!-- @example.replace_emphasis(''' | |
564 | assert(args[x] == 0); | |
565 | assert(args[y | 1] == 1); | |
566 | return 0; | |
567 | ''') --> | |
568 | <!-- @example.replace_emphasis('my_module') --> | |
569 | <!-- @my_module = build( | |
570 | output = 'my_module' | |
571 | , target_rule = 'python-extension' | |
572 | , input = '/boost/python//boost_python' | |
573 | ) --> | |
574 | </div> | |
575 | </div> | |
576 | <hr class="docutils" /> | |
577 | <div class="section" id="class-template-function"> | |
578 | <h1><a class="toc-backref" href="#id13">class template <tt class="docutils literal">function</tt></a></h1> | |
579 | <p>Defines a named parameter enabled member function.</p> | |
580 | <pre class="literal-block"> | |
581 | template <class Fwd, class ParameterSpecs> | |
582 | struct function : python::def_visitor<function<Fwd, ParameterSpecs> > | |
583 | { | |
584 | template <class Class, class Options> | |
585 | void def(Class& class_, char const* name, Options const& options); | |
586 | }; | |
587 | </pre> | |
588 | <!-- @ignore() --> | |
589 | <div class="section" id="function-requirements"> | |
590 | <h2><tt class="docutils literal">function</tt> requirements</h2> | |
591 | <ul> | |
592 | <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 | |
593 | except the first models <span class="concept">ParameterSpec</span>. The first element | |
594 | 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 | |
595 | function.</p> | |
596 | </li> | |
597 | <li><p class="first">An instance of <tt class="docutils literal">Fwd</tt> must support this expression:</p> | |
598 | <table border="1" class="docutils"> | |
599 | <colgroup> | |
600 | <col width="39%" /> | |
601 | <col width="18%" /> | |
602 | <col width="43%" /> | |
603 | </colgroup> | |
604 | <thead valign="bottom"> | |
605 | <tr><th class="head"><p class="first last">Expression</p> | |
606 | </th> | |
607 | <th class="head"><p class="first last">Return type</p> | |
608 | </th> | |
609 | <th class="head"><p class="first last">Requirements</p> | |
610 | </th> | |
611 | </tr> | |
612 | </thead> | |
613 | <tbody valign="top"> | |
614 | <tr><td><p class="first last"><tt class="docutils literal"><span class="pre">fwd(boost::type<R>(),</span> self, a0, …, aN)</tt></p> | |
615 | </td> | |
616 | <td><p class="first last">Convertible to <tt class="docutils literal">R</tt></p> | |
617 | </td> | |
618 | <td><p class="first last"><tt class="docutils literal">self</tt> is a reference to the object on which | |
619 | the function should be invoked. <tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt> | |
620 | are tagged arguments.</p> | |
621 | </td> | |
622 | </tr> | |
623 | </tbody> | |
624 | </table> | |
625 | <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> | |
626 | </li> | |
627 | </ul> | |
628 | </div> | |
629 | <div class="section" id="id5"> | |
630 | <h2>Example</h2> | |
631 | <p>This example exports a member function <tt class="docutils literal">f(int x, int y = …)</tt> to Python. The | |
632 | sequence of <span class="concept">ParameterSpec</span>'s <tt class="docutils literal"><span class="pre">mpl::vector2<tag::x(int),</span> <span class="pre">tag::y*(int)></span></tt> has | |
633 | an <strong>arity range</strong> of [2,2], so we only need one forwarding overload.</p> | |
634 | <pre class="literal-block"> | |
635 | #include <boost/parameter/keyword.hpp> | |
636 | #include <boost/parameter/preprocessor.hpp> | |
637 | #include <boost/parameter/python.hpp> | |
638 | #include <boost/python.hpp> | |
639 | #include <boost/mpl/vector.hpp> | |
640 | ||
641 | BOOST_PARAMETER_KEYWORD(tag, x) | |
642 | BOOST_PARAMETER_KEYWORD(tag, y) | |
643 | ||
644 | class X | |
645 | { | |
646 | public: | |
647 | BOOST_PARAMETER_MEMBER_FUNCTION((void), f, tag, | |
648 | (required (x, *)) | |
649 | (optional (y, *, 1)) | |
650 | ) | |
651 | { | |
652 | <em>…</em> | |
653 | } | |
654 | }; | |
655 | ||
656 | struct f_fwd | |
657 | { | |
658 | template <class A0, class A1> | |
659 | void operator()(boost::type<void>, X& self, A0 const& a0, A1 const& a1) | |
660 | { | |
661 | self.f(a0, a1); | |
662 | } | |
663 | }; | |
664 | ||
665 | BOOST_PYTHON_MODULE(<em>module name</em>) | |
666 | { | |
667 | using namespace boost::python; | |
668 | namespace py = boost::parameter::python; | |
669 | namespace mpl = boost::mpl; | |
670 | ||
671 | class_<X>("X") | |
672 | .def("f", | |
673 | py::function< | |
674 | f_fwd | |
675 | , mpl::vector<void, tag::x(int), tag::y*(int)> | |
676 | >() | |
677 | ); | |
678 | } | |
679 | </pre> | |
680 | <!-- @example.replace_emphasis(''' | |
681 | assert(x == 0); | |
682 | assert(y == 1); | |
683 | ''') --> | |
684 | <!-- @example.replace_emphasis('my_module') --> | |
685 | <!-- @my_module = build( | |
686 | output = 'my_module' | |
687 | , target_rule = 'python-extension' | |
688 | , input = '/boost/python//boost_python' | |
689 | ) --> | |
690 | </div> | |
691 | </div> | |
692 | <hr class="docutils" /> | |
693 | <div class="section" id="function-template-def"> | |
694 | <h1><a class="toc-backref" href="#id14">function template <tt class="docutils literal">def</tt></a></h1> | |
695 | <p>Defines a named parameter enabled free function in the current Python scope.</p> | |
696 | <pre class="literal-block"> | |
697 | template <class Fwd, class ParameterSpecs> | |
698 | void def(char const* name); | |
699 | </pre> | |
700 | <!-- @ignore() --> | |
701 | <div class="section" id="def-requirements"> | |
702 | <h2><tt class="docutils literal">def</tt> requirements</h2> | |
703 | <ul> | |
704 | <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 | |
705 | except the first models <span class="concept">ParameterSpec</span>. The first element | |
706 | 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> | |
707 | </li> | |
708 | <li><p class="first">An instance of <tt class="docutils literal">Fwd</tt> must support this expression:</p> | |
709 | <table border="1" class="docutils"> | |
710 | <colgroup> | |
711 | <col width="39%" /> | |
712 | <col width="21%" /> | |
713 | <col width="40%" /> | |
714 | </colgroup> | |
715 | <thead valign="bottom"> | |
716 | <tr><th class="head"><p class="first last">Expression</p> | |
717 | </th> | |
718 | <th class="head"><p class="first last">Return type</p> | |
719 | </th> | |
720 | <th class="head"><p class="first last">Requirements</p> | |
721 | </th> | |
722 | </tr> | |
723 | </thead> | |
724 | <tbody valign="top"> | |
725 | <tr><td><p class="first last"><tt class="docutils literal"><span class="pre">fwd(boost::type<R>(),</span> a0, …, aN)</tt></p> | |
726 | </td> | |
727 | <td><p class="first last">Convertible to <tt class="docutils literal">R</tt></p> | |
728 | </td> | |
729 | <td><p class="first last"><tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt> are tagged arguments.</p> | |
730 | </td> | |
731 | </tr> | |
732 | </tbody> | |
733 | </table> | |
734 | <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> | |
735 | </li> | |
736 | </ul> | |
737 | </div> | |
738 | <div class="section" id="id6"> | |
739 | <h2>Example</h2> | |
740 | <p>This example exports a function <tt class="docutils literal">f(int x, int y = …)</tt> to Python. The | |
741 | sequence of <span class="concept">ParameterSpec</span>'s <tt class="docutils literal"><span class="pre">mpl::vector2<tag::x(int),</span> <span class="pre">tag::y*(int)></span></tt> has | |
742 | an <strong>arity range</strong> of [2,2], so we only need one forwarding overload.</p> | |
743 | <pre class="literal-block"> | |
744 | BOOST_PARAMETER_FUNCTION((void), f, tag, | |
745 | (required (x, *)) | |
746 | (optional (y, *, 1)) | |
747 | ) | |
748 | { | |
749 | <em>…</em> | |
750 | } | |
751 | ||
752 | struct f_fwd | |
753 | { | |
754 | template <class A0, class A1> | |
755 | void operator()(boost::type<void>, A0 const& a0, A1 const& a1) | |
756 | { | |
757 | f(a0, a1); | |
758 | } | |
759 | }; | |
760 | ||
761 | BOOST_PYTHON_MODULE(…) | |
762 | { | |
763 | def< | |
764 | f_fwd | |
765 | , mpl::vector< | |
766 | void, tag::x(int), tag::y*(int) | |
767 | > | |
768 | >("f"); | |
769 | } | |
770 | </pre> | |
771 | <!-- @ignore() --> | |
772 | <!-- again, the undefined ``fwd`` identifier. --> | |
773 | </div> | |
774 | </div> | |
775 | <div class="section" id="portability"> | |
776 | <h1><a class="toc-backref" href="#id15">Portability</a></h1> | |
777 | <p>The Boost.Parameter Python binding library requires <em>partial template | |
778 | specialization</em>.</p> | |
779 | </div> | |
780 | </div> | |
781 | <div class="footer"> | |
782 | <hr class="footer" /> | |
783 | Generated on: 2011-11-08 21:40 UTC. | |
784 | 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. | |
785 | ||
786 | </div> | |
787 | </body> | |
788 | </html> |