[DEV] add v1.76.0

This commit is contained in:
2021-10-05 21:37:46 +02:00
parent a97e9ae7d4
commit d0115b733d
45133 changed files with 4744437 additions and 1026325 deletions

View File

@@ -0,0 +1,30 @@
# Copyright David Abrahams 2006. 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)
import docutils ;
sources = [ glob *.rst ] ;
bases = $(sources:S=) ;
# This is a path relative to the html/ subdirectory where the
# generated output will eventually be moved.
stylesheet = "--stylesheet=rst.css" ;
for local b in $(bases)
{
html $(b) : $(b).rst :
#
<docutils-html>"-gdt --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet)
;
}
alias htmls : $(bases) ;
stage html : $(bases) ;
###############################################################################
alias boostdoc ;
explicit boostdoc ;
alias boostrelease : html ;
explicit boostrelease ;

View File

@@ -0,0 +1,764 @@
<?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&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="last reference external" href="mailto:daniel&#64;boostpro.com">daniel&#64;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 &lt;boost/parameter/keyword.hpp&gt;
#include &lt;boost/parameter/preprocessor.hpp&gt;
#include &lt;boost/parameter/python.hpp&gt;
#include &lt;boost/python.hpp&gt;
// 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 &lt;class A0, class A1, class A2&gt;
void operator()(
boost::type&lt;void&gt;, window&amp; self
, A0 const&amp; a0, A1 const&amp; a1, A2 const&amp; a2
)
{
self.open(a0, a1, a2);
}
};
</pre>
<p>The first parameter, <tt class="docutils literal"><span class="pre">boost::type&lt;void&gt;</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_&lt;window&gt;(&quot;window&quot;)
.def(
&quot;open&quot;, py::function&lt;
open_fwd
, mpl::vector&lt;
void
, tag::title(std::string)
, tag::width*(unsigned)
, tag::height*(unsigned)
&gt;
&gt;()
);
}
</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">
&gt;&gt;&gt; w = my_module.window()
&gt;&gt;&gt; w.open(title = &quot;foo&quot;, 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&lt;S&gt; - number of <em>special</em> keyword tags in <tt class="docutils literal">S</tt>, mpl::size&lt;S&gt; ]
</pre>
<p>For example, the <strong>arity range</strong> of <tt class="docutils literal"><span class="pre">mpl::vector2&lt;x(int),y(int)&gt;</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&lt;x(int),y*(int)&gt;</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&lt;x(int),y**(int)&gt;</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 &lt;class ArgumentPack&gt;
void dfs_dispatch(ArgumentPack const&amp; args, mpl::false_)
{
<em>…compute and use default color map…</em>
}
template &lt;class ArgumentPack, class ColorMap&gt;
void dfs_dispatch(ArgumentPack const&amp; args, ColorMap colormap)
{
<em>…use colormap…</em>
}
}
template &lt;class ArgumentPack&gt;
void depth_first_search(ArgumentPack const&amp; 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 &lt;class ParameterSpecs&gt;
struct init : python::def_visitor&lt;init&lt;ParameterSpecs&gt; &gt;
{
template &lt;class Class&gt;
void def(Class&amp; class_);
template &lt;class CallPolicies&gt;
<em>def_visitor</em> operator[](CallPolicies const&amp; 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 &lt;class CallPolicies&gt; <span class="pre">operator[](CallPolicies</span> const&amp;)</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 &lt;boost/parameter/keyword.hpp&gt;
#include &lt;boost/parameter/preprocessor.hpp&gt;
#include &lt;boost/parameter/python.hpp&gt;
#include &lt;boost/python.hpp&gt;
#include &lt;boost/mpl/vector.hpp&gt;
BOOST_PARAMETER_KEYWORD(tag, x)
BOOST_PARAMETER_KEYWORD(tag, y)
struct base
{
template &lt;class ArgumentPack&gt;
base(ArgumentPack const&amp; 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_&lt;X&gt;(&quot;X&quot;, no_init)
.def(
py::init&lt;
mpl::vector&lt;tag::x(int), tag::y*(int)&gt;
&gt;()
);
}
</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 &lt;class ParameterSpecs&gt;
struct call : python::def_visitor&lt;call&lt;ParameterSpecs&gt; &gt;
{
template &lt;class Class&gt;
void def(Class&amp; class_);
template &lt;class CallPolicies&gt;
<em>def_visitor</em> operator[](CallPolicies const&amp; 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 &lt;class CallPolicies&gt; <span class="pre">operator[](CallPolicies</span> const&amp;)</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 &lt;boost/parameter/keyword.hpp&gt;
#include &lt;boost/parameter/preprocessor.hpp&gt;
#include &lt;boost/parameter/python.hpp&gt;
#include &lt;boost/python.hpp&gt;
#include &lt;boost/mpl/vector.hpp&gt;
BOOST_PARAMETER_KEYWORD(tag, x)
BOOST_PARAMETER_KEYWORD(tag, y)
namespace parameter = boost::parameter;
typedef parameter::parameters&lt;
parameter::required&lt;tag::x&gt;
, parameter::optional&lt;tag::y&gt;
&gt; call_parameters;
class X
{
public:
template &lt;class ArgumentPack&gt;
int call_impl(ArgumentPack const&amp; args)
{
<em>… use args …</em>
}
template &lt;class A0&gt;
int operator()(A0 const&amp; a0)
{
return call_impl(call_parameters()(a0));
}
template &lt;class A0, class A1&gt;
int operator()(A0 const&amp; a0, A1 const&amp; 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_&lt;X&gt;(&quot;X&quot;)
.def(
py::call&lt;
mpl::vector&lt;int, tag::x(int), tag::y*(int)&gt;
&gt;()
);
}
</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 &lt;class Fwd, class ParameterSpecs&gt;
struct function : python::def_visitor&lt;function&lt;Fwd, ParameterSpecs&gt; &gt;
{
template &lt;class Class, class Options&gt;
void def(Class&amp; class_, char const* name, Options const&amp; 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&lt;R&gt;(),</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&lt;tag::x(int),</span> <span class="pre">tag::y*(int)&gt;</span></tt> has
an <strong>arity range</strong> of [2,2], so we only need one forwarding overload.</p>
<pre class="literal-block">
#include &lt;boost/parameter/keyword.hpp&gt;
#include &lt;boost/parameter/preprocessor.hpp&gt;
#include &lt;boost/parameter/python.hpp&gt;
#include &lt;boost/python.hpp&gt;
#include &lt;boost/mpl/vector.hpp&gt;
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 &lt;class A0, class A1&gt;
void operator()(boost::type&lt;void&gt;, X&amp; self, A0 const&amp; a0, A1 const&amp; 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_&lt;X&gt;(&quot;X&quot;)
.def(&quot;f&quot;,
py::function&lt;
f_fwd
, mpl::vector&lt;void, tag::x(int), tag::y*(int)&gt;
&gt;()
);
}
</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 &lt;class Fwd, class ParameterSpecs&gt;
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&lt;R&gt;(),</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&lt;tag::x(int),</span> <span class="pre">tag::y*(int)&gt;</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 &lt;class A0, class A1&gt;
void operator()(boost::type&lt;void&gt;, A0 const&amp; a0, A1 const&amp; a1)
{
f(a0, a1);
}
};
BOOST_PYTHON_MODULE(…)
{
def&lt;
f_fwd
, mpl::vector&lt;
void, tag::x(int), tag::y*(int)
&gt;
&gt;(&quot;f&quot;);
}
</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: 2021-04-13 16:26 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>

View File

@@ -0,0 +1,43 @@
/* Copyright David Abrahams 2006. 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)
*/
@import "../../../../rst.css";
div.section div.section div.section dl {
margin-left: 2em;
}
td span {
vertical-align: text-top;
}
img {
border: none;
vertical-align: middle
}
span.vellipsis {
display: block;
width: 5px;
height: 22px;
background: url("vellipsis.gif");
margin-left: 3em;
text-indent: -1000px;
}
PRE
{
FONT-FAMILY: monospace ;
}
CODE
{
FONT-FAMILY: monospace;
}
.pre
{
FONT-FAMILY: monospace;
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 62 B

View File

@@ -0,0 +1,778 @@
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
The Boost Parameter Library Python Binding Documentation
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
:Authors: David Abrahams, Daniel Wallin
:Contact: dave@boost-consulting.com, daniel@boostpro.com
:organization: `BoostPro Computing`_
:date: $Date$
:copyright: 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)
:abstract: Makes it possible to bind Boost.Parameter-enabled
functions, operators and constructors to Python.
|(logo)|__
.. |(logo)| image:: ../../../../boost.png
:alt: Boost
__ ../../../../index.htm
.. _`BoostPro Computing`: http://www.boostpro.com
.. role:: class
:class: class
.. role:: concept
:class: concept
.. role:: function
:class: function
.. |ParameterSpec| replace:: :concept:`ParameterSpec`
.. contents::
:depth: 1
Introduction
------------
``boost/parameter/python.hpp`` introduces a group of |def_visitors|_ that can
be used to easily expose Boost.Parameter-enabled member functions to Python with
Boost.Python. It also provides a function template ``def()`` that can be used
to expose Boost.Parameter-enabled free functions.
.. |def_visitor| replace:: ``def_visitor``
.. |def_visitors| replace:: ``def_visitors``
.. _def_visitor: def_visitors_
.. _def_visitors: ../../../python/doc/v2/def_visitor.html
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.
.. 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.
The keyword tags and associated argument types are specified as an `MPL
Sequence`_, using the function type syntax described in |ParameterSpec|_
below. 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.
.. 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?
.. _`MPL Sequence`: ../../../mpl/doc/refmanual/sequences.html
.. _parameterspec: `concept ParameterSpec`_
Tutorial
--------
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 macros_ are required to understand this section.
.. _macros: index.html
The class and member function we are interested in binding looks
like this:
.. parsed-literal::
#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))
)
{
*… function implementation …*
}
};
.. @example.prepend('#include <cassert>')
.. @example.replace_emphasis('''
assert(title == "foo");
assert(height == 20);
assert(width == 400);
''')
It defines a set of overloaded member functions called ``open`` with one
required parameter and two optional ones. To bind this member function to
Python we use the binding utility ``boost::parameter::python::function``.
``boost::parameter::python::function`` is a |def_visitor|_ that we'll instantiate
and pass to ``boost::python::class_::def()``.
To use ``boost::parameter::python::function`` we first need to define
a class with forwarding overloads. This is needed because ``window::open()``
is a function template, so we can't refer to it in any other way.
::
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);
}
};
The first parameter, ``boost::type<void>``, 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.
``window::open()`` takes a total of 3 parameters, so the forwarding function
needs to take three parameters as well.
.. Note::
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
`special keywords`_.
Next we'll define the module and export the class:
::
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)
>
>()
);
}
.. @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[:]
``py::function`` is passed two parameters. The first one is the class with
forwarding overloads that we defined earlier. The second one is an `MPL
Sequence`_ with the keyword tag types and argument types for the function
specified as function types. The pointer syntax used in ``tag::width*`` and
``tag::height*`` means that the parameter is optional. The first element of
the `MPL Sequence`_ is the return type of the function, in this case ``void``,
which is passed as the first argument to ``operator()`` in the forwarding
class.
.. 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()
That's it! This class can now be used in Python with the expected syntax::
>>> w = my_module.window()
>>> w.open(title = "foo", height = 20)
.. @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).
------------------------------------------------------------------------------
concept |ParameterSpec|
-----------------------
A |ParameterSpec| is a function type ``K(T)`` that describes both the keyword tag,
``K``, and the argument type, ``T``, for a parameter.
``K`` is either:
* A *required* keyword of the form ``Tag``
* **or**, an *optional* keyword of the form ``Tag*``
* **or**, a *special* keyword of the form ``Tag**``
where ``Tag`` is a keyword tag type, as used in a specialization
of |keyword|__.
.. |keyword| replace:: ``boost::parameter::keyword``
__ ../../../parameter/doc/html/reference.html#keyword
The **arity range** for an `MPL Sequence`_ of |ParameterSpec|'s is
defined as the closed range:
.. parsed-literal::
[ mpl::size<S> - number of *special* keyword tags in ``S``, mpl::size<S> ]
For example, the **arity range** of ``mpl::vector2<x(int),y(int)>`` is ``[2,2]``,
the **arity range** of ``mpl::vector2<x(int),y*(int)>`` is ``[2,2]`` and the
**arity range** of ``mpl::vector2<x(int),y**(int)>`` is ``[1,2]``.
*special* keywords
---------------------------------
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:
.. 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:
.. parsed-literal::
namespace core
{
template <class ArgumentPack>
void dfs_dispatch(ArgumentPack const& args, mpl::false\_)
{
*…compute and use default color map…*
}
template <class ArgumentPack, class ColorMap>
void dfs_dispatch(ArgumentPack const& args, ColorMap colormap)
{
*…use colormap…*
}
}
template <class ArgumentPack>
void depth_first_search(ArgumentPack const& args)
{
core::dfs_dispatch(args, args[color | mpl::false_()]);
}
.. @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
In the above example the type of the default for ``color`` is ``mpl::false_``, a
type that is distinct from any color map that the user might supply.
When binding the case outlined above, the default type for ``color`` will not
be convertible to the parameter type. Therefore we need to tag the ``color``
keyword as a *special* keyword. This is done by specifying the tag as
``tag::color**`` when binding the function (see `concept ParameterSpec`_ for
more details on the tagging). By doing this we tell the binding functions that
it needs to generate two overloads, one with the ``color`` parameter present
and one without. Had there been two *special* keywords, four overloads would
need to be generated. The number of generated overloads is equal to 2\
:sup:`N`, where ``N`` is the number of *special* keywords.
------------------------------------------------------------------------------
class template ``init``
-----------------------
Defines a named parameter enabled constructor.
.. parsed-literal::
template <class ParameterSpecs>
struct init : python::def_visitor<init<ParameterSpecs> >
{
template <class Class>
void def(Class& class\_);
template <class CallPolicies>
*def\_visitor* operator[](CallPolicies const& policies) const;
};
.. @ignore()
``init`` requirements
~~~~~~~~~~~~~~~~~~~~~
* ``ParameterSpecs`` is an `MPL sequence`_ where each element is a
model of |ParameterSpec|.
* For every ``N`` in ``[U,V]``, where ``[U,V]`` is the **arity
range** of ``ParameterSpecs``, ``Class`` must support these
expressions:
======================= ============= =========================================
Expression Return type Requirements
======================= ============= =========================================
``Class(a0, …, aN)`` \- ``a0``\ …\ ``aN`` are tagged arguments.
======================= ============= =========================================
``template <class CallPolicies> operator[](CallPolicies const&)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns a ``def_visitor`` equivalent to ``*this``, except that it
uses CallPolicies when creating the binding.
Example
~~~~~~~
.. parsed-literal::
#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)
{
*… use args …*
}
};
class X : base
{
public:
BOOST_PARAMETER_CONSTRUCTOR(X, (base), tag,
(required (x, \*))
(optional (y, \*))
)
};
BOOST_PYTHON_MODULE(*module name*)
{
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)>
>()
);
}
.. @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'
)
------------------------------------------------------------------------------
class template ``call``
-----------------------
Defines a ``__call__`` operator, mapped to ``operator()`` in C++.
.. parsed-literal::
template <class ParameterSpecs>
struct call : python::def_visitor<call<ParameterSpecs> >
{
template <class Class>
void def(Class& class\_);
template <class CallPolicies>
*def\_visitor* operator[](CallPolicies const& policies) const;
};
.. @ignore()
``call`` requirements
~~~~~~~~~~~~~~~~~~~~~
* ``ParameterSpecs`` is an `MPL sequence`_ where each element
except the first models |ParameterSpec|. The first element
is the result type of ``c(…)``.
* ``Class`` must support these expressions, where ``c`` is an
instance of ``Class``:
=================== ==================== =======================================
Expression Return type Requirements
=================== ==================== =======================================
``c(a0, …, aN)`` Convertible to ``R`` ``a0``\ …\ ``aN`` are tagged arguments.
=================== ==================== =======================================
For every ``N`` in ``[U,V]``, where ``[U,V]`` is the **arity range** of ``ParameterSpecs``.
``template <class CallPolicies> operator[](CallPolicies const&)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns a ``def_visitor`` equivalent to ``*this``, except that it
uses CallPolicies when creating the binding.
Example
~~~~~~~
.. parsed-literal::
#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)
{
*… use args …*
}
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(*module name*)
{
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)>
>()
);
}
.. @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'
)
------------------------------------------------------------------------------
class template ``function``
---------------------------
Defines a named parameter enabled member function.
.. parsed-literal::
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);
};
.. @ignore()
``function`` requirements
~~~~~~~~~~~~~~~~~~~~~~~~~
* ``ParameterSpecs`` is an `MPL sequence`_ where each element
except the first models |ParameterSpec|. The first element
is the result type of ``c.f(…)``, where ``f`` is the member
function.
* An instance of ``Fwd`` must support this expression:
============================================ ==================== =================================================
Expression Return type Requirements
============================================ ==================== =================================================
``fwd(boost::type<R>(), self, a0, …, aN)`` Convertible to ``R`` ``self`` is a reference to the object on which
the function should be invoked. ``a0``\ …\ ``aN``
are tagged arguments.
============================================ ==================== =================================================
For every ``N`` in ``[U,V]``, where ``[U,V]`` is the **arity range** of ``ParameterSpecs``.
Example
~~~~~~~
This example exports a member function ``f(int x, int y = …)`` to Python. The
sequence of |ParameterSpec|'s ``mpl::vector2<tag::x(int), tag::y*(int)>`` has
an **arity range** of [2,2], so we only need one forwarding overload.
.. parsed-literal::
#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))
)
{
*…*
}
};
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(*module name*)
{
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)>
>()
);
}
.. @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'
)
------------------------------------------------------------------------------
function template ``def``
-------------------------
Defines a named parameter enabled free function in the current Python scope.
.. parsed-literal::
template <class Fwd, class ParameterSpecs>
void def(char const* name);
.. @ignore()
``def`` requirements
~~~~~~~~~~~~~~~~~~~~
* ``ParameterSpecs`` is an `MPL sequence`_ where each element
except the first models |ParameterSpec|. The first element
is the result type of ``f(…)``, where ``f`` is the function.
* An instance of ``Fwd`` must support this expression:
====================================== ==================== =======================================
Expression Return type Requirements
====================================== ==================== =======================================
``fwd(boost::type<R>(), a0, …, aN)`` Convertible to ``R`` ``a0``\ …\ ``aN`` are tagged arguments.
====================================== ==================== =======================================
For every ``N`` in ``[U,V]``, where ``[U,V]`` is the **arity range** of ``ParameterSpecs``.
Example
~~~~~~~
This example exports a function ``f(int x, int y = …)`` to Python. The
sequence of |ParameterSpec|'s ``mpl::vector2<tag::x(int), tag::y*(int)>`` has
an **arity range** of [2,2], so we only need one forwarding overload.
.. parsed-literal::
BOOST_PARAMETER_FUNCTION((void), f, tag,
(required (x, \*))
(optional (y, \*, 1))
)
{
*…*
}
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");
}
.. @ignore()
.. again, the undefined ``fwd`` identifier.
Portability
-----------
The Boost.Parameter Python binding library requires *partial template
specialization*.