[pygccxml-commit] SF.net SVN: pygccxml: [784] pyplusplus_dev/docs/documentation/functions

[<rom...@us...>]

Revision: 784
          http://svn.sourceforge.net/pygccxml/?rev=784&view=rev
Author:   roman_yakovenko
Date:     2006-12-06 06:58:17 -0800 (Wed, 06 Dec 2006)

Log Message:
-----------
adding FT documentation

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/functions/transformation/
    pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest
    pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py

Added: pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest	2006-12-06 14:58:17 UTC (rev 784)
@@ -0,0 +1,101 @@
+=======================
+Function transformation
+=======================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+During the development of Python bindings for some C++ library, it might get 
+necessary to write custom wrapper code for a particular function in order to 
+make that function usable from `Python`_.
+
+An often mentioned example that demonstrates the problem is the ``get_size()`` 
+method of a fictitious image class:
+
+.. code-block:: C++
+
+  void get_size(int& width, int& height);
+
+This member function cannot be exposed with standard `Boost.Python`_ mechanisms.
+The main reasons for this is that ``int`` is immutable type in `Python`_. 
+An instance of immutable type could not be changed after construction. The only 
+way to expose this function to `Python`_ is to create small wrapper, which will 
+return a tuple. In `Python`_, the above function would instead be invoked like this:
+
+.. code-block:: Python
+
+  width, height = img.get_size()
+
+and the wrapper could look like this:
+
+.. code-block:: C++
+
+  boost::python::tuple get_size( const image_t& img ){
+      int width;
+      int height;
+      img.get_size( width, height );
+      return boost::python::make_tuple( width, height );
+  }
+  
+As you can see this function is simply invokes the original ``get_size()`` member 
+function and return the output values as a tuple.
+
+Unfortunately, C++ source code cannot describe the semantics of an argument so 
+there is no way for a code generator tool such as `Py++`_ to know whether an 
+argument that has a reference type is actually an output argument, an input 
+argument or an input/output argument. That's why the user will always have to 
+"enhance" the C++ code and tell the code generator tool about the missing 
+information. 
+
+Note: C++ fundamental types, enumerations and string are all mapped to `Python`_
+immutable types.
+
+Instead of forcing you to write the entire wrapper function, `Py++`_ allows you 
+to provide the semantics of an argument(s) and then it will take care of 
+producing the correct code:
+
+.. code-block:: Python
+
+   from pyplusplus import module_builder
+   from pyplusplus import function_transformers as FT
+   
+   mb = module_builder.module_builder_t( ... )
+   get_size = mb.mem_fun( 'image_t::get_size' )
+   get_size.add_transformation( FT.output(0), FT.output(1) )
+   #Next line has same effect
+   get_size.add_transformation( FT.output('width'), FT.output('height') )
+
+`Py++`_ will generate very similar code you just saw.
+
+-----------
+Terminology
+-----------
+
+* Immutable type 
+
+  An instance of this type could not be modified after construction
+
+* Function wrapper
+
+  C++ function that call the original one
+
+* Function transformation
+
+  `Py++`_ sub system\\framework, which will allow you to create function wrappers
+  and to keep smile.
+
+.. _`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/transformation/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py	2006-12-06 14:58:17 UTC (rev 784)
@@ -0,0 +1,5 @@
+name = 'function transformation'
+#main_html_file = 'index.html'
+
+names = { 
+}


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.