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">
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" />
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" />
21 <tr><th class=
"docinfo-name">Authors:
</th>
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>
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>
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>
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>
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
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 -->
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
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
>
98 BOOST_PARAMETER_KEYWORD(tag, title)
99 BOOST_PARAMETER_KEYWORD(tag, width)
100 BOOST_PARAMETER_KEYWORD(tag, height)
105 BOOST_PARAMETER_MEMBER_FUNCTION(
107 (required (title, (std::string)))
108 (optional (width, (unsigned),
400)
109 (height, (unsigned),
400))
112 <em>… function implementation …
</em>
116 <!-- @example.prepend('#include <cassert>') -->
117 <!-- @example.replace_emphasis('''
118 assert(title == "foo");
119 assert(height == 20);
120 assert(width == 400);
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">
133 template
<class A0, class A1, class A2
>
135 boost::type
<void
>, window
& self
136 , A0 const
& a0, A1 const
& a1, A2 const
& a2
139 self.open(a0, a1, a2);
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>
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>
157 <p>Next we'll define the module and export the class:
</p>
158 <pre class=
"literal-block">
159 BOOST_PYTHON_MODULE(my_module)
161 using namespace boost::python;
162 namespace py = boost::parameter::python;
163 namespace mpl = boost::mpl;
165 class_
<window
>(
"window
")
167 "open
", py::function
<
171 , tag::title(std::string)
172 , tag::width*(unsigned)
173 , tag::height*(unsigned)
179 <!-- @jam_prefix.append('import python ;') -->
180 <!-- @jam_prefix.append('stage . : my_module /boost/python//boost_python ;') -->
181 <!-- @my_module = build(
183 , target_rule = 'python-extension'
184 , input = '/boost/python//boost_python'
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
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:
204 mpl::vector<void, std::string, unsigned, unsigned>
205 *return type* *title* *width* *height*
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)
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:
218 class_<window>("window")
222 tag::title(std::string),
223 tag::width*(unsigned),
224 tag::height*(unsigned))
230 class_<window>("window")
235 tag::title(std::string),
236 tag::width*(unsigned),
237 tag::height*(unsigned)
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
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>
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>
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
> ]
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>
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">
277 template
<class ArgumentPack
>
278 void dfs_dispatch(ArgumentPack const
& args, mpl::false_)
280 <em>…compute and use default color map…
</em>
283 template
<class ArgumentPack, class ColorMap
>
284 void dfs_dispatch(ArgumentPack const
& args, ColorMap colormap)
286 <em>…use colormap…
</em>
290 template
<class ArgumentPack
>
291 void depth_first_search(ArgumentPack const
& args)
293 core::dfs_dispatch(args, args[color | mpl::false_()]);
296 <!-- @example.prepend('''
297 #include <boost/parameter/keyword.hpp>
298 #include <boost/parameter/parameters.hpp>
299 #include <boost/mpl/bool.hpp>
302 BOOST_PARAMETER_KEYWORD(tag, color);
304 typedef boost::parameter::parameters<tag::color> params;
306 namespace mpl = boost::mpl;
308 <!-- @example.replace_emphasis('''
309 assert(args[color | 1] == 1);
311 <!-- @example.replace_emphasis('''
312 assert(args[color | 1] == 0);
314 <!-- @example.append('''
317 depth_first_search(params()());
318 depth_first_search(params()(color = 0));
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>
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
> >
341 template
<class Class
>
342 void def(Class
& class_);
344 template
<class CallPolicies
>
345 <em>def_visitor
</em> operator[](CallPolicies const
& policies) const;
349 <div class=
"section" id=
"init-requirements">
350 <h2><tt class=
"docutils literal">init
</tt> requirements
</h2>
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>
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
358 <table border=
"1" class=
"docutils">
364 <thead valign=
"bottom">
365 <tr><th class=
"head"><p class=
"first last">Expression
</p>
367 <th class=
"head"><p class=
"first last">Return type
</p>
369 <th class=
"head"><p class=
"first last">Requirements
</p>
374 <tr><td><p class=
"first last"><tt class=
"docutils literal">Class(a0, …, aN)
</tt></p>
376 <td><p class=
"first last">-
</p>
378 <td><p class=
"first last"><tt class=
"docutils literal">a0
</tt>…
<tt class=
"docutils literal">aN
</tt> are tagged arguments.
</p>
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>
391 <div class=
"section" id=
"example">
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
>
400 BOOST_PARAMETER_KEYWORD(tag, x)
401 BOOST_PARAMETER_KEYWORD(tag, y)
405 template
<class ArgumentPack
>
406 base(ArgumentPack const
& args)
408 <em>… use args …
</em>
415 BOOST_PARAMETER_CONSTRUCTOR(X, (base), tag,
421 BOOST_PYTHON_MODULE(
<em>module name
</em>)
423 using namespace boost::python;
424 namespace py = boost::parameter::python;
425 namespace mpl = boost::mpl;
427 class_
<X
>(
"X
", no_init)
430 mpl::vector
<tag::x(int), tag::y*(int)
>
435 <!-- @example.replace_emphasis('''
436 assert(args[x] == 0);
437 assert(args[y | 1] == 1);
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(
444 , target_rule = 'python-extension'
445 , input = '/boost/python//boost_python'
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
> >
457 template
<class Class
>
458 void def(Class
& class_);
460 template
<class CallPolicies
>
461 <em>def_visitor
</em> operator[](CallPolicies const
& policies) const;
465 <div class=
"section" id=
"call-requirements">
466 <h2><tt class=
"docutils literal">call
</tt> requirements
</h2>
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>
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">
480 <thead valign=
"bottom">
481 <tr><th class=
"head"><p class=
"first last">Expression
</p>
483 <th class=
"head"><p class=
"first last">Return type
</p>
485 <th class=
"head"><p class=
"first last">Requirements
</p>
490 <tr><td><p class=
"first last"><tt class=
"docutils literal">c(a0, …, aN)
</tt></p>
492 <td><p class=
"first last">Convertible to
<tt class=
"docutils literal">R
</tt></p>
494 <td><p class=
"first last"><tt class=
"docutils literal">a0
</tt>…
<tt class=
"docutils literal">aN
</tt> are tagged arguments.
</p>
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>
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>
508 <div class=
"section" id=
"id4">
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
>
517 BOOST_PARAMETER_KEYWORD(tag, x)
518 BOOST_PARAMETER_KEYWORD(tag, y)
520 namespace parameter = boost::parameter;
522 typedef parameter::parameters
<
523 parameter::required
<tag::x
>
524 , parameter::optional
<tag::y
>
525 > call_parameters;
530 template
<class ArgumentPack
>
531 int call_impl(ArgumentPack const
& args)
533 <em>… use args …
</em>
536 template
<class A0
>
537 int operator()(A0 const
& a0)
539 return call_impl(call_parameters()(a0));
542 template
<class A0, class A1
>
543 int operator()(A0 const
& a0, A1 const
& a1)
545 return call_impl(call_parameters()(a0,a1));
549 BOOST_PYTHON_MODULE(
<em>module name
</em>)
551 using namespace boost::python;
552 namespace py = parameter::python;
553 namespace mpl = boost::mpl;
555 class_
<X
>(
"X
")
558 mpl::vector
<int, tag::x(int), tag::y*(int)
>
563 <!-- @example.replace_emphasis('''
564 assert(args[x] == 0);
565 assert(args[y | 1] == 1);
568 <!-- @example.replace_emphasis('my_module') -->
569 <!-- @my_module = build(
571 , target_rule = 'python-extension'
572 , input = '/boost/python//boost_python'
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
> >
584 template
<class Class, class Options
>
585 void def(Class
& class_, char const* name, Options const
& options);
589 <div class=
"section" id=
"function-requirements">
590 <h2><tt class=
"docutils literal">function
</tt> requirements
</h2>
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
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">
604 <thead valign=
"bottom">
605 <tr><th class=
"head"><p class=
"first last">Expression
</p>
607 <th class=
"head"><p class=
"first last">Return type
</p>
609 <th class=
"head"><p class=
"first last">Requirements
</p>
614 <tr><td><p class=
"first last"><tt class=
"docutils literal"><span class=
"pre">fwd(boost::type
<R
>(),
</span> self, a0, …, aN)
</tt></p>
616 <td><p class=
"first last">Convertible to
<tt class=
"docutils literal">R
</tt></p>
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>
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>
629 <div class=
"section" id=
"id5">
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
>
641 BOOST_PARAMETER_KEYWORD(tag, x)
642 BOOST_PARAMETER_KEYWORD(tag, y)
647 BOOST_PARAMETER_MEMBER_FUNCTION((void), f, tag,
658 template
<class A0, class A1
>
659 void operator()(boost::type
<void
>, X
& self, A0 const
& a0, A1 const
& a1)
665 BOOST_PYTHON_MODULE(
<em>module name
</em>)
667 using namespace boost::python;
668 namespace py = boost::parameter::python;
669 namespace mpl = boost::mpl;
671 class_
<X
>(
"X
")
675 , mpl::vector
<void, tag::x(int), tag::y*(int)
>
680 <!-- @example.replace_emphasis('''
684 <!-- @example.replace_emphasis('my_module') -->
685 <!-- @my_module = build(
687 , target_rule = 'python-extension'
688 , input = '/boost/python//boost_python'
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);
701 <div class=
"section" id=
"def-requirements">
702 <h2><tt class=
"docutils literal">def
</tt> requirements
</h2>
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>
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">
715 <thead valign=
"bottom">
716 <tr><th class=
"head"><p class=
"first last">Expression
</p>
718 <th class=
"head"><p class=
"first last">Return type
</p>
720 <th class=
"head"><p class=
"first last">Requirements
</p>
725 <tr><td><p class=
"first last"><tt class=
"docutils literal"><span class=
"pre">fwd(boost::type
<R
>(),
</span> a0, …, aN)
</tt></p>
727 <td><p class=
"first last">Convertible to
<tt class=
"docutils literal">R
</tt></p>
729 <td><p class=
"first last"><tt class=
"docutils literal">a0
</tt>…
<tt class=
"docutils literal">aN
</tt> are tagged arguments.
</p>
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>
738 <div class=
"section" id=
"id6">
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,
754 template
<class A0, class A1
>
755 void operator()(boost::type
<void
>, A0 const
& a0, A1 const
& a1)
761 BOOST_PYTHON_MODULE(…)
766 void, tag::x(int), tag::y*(int)
772 <!-- again, the undefined ``fwd`` identifier. -->
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>
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.