|
From: <rom...@us...> - 2006-10-15 19:22:07
|
Revision: 661
http://svn.sourceforge.net/pygccxml/?rev=661&view=rev
Author: roman_yakovenko
Date: 2006-10-15 12:21:55 -0700 (Sun, 15 Oct 2006)
Log Message:
-----------
adding functions documentation
Modified Paths:
--------------
pyplusplus_dev/docs/documentation/containers.rest
pyplusplus_dev/docs/documentation/functions/www_configuration.py
Added Paths:
-----------
pyplusplus_dev/docs/documentation/functions/default_args.rest
pyplusplus_dev/docs/documentation/functions/overloading.rest
Modified: pyplusplus_dev/docs/documentation/containers.rest
===================================================================
--- pyplusplus_dev/docs/documentation/containers.rest 2006-10-12 14:59:28 UTC (rev 660)
+++ pyplusplus_dev/docs/documentation/containers.rest 2006-10-15 19:21:55 UTC (rev 661)
@@ -51,10 +51,12 @@
.. _`documentation` : ./indexing_suite_v2.html
.. _`post` : http://mail.python.org/pipermail/c++-sig/2003-October/005802.html
-
-------------------------
-Py++ and indexing suites
-------------------------
+
+
+------------------------
+Py++ and indexing suites
+------------------------
+
`Py++`_ implements support for both indexing suites. More over, you can
freely mix indexing suites. For example you can expose ``std::vector<int>`` using
`Boost.Python`_ built-in indexing suite and ``std::map< int, std::string>`` using
Added: pyplusplus_dev/docs/documentation/functions/default_args.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/default_args.rest (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/default_args.rest 2006-10-15 19:21:55 UTC (rev 661)
@@ -0,0 +1,128 @@
+=================
+Default arguments
+=================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+There is more than one way to export function with default arguments. Before we
+proceed, please take a look on next class:
+
+.. code-block:: C++
+
+ struct X
+ {
+ bool f(int a=12)
+ {
+ return true;
+ }
+ };
+
+-------------------
+Do nothing approach
+-------------------
+
+By default `Py++`_ exposes function with its default arguments.
+
+.. code-block:: C++
+
+ namespace bp = boost::python;
+
+ BOOST_PYTHON_MODULE(pyplusplus){
+ bp::class_< X >( "X" )
+ .def(
+ "f"
+ , &::X::f
+ , ( bp::arg("a")=(int)(12) ) );
+ }
+
+This approach brings another additional value: keyword arguments. Your users
+will be able to call function ``f`` like this:
+
+.. code-block:: Python
+
+ x = X()
+ x.f( a=13 )
+
+----------------------------
+Default values, using macros
+----------------------------
+
+``BOOST_PYTHON_FUNCTION_OVERLOADS`` and ``BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS``
+macros help to deal with default values. You can turn ``use_overload_macro``
+to ``True`` as shown in `overloading`_ document.
+
+.. _`overloading` : ./overloading.html
+
+--------------------------
+Registration order problem
+--------------------------
+
+There are different trades-off between these approaches. In general you should
+use the first one, untill you have "registration order" problem:
+
+.. code-block:: C++
+
+ struct S1;
+ struct S2;
+
+ struct S1{
+ void do_smth( S2* s2=0 );
+ };
+
+ struct S2{
+ void do_smth( S1 s1=S1() );
+ };
+
+ BOOST_PYTHON_MODULE( ... ){
+ using namespace boost::python;
+
+ class_< S2 >( "S2" )
+ .def( "do_smth", &S2::do_smth, ( arg("s1")=S1() ) );
+
+ class_< S1 >( "S1" )
+ .def( "do_smth", &S1::do_smth, ( arg("s2")=object() ) );
+
+ }
+
+These module could not be loaded, because the expression ``arg("s1")=S1()``
+requieres ``S1`` struct to be registered. `GCC-XML`_ reports default arguments
+as strings. `Py++`_ doesn't have enough information to generate code with the
+right class registration order.
+
+
+Unfortunatelly these macros have some limitations:
+
+1. The overloaded functions must have a common sequence of initial arguments.
+
+2. You will not be able to override virtual functions in `Python`_.
+
+3. You will not be able to use "named" arguments.
+
+4. You will not be able to set the functions documentation.
+
+Nevertheless these limitations the macros becomes very useful when you have
+"registration order" problem with default arguments.
+
+
+
+
+`Py++`_ needs your help to generate right code:
+
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+ Local Variables:
+ mode: indented-text
+ indent-tabs-mode: nil
+ sentence-end-double-space: t
+ fill-column: 70
+ End:
Added: pyplusplus_dev/docs/documentation/functions/overloading.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/overloading.rest (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/overloading.rest 2006-10-15 19:21:55 UTC (rev 661)
@@ -0,0 +1,179 @@
+===========
+Overloading
+===========
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+Things get a little bit complex, when you should export overloaded functions.
+In general the solution is to explicitly say to compiler what function you
+want to export, by specifying its type. Before we proceed, please take a look
+on next class:
+
+.. code-block:: C++
+
+ struct X
+ {
+ bool f(int a)
+ {
+ return true;
+ }
+
+ bool f(int a, double b)
+ {
+ return true;
+ }
+
+ bool f(int a, double b, char c)
+ {
+ return true;
+ }
+ };
+
+This class has been taken from `Boost.Python`_ `tutorials`__.
+
+.. __ : http://boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.overloading
+
+There are few approaches, which you can use in order to exort the functions.
+
+-------------------
+Do nothing approach
+-------------------
+
+I am sure you will like "do nothing" approach. `Py++`_ recognize that you want to
+export an overloaded function and will generate the right code:
+
+.. code-block:: C++
+
+ namespace bp = boost::python;
+
+ BOOST_PYTHON_MODULE(pyplusplus){
+ bp::class_< X >( "X" )
+ .def(
+ "f"
+ , (bool ( ::X::* )( int ) )( &::X::f )
+ , ( bp::arg("a") ) )
+ .def(
+ "f"
+ , (bool ( ::X::* )( int,double ) )( &::X::f )
+ , ( bp::arg("a"), bp::arg("b") ) )
+ .def(
+ "f"
+ , (bool ( ::X::* )( int,double,char ) )( &::X::f )
+ , ( bp::arg("a"), bp::arg("b"), bp::arg("c") ) );
+ }
+
+From my experience, this approach works pretty well and in most cases the only
+customization you should do on exported function is to setup right call policies.
+
+--------------------------------
+"create_with_signature" approach
+--------------------------------
+
+Well, while previous approach is very attractive it does not work in all cases
+and have a weakness.
+
+Overloaded template function
+----------------------------
+
+I am sure you already know next facts, but still I want to remind them:
+
+1. `GCC-XML`_ doesn't report about uninstantiated templates
+
+2. `Boost.Python`_ is able to export only template instantiation
+
+It is very important to understand the first fact. Lets take a look on next source
+code:
+
+.. code-block:: C++
+
+ struct Y{
+
+ void do_smth( int );
+
+ template< class T>
+ void do_smth( T t );
+
+ };
+
+If you didn't instantiate( use ) ``do_smth`` member function, than `GCC-XML`_
+will not report it. As a result, `Py++`_ will not be aware of the fact that
+``do_smth`` is an overloaded function. To make the long story short the generated
+code will not compile. You have to instruct `Py++`_ to generate code, which
+contains function type:
+
+.. code-block:: Python
+
+ from pyplusplus import module_builder
+
+ mb = module_builder.module_builder_t( ... )
+ y = mb.class_( 'Y' )
+ y.member_function( 'do_smth' ).create_with_signature = True
+ #------------------------------^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Every `Py++`_ class, which describes C++ function\\operator has ``create_with_signature``
+property. You have to set it to ``True``. Default value of the property is
+computed. If the exported function is overloaded, then its value is ``True``
+otherwise it will be ``False``.
+
+Do nothing approach weakness
+----------------------------
+
+Code modification - the weakness of the "do nothing" approach. We live in the
+dynamic world. You can create bindings for a project, but a month letter, the
+project developers will add a new function to the exported class. Lets assume
+that the function will introduce overloading. If ``create_with_signature`` has
+``False`` as a value, than the previously generated code will not compile. My
+advise to you: explicitly set ``create_with_signature`` to ``True``. It will
+save your time in future.
+
+------------------------
+Overloading using macros
+------------------------
+
+`Boost.Python`_ provides two macros, which help you to deal with overloaded
+functions:
+
+* ``BOOST_PYTHON_FUNCTION_OVERLOADS``
+
+* ``BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS``
+
+`Boost.Python`_ tutorials contains an `explanation`_ about this macros.
+
+.. _`explanation` : http://boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.auto_overloading
+
+You can instruct `Py++`_ to generate code, which will use the macros:
+
+.. code-block:: Python
+
+ import module_builder
+
+ mb = module_builder.module_builder_t( ... )
+ x = mb.class_( "X" )
+ x.member_functions( "f" ).use_overload_macro = True
+ #-------------------------^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Member and free functions declaration classes have ``use_overload_macro`` property.
+The default value of the property is ``False``.
+
+You don't really have to use the macros, unless you have "registration order"
+problem. The problem and work around described in `default arguments`_ document.
+
+.. _`default arguments` : ./default_args.html
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+ Local Variables:
+ mode: indented-text
+ indent-tabs-mode: nil
+ sentence-end-double-space: t
+ fill-column: 70
+ End:
Modified: pyplusplus_dev/docs/documentation/functions/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/functions/www_configuration.py 2006-10-12 14:59:28 UTC (rev 660)
+++ pyplusplus_dev/docs/documentation/functions/www_configuration.py 2006-10-15 19:21:55 UTC (rev 661)
@@ -2,4 +2,5 @@
#main_html_file = 'index.html'
names = { 'call_policies' : 'call policies'
+ , 'default_args' : 'default arguments'
}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
