Thread: [pygccxml-commit] SF.net SVN: pygccxml: [785] pyplusplus_dev/docs/documentation/functions/ transfor

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Revision: 785
          http://svn.sourceforge.net/pygccxml/?rev=785&view=rev
Author:   roman_yakovenko
Date:     2006-12-07 02:39:03 -0800 (Thu, 07 Dec 2006)

Log Message:
-----------
adding output transformer documentation

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

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

Added: pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest
===================================================================

--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest	2006-12-07 10:39:03 UTC (rev 785)
@@ -0,0 +1,41 @@
+=====================
+Built-in transformers
+=====================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+`Py++`_ comes with few predefined transformers:
+
+* ``output``
+
+* ``input``
+
+* ``inout``
+
+* ``input_array``
+
+* ``output_array``
+
+This set doesn't cover all common use cases, but it will grow with every new 
+version of `Py++`_. If you created your own transformer consider to contribute 
+it to the project.
+
+I suggest you to start reading ``output`` transformer. It is pretty simple and 
+well explained.
+
+.. _`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/built_in/output.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/output.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/output.rest	2006-12-07 10:39:03 UTC (rev 785)
@@ -0,0 +1,104 @@
+======================
+``output`` transformer
+======================
+
+.. contents:: Table of contents
+
+----------
+Definition
+----------
+
+``output`` transformer removes an argument from the function definition and adds
+the "returned", by the original function, value to the return statement of the 
+function-wrapper.
+
+``output`` transformer takes as argument name or index of the original function
+argument. The argument should have "reference" type. Support for "pointer" type
+will be added pretty soon.
+
+-------
+Example
+-------
+
+.. code-block:: C++
+
+  #include <string>
+  
+  inline void hello_world( std::string& hw ){
+      hw = "hello world!";
+  }
+
+Lets say that you need to expose ``hello_world`` function. As you know
+``std::string`` is mapped to `Python`_ string, which is immutable type, so you 
+have to create small wrapper for the function. Next `Py++`_ code does it for you:
+
+  .. code-block:: Python
+
+     from pyplusplus import module_builder
+     from pyplusplus import function_transformers as FT
+     
+     mb = module_builder.module_builder_t( ... )
+     hw = mb.mem_fun( 'hello_world' )
+     hw.add_transformation( FT.output(0) )
+
+What you see below is the relevant pieces of generated code:
+
+  .. code-block:: C++
+
+     namespace bp = boost::python;
+     
+     static boost::python::object hello_world_a3478182294a057b61508c30b1361318(  ){
+         std::string hw2;
+         ::hello_world(hw2);
+         return bp::object( hw2 );
+     }
+     
+     BOOST_PYTHON_MODULE(...){
+         ...
+         bp::def( "hello_world", &hello_world_a3478182294a057b61508c30b1361318 );
+      }
+
+Explanation
+-----------
+
+I feel like I need to explain why the function wrapper for ``hello_world`` function
+has such strange name - ``hello_world_a3478182294a057b61508c30b1361318``. The
+short answer is function overloading. Consider next code that you need to export:
+
+  .. code-block:: C++
+
+     void get_distance( long& );
+     void get_distance( double& );
+
+In order to expose ``get_distance`` functions you have to create 2 function
+wrappers and give them distinguish names. You also have to register them under 
+different aliases, otherwise your users will not be able to call the functions.
+`Py++`_ does it for you. The generated wrapper names are unique in the whole 
+project. They will not be changed between different runs of the code generator.
+The aliases `Py++`_ gives to the functions are ugly. You have to provide your 
+own aliases:
+
+    .. code-block:: Python
+
+     from pyplusplus import module_builder
+     from pyplusplus import function_transformers as FT
+     
+     mb = module_builder.module_builder_t( ... )
+     get_distance_int = mb.mem_fun( 'get_distance', arg_types=[ 'int &'] )
+     get_distance_int.add_transformation( FT.output(0), alias="get_distance_as_int" )
+
+The main reason for the behaviour is that even if you forget to give an alias
+to a function, your users will still be able to call the function.
+
+.. _`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/built_in/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/www_configuration.py	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/www_configuration.py	2006-12-07 10:39:03 UTC (rev 785)
@@ -0,0 +1,4 @@
+name = 'built-in transformers'
+#main_html_file = 'index.html'
+
+names = { }

Added: pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest	2006-12-07 10:39:03 UTC (rev 785)
@@ -0,0 +1,41 @@
+===========
+Terminology
+===========
+
+.. contents:: Table of contents
+
+* Function transformation
+
+  `Py++`_ sub-system\\framework, which allows you to create function wrappers
+  and to keep smile.
+  
+  The operation of changing one function into another in accordance with some 
+  rules. Especially: a change of return type and\\or arguments and their mapping
+  to the original ones.
+  
+* Function wrapper
+
+  C++ function, which calls some other function. 
+
+* Immutable type 
+
+  An instance of this type could not be modified after construction
+
+* Transformer
+
+  An object that applies predefined set of rules on a function, during 
+  function-wrapper construction process.
+
+
+.. _`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/transformation/transformation.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest	2006-12-06 14:58:17 UTC (rev 784)
+++ pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest	2006-12-07 10:39:03 UTC (rev 785)
@@ -8,12 +8,12 @@
 Introduction
 ------------
 
-During the development of Python bindings for some C++ library, it might get 
+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:
+member function of a fictitious image class:
 
 .. code-block:: C++
 
@@ -68,25 +68,16 @@
    #Next line has same effect
    get_size.add_transformation( FT.output('width'), FT.output('height') )
 
-`Py++`_ will generate very similar code you just saw.
+`Py++`_ will generate a code, very similar to one found in 
+``boost::python::tuple get_size( const image_t& img )`` function.
 
------------
-Terminology
------------
+---------
+Thanks to 
+---------
 
-* Immutable type 
+Thanks goes to Matthias Baas for his efforts and hard work. He did a research,
+implemented the initial working version and wrote a lot of documentation. 
 
-  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

Modified: pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py	2006-12-06 14:58:17 UTC (rev 784)
+++ pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py	2006-12-07 10:39:03 UTC (rev 785)
@@ -1,5 +1,5 @@
 name = 'function transformation'
 #main_html_file = 'index.html'
 
-names = { 
+names = { 'built_in_transformers' : 'built-in transformers'
 }


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


