|
|
|
|
@@ -7,7 +7,7 @@
|
|
|
|
|
<title>The Boost Parameter Library Python Binding Documentation</title>
|
|
|
|
|
<meta name="authors" content="Daniel Wallin" />
|
|
|
|
|
<meta name="organization" content="Boost Consulting" />
|
|
|
|
|
<meta name="date" content="2006-09-21" />
|
|
|
|
|
<meta name="date" content="2006-12-14" />
|
|
|
|
|
<meta name="copyright" content="Copyright David Abrahams, Daniel Wallin 2005. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)" />
|
|
|
|
|
<link rel="stylesheet" href="rst.css" type="text/css" />
|
|
|
|
|
</head>
|
|
|
|
|
@@ -25,7 +25,7 @@
|
|
|
|
|
<tr><th class="docinfo-name">Organization:</th>
|
|
|
|
|
<td><a class="first last reference" href="http://www.boost-consulting.com">Boost Consulting</a></td></tr>
|
|
|
|
|
<tr><th class="docinfo-name">Date:</th>
|
|
|
|
|
<td>2006-09-21</td></tr>
|
|
|
|
|
<td>2006-12-14</td></tr>
|
|
|
|
|
<tr><th class="docinfo-name">Copyright:</th>
|
|
|
|
|
<td>Copyright David Abrahams, Daniel Wallin
|
|
|
|
|
2005. Distributed under the Boost Software License,
|
|
|
|
|
@@ -42,19 +42,19 @@ functions, operators and constructors to Python.</p>
|
|
|
|
|
<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="id8" name="id8">Introduction</a></li>
|
|
|
|
|
<li><a class="reference" href="#tutorial" id="id9" name="id9">Tutorial</a></li>
|
|
|
|
|
<li><a class="reference" href="#concept-parameterspec" id="id10" name="id10">concept <span class="concept">ParameterSpec</span></a></li>
|
|
|
|
|
<li><a class="reference" href="#special-keywords" id="id11" name="id11"><em>special</em> keywords</a></li>
|
|
|
|
|
<li><a class="reference" href="#class-template-init" id="id12" name="id12">class template <tt class="docutils literal"><span class="pre">init</span></tt></a></li>
|
|
|
|
|
<li><a class="reference" href="#class-template-call" id="id13" name="id13">class template <tt class="docutils literal"><span class="pre">call</span></tt></a></li>
|
|
|
|
|
<li><a class="reference" href="#class-template-function" id="id14" name="id14">class template <tt class="docutils literal"><span class="pre">function</span></tt></a></li>
|
|
|
|
|
<li><a class="reference" href="#function-template-def" id="id15" name="id15">function template <tt class="docutils literal"><span class="pre">def</span></tt></a></li>
|
|
|
|
|
<li><a class="reference" href="#portability" id="id16" name="id16">Portability</a></li>
|
|
|
|
|
<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-parameterspec" id="id9" name="id9">concept <span class="concept">ParameterSpec</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="#id8" id="introduction" name="introduction">Introduction</a></h1>
|
|
|
|
|
<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"><tt class="docutils literal"><span class="pre">def_visitors</span></tt></a> that can
|
|
|
|
|
be used to easily expose Boost.Parameter-enabled member functions to Python with
|
|
|
|
|
Boost.Python. It also provides a function template <tt class="docutils literal"><span class="pre">def()</span></tt> that can be used
|
|
|
|
|
@@ -81,7 +81,7 @@ We will take a closer look at how this is done in the tutorial section below.</p
|
|
|
|
|
<!-- function? -->
|
|
|
|
|
</div>
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h1><a class="toc-backref" href="#id9" id="tutorial" name="tutorial">Tutorial</a></h1>
|
|
|
|
|
<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>
|
|
|
|
|
@@ -124,7 +124,8 @@ Python we use the binding utility <tt class="docutils literal"><span class="pre"
|
|
|
|
|
<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"><tt class="docutils literal"><span class="pre">def_visitor</span></tt></a> that we'll instantiate
|
|
|
|
|
and pass to <tt class="docutils literal"><span class="pre">boost::python::class_::def()</span></tt>.</p>
|
|
|
|
|
<p>To use <tt class="docutils literal"><span class="pre">boost::parameter::python::function</span></tt> we first need to define
|
|
|
|
|
a class with forwarding overloads.</p>
|
|
|
|
|
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
|
|
|
|
|
{
|
|
|
|
|
@@ -188,7 +189,9 @@ forwarding overloads that we defined earlier. The second one is an <a class="ref
|
|
|
|
|
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" href="../../../mpl/doc/refmanual/sequences.html">MPL Sequence</a> is the return type of the function, in this case <tt class="docutils literal"><span class="pre">void</span></tt>.</p>
|
|
|
|
|
the <a class="reference" href="../../../mpl/doc/refmanual/sequences.html">MPL Sequence</a> is the return type of the function, in this case <tt class="docutils literal"><span class="pre">void</span></tt>,
|
|
|
|
|
which is passed as the first argument to <tt class="docutils literal"><span class="pre">operator()</span></tt> in the forwarding
|
|
|
|
|
class.</p>
|
|
|
|
|
<!-- The
|
|
|
|
|
pointer syntax means that the parameter is optional, so in this case
|
|
|
|
|
``width`` and ``height`` are optional parameters. The third parameter
|
|
|
|
|
@@ -240,7 +243,7 @@ types instead). -->
|
|
|
|
|
</div>
|
|
|
|
|
<hr class="docutils" />
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h1><a class="toc-backref" href="#id10" id="concept-parameterspec" name="concept-parameterspec">concept <span class="concept">ParameterSpec</span></a></h1>
|
|
|
|
|
<h1><a class="toc-backref" href="#id9" id="concept-parameterspec" name="concept-parameterspec">concept <span class="concept">ParameterSpec</span></a></h1>
|
|
|
|
|
<p>A <span class="concept">ParameterSpec</span> is a function type <tt class="docutils literal"><span class="pre">K(T)</span></tt> that describes both the keyword tag,
|
|
|
|
|
<tt class="docutils literal"><span class="pre">K</span></tt>, and the argument type, <tt class="docutils literal"><span class="pre">T</span></tt>, for a parameter.</p>
|
|
|
|
|
<p><tt class="docutils literal"><span class="pre">K</span></tt> is either:</p>
|
|
|
|
|
@@ -261,11 +264,12 @@ the <strong>arity range</strong> of <tt class="docutils literal"><span class="pr
|
|
|
|
|
<strong>arity range</strong> of <tt class="docutils literal"><span class="pre">mpl::vector2<x(int),y**(int)></span></tt> is <tt class="docutils literal"><span class="pre">[1,2]</span></tt>.</p>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h1><a class="toc-backref" href="#id11" id="special-keywords" name="special-keywords"><em>special</em> keywords</a></h1>
|
|
|
|
|
<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>
|
|
|
|
|
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
|
|
|
|
|
{
|
|
|
|
|
@@ -313,19 +317,21 @@ int main()
|
|
|
|
|
depth_first_search(params()(color = 0));
|
|
|
|
|
}''') -->
|
|
|
|
|
<!-- @build() -->
|
|
|
|
|
<!-- .. _example: index.html#dispatching-based-on-the-presence-of-a-default -->
|
|
|
|
|
<p>In the above example the type of the default for <tt class="docutils literal"><span class="pre">color</span></tt> is <tt class="docutils literal"><span class="pre">mpl::false_</span></tt>, a
|
|
|
|
|
type that is distinct from any color map that the user might supply.</p>
|
|
|
|
|
<p>When binding the case outlined above, the default type for <tt class="docutils literal"><span class="pre">color</span></tt> will not
|
|
|
|
|
be convertible to the parameter type. Therefore we need to tag the <tt class="docutils literal"><span class="pre">color</span></tt>
|
|
|
|
|
keyword as a <em>special</em> keyword. By doing this we tell the binding functions
|
|
|
|
|
that it needs to generate two overloads, one with the <tt class="docutils literal"><span class="pre">color</span></tt> parameter
|
|
|
|
|
present and one without. Had there been two <em>special</em> keywords, four
|
|
|
|
|
overloads would need to be generated. The number of generated overloads is
|
|
|
|
|
equal to 2<sup>N</sup>, where <tt class="docutils literal"><span class="pre">N</span></tt> is the number of <em>special</em> keywords.</p>
|
|
|
|
|
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" href="#concept-parameterspec">concept ParameterSpec</a> for
|
|
|
|
|
more details on the tagging). By doing this we tell the binding functions that
|
|
|
|
|
it needs to generate two overloads, one with the <tt class="docutils literal"><span class="pre">color</span></tt> parameter present
|
|
|
|
|
and one without. Had there been two <em>special</em> keywords, four overloads would
|
|
|
|
|
need to be generated. The number of generated overloads is equal to 2<sup>N</sup>, where <tt class="docutils literal"><span class="pre">N</span></tt> is the number of <em>special</em> keywords.</p>
|
|
|
|
|
</div>
|
|
|
|
|
<hr class="docutils" />
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h1><a class="toc-backref" href="#id12" id="class-template-init" name="class-template-init">class template <tt class="docutils literal"><span class="pre">init</span></tt></a></h1>
|
|
|
|
|
<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 ParameterSpecs>
|
|
|
|
|
@@ -348,7 +354,7 @@ model of <span class="concept">ParameterSpec</span>.</p>
|
|
|
|
|
<li><p class="first">For every <tt class="docutils literal"><span class="pre">N</span></tt> in <tt class="docutils literal"><span class="pre">[U,V]</span></tt>, where <tt class="docutils literal"><span class="pre">[U,V]</span></tt> is the <strong>arity
|
|
|
|
|
range</strong> of <tt class="docutils literal"><span class="pre">ParameterSpecs</span></tt>, <tt class="docutils literal"><span class="pre">Class</span></tt> must support these
|
|
|
|
|
expressions:</p>
|
|
|
|
|
<table border="1" class="docutils table">
|
|
|
|
|
<table border="1" class="docutils">
|
|
|
|
|
<colgroup>
|
|
|
|
|
<col width="30%" />
|
|
|
|
|
<col width="17%" />
|
|
|
|
|
@@ -382,7 +388,7 @@ expressions:</p>
|
|
|
|
|
uses CallPolicies when creating the binding.</p>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h2><a id="id3" name="id3">Example</a></h2>
|
|
|
|
|
<h2><a id="example" name="example">Example</a></h2>
|
|
|
|
|
<pre class="literal-block">
|
|
|
|
|
#include <boost/parameter/keyword.hpp>
|
|
|
|
|
#include <boost/parameter/preprocessor.hpp>
|
|
|
|
|
@@ -441,7 +447,7 @@ assert(args[y | 1] == 1);
|
|
|
|
|
</div>
|
|
|
|
|
<hr class="docutils" />
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h1><a class="toc-backref" href="#id13" id="class-template-call" name="class-template-call">class template <tt class="docutils literal"><span class="pre">call</span></tt></a></h1>
|
|
|
|
|
<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 ParameterSpecs>
|
|
|
|
|
@@ -464,7 +470,7 @@ is the result type of <tt class="docutils literal"><span class="pre">c(…)</spa
|
|
|
|
|
</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 table">
|
|
|
|
|
<table border="1" class="docutils">
|
|
|
|
|
<colgroup>
|
|
|
|
|
<col width="24%" />
|
|
|
|
|
<col width="26%" />
|
|
|
|
|
@@ -494,12 +500,12 @@ instance of <tt class="docutils literal"><span class="pre">Class</span></tt>:</p
|
|
|
|
|
</ul>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h2><a id="id4" name="id4"><tt class="docutils literal"><span class="pre">template</span> <span class="pre"><class</span> <span class="pre">CallPolicies></span> <span class="pre">operator[](CallPolicies</span> <span class="pre">const&)</span></tt></a></h2>
|
|
|
|
|
<h2><a id="id3" name="id3"><tt class="docutils literal"><span class="pre">template</span> <span class="pre"><class</span> <span class="pre">CallPolicies></span> <span class="pre">operator[](CallPolicies</span> <span class="pre">const&)</span></tt></a></h2>
|
|
|
|
|
<p>Returns a <tt class="docutils literal"><span class="pre">def_visitor</span></tt> equivalent to <tt class="docutils literal"><span class="pre">*this</span></tt>, except that it
|
|
|
|
|
uses CallPolicies when creating the binding.</p>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h2><a id="id5" name="id5">Example</a></h2>
|
|
|
|
|
<h2><a id="id4" name="id4">Example</a></h2>
|
|
|
|
|
<pre class="literal-block">
|
|
|
|
|
#include <boost/parameter/keyword.hpp>
|
|
|
|
|
#include <boost/parameter/preprocessor.hpp>
|
|
|
|
|
@@ -568,7 +574,7 @@ return 0;
|
|
|
|
|
</div>
|
|
|
|
|
<hr class="docutils" />
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h1><a class="toc-backref" href="#id14" id="class-template-function" name="class-template-function">class template <tt class="docutils literal"><span class="pre">function</span></tt></a></h1>
|
|
|
|
|
<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 ParameterSpecs>
|
|
|
|
|
@@ -588,7 +594,7 @@ is the result type of <tt class="docutils literal"><span class="pre">c.f(…)</s
|
|
|
|
|
function.</p>
|
|
|
|
|
</li>
|
|
|
|
|
<li><p class="first">An instance of <tt class="docutils literal"><span class="pre">Fwd</span></tt> must support this expression:</p>
|
|
|
|
|
<table border="1" class="docutils table">
|
|
|
|
|
<table border="1" class="docutils">
|
|
|
|
|
<colgroup>
|
|
|
|
|
<col width="39%" />
|
|
|
|
|
<col width="18%" />
|
|
|
|
|
@@ -620,7 +626,7 @@ are tagged arguments.</p>
|
|
|
|
|
</ul>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h2><a id="id6" name="id6">Example</a></h2>
|
|
|
|
|
<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
|
|
|
|
|
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>
|
|
|
|
|
@@ -684,7 +690,7 @@ assert(y == 1);
|
|
|
|
|
</div>
|
|
|
|
|
<hr class="docutils" />
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h1><a class="toc-backref" href="#id15" id="function-template-def" name="function-template-def">function template <tt class="docutils literal"><span class="pre">def</span></tt></a></h1>
|
|
|
|
|
<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 ParameterSpecs>
|
|
|
|
|
@@ -699,7 +705,7 @@ except the first models <span class="concept">ParameterSpec</span>. The first el
|
|
|
|
|
is the result type of <tt class="docutils literal"><span class="pre">f(…)</span></tt>, where <tt class="docutils literal"><span class="pre">f</span></tt> is the function.</p>
|
|
|
|
|
</li>
|
|
|
|
|
<li><p class="first">An instance of <tt class="docutils literal"><span class="pre">Fwd</span></tt> must support this expression:</p>
|
|
|
|
|
<table border="1" class="docutils table">
|
|
|
|
|
<table border="1" class="docutils">
|
|
|
|
|
<colgroup>
|
|
|
|
|
<col width="39%" />
|
|
|
|
|
<col width="21%" />
|
|
|
|
|
@@ -729,7 +735,7 @@ is the result type of <tt class="docutils literal"><span class="pre">f(…)</spa
|
|
|
|
|
</ul>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h2><a id="id7" name="id7">Example</a></h2>
|
|
|
|
|
<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
|
|
|
|
|
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>
|
|
|
|
|
@@ -766,14 +772,14 @@ BOOST_PYTHON_MODULE(…)
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="section">
|
|
|
|
|
<h1><a class="toc-backref" href="#id16" id="portability" name="portability">Portability</a></h1>
|
|
|
|
|
<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: 2007-01-03 17:02 UTC.
|
|
|
|
|
Generated on: 2007-01-03 16:40 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>
|
|
|
|
|
|