|
From: <rom...@us...> - 2006-12-07 10:39:04
|
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.
|
