123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764 |
- <?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.12: http://docutils.sourceforge.net/" />
- <title>The Boost Parameter Library Python Binding Documentation</title>
- <meta name="authors" content="David Abrahams Daniel Wallin" />
- <meta name="organization" content="BoostPro Computing" />
- <meta name="date" content="$Date$" />
- <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)" />
- <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>David Abrahams
- <br />Daniel Wallin</td></tr>
- <tr><th class="docinfo-name">Contact:</th>
- <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>
- <tr><th class="docinfo-name">Organization:</th>
- <td><a class="first last reference external" href="http://www.boostpro.com">BoostPro Computing</a></td></tr>
- <tr><th class="docinfo-name">Date:</th>
- <td>$Date$</td></tr>
- <tr><th class="docinfo-name">Copyright:</th>
- <td>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 <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">init</tt></a></li>
- <li><a class="reference internal" href="#class-template-call" id="id12">class template <tt class="docutils literal">call</tt></a></li>
- <li><a class="reference internal" href="#class-template-function" id="id13">class template <tt class="docutils literal">function</tt></a></li>
- <li><a class="reference internal" href="#function-template-def" id="id14">function template <tt class="docutils literal">def</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">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
- 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">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 <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">open</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">def_visitor</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">void</tt>,
- which is passed as the first argument to <tt class="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>
- <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">K(T)</tt> that describes both the keyword tag,
- <tt class="docutils literal">K</tt>, and the argument type, <tt class="docutils literal">T</tt>, for a parameter.</p>
- <p><tt class="docutils literal">K</tt> is either:</p>
- <ul class="simple">
- <li>A <em>required</em> keyword of the form <tt class="docutils literal">Tag</tt></li>
- <li><strong>or</strong>, an <em>optional</em> keyword of the form <tt class="docutils literal">Tag*</tt></li>
- <li><strong>or</strong>, a <em>special</em> keyword of the form <tt class="docutils literal">Tag**</tt></li>
- </ul>
- <p>where <tt class="docutils literal">Tag</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">S</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">[2,2]</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">[2,2]</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">[1,2]</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">color</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">color</tt> will not
- be convertible to the parameter type. Therefore we need to tag the <tt class="docutils literal">color</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">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 <tt class="docutils literal">N</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">init</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">init</tt> requirements</h2>
- <ul>
- <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
- model of <span class="concept">ParameterSpec</span>.</p>
- </li>
- <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
- range</strong> of <tt class="docutils literal">ParameterSpecs</tt>, <tt class="docutils literal">Class</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">Expression</th>
- <th class="head">Return type</th>
- <th class="head">Requirements</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr><td><tt class="docutils literal">Class(a0, …, aN)</tt></td>
- <td>-</td>
- <td><tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt> are tagged arguments.</td>
- </tr>
- </tbody>
- </table>
- </li>
- </ul>
- </div>
- <div class="section" id="template-class-callpolicies-operator-callpolicies-const">
- <h2><tt class="docutils literal">template <class CallPolicies> <span class="pre">operator[](CallPolicies</span> const&)</tt></h2>
- <p>Returns a <tt class="docutils literal">def_visitor</tt> equivalent to <tt class="docutils literal">*this</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">call</tt></a></h1>
- <p>Defines a <tt class="docutils literal">__call__</tt> operator, mapped to <tt class="docutils literal">operator()</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">call</tt> requirements</h2>
- <ul>
- <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
- 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">Class</tt> must support these expressions, where <tt class="docutils literal">c</tt> is an
- instance of <tt class="docutils literal">Class</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">Expression</th>
- <th class="head">Return type</th>
- <th class="head">Requirements</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr><td><tt class="docutils literal">c(a0, …, aN)</tt></td>
- <td>Convertible to <tt class="docutils literal">R</tt></td>
- <td><tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt> are tagged arguments.</td>
- </tr>
- </tbody>
- </table>
- <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>
- </li>
- </ul>
- </div>
- <div class="section" id="id3">
- <h2><tt class="docutils literal">template <class CallPolicies> <span class="pre">operator[](CallPolicies</span> const&)</tt></h2>
- <p>Returns a <tt class="docutils literal">def_visitor</tt> equivalent to <tt class="docutils literal">*this</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">function</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">function</tt> requirements</h2>
- <ul>
- <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
- 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">f</tt> is the member
- function.</p>
- </li>
- <li><p class="first">An instance of <tt class="docutils literal">Fwd</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">Expression</th>
- <th class="head">Return type</th>
- <th class="head">Requirements</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr><td><tt class="docutils literal"><span class="pre">fwd(boost::type<R>(),</span> self, a0, …, aN)</tt></td>
- <td>Convertible to <tt class="docutils literal">R</tt></td>
- <td><tt class="docutils literal">self</tt> is a reference to the object on which
- the function should be invoked. <tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt>
- are tagged arguments.</td>
- </tr>
- </tbody>
- </table>
- <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>
- </li>
- </ul>
- </div>
- <div class="section" id="id5">
- <h2>Example</h2>
- <p>This example exports a member function <tt class="docutils literal">f(int x, int y = …)</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">def</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">def</tt> requirements</h2>
- <ul>
- <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
- 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">f</tt> is the function.</p>
- </li>
- <li><p class="first">An instance of <tt class="docutils literal">Fwd</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">Expression</th>
- <th class="head">Return type</th>
- <th class="head">Requirements</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr><td><tt class="docutils literal"><span class="pre">fwd(boost::type<R>(),</span> a0, …, aN)</tt></td>
- <td>Convertible to <tt class="docutils literal">R</tt></td>
- <td><tt class="docutils literal">a0</tt>…<tt class="docutils literal">aN</tt> are tagged arguments.</td>
- </tr>
- </tbody>
- </table>
- <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>
- </li>
- </ul>
- </div>
- <div class="section" id="id6">
- <h2>Example</h2>
- <p>This example exports a function <tt class="docutils literal">f(int x, int y = …)</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: 2019-12-10 00:22 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>
|