python.rst

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 The Boost Parameter Library Python Binding Documentation 
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

:Authors:       Daniel Wallin
:Contact:       [e-mail]
:organization:  `Boost Consulting`_
:date:          $Date: 2008-03-22 17:45:55 -0400 (Sat, 22 Mar 2008) $

: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)

:abstract:      Makes it possible to bind Boost.Parameter-enabled
                functions, operators and constructors to Python.

|(logo)|__

.. |(logo)| image:: ../../../../boost.png
   :alt: Boost

__ ../../../../index.htm

.. _`Boost Consulting`: http://www.boost-consulting.com


.. role:: class
    :class: class

.. role:: concept
    :class: concept

.. role:: function
    :class: function

.. |ParameterSpec| replace:: :concept:`ParameterSpec`

.. contents::
    :depth: 1

Introduction
------------

``boost/parameter/python.hpp`` introduces a group of |def_visitors|_ that can
be used to easily expose Boost.Parameter-enabled member functions to Python with 
Boost.Python. It also provides a function template ``def()`` that can be used
to expose Boost.Parameter-enabled free functions.

.. |def_visitor| replace:: ``def_visitor``
.. |def_visitors| replace:: ``def_visitors``

.. _def_visitor: def_visitors_
.. _def_visitors: ../../../python/doc/v2/def_visitor.html

When binding a Boost.Parameter enabled function, the keyword tags
must be specified.  Additionally, because Boost.Parameter enabled
functions are templates, the desired function signature must be
specified.

..  The keyword tags are specified as an `MPL Sequence`_, using the
    pointer qualifications described in |ParameterSpec|_ below.  The
    signature is also specifid as an `MPL sequence`_ of parameter
    types. Additionally, ``boost::parameter::python::function`` and
    ``boost::parameter::python::def`` requires a class with forwarding
    overloads. We will take a closer look at how this is done in the
    tutorial section below.

The keyword tags and associated argument types are specified as an `MPL
Sequence`_, using the function type syntax described in |ParameterSpec|_
below. Additionally, ``boost::parameter::python::function`` and
``boost::parameter::python::def`` requires a class with forwarding overloads.
We will take a closer look at how this is done in the tutorial section below.

.. The last two sentences are terribly vague.  Which namespace is
.. ``function`` in?  Isn't the return type always needed?  What
.. else are we going to do other than pass these sequences to
.. function?

.. _`MPL Sequence`: ../../../mpl/doc/refmanual/sequences.html
.. _parameterspec: `concept ParameterSpec`_

Tutorial
--------

In this section we will outline the steps needed to bind a simple
Boost.Parameter-enabled member function to Python. Knowledge of the
Boost.Parameter macros_ are required to understand this section.

.. _macros: index.html

The class and member function we are interested in binding looks
like this:

.. parsed-literal::

  #include <boost/parameter/keyword.hpp>
  #include <boost/parameter/preprocessor.hpp>
  #include <boost/parameter/python.hpp>
  #include <boost/python.hpp>

  // First the keywords
  BOOST_PARAMETER_KEYWORD(tag, title)
  BOOST_PARAMETER_KEYWORD(tag, width)
  BOOST_PARAMETER_KEYWORD(tag, height)

  class window
  {
  public:
      BOOST_PARAMETER_MEMBER_FUNCTION(
        (void), open, tag,
        (required (title, (std::string)))
        (optional (width, (unsigned), 400)
                  (height, (unsigned), 400))
      )
      {
          *鈥