The Boost Parameter Library Python Binding Documentation

Authors:	Daniel Wallin
Contact:	dalwan01@student.umu.se
organization:	Boost Consulting
date:	$Date$
copyright:	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)

Contents

Introduction
concept KeywordsSpec
special keyword tags
class template init
class template call
class template function
function template def
Portability

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.

To bind 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 using the syntax described in KeywordsSpec below, and the signature as an MPL sequence of parameter types. Additional data may be needed in the signature sequence by specific binding utilities. For example, function requires the return type to be part of the signature sequence.

concept KeywordsSpec

A KeywordsSpec is an MPL sequence where each element is either:

A required keyword of the form K
or, an optional keyword of the form K*
or, a special keyword of the form K**

where K is a keyword tag type.

The arity range of a KeywordsSpec is defined as:

[ mpl::size<S> - number of special keyword tags in S , mpl::size<S> ]

For example, the arity range of mpl::vector2<x,y> is [2,2], the arity range of mpl::vector2<x,y*> is [2,2] and the arity range of mpl::vector2<x,y**> is [1,2].

special keyword tags

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 example of this is given in the Boost.Parameter docs. The example uses a different technique, but could also have been written like this:

template <class ArgumentPack>
void dfs_dispatch(ArgumentPack& args, mpl::false_)
{
    …compute and use default color map…
}

template <class ArgumentPack, class ColorMap>
void dfs_dispatch(ArgumentPack& args, ColorMap colormap)
{
    …use colormap…
}

template <class ArgumentPack>
void depth_first_search(ArgumentPack& args)
{
    core::dfs_dispatch(args, args[color | mpl::false_());
}

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. By doing this we tell the binding functions that it needs to generate two overloads, one with the color parameter present and one without. If we would have had two special keywords, four overloads would need to be generated. The number of generated overloads is equal to 2^N, where N is the number of special keywords.

class template `init`

Defines a named parameter enabled constructor.

template <class Keywords, class Signature>
struct init : python::def_visitor<init<Keywords, Signature> >
{
    template <class Class> 
    void def(Class& class_);
};

`init` requirements

Keywords is a model of KeywordsSpec.
Signature is an MPL sequence with the types of the keyword , in the order dictated by Keywords.
Class must support these expressions:

Expression

Return type

Requirements

Class(a0, ..., aN)

-

a0..aN are tagged arguments.

For every N in [U,V], where [U,V] is the arity range of Keywords.

Expression	Return type	Requirements
`Class(a0, ..., aN)`	-	`a0`..`aN` are tagged arguments.

Example

struct base { /* ... */ };

class X : base
{
public:
    BOOST_PARAMETER_CONSTRUCTOR(X, (base),
        (required (x, *))
        (optional (y, *))
    )
};

BOOST_PYTHON_MODULE(..)
{
    class_<X>("X")
        .def(
            init<
              , mpl::vector2<tag::x, tag::y*>
              , mpl::vector2<int, int>
            >()
        );
}

class template `call`

Defines a __call__ operator, mapped to operator() in C++.

template <class Keywords, class Signature>
struct call : python::def_visitor<call<Keywords, Signature> >
{
    template <class Class> 
    void def(Class& class_);
};

`call` requirements

Keywords is a model of KeywordsSpec.
Signature is an MPL sequence with the types of the keyword parameters, in the order dictated by Keywords, and the return type prepended.
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 Keywords.

Expression	Return type	Requirements
`c(a0, ..., aN)`	Convertible to `R`	`a0`..`aN` are tagged arguments.

Example

typedef parameter::parameters<
    parameter::required<tag::x>
  , parameter::optional<tag::y>
> call_parameters;

class X
{
public:
    template <class Args>
    int call_impl(Args const& 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(..)
{
    class_<X>("X")
        .def("f",
            call<
              , mpl::vector2<tag::x, tag::y*>
              , mpl::vector3<int, int, int>
            >()
        );
}

class template `function`

Defines a named parameter enabled member function.

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);
};

`function` requirements

Keywords is a model of KeywordsSpec.
Signature is an MPL sequence with the types of the keyword parameters, in the order dictated by Keywords, and the return type prepended.

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 Keywords.

Example

This example exports a member function f(int x, int y = ..) to Python. The KeywordsSpec mpl::vector2<tag::x, tag::y*> has an arity range of [2,2], so we only need one forwarding overload.

class X
{
public:
    BOOST_PARAMETER_MEMBER_FUNCTION((void), f, tag,
        (required (x, *))
        (optional (y, *))
    )
    {
        /* .. */
    }
};

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(..)
{
    class_<X>("X")
        .def("f",
            function<
                fwd
              , mpl::vector2<tag::x, tag::y*>
              , mpl::vector3<void, int, int>
            >()
        );
}

function template `def`

Defines a named parameter enabled free function in the current Python scope.

template <class Fwd, class Keywords, class Signature>
void def(char const* name);

`def` requirements

Keywords is a model of KeywordsSpec.
Signature is an MPL sequence with the types of the keyword parameters, in the order dictated by Keywords, and the return type prepended.
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 Keywords.

Expression	Return type	Requirements
`fwd(boost::type<R>(), a0, ..., aN)`	Convertible to `R`	`a0`..`aN` are tagged arguments.

Example

This example exports a function f(int x, int y = ..) to Python. The KeywordsSpec mpl::vector2<tag::x, tag::y*> has an arity range of [2,2], so we only need one forwarding overload.

BOOST_PARAMETER_FUNCTION((void), f, tag,
    (required (x, *))
    (optional (y, *))
)
{
    /* .. */
}

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<
        fwd
      , mpl::vector2<tag::x, tag::y*>
      , mpl::vector3<void, int, int>
    >("f");
}

Portability

The Boost.Parameter Python binding library requires partial template specialization.