|
From: <rom...@us...> - 2006-12-10 20:41:33
|
Revision: 792
http://svn.sourceforge.net/pygccxml/?rev=792&view=rev
Author: roman_yakovenko
Date: 2006-12-10 12:41:30 -0800 (Sun, 10 Dec 2006)
Log Message:
-----------
adding documentation for built-in transformers
Modified Paths:
--------------
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/terminology.rest
pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py
Added Paths:
-----------
pyplusplus_dev/docs/documentation/functions/transformation/built_in/inout.rest
pyplusplus_dev/docs/documentation/functions/transformation/built_in/input.rest
pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest
Modified: pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest 2006-12-10 18:42:00 UTC (rev 791)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest 2006-12-10 20:41:30 UTC (rev 792)
@@ -20,13 +20,20 @@
* ``output_array``
-This set doesn't cover all common use cases, but it will grow with every new
+The 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.
+All built-in transformers could be applied on any function, except constructors.
+The support for constructors will be added in future releases.
+
+You don't have to warry about call policies. You can set the call policy and
+`Py++`_ will generate correct code.
+
+
.. _`Py++` : ./../pyplusplus.html
.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
.. _`Python`: http://www.python.org
Added: pyplusplus_dev/docs/documentation/functions/transformation/built_in/inout.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/inout.rest (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/inout.rest 2006-12-10 20:41:30 UTC (rev 792)
@@ -0,0 +1,75 @@
+======================
+``inout`` transformer
+======================
+
+.. contents:: Table of contents
+
+----------
+Definition
+----------
+
+``inout`` transformer is a combination of `input`_ and `output`_ transformers.
+It removes a "reference" type from the function argument and then adds the
+"returned", by the original function, value to the return statement of the
+function-wrapper.
+
+``inout`` 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.
+
+.. _`input` : input.html
+.. _`output` : output.html
+
+-------
+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.inout(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 hw ){
+ ::hello_world(hw);
+ return bp::object( hw );
+ }
+
+ BOOST_PYTHON_MODULE(...){
+ ...
+ bp::def( "hello_world", &hello_world_a3478182294a057b61508c30b1361318 );
+ }
+
+.. _`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/input.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/input.rest (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/input.rest 2006-12-10 20:41:30 UTC (rev 792)
@@ -0,0 +1,68 @@
+======================
+``input`` transformer
+======================
+
+.. contents:: Table of contents
+
+----------
+Definition
+----------
+
+"input" transformer removes a "reference" type from the function argument.
+
+"input" 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.input(0) )
+
+What you see below is the relevant pieces of generated code:
+
+ .. code-block:: C++
+
+ namespace bp = boost::python;
+
+ static void hello_world_a3478182294a057b61508c30b1361318( ::std::string hw ){
+ ::hello_world(hw);
+ }
+
+ BOOST_PYTHON_MODULE(...){
+ ...
+ bp::def( "hello_world", &hello_world_a3478182294a057b61508c30b1361318 );
+ }
+
+.. _`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/built_in/output.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/output.rest 2006-12-10 18:42:00 UTC (rev 791)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/output.rest 2006-12-10 20:41:30 UTC (rev 792)
@@ -8,11 +8,11 @@
Definition
----------
-``output`` transformer removes an argument from the function definition and adds
+"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
+"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.
@@ -58,38 +58,7 @@
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
Added: pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest 2006-12-10 20:41:30 UTC (rev 792)
@@ -0,0 +1,91 @@
+=============
+Name mangling
+=============
+
+.. contents:: Table of contents
+
+----------
+Definition
+----------
+
+Wikipedia has a nice `explantion`_ what name mangling is.
+
+.. _`explantion` : http://en.wikipedia.org/wiki/Name_mangling
+
+----
+Why?
+----
+
+I am sure you want to ask why and where `Py++`_ uses name mangling? `Py++`_ uses
+name mangling to create function-wrappers for overloaded and\\or free functions.
+Consider next use case:
+
+ .. 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:
+
+ .. code-block:: C++
+
+ long get_distance_as_long(){...}
+ double get_distance_as_double(){...}
+
+You have to give them distinguish names - C++ does not allow overloading, base
+on return type only. You also have to exposes them under different aliases,
+otherwise they will not be callable from `Python`_:
+
+ .. code-block:: C++
+
+ namespace bp = boost::python;
+ BOOST_PYTHON_MODULE(...){
+ bp::def( "get_distance_as_long", &get_distance_as_long );
+ bp::def( "get_distance_as_double", &get_distance_as_double );
+ }
+
+------------
+The solution
+------------
+
+`Py++`_ implements a solution to the problem. The generated wrapper names are
+unique in the whole project. However, they are pretty ugly:
+
+* ``get_distance_610ef0e8a293a62001a25cd3dc59b769`` for ``get_distance( long& )``
+ function
+
+* ``get_distance_702c7b971ac4e91b12f260ac85b36d84`` for ``get_distance( double& )``
+ function
+
+The good news - they will not be changed between different runs of the code
+generator. If you are exposing an overloaded function, than `Py++`_ uses the ugly
+function-wrapper name as an alias. It is up to you to change the alias:
+
+ .. code-block:: Python
+
+ from pyplusplus import module_builder
+ from pyplusplus import function_transformers as FT
+
+ mb = module_builder.module_builder_t( ... )
+ get_distance_as_long = mb.mem_fun( 'get_distance', arg_types=['long &'] )
+ get_distance_as_long.add_transformation( FT.output(0), alias="get_distance_as_long" )
+
+There are two main reasons for such implementation\\behaviour:
+
+1. The generated code will always compile and be correct.
+2. If you forgot to give an alias to a function, your users will still be able
+ to call the function. So no need to rush and create new release.
+
+.. _`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/terminology.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest 2006-12-10 18:42:00 UTC (rev 791)
+++ pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest 2006-12-10 20:41:30 UTC (rev 792)
@@ -13,7 +13,7 @@
rules. Especially: a change of return type and\\or arguments and their mapping
to the original ones.
-* Function wrapper
+* Function wrapper ( or just wrapper )
C++ function, which calls some other function.
@@ -26,7 +26,11 @@
An object that applies predefined set of rules on a function, during
function-wrapper construction process.
+* Function alias ( or just alias )
+ Name under which `Python`_ users see the exposed function
+
+
.. _`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-10 18:42:00 UTC (rev 791)
+++ pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py 2006-12-10 20:41:30 UTC (rev 792)
@@ -2,4 +2,5 @@
#main_html_file = 'index.html'
names = { 'built_in_transformers' : 'built-in transformers'
+ , 'name_mangling' : 'name mangling'
}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
