<metaname="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)"/>
<p><ttclass="docutils literal">boost/parameter/python.hpp</tt> introduces a group of <aclass="reference external"href="../../../python/doc/v2/def_visitor.html"><ttclass="docutils literal">def_visitors</tt></a> that can
be used to easily expose Boost.Parameter-enabled member functions to Python with
Boost.Python. It also provides a function template <ttclass="docutils literal">def()</tt> that can be used
to expose Boost.Parameter-enabled free functions.</p>
<p>When binding a Boost.Parameter enabled function, the keyword tags
must be specified. Additionally, because Boost.Parameter enabled
functions are templates, the desired function signature must be
specified.</p>
<!-- The keyword tags are specified as an `MPL Sequence`_, using the
pointer qualifications described in |ParameterSpec|_ below. The
signature is also specifid as an `MPL sequence`_ of parameter
types. Additionally, ``boost::parameter::python::function`` and
``boost::parameter::python::def`` requires a class with forwarding
overloads. We will take a closer look at how this is done in the
tutorial section below. -->
<p>The keyword tags and associated argument types are specified as an <aclass="reference external"href="../../../mpl/doc/refmanual/sequences.html">MPL
Sequence</a>, using the function type syntax described in <aclass="reference internal"href="#concept-parameterspec"><spanclass="concept">ParameterSpec</span></a>
below. Additionally, <ttclass="docutils literal"><spanclass="pre">boost::parameter::python::function</span></tt> and
<ttclass="docutils literal"><spanclass="pre">boost::parameter::python::def</span></tt> requires a class with forwarding overloads.
We will take a closer look at how this is done in the tutorial section below.</p>
<!-- The last two sentences are terribly vague. Which namespace is -->
<!-- ``function`` in? Isn't the return type always needed? What -->
<!-- else are we going to do other than pass these sequences to -->
<p>In this section we will outline the steps needed to bind a simple
Boost.Parameter-enabled member function to Python. Knowledge of the
Boost.Parameter <aclass="reference external"href="index.html">macros</a> are required to understand this section.</p>
<p>The class and member function we are interested in binding looks
like this:</p>
<preclass="literal-block">
#include <boost/parameter/keyword.hpp>
#include <boost/parameter/preprocessor.hpp>
#include <boost/parameter/python.hpp>
#include <boost/python.hpp>
// First the keywords
BOOST_PARAMETER_KEYWORD(tag, title)
BOOST_PARAMETER_KEYWORD(tag, width)
BOOST_PARAMETER_KEYWORD(tag, height)
class window
{
public:
BOOST_PARAMETER_MEMBER_FUNCTION(
(void), open, tag,
(required (title, (std::string)))
(optional (width, (unsigned), 400)
(height, (unsigned), 400))
)
{
<em>… function implementation …</em>
}
};
</pre>
<!-- @example.prepend('#include <cassert>') -->
<!-- @example.replace_emphasis('''
assert(title == "foo");
assert(height == 20);
assert(width == 400);
''') -->
<p>It defines a set of overloaded member functions called <ttclass="docutils literal">open</tt> with one
required parameter and two optional ones. To bind this member function to
Python we use the binding utility <ttclass="docutils literal"><spanclass="pre">boost::parameter::python::function</span></tt>.
<ttclass="docutils literal"><spanclass="pre">boost::parameter::python::function</span></tt> is a <aclass="reference external"href="../../../python/doc/v2/def_visitor.html"><ttclass="docutils literal">def_visitor</tt></a> that we'll instantiate
and pass to <ttclass="docutils literal"><spanclass="pre">boost::python::class_::def()</span></tt>.</p>
<p>To use <ttclass="docutils literal"><spanclass="pre">boost::parameter::python::function</span></tt> we first need to define
a class with forwarding overloads. This is needed because <ttclass="docutils literal"><spanclass="pre">window::open()</span></tt>
is a function template, so we can't refer to it in any other way.</p>
<p><ttclass="docutils literal"><spanclass="pre">py::function</span></tt> is passed two parameters. The first one is the class with
forwarding overloads that we defined earlier. The second one is an <aclass="reference external"href="../../../mpl/doc/refmanual/sequences.html">MPL
Sequence</a> with the keyword tag types and argument types for the function
specified as function types. The pointer syntax used in <ttclass="docutils literal"><spanclass="pre">tag::width*</span></tt> and
<ttclass="docutils literal"><spanclass="pre">tag::height*</span></tt> means that the parameter is optional. The first element of
the <aclass="reference external"href="../../../mpl/doc/refmanual/sequences.html">MPL Sequence</a> is the return type of the function, in this case <ttclass="docutils literal">void</tt>,
which is passed as the first argument to <ttclass="docutils literal">operator()</tt> in the forwarding
class.</p>
<!-- The
pointer syntax means that the parameter is optional, so in this case
``width`` and ``height`` are optional parameters. The third parameter
is an `MPL Sequence`_ with the desired function signature. The return type comes first, and
then the parameter types:
.. parsed-literal::
mpl::vector<void,std::string,unsigned,unsigned>
*return type* *title* *width* *height*
.. @ignore() -->
<p>That's it! This class can now be used in Python with the expected syntax:</p>
<p>A <spanclass="concept">ParameterSpec</span> is a function type <ttclass="docutils literal">K(T)</tt> that describes both the keyword tag,
<ttclass="docutils literal">K</tt>, and the argument type, <ttclass="docutils literal">T</tt>, for a parameter.</p>
<p><ttclass="docutils literal">K</tt> is either:</p>
<ulclass="simple">
<li>A <em>required</em> keyword of the form <ttclass="docutils literal">Tag</tt></li>
<li><strong>or</strong>, an <em>optional</em> keyword of the form <ttclass="docutils literal">Tag*</tt></li>
<li><strong>or</strong>, a <em>special</em> keyword of the form <ttclass="docutils literal">Tag**</tt></li>
</ul>
<p>where <ttclass="docutils literal">Tag</tt> is a keyword tag type, as used in a specialization
of <aclass="reference external"href="../../../parameter/doc/html/reference.html#keyword"><ttclass="docutils literal"><spanclass="pre">boost::parameter::keyword</span></tt></a>.</p>
<p>The <strong>arity range</strong> for an <aclass="reference external"href="../../../mpl/doc/refmanual/sequences.html">MPL Sequence</a> of <spanclass="concept">ParameterSpec</span>'s is
defined as the closed range:</p>
<preclass="literal-block">
[ mpl::size<S> - number of <em>special</em> keyword tags in <ttclass="docutils literal">S</tt>, mpl::size<S> ]
</pre>
<p>For example, the <strong>arity range</strong> of <ttclass="docutils literal"><spanclass="pre">mpl::vector2<x(int),y(int)></span></tt> is <ttclass="docutils literal">[2,2]</tt>,
the <strong>arity range</strong> of <ttclass="docutils literal"><spanclass="pre">mpl::vector2<x(int),y*(int)></span></tt> is <ttclass="docutils literal">[2,2]</tt> and the
<strong>arity range</strong> of <ttclass="docutils literal"><spanclass="pre">mpl::vector2<x(int),y**(int)></span></tt> is <ttclass="docutils literal">[1,2]</tt>.</p>
<p>In the above example the type of the default for <ttclass="docutils literal">color</tt> is <ttclass="docutils literal"><spanclass="pre">mpl::false_</span></tt>, a
type that is distinct from any color map that the user might supply.</p>
<p>When binding the case outlined above, the default type for <ttclass="docutils literal">color</tt> will not
be convertible to the parameter type. Therefore we need to tag the <ttclass="docutils literal">color</tt>
keyword as a <em>special</em> keyword. This is done by specifying the tag as
<ttclass="docutils literal"><spanclass="pre">tag::color**</span></tt> when binding the function (see <aclass="reference internal"href="#concept-parameterspec">concept ParameterSpec</a> for
more details on the tagging). By doing this we tell the binding functions that
it needs to generate two overloads, one with the <ttclass="docutils literal">color</tt> parameter present
and one without. Had there been two <em>special</em> keywords, four overloads would
need to be generated. The number of generated overloads is equal to 2<sup>N</sup>, where <ttclass="docutils literal">N</tt> is the number of <em>special</em> keywords.</p>
<li><pclass="first"><ttclass="docutils literal">ParameterSpecs</tt> is an <aclass="reference external"href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element is a
model of <spanclass="concept">ParameterSpec</span>.</p>
</li>
<li><pclass="first">For every <ttclass="docutils literal">N</tt> in <ttclass="docutils literal">[U,V]</tt>, where <ttclass="docutils literal">[U,V]</tt> is the <strong>arity
range</strong> of <ttclass="docutils literal">ParameterSpecs</tt>, <ttclass="docutils literal">Class</tt> must support these
<li><pclass="first"><ttclass="docutils literal">ParameterSpecs</tt> is an <aclass="reference external"href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element
except the first models <spanclass="concept">ParameterSpec</span>. The first element
is the result type of <ttclass="docutils literal"><spanclass="pre">c(…)</span></tt>.</p>
</li>
<li><pclass="first"><ttclass="docutils literal">Class</tt> must support these expressions, where <ttclass="docutils literal">c</tt> is an
instance of <ttclass="docutils literal">Class</tt>:</p>
<p>For every <ttclass="docutils literal">N</tt> in <ttclass="docutils literal">[U,V]</tt>, where <ttclass="docutils literal">[U,V]</tt> is the <strong>arity range</strong> of <ttclass="docutils literal">ParameterSpecs</tt>.</p>
<li><pclass="first"><ttclass="docutils literal">ParameterSpecs</tt> is an <aclass="reference external"href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element
except the first models <spanclass="concept">ParameterSpec</span>. The first element
is the result type of <ttclass="docutils literal"><spanclass="pre">c.f(…)</span></tt>, where <ttclass="docutils literal">f</tt> is the member
function.</p>
</li>
<li><pclass="first">An instance of <ttclass="docutils literal">Fwd</tt> must support this expression:</p>
<p>For every <ttclass="docutils literal">N</tt> in <ttclass="docutils literal">[U,V]</tt>, where <ttclass="docutils literal">[U,V]</tt> is the <strong>arity range</strong> of <ttclass="docutils literal">ParameterSpecs</tt>.</p>
</li>
</ul>
</div>
<divclass="section"id="id5">
<h2>Example</h2>
<p>This example exports a member function <ttclass="docutils literal">f(int x, int y = …)</tt> to Python. The
sequence of <spanclass="concept">ParameterSpec</span>'s <ttclass="docutils literal"><spanclass="pre">mpl::vector2<tag::x(int),</span><spanclass="pre">tag::y*(int)></span></tt> has
an <strong>arity range</strong> of [2,2], so we only need one forwarding overload.</p>
<li><pclass="first"><ttclass="docutils literal">ParameterSpecs</tt> is an <aclass="reference external"href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element
except the first models <spanclass="concept">ParameterSpec</span>. The first element
is the result type of <ttclass="docutils literal"><spanclass="pre">f(…)</span></tt>, where <ttclass="docutils literal">f</tt> is the function.</p>
</li>
<li><pclass="first">An instance of <ttclass="docutils literal">Fwd</tt> must support this expression:</p>
<p>For every <ttclass="docutils literal">N</tt> in <ttclass="docutils literal">[U,V]</tt>, where <ttclass="docutils literal">[U,V]</tt> is the <strong>arity range</strong> of <ttclass="docutils literal">ParameterSpecs</tt>.</p>
</li>
</ul>
</div>
<divclass="section"id="id6">
<h2>Example</h2>
<p>This example exports a function <ttclass="docutils literal">f(int x, int y = …)</tt> to Python. The
sequence of <spanclass="concept">ParameterSpec</span>'s <ttclass="docutils literal"><spanclass="pre">mpl::vector2<tag::x(int),</span><spanclass="pre">tag::y*(int)></span></tt> has
an <strong>arity range</strong> of [2,2], so we only need one forwarding overload.</p>
Generated by <aclass="reference external"href="http://docutils.sourceforge.net/">Docutils</a> from <aclass="reference external"href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
