mirror of
https://github.com/boostorg/parameter.git
synced 2026-01-20 16:52:13 +00:00
751 lines
32 KiB
HTML
751 lines
32 KiB
HTML
<?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.5: http://docutils.sourceforge.net/" />
|
|
<title>The Boost Parameter Library Python Binding Documentation</title>
|
|
<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>
|
|
|
|
<p><a class="reference" href="../../../../index.htm"><img alt="Boost" src="../../../../boost.png" /></a></p>
|
|
<table class="docutils field-list" frame="void" rules="none">
|
|
<col class="field-name" />
|
|
<col class="field-body" />
|
|
<tbody valign="top">
|
|
<tr class="field"><th class="field-name">Authors:</th><td class="field-body">Daniel Wallin</td>
|
|
</tr>
|
|
<tr class="field"><th class="field-name">Contact:</th><td class="field-body"><a class="reference" href="mailto:dalwan01@student.umu.se">dalwan01@student.umu.se</a></td>
|
|
</tr>
|
|
<tr class="field"><th class="field-name">organization:</th><td class="field-body"><a class="reference" href="http://www.boost-consulting.com">Boost Consulting</a></td>
|
|
</tr>
|
|
<tr class="field"><th class="field-name">date:</th><td class="field-body">$Date$</td>
|
|
</tr>
|
|
<tr class="field"><th class="field-name">copyright:</th><td class="field-body">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" href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="contents topic">
|
|
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
|
|
<ul class="simple">
|
|
<li><a class="reference" href="#introduction" id="id7" name="id7">Introduction</a></li>
|
|
<li><a class="reference" href="#tutorial" id="id8" name="id8">Tutorial</a></li>
|
|
<li><a class="reference" href="#concept-keywordsspec" id="id9" name="id9">concept <span class="concept">KeywordsSpec</span></a></li>
|
|
<li><a class="reference" href="#special-keywords" id="id10" name="id10"><em>special</em> keywords</a></li>
|
|
<li><a class="reference" href="#class-template-init" id="id11" name="id11">class template <tt class="docutils literal"><span class="pre">init</span></tt></a></li>
|
|
<li><a class="reference" href="#class-template-call" id="id12" name="id12">class template <tt class="docutils literal"><span class="pre">call</span></tt></a></li>
|
|
<li><a class="reference" href="#class-template-function" id="id13" name="id13">class template <tt class="docutils literal"><span class="pre">function</span></tt></a></li>
|
|
<li><a class="reference" href="#function-template-def" id="id14" name="id14">function template <tt class="docutils literal"><span class="pre">def</span></tt></a></li>
|
|
<li><a class="reference" href="#portability" id="id15" name="id15">Portability</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id7" id="introduction" name="introduction">Introduction</a></h1>
|
|
<p><tt class="docutils literal"><span class="pre">boost/parameter/python.hpp</span></tt> introduces a group of <a class="reference" href="../../../python/doc/v2/def_visitor.html">def_visitors</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>
|
|
<p>The keyword tags are specified as an <a class="reference" href="../../../mpl/doc/refmanual/sequences.html">MPL Sequence</a>, using the
|
|
pointer qualifications described in <a class="reference" href="#concept-keywordsspec"><span class="concept">KeywordsSpec</span></a> below. The
|
|
signature is also specifid as an <a class="reference" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> of parameter
|
|
types. 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">
|
|
<h1><a class="toc-backref" href="#id8" id="tutorial" name="tutorial">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" 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>…</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" href="../../../python/doc/v2/def_visitor.html">def_visitor</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.</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" 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 three parameters. The first one is the class
|
|
with forwarding overloads that we defined earlier. The second one is
|
|
an <a class="reference" href="../../../mpl/doc/refmanual/sequences.html">MPL Sequence</a> with the keyword tag types for the function. The
|
|
pointer syntax means that the parameter is optional, so in this case
|
|
<tt class="docutils literal"><span class="pre">width</span></tt> and <tt class="docutils literal"><span class="pre">height</span></tt> are optional parameters. The third parameter
|
|
is an <a class="reference" href="../../../mpl/doc/refmanual/sequences.html">MPL Sequence</a> with the desired function signature. The return type comes first, and
|
|
then the parameter types:</p>
|
|
<pre class="literal-block">
|
|
mpl::vector<void, std::string, unsigned, unsigned>
|
|
<em>return type</em> <em>title</em> <em>width</em> <em>height</em>
|
|
</pre>
|
|
<!-- @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">
|
|
<h1><a class="toc-backref" href="#id9" id="concept-keywordsspec" name="concept-keywordsspec">concept <span class="concept">KeywordsSpec</span></a></h1>
|
|
<p>A <span class="concept">KeywordsSpec</span> is an <a class="reference" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element is either:</p>
|
|
<ul class="simple">
|
|
<li>A <em>required</em> keyword of the form <tt class="docutils literal"><span class="pre">K</span></tt></li>
|
|
<li><strong>or</strong>, an <em>optional</em> keyword of the form <tt class="docutils literal"><span class="pre">K*</span></tt></li>
|
|
<li><strong>or</strong>, a <em>special</em> keyword of the form <tt class="docutils literal"><span class="pre">K**</span></tt></li>
|
|
</ul>
|
|
<p>where <tt class="docutils literal"><span class="pre">K</span></tt> is a keyword tag type, as used in a specialization
|
|
of boost::parameter::<a class="reference" href="../../../parameter/doc/html/reference.html#keyword">keyword</a>.</p>
|
|
<p>The <strong>arity range</strong> of a <span class="concept">KeywordsSpec</span> 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>
|
|
<!-- @ignore() -->
|
|
<p>For example, the <strong>arity range</strong> of <tt class="docutils literal"><span class="pre">mpl::vector2<x,y></span></tt> is [2,2], the <strong>arity range</strong> of
|
|
<tt class="docutils literal"><span class="pre">mpl::vector2<x,y*></span></tt> is [2,2] and the <strong>arity range</strong> of <tt class="docutils literal"><span class="pre">mpl::vector2<x,y**></span></tt> is [1,2].</p>
|
|
<!-- Don't optional keywords affect the arity range? -->
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id10" id="special-keywords" name="special-keywords"><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. An <a class="reference" href="index.html#dispatching-based-on-the-presence-of-a-default">example</a> of this is given in the Boost.Parameter
|
|
docs. The example uses a different technique, but could also have been written like this:</p>
|
|
<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() -->
|
|
<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. 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 <tt class="docutils literal"><span class="pre">2^N</span></tt>, 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">
|
|
<h1><a class="toc-backref" href="#id11" id="class-template-init" name="class-template-init">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 Keywords, class Signature>
|
|
struct init : python::def_visitor<init<Keywords, Signature> >
|
|
{
|
|
template <class Class>
|
|
void def(Class& class_);
|
|
};
|
|
</pre>
|
|
<!-- @ignore() -->
|
|
<div class="section">
|
|
<h2><a id="init-requirements" name="init-requirements"><tt class="docutils literal"><span class="pre">init</span></tt> requirements</a></h2>
|
|
<ul>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">Keywords</span></tt> is a model of <span class="concept">KeywordsSpec</span>.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">Signature</span></tt> is an MPL sequence of parameter types,
|
|
in the order dictated by <tt class="docutils literal"><span class="pre">Keywords</span></tt>.</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">Keywords</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>
|
|
<!-- Limit the width of these table cells. Some rst backend -->
|
|
<!-- processors actually produce different results depending on the -->
|
|
<!-- distribution of width. -->
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="id3" name="id3">Example</a></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">
|
|
<h1><a class="toc-backref" href="#id12" id="class-template-call" name="class-template-call">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 Keywords, class Signature>
|
|
struct call : python::def_visitor<call<Keywords, Signature> >
|
|
{
|
|
template <class Class>
|
|
void def(Class& class_);
|
|
};
|
|
</pre>
|
|
<!-- @ignore() -->
|
|
<div class="section">
|
|
<h2><a id="call-requirements" name="call-requirements"><tt class="docutils literal"><span class="pre">call</span></tt> requirements</a></h2>
|
|
<ul>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">Keywords</span></tt> is a model of <span class="concept">KeywordsSpec</span>.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">Signature</span></tt> is an MPL sequence with the types of the keyword parameters,
|
|
in the order dictated by <tt class="docutils literal"><span class="pre">Keywords</span></tt>, and the return type prepended.</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">Keywords</span></tt>.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="id4" name="id4">Example</a></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">
|
|
<h1><a class="toc-backref" href="#id13" id="class-template-function" name="class-template-function">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 Keywords, class Signature>
|
|
struct function : python::def_visitor<function<Fwd, Keywords, Signature> >
|
|
{
|
|
template <class Class, class Options>
|
|
void def(Class& class_, char const* name, Options const& options);
|
|
};
|
|
</pre>
|
|
<!-- @ignore() -->
|
|
<div class="section">
|
|
<h2><a id="function-requirements" name="function-requirements"><tt class="docutils literal"><span class="pre">function</span></tt> requirements</a></h2>
|
|
<ul>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">Keywords</span></tt> is a model of <span class="concept">KeywordsSpec</span>.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">Signature</span></tt> is an MPL sequence with the types of the keyword parameters,
|
|
in the order dictated by <tt class="docutils literal"><span class="pre">Keywords</span></tt>, and the return type prepended.</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="40%" />
|
|
<col width="18%" />
|
|
<col width="42%" />
|
|
</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``…``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">Keywords</span></tt>.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="id5" name="id5">Example</a></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 <span class="concept">KeywordsSpec</span> <tt class="docutils literal"><span class="pre">mpl::vector2<tag::x,</span> <span class="pre">tag::y*></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">
|
|
<h1><a class="toc-backref" href="#id14" id="function-template-def" name="function-template-def">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 Keywords, class Signature>
|
|
void def(char const* name);
|
|
</pre>
|
|
<!-- @ignore() -->
|
|
<div class="section">
|
|
<h2><a id="def-requirements" name="def-requirements"><tt class="docutils literal"><span class="pre">def</span></tt> requirements</a></h2>
|
|
<ul>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">Keywords</span></tt> is a model of <span class="concept">KeywordsSpec</span>.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">Signature</span></tt> is an MPL sequence of parameters types,
|
|
in the order dictated by <tt class="docutils literal"><span class="pre">Keywords</span></tt>, with the return type
|
|
prepended.</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="40%" />
|
|
<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``…``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">Keywords</span></tt>.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="id6" name="id6">Example</a></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 <span class="concept">KeywordsSpec</span> <tt class="docutils literal"><span class="pre">mpl::vector2<tag::x,</span> <span class="pre">tag::y*></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, <a class="reference" href="tag::x(int">tag::x(int</a>), <a class="reference" href="tag::y*(int">tag::y*(int</a>)
|
|
>
|
|
>("f");
|
|
}
|
|
</pre>
|
|
<!-- @ignore() -->
|
|
<!-- again, the undefined ``fwd`` identifier. -->
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id15" id="portability" name="portability">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: 2006-07-26 14:14 UTC.
|
|
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|