<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> <title>The Boost Parameter Library Python Binding Documentation</title> <meta name="authors" content="Daniel Wallin" /> <meta name="organization" content="Boost Consulting" /> <meta name="date" content="2008-03-22" /> <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)" /> <link rel="stylesheet" href="rst.css" type="text/css" /> </head> <body> <div class="document" id="the-boost-parameter-library-python-binding-documentation"> <h1 class="title">The Boost Parameter Library Python Binding Documentation</h1> <table class="docinfo" frame="void" rules="none"> <col class="docinfo-name" /> <col class="docinfo-content" /> <tbody valign="top"> <tr><th class="docinfo-name">Authors:</th> <td>Daniel Wallin</td></tr> <tr><th class="docinfo-name">Contact:</th> <td><a class="first last reference external" href="mailto:dalwan01@student.umu.se">dalwan01@student.umu.se</a></td></tr> <tr><th class="docinfo-name">Organization:</th> <td><a class="first last reference external" href="http://www.boost-consulting.com">Boost Consulting</a></td></tr> <tr><th class="docinfo-name">Date:</th> <td>2008-03-22</td></tr> <tr><th class="docinfo-name">Copyright:</th> <td>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 <a class="reference external" href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</td></tr> </tbody> </table> <div class="abstract topic"> <p class="topic-title first">Abstract</p> <p>Makes it possible to bind Boost.Parameter-enabled functions, operators and constructors to Python.</p> </div> <p><a class="reference external" href="../../../../index.htm"><img alt="Boost" src="../../../../boost.png" /></a></p> <div class="contents topic" id="contents"> <p class="topic-title first">Contents</p> <ul class="simple"> <li><a class="reference internal" href="#introduction" id="id7">Introduction</a></li> <li><a class="reference internal" href="#tutorial" id="id8">Tutorial</a></li> <li><a class="reference internal" href="#concept-parameterspec" id="id9">concept <span class="concept">ParameterSpec</span></a></li> <li><a class="reference internal" href="#special-keywords" id="id10"><em>special</em> keywords</a></li> <li><a class="reference internal" href="#class-template-init" id="id11">class template <tt class="docutils literal"><span class="pre">init</span></tt></a></li> <li><a class="reference internal" href="#class-template-call" id="id12">class template <tt class="docutils literal"><span class="pre">call</span></tt></a></li> <li><a class="reference internal" href="#class-template-function" id="id13">class template <tt class="docutils literal"><span class="pre">function</span></tt></a></li> <li><a class="reference internal" href="#function-template-def" id="id14">function template <tt class="docutils literal"><span class="pre">def</span></tt></a></li> <li><a class="reference internal" href="#portability" id="id15">Portability</a></li> </ul> </div> <div class="section" id="introduction"> <h1><a class="toc-backref" href="#id7">Introduction</a></h1> <p><tt class="docutils literal"><span class="pre">boost/parameter/python.hpp</span></tt> introduces a group of <a class="reference external" href="../../../python/doc/v2/def_visitor.html"><tt class="docutils literal"><span class="pre">def_visitors</span></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 <tt class="docutils literal"><span class="pre">def()</span></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 <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL Sequence</a>, using the function type syntax described in <a class="reference internal" href="#concept-parameterspec"><span class="concept">ParameterSpec</span></a> below. Additionally, <tt class="docutils literal"><span class="pre">boost::parameter::python::function</span></tt> and <tt class="docutils literal"><span class="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 --> <!-- function? --> </div> <div class="section" id="tutorial"> <h1><a class="toc-backref" href="#id8">Tutorial</a></h1> <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 <a class="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> <pre class="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 <tt class="docutils literal"><span class="pre">open</span></tt> with one required parameter and two optional ones. To bind this member function to Python we use the binding utility <tt class="docutils literal"><span class="pre">boost::parameter::python::function</span></tt>. <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"><span class="pre">def_visitor</span></tt></a> that we'll instantiate and pass to <tt class="docutils literal"><span class="pre">boost::python::class_::def()</span></tt>.</p> <p>To use <tt class="docutils literal"><span class="pre">boost::parameter::python::function</span></tt> we first need to define a class with forwarding overloads. This is needed because <tt class="docutils literal"><span class="pre">window::open()</span></tt> is a function template, so we can't refer to it in any other way.</p> <pre class="literal-block"> struct open_fwd { template <class A0, class A1, class A2> void operator()( boost::type<void>, window& self , A0 const& a0, A1 const& a1, A2 const& a2 ) { self.open(a0, a1, a2); } }; </pre> <p>The first parameter, <tt class="docutils literal"><span class="pre">boost::type<void></span></tt>, tells the forwarding overload what the return type should be. In this case we know that it's always void but in some cases, when we are exporting several specializations of a Boost.Parameter-enabled template, we need to use that parameter to deduce the return type.</p> <p><tt class="docutils literal"><span class="pre">window::open()</span></tt> takes a total of 3 parameters, so the forwarding function needs to take three parameters as well.</p> <div class="note"> <p class="first admonition-title">Note</p> <p class="last">We only need one overload in the forwarding class, despite the fact that there are two optional parameters. There are special circumstances when several overload are needed; see <a class="reference internal" href="#special-keywords">special keywords</a>.</p> </div> <p>Next we'll define the module and export the class:</p> <pre class="literal-block"> BOOST_PYTHON_MODULE(my_module) { using namespace boost::python; namespace py = boost::parameter::python; namespace mpl = boost::mpl; class_<window>("window") .def( "open", py::function< open_fwd , mpl::vector< void , tag::title(std::string) , tag::width*(unsigned) , tag::height*(unsigned) > >() ); } </pre> <!-- @jam_prefix.append('import python ;') --> <!-- @jam_prefix.append('stage . : my_module /boost/python//boost_python ;') --> <!-- @my_module = build( output = 'my_module' , target_rule = 'python-extension' , input = '/boost/python//boost_python' , howmany = 'all' ) --> <!-- @del jam_prefix[:] --> <p><tt class="docutils literal"><span class="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 <a class="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 <tt class="docutils literal"><span class="pre">tag::width*</span></tt> and <tt class="docutils literal"><span class="pre">tag::height*</span></tt> means that the parameter is optional. The first element of 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"><span class="pre">void</span></tt>, which is passed as the first argument to <tt class="docutils literal"><span class="pre">operator()</span></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> <pre class="literal-block"> >>> w = my_module.window() >>> w.open(title = "foo", height = 20) </pre> <!-- @example.prepend('import my_module') --> <!-- @run_python(module_path = my_module) --> <!-- Sorry to say this at such a late date, but this syntax really --> <!-- strikes me as cumbersome. Couldn't we do something like: class_<window>("window") .def( "open", (void (*)( tag::title(std::string), tag::width*(unsigned), tag::height*(unsigned)) )0 ); or at least: class_<window>("window") .def( "open", mpl::vector< void, tag::title(std::string), tag::width*(unsigned), tag::height*(unsigned) >() ); assuming, that is, that we will have to repeat the tags (yes, users of broken compilers will have to give us function pointer types instead). --> </div> <hr class="docutils" /> <div class="section" id="concept-parameterspec"> <h1><a class="toc-backref" href="#id9">concept <span class="concept">ParameterSpec</span></a></h1> <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, <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> <p><tt class="docutils literal"><span class="pre">K</span></tt> is either:</p> <ul class="simple"> <li>A <em>required</em> keyword of the form <tt class="docutils literal"><span class="pre">Tag</span></tt></li> <li><strong>or</strong>, an <em>optional</em> keyword of the form <tt class="docutils literal"><span class="pre">Tag*</span></tt></li> <li><strong>or</strong>, a <em>special</em> keyword of the form <tt class="docutils literal"><span class="pre">Tag**</span></tt></li> </ul> <p>where <tt class="docutils literal"><span class="pre">Tag</span></tt> is a keyword tag type, as used in a specialization 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> <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 defined as the closed range:</p> <pre class="literal-block"> [ mpl::size<S> - number of <em>special</em> keyword tags in <tt class="docutils literal"><span class="pre">S</span></tt>, mpl::size<S> ] </pre> <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"><span class="pre">[2,2]</span></tt>, 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"><span class="pre">[2,2]</span></tt> and 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"><span class="pre">[1,2]</span></tt>.</p> </div> <div class="section" id="special-keywords"> <h1><a class="toc-backref" href="#id10"><em>special</em> keywords</a></h1> <p>Sometimes it is desirable to have a default value for a parameter that differ in type from the parameter. This technique is useful for doing simple tag-dispatching based on the presence of a parameter. For example:</p> <!-- An example_ of this is given in the Boost.Parameter docs. The example uses a different technique, but could also have been written like this: --> <pre class="literal-block"> namespace core { template <class ArgumentPack> void dfs_dispatch(ArgumentPack const& args, mpl::false_) { <em>…compute and use default color map…</em> } template <class ArgumentPack, class ColorMap> void dfs_dispatch(ArgumentPack const& args, ColorMap colormap) { <em>…use colormap…</em> } } template <class ArgumentPack> void depth_first_search(ArgumentPack const& args) { core::dfs_dispatch(args, args[color | mpl::false_()]); } </pre> <!-- @example.prepend(''' #include <boost/parameter/keyword.hpp> #include <boost/parameter/parameters.hpp> #include <boost/mpl/bool.hpp> #include <cassert> BOOST_PARAMETER_KEYWORD(tag, color); typedef boost::parameter::parameters<tag::color> params; namespace mpl = boost::mpl; ''') --> <!-- @example.replace_emphasis(''' assert(args[color | 1] == 1); ''') --> <!-- @example.replace_emphasis(''' assert(args[color | 1] == 0); ''') --> <!-- @example.append(''' int main() { depth_first_search(params()()); depth_first_search(params()(color = 0)); }''') --> <!-- @build() --> <!-- .. _example: index.html#dispatching-based-on-the-presence-of-a-default --> <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 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 <tt class="docutils literal"><span class="pre">color</span></tt> will not be convertible to the parameter type. Therefore we need to tag the <tt class="docutils literal"><span class="pre">color</span></tt> keyword as a <em>special</em> keyword. This is done by specifying the tag as <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 more details on the tagging). By doing this we tell the binding functions that it needs to generate two overloads, one with the <tt class="docutils literal"><span class="pre">color</span></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 <tt class="docutils literal"><span class="pre">N</span></tt> is the number of <em>special</em> keywords.</p> </div> <hr class="docutils" /> <div class="section" id="class-template-init"> <h1><a class="toc-backref" href="#id11">class template <tt class="docutils literal"><span class="pre">init</span></tt></a></h1> <p>Defines a named parameter enabled constructor.</p> <pre class="literal-block"> template <class ParameterSpecs> struct init : python::def_visitor<init<ParameterSpecs> > { template <class Class> void def(Class& class_); template <class CallPolicies> <em>def_visitor</em> operator[](CallPolicies const& policies) const; }; </pre> <!-- @ignore() --> <div class="section" id="init-requirements"> <h2><tt class="docutils literal"><span class="pre">init</span></tt> requirements</h2> <ul> <li><p class="first"><tt class="docutils literal"><span class="pre">ParameterSpecs</span></tt> is an <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element is a model of <span class="concept">ParameterSpec</span>.</p> </li> <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 range</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 expressions:</p> <table border="1" class="docutils"> <colgroup> <col width="30%" /> <col width="17%" /> <col width="53%" /> </colgroup> <thead valign="bottom"> <tr><th class="head"><p class="first last">Expression</p> </th> <th class="head"><p class="first last">Return type</p> </th> <th class="head"><p class="first last">Requirements</p> </th> </tr> </thead> <tbody valign="top"> <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> </td> <td><p class="first last">-</p> </td> <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> </td> </tr> </tbody> </table> </li> </ul> </div> <div class="section" id="template-class-callpolicies-operator-callpolicies-const"> <h2><tt class="docutils literal"><span class="pre">template</span> <span class="pre"><class</span> <span class="pre">CallPolicies></span> <span class="pre">operator[](CallPolicies</span> <span class="pre">const&)</span></tt></h2> <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 uses CallPolicies when creating the binding.</p> </div> <div class="section" id="example"> <h2>Example</h2> <pre class="literal-block"> #include <boost/parameter/keyword.hpp> #include <boost/parameter/preprocessor.hpp> #include <boost/parameter/python.hpp> #include <boost/python.hpp> #include <boost/mpl/vector.hpp> BOOST_PARAMETER_KEYWORD(tag, x) BOOST_PARAMETER_KEYWORD(tag, y) struct base { template <class ArgumentPack> base(ArgumentPack const& args) { <em>… use args …</em> } }; class X : base { public: BOOST_PARAMETER_CONSTRUCTOR(X, (base), tag, (required (x, *)) (optional (y, *)) ) }; BOOST_PYTHON_MODULE(<em>module name</em>) { using namespace boost::python; namespace py = boost::parameter::python; namespace mpl = boost::mpl; class_<X>("X", no_init) .def( py::init< mpl::vector<tag::x(int), tag::y*(int)> >() ); } </pre> <!-- @example.replace_emphasis(''' assert(args[x] == 0); assert(args[y | 1] == 1); ''') --> <!-- @example.replace_emphasis('my_module') --> <!-- @jam_prefix.append('import python ;') --> <!-- @jam_prefix.append('stage . : my_module /boost/python//boost_python ;') --> <!-- @my_module = build( output = 'my_module' , target_rule = 'python-extension' , input = '/boost/python//boost_python' ) --> </div> </div> <hr class="docutils" /> <div class="section" id="class-template-call"> <h1><a class="toc-backref" href="#id12">class template <tt class="docutils literal"><span class="pre">call</span></tt></a></h1> <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> <pre class="literal-block"> template <class ParameterSpecs> struct call : python::def_visitor<call<ParameterSpecs> > { template <class Class> void def(Class& class_); template <class CallPolicies> <em>def_visitor</em> operator[](CallPolicies const& policies) const; }; </pre> <!-- @ignore() --> <div class="section" id="call-requirements"> <h2><tt class="docutils literal"><span class="pre">call</span></tt> requirements</h2> <ul> <li><p class="first"><tt class="docutils literal"><span class="pre">ParameterSpecs</span></tt> is an <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element except the first models <span class="concept">ParameterSpec</span>. The first element is the result type of <tt class="docutils literal"><span class="pre">c(…)</span></tt>.</p> </li> <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 instance of <tt class="docutils literal"><span class="pre">Class</span></tt>:</p> <table border="1" class="docutils"> <colgroup> <col width="24%" /> <col width="26%" /> <col width="50%" /> </colgroup> <thead valign="bottom"> <tr><th class="head"><p class="first last">Expression</p> </th> <th class="head"><p class="first last">Return type</p> </th> <th class="head"><p class="first last">Requirements</p> </th> </tr> </thead> <tbody valign="top"> <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> </td> <td><p class="first last">Convertible to <tt class="docutils literal"><span class="pre">R</span></tt></p> </td> <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> </td> </tr> </tbody> </table> <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> </li> </ul> </div> <div class="section" id="id3"> <h2><tt class="docutils literal"><span class="pre">template</span> <span class="pre"><class</span> <span class="pre">CallPolicies></span> <span class="pre">operator[](CallPolicies</span> <span class="pre">const&)</span></tt></h2> <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 uses CallPolicies when creating the binding.</p> </div> <div class="section" id="id4"> <h2>Example</h2> <pre class="literal-block"> #include <boost/parameter/keyword.hpp> #include <boost/parameter/preprocessor.hpp> #include <boost/parameter/python.hpp> #include <boost/python.hpp> #include <boost/mpl/vector.hpp> BOOST_PARAMETER_KEYWORD(tag, x) BOOST_PARAMETER_KEYWORD(tag, y) namespace parameter = boost::parameter; typedef parameter::parameters< parameter::required<tag::x> , parameter::optional<tag::y> > call_parameters; class X { public: template <class ArgumentPack> int call_impl(ArgumentPack const& args) { <em>… use args …</em> } template <class A0> int operator()(A0 const& a0) { return call_impl(call_parameters()(a0)); } template <class A0, class A1> int operator()(A0 const& a0, A1 const& a1) { return call_impl(call_parameters()(a0,a1)); } }; BOOST_PYTHON_MODULE(<em>module name</em>) { using namespace boost::python; namespace py = parameter::python; namespace mpl = boost::mpl; class_<X>("X") .def( py::call< mpl::vector<int, tag::x(int), tag::y*(int)> >() ); } </pre> <!-- @example.replace_emphasis(''' assert(args[x] == 0); assert(args[y | 1] == 1); return 0; ''') --> <!-- @example.replace_emphasis('my_module') --> <!-- @my_module = build( output = 'my_module' , target_rule = 'python-extension' , input = '/boost/python//boost_python' ) --> </div> </div> <hr class="docutils" /> <div class="section" id="class-template-function"> <h1><a class="toc-backref" href="#id13">class template <tt class="docutils literal"><span class="pre">function</span></tt></a></h1> <p>Defines a named parameter enabled member function.</p> <pre class="literal-block"> template <class Fwd, class ParameterSpecs> struct function : python::def_visitor<function<Fwd, ParameterSpecs> > { template <class Class, class Options> void def(Class& class_, char const* name, Options const& options); }; </pre> <!-- @ignore() --> <div class="section" id="function-requirements"> <h2><tt class="docutils literal"><span class="pre">function</span></tt> requirements</h2> <ul> <li><p class="first"><tt class="docutils literal"><span class="pre">ParameterSpecs</span></tt> is an <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element except the first models <span class="concept">ParameterSpec</span>. The first element is 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 function.</p> </li> <li><p class="first">An instance of <tt class="docutils literal"><span class="pre">Fwd</span></tt> must support this expression:</p> <table border="1" class="docutils"> <colgroup> <col width="39%" /> <col width="18%" /> <col width="43%" /> </colgroup> <thead valign="bottom"> <tr><th class="head"><p class="first last">Expression</p> </th> <th class="head"><p class="first last">Return type</p> </th> <th class="head"><p class="first last">Requirements</p> </th> </tr> </thead> <tbody valign="top"> <tr><td><p class="first last"><tt class="docutils literal"><span class="pre">fwd(boost::type<R>(),</span> <span class="pre">self,</span> <span class="pre">a0,</span> <span class="pre">…,</span> <span class="pre">aN)</span></tt></p> </td> <td><p class="first last">Convertible to <tt class="docutils literal"><span class="pre">R</span></tt></p> </td> <td><p class="first last"><tt class="docutils literal"><span class="pre">self</span></tt> is a reference to the object on which the function should be invoked. <tt class="docutils literal"><span class="pre">a0</span></tt>…<tt class="docutils literal"><span class="pre">aN</span></tt> are tagged arguments.</p> </td> </tr> </tbody> </table> <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> </li> </ul> </div> <div class="section" id="id5"> <h2>Example</h2> <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 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 an <strong>arity range</strong> of [2,2], so we only need one forwarding overload.</p> <pre class="literal-block"> #include <boost/parameter/keyword.hpp> #include <boost/parameter/preprocessor.hpp> #include <boost/parameter/python.hpp> #include <boost/python.hpp> #include <boost/mpl/vector.hpp> BOOST_PARAMETER_KEYWORD(tag, x) BOOST_PARAMETER_KEYWORD(tag, y) class X { public: BOOST_PARAMETER_MEMBER_FUNCTION((void), f, tag, (required (x, *)) (optional (y, *, 1)) ) { <em>…</em> } }; struct f_fwd { template <class A0, class A1> void operator()(boost::type<void>, X& self, A0 const& a0, A1 const& a1) { self.f(a0, a1); } }; BOOST_PYTHON_MODULE(<em>module name</em>) { using namespace boost::python; namespace py = boost::parameter::python; namespace mpl = boost::mpl; class_<X>("X") .def("f", py::function< f_fwd , mpl::vector<void, tag::x(int), tag::y*(int)> >() ); } </pre> <!-- @example.replace_emphasis(''' assert(x == 0); assert(y == 1); ''') --> <!-- @example.replace_emphasis('my_module') --> <!-- @my_module = build( output = 'my_module' , target_rule = 'python-extension' , input = '/boost/python//boost_python' ) --> </div> </div> <hr class="docutils" /> <div class="section" id="function-template-def"> <h1><a class="toc-backref" href="#id14">function template <tt class="docutils literal"><span class="pre">def</span></tt></a></h1> <p>Defines a named parameter enabled free function in the current Python scope.</p> <pre class="literal-block"> template <class Fwd, class ParameterSpecs> void def(char const* name); </pre> <!-- @ignore() --> <div class="section" id="def-requirements"> <h2><tt class="docutils literal"><span class="pre">def</span></tt> requirements</h2> <ul> <li><p class="first"><tt class="docutils literal"><span class="pre">ParameterSpecs</span></tt> is an <a class="reference external" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element except the first models <span class="concept">ParameterSpec</span>. The first element is 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> </li> <li><p class="first">An instance of <tt class="docutils literal"><span class="pre">Fwd</span></tt> must support this expression:</p> <table border="1" class="docutils"> <colgroup> <col width="39%" /> <col width="21%" /> <col width="40%" /> </colgroup> <thead valign="bottom"> <tr><th class="head"><p class="first last">Expression</p> </th> <th class="head"><p class="first last">Return type</p> </th> <th class="head"><p class="first last">Requirements</p> </th> </tr> </thead> <tbody valign="top"> <tr><td><p class="first last"><tt class="docutils literal"><span class="pre">fwd(boost::type<R>(),</span> <span class="pre">a0,</span> <span class="pre">…,</span> <span class="pre">aN)</span></tt></p> </td> <td><p class="first last">Convertible to <tt class="docutils literal"><span class="pre">R</span></tt></p> </td> <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> </td> </tr> </tbody> </table> <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> </li> </ul> </div> <div class="section" id="id6"> <h2>Example</h2> <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 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 an <strong>arity range</strong> of [2,2], so we only need one forwarding overload.</p> <pre class="literal-block"> BOOST_PARAMETER_FUNCTION((void), f, tag, (required (x, *)) (optional (y, *, 1)) ) { <em>…</em> } struct f_fwd { template <class A0, class A1> void operator()(boost::type<void>, A0 const& a0, A1 const& a1) { f(a0, a1); } }; BOOST_PYTHON_MODULE(…) { def< f_fwd , mpl::vector< void, tag::x(int), tag::y*(int) > >("f"); } </pre> <!-- @ignore() --> <!-- again, the undefined ``fwd`` identifier. --> </div> </div> <div class="section" id="portability"> <h1><a class="toc-backref" href="#id15">Portability</a></h1> <p>The Boost.Parameter Python binding library requires <em>partial template specialization</em>.</p> </div> </div> <div class="footer"> <hr class="footer" /> Generated on: 2008-06-26 21:51 UTC. 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. </div> </body> </html>