File: python.html

package info (click to toggle)
boost1.35 1.35.0-5
links: PTS
area: main
in suites: lenny
size: 203,856 kB
ctags: 337,867
sloc: cpp: 938,683; xml: 56,847; ansic: 41,589; python: 18,999; sh: 11,566; makefile: 664; perl: 494; yacc: 456; asm: 353; csh: 6
file content (787 lines) | stat: -rw-r--r-- 36,136 bytes
<?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>
<meta name="authors" content="Daniel Wallin" />
<meta name="organization" content="Boost Consulting" />
<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>
<body>
<div class="document" id="the-boost-parameter-library-python-binding-documentation">
<h1 class="title">The Boost Parameter Library Python Binding Documentation</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Authors:</th>
<td>Daniel Wallin</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference" href="mailto:dalwan01&#64;student.umu.se">dalwan01&#64;student.umu.se</a></td></tr>
<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-12-14</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Daniel Wallin
2005. Distributed under the Boost Software License,
Version 1.0. (See accompanying file LICENSE_1_0.txt
or copy at <a class="reference" 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" href="../../../../index.htm"><img alt="Boost" src="../../../../boost.png" /></a></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="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="#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
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" href="../../../mpl/doc/refmanual/sequences.html">MPL
Sequence</a>, using the function type syntax described in <a class="reference" 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">
<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 &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"><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"><tt class="docutils literal"><span class="pre">def_visitor</span></tt></a> that we'll instantiate
and pass to <tt class="docutils literal"><span class="pre">boost::python::class_::def()</span></tt>.</p>
<p>To use <tt class="docutils literal"><span class="pre">boost::parameter::python::function</span></tt> we first need to define
a class with forwarding overloads. This is needed because <tt class="docutils literal"><span class="pre">window::open()</span></tt>
is a function template, so we can't refer to it in any other way.</p>
<pre class="literal-block">
struct open_fwd
{
    template &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" 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" 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" href="../../../mpl/doc/refmanual/sequences.html">MPL Sequence</a> is the return type of the function, in this case <tt class="docutils literal"><span class="pre">void</span></tt>,
which is passed as the first argument to <tt class="docutils literal"><span class="pre">operator()</span></tt> in the forwarding
class.</p>
<!-- The
pointer syntax means that the parameter is optional, so in this case
``width`` and ``height`` are optional parameters. The third parameter
is an `MPL Sequence`_ with the desired function signature. The return type comes first, and
then the parameter types:

.. parsed-literal::

    mpl::vector<void,        std::string, unsigned, unsigned>
                *return type*  *title*        *width*     *height*

.. @ignore() -->
<p>That's it! This class can now be used in Python with the expected syntax:</p>
<pre class="literal-block">
&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">
<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>
<ul class="simple">
<li>A <em>required</em> keyword of the form <tt class="docutils literal"><span class="pre">Tag</span></tt></li>
<li><strong>or</strong>, an <em>optional</em> keyword of the form <tt class="docutils literal"><span class="pre">Tag*</span></tt></li>
<li><strong>or</strong>, a <em>special</em> keyword of the form <tt class="docutils literal"><span class="pre">Tag**</span></tt></li>
</ul>
<p>where <tt class="docutils literal"><span class="pre">Tag</span></tt> is a keyword tag type, as used in a specialization
of <a class="reference" 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" 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"><span class="pre">S</span></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"><span class="pre">[2,2]</span></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"><span class="pre">[2,2]</span></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"><span class="pre">[1,2]</span></tt>.</p>
</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. 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"><span class="pre">color</span></tt> is <tt class="docutils literal"><span class="pre">mpl::false_</span></tt>, a
type that is distinct from any color map that the user might supply.</p>
<p>When binding the case outlined above, the default type for <tt class="docutils literal"><span class="pre">color</span></tt> will not
be convertible to the parameter type. Therefore we need to tag the <tt class="docutils literal"><span class="pre">color</span></tt>
keyword as a <em>special</em> keyword. This is done by specifying the tag as
<tt class="docutils literal"><span class="pre">tag::color**</span></tt> when binding the function (see <a class="reference" 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="#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 &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">
<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">ParameterSpecs</span></tt> is an <a class="reference" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element is a
model of <span class="concept">ParameterSpec</span>.</p>
</li>
<li><p class="first">For every <tt class="docutils literal"><span class="pre">N</span></tt> in <tt class="docutils literal"><span class="pre">[U,V]</span></tt>, where <tt class="docutils literal"><span class="pre">[U,V]</span></tt> is the <strong>arity
range</strong> of <tt class="docutils literal"><span class="pre">ParameterSpecs</span></tt>, <tt class="docutils literal"><span class="pre">Class</span></tt> must support these
expressions:</p>
<table border="1" class="docutils">
<colgroup>
<col width="30%" />
<col width="17%" />
<col width="53%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head"><p class="first last">Expression</p>
</th>
<th class="head"><p class="first last">Return type</p>
</th>
<th class="head"><p class="first last">Requirements</p>
</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><p class="first last"><tt class="docutils literal"><span class="pre">Class(a0,</span> <span class="pre">…,</span> <span class="pre">aN)</span></tt></p>
</td>
<td><p class="first last">-</p>
</td>
<td><p class="first last"><tt class="docutils literal"><span class="pre">a0</span></tt>…<tt class="docutils literal"><span class="pre">aN</span></tt> are tagged arguments.</p>
</td>
</tr>
</tbody>
</table>
</li>
</ul>
</div>
<div class="section">
<h2><a id="template-class-callpolicies-operator-callpolicies-const" name="template-class-callpolicies-operator-callpolicies-const"><tt class="docutils literal"><span class="pre">template</span> <span class="pre">&lt;class</span> <span class="pre">CallPolicies&gt;</span> <span class="pre">operator[](CallPolicies</span> <span class="pre">const&amp;)</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="example" name="example">Example</a></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">
<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 &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">
<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">ParameterSpecs</span></tt> is an <a class="reference" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element
except the first models <span class="concept">ParameterSpec</span>. The first element
is the result type of <tt class="docutils literal"><span class="pre">c(…)</span></tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">Class</span></tt> must support these expressions, where <tt class="docutils literal"><span class="pre">c</span></tt> is an
instance of <tt class="docutils literal"><span class="pre">Class</span></tt>:</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="26%" />
<col width="50%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head"><p class="first last">Expression</p>
</th>
<th class="head"><p class="first last">Return type</p>
</th>
<th class="head"><p class="first last">Requirements</p>
</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><p class="first last"><tt class="docutils literal"><span class="pre">c(a0,</span> <span class="pre">…,</span> <span class="pre">aN)</span></tt></p>
</td>
<td><p class="first last">Convertible to <tt class="docutils literal"><span class="pre">R</span></tt></p>
</td>
<td><p class="first last"><tt class="docutils literal"><span class="pre">a0</span></tt>…<tt class="docutils literal"><span class="pre">aN</span></tt> are tagged arguments.</p>
</td>
</tr>
</tbody>
</table>
<p>For every <tt class="docutils literal"><span class="pre">N</span></tt> in <tt class="docutils literal"><span class="pre">[U,V]</span></tt>, where <tt class="docutils literal"><span class="pre">[U,V]</span></tt> is the <strong>arity range</strong> of <tt class="docutils literal"><span class="pre">ParameterSpecs</span></tt>.</p>
</li>
</ul>
</div>
<div class="section">
<h2><a id="id3" name="id3"><tt class="docutils literal"><span class="pre">template</span> <span class="pre">&lt;class</span> <span class="pre">CallPolicies&gt;</span> <span class="pre">operator[](CallPolicies</span> <span class="pre">const&amp;)</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="id4" name="id4">Example</a></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">
<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 &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">
<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">ParameterSpecs</span></tt> is an <a class="reference" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element
except the first models <span class="concept">ParameterSpec</span>. The first element
is the result type of <tt class="docutils literal"><span class="pre">c.f(…)</span></tt>, where <tt class="docutils literal"><span class="pre">f</span></tt> is the member
function.</p>
</li>
<li><p class="first">An instance of <tt class="docutils literal"><span class="pre">Fwd</span></tt> must support this expression:</p>
<table border="1" class="docutils">
<colgroup>
<col width="39%" />
<col width="18%" />
<col width="43%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head"><p class="first last">Expression</p>
</th>
<th class="head"><p class="first last">Return type</p>
</th>
<th class="head"><p class="first last">Requirements</p>
</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><p class="first last"><tt class="docutils literal"><span class="pre">fwd(boost::type&lt;R&gt;(),</span> <span class="pre">self,</span> <span class="pre">a0,</span> <span class="pre">…,</span> <span class="pre">aN)</span></tt></p>
</td>
<td><p class="first last">Convertible to <tt class="docutils literal"><span class="pre">R</span></tt></p>
</td>
<td><p class="first last"><tt class="docutils literal"><span class="pre">self</span></tt> is a reference to the object on which
the function should be invoked. <tt class="docutils literal"><span class="pre">a0</span></tt>…<tt class="docutils literal"><span class="pre">aN</span></tt>
are tagged arguments.</p>
</td>
</tr>
</tbody>
</table>
<p>For every <tt class="docutils literal"><span class="pre">N</span></tt> in <tt class="docutils literal"><span class="pre">[U,V]</span></tt>, where <tt class="docutils literal"><span class="pre">[U,V]</span></tt> is the <strong>arity range</strong> of <tt class="docutils literal"><span class="pre">ParameterSpecs</span></tt>.</p>
</li>
</ul>
</div>
<div class="section">
<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&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">
<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 &lt;class Fwd, class ParameterSpecs&gt;
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">ParameterSpecs</span></tt> is an <a class="reference" href="../../../mpl/doc/refmanual/sequences.html">MPL sequence</a> where each element
except the first models <span class="concept">ParameterSpec</span>. The first element
is the result type of <tt class="docutils literal"><span class="pre">f(…)</span></tt>, where <tt class="docutils literal"><span class="pre">f</span></tt> is the function.</p>
</li>
<li><p class="first">An instance of <tt class="docutils literal"><span class="pre">Fwd</span></tt> must support this expression:</p>
<table border="1" class="docutils">
<colgroup>
<col width="39%" />
<col width="21%" />
<col width="40%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head"><p class="first last">Expression</p>
</th>
<th class="head"><p class="first last">Return type</p>
</th>
<th class="head"><p class="first last">Requirements</p>
</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><p class="first last"><tt class="docutils literal"><span class="pre">fwd(boost::type&lt;R&gt;(),</span> <span class="pre">a0,</span> <span class="pre">…,</span> <span class="pre">aN)</span></tt></p>
</td>
<td><p class="first last">Convertible to <tt class="docutils literal"><span class="pre">R</span></tt></p>
</td>
<td><p class="first last"><tt class="docutils literal"><span class="pre">a0</span></tt>…<tt class="docutils literal"><span class="pre">aN</span></tt> are tagged arguments.</p>
</td>
</tr>
</tbody>
</table>
<p>For every <tt class="docutils literal"><span class="pre">N</span></tt> in <tt class="docutils literal"><span class="pre">[U,V]</span></tt>, where <tt class="docutils literal"><span class="pre">[U,V]</span></tt> is the <strong>arity range</strong> of <tt class="docutils literal"><span class="pre">ParameterSpecs</span></tt>.</p>
</li>
</ul>
</div>
<div class="section">
<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&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">
<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 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>
</body>
</html>