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

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

Revision: 1189
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1189&view=rev
Author:   roman_yakovenko
Date:     2007-12-04 05:46:10 -0800 (Tue, 04 Dec 2007)

Log Message:
-----------
join build-in transformers with the "transformation" documentation

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

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/functions/transformation/inout.rest
    pyplusplus_dev/docs/documentation/functions/transformation/input.rest
    pyplusplus_dev/docs/documentation/functions/transformation/input_c_buffer.rest
    pyplusplus_dev/docs/documentation/functions/transformation/input_static_array.rest
    pyplusplus_dev/docs/documentation/functions/transformation/modify_type.rest
    pyplusplus_dev/docs/documentation/functions/transformation/output.rest
    pyplusplus_dev/docs/documentation/functions/transformation/output_static_array.rest
    pyplusplus_dev/docs/documentation/functions/transformation/transfer_ownership.rest

Added: pyplusplus_dev/docs/documentation/functions/transformation/inout.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/inout.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/inout.rest	2007-12-04 13:46:10 UTC (rev 1189)
@@ -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/input.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/input.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/input.rest	2007-12-04 13:46:10 UTC (rev 1189)
@@ -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:

Added: pyplusplus_dev/docs/documentation/functions/transformation/input_c_buffer.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/input_c_buffer.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/input_c_buffer.rest	2007-12-04 13:46:10 UTC (rev 1189)
@@ -0,0 +1,82 @@
+==================================
+``input_c_buffer`` transformer
+==================================
+
+.. contents:: Table of contents
+
+----------
+Definition
+----------
+
+"input_c_buffer" transformer works on C buffers. It handles the translation 
+between a `Python`_ sequence object and the buffer.
+
+"input_c_buffer" transformer takes as first argument name or index of the
+"buffer" argument. The argument should have "array" or "pointer" type.
+The second argument should be name or index of another original function argument,
+which represents array size.
+
+-------
+Example
+-------
+
+.. code-block:: C++
+
+  struct file_t{
+      void write( char* buffer, int size ) const;	
+  };
+
+In order to expose ``write`` member function we need to create small wrapper:
+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( ... )
+     f = mb.class_( 'file_t' )
+     f.mem_fun( 'write' ).add_transformation( FT.input_c_buffer( 'buffer', 'size' ) )
+
+What you see below is the relevant pieces of generated code:
+
+  .. code-block:: C++
+
+     #include "__convenience.pypp.hpp" //Py++ header file, which contains few convenience function
+
+     #include <vector>
+
+     #include <iterator>
+     
+     namespace bp = boost::python;
+
+     static void write_8883fea8925bad9911e6c5a4015ed106( ::file_t const & inst, boost::python::object buffer ){
+        int size2 = boost::python::len(buffer);
+        std::vector< char > native_buffer;
+        native_buffer.reserve( size2 );
+        pyplus_conv::ensure_uniform_sequence< char >( buffer );
+        pyplus_conv::copy_sequence( buffer, std::back_inserter( native_buffer), boost::type< char >() );
+        inst.write(&native_buffer[0], size2);
+     }
+
+     BOOST_PYTHON_MODULE(...){
+         ...
+         bp::class_< file_t >( "file_t" )    
+            .def( 
+                  "write"
+                , (void (*)( ::file_t const &,boost::python::object ))( &write_8883fea8925bad9911e6c5a4015ed106 )
+                , ( bp::arg("inst"), bp::arg("buffer") ) );
+     }
+
+.. _`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/input_static_array.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/input_static_array.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/input_static_array.rest	2007-12-04 13:46:10 UTC (rev 1189)
@@ -0,0 +1,85 @@
+==================================
+``input_static_array`` transformer
+==================================
+
+.. contents:: Table of contents
+
+----------
+Definition
+----------
+
+"input_static_array" transformer works on native static arrays. It handles the
+translation between `Python`_ object, passed as argument that represent a sequence,
+and the array. Size of array should be predefined.
+
+"input_static_array" transformer takes as first argument name or index of the
+original function argument. The argument should have "array" or "pointer" type.
+The second argument should an integer value, which represents array size.
+
+-------
+Example
+-------
+
+.. code-block:: C++
+
+   struct vector3{
+
+       void init( int values[3] ){
+           x = values[0];
+           y = values[1];
+           z = values[2];
+       }
+
+       int x,y,z;
+   };
+
+In order to expose ``init`` member function we need to create small wrapper:
+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( ... )
+     v3 = mb.class_( 'vector3' )
+     v3.mem_fun( 'init' ).add_transformation( FT.input_static_array( 0, 3 ) )
+
+What you see below is the relevant pieces of generated code:
+
+  .. code-block:: C++
+
+     #include "__convenience.pypp.hpp" //Py++ header file, which contains few convenience function
+
+     namespace bp = boost::python;
+
+     static void init_418e52f4a347efa6b7e123b96f32a73c( ::ft::vector3 & inst, boost::python::object values ){
+         int native_values[3];
+         pyplus_conv::ensure_uniform_sequence< int >( values, 3 );
+         pyplus_conv::copy_sequence( values, pyplus_conv::array_inserter( native_values, 3 ) );
+         inst.init(native_values);
+     }
+
+     BOOST_PYTHON_MODULE(...){
+         ...
+         bp::class_< ft::vector3 >( "vector3", "documentation" )
+        .def( "init"
+              , &init_418e52f4a347efa6b7e123b96f32a73c
+              , ( bp::arg("inst"), bp::arg("values") ) )
+        .def_readwrite( "x", &ft::vector3::x )
+        .def_readwrite( "y", &ft::vector3::y )
+        .def_readwrite( "z", &ft::vector3::z );
+     }
+
+.. _`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/modify_type.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/modify_type.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/modify_type.rest	2007-12-04 13:46:10 UTC (rev 1189)
@@ -0,0 +1,79 @@
+===========================
+``modify_type`` transformer
+===========================
+
+.. contents:: Table of contents
+
+----------
+Definition
+----------
+
+"modify_type" transformer changes type of the function argument.
+
+"modify_type" transformer takes two arguments:
+
+1. name or index of the original function argument
+
+2. a callable, which takes as argument reference to type and returns new type
+
+New in version greater than 0.8.5.
+
+Pay attention!
+--------------
+
+If implicit conversion between new type and the old one does not exist
+"reinterpret_cast" will be used.
+
+-------
+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 pygccxml import declarations
+     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.modify_type(0, declarations.remove_reference) )
+
+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:

Added: pyplusplus_dev/docs/documentation/functions/transformation/output.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/output.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/output.rest	2007-12-04 13:46:10 UTC (rev 1189)
@@ -0,0 +1,73 @@
+======================
+``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 );
+      }
+
+
+.. _`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/output_static_array.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/output_static_array.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/output_static_array.rest	2007-12-04 13:46:10 UTC (rev 1189)
@@ -0,0 +1,85 @@
+===================================
+``output_static_array`` transformer
+===================================
+
+.. contents:: Table of contents
+
+----------
+Definition
+----------
+
+"output_static_array" transformer works on native static arrays. It handles the
+translation between array and `Python`_ list object. Size of array should be predefined.
+
+"output_static_array" transformer takes as first argument name or index of the
+original function argument. The argument should have "array" or "pointer" type.
+The second argument should an integer value, which represents array size.
+
+-------
+Example
+-------
+
+.. code-block:: C++
+
+   struct vector3{
+
+       void get_values( int values[3] ){
+           values[0] = x;
+           values[1] = y;
+           values[2] = z;
+       }
+
+       int x,y,z;
+   };
+
+In order to expose ``get_values`` member function we need to create small wrapper:
+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( ... )
+     v3 = mb.class_( 'vector3' )
+     v3.mem_fun( 'get_values' ).add_transformation( FT.output_static_array( 0, 3 ) )
+
+What you see below is the relevant pieces of generated code:
+
+  .. code-block:: C++
+
+     #include "__convenience.pypp.hpp" //Py++ header file, which contains few convenience function
+
+     namespace bp = boost::python;
+
+     static boost::python::object get_values_22786c66e5973b70f714e7662e2aecd2( ::ft::vector3 & inst ){
+        int native_values[3];
+        boost::python::list py_values;
+        inst.get_values(native_values);
+        pyplus_conv::copy_container( native_values, native_values + 3, pyplus_conv::list_inserter( py_values ) );
+        return bp::object( py_values );
+     }
+
+     BOOST_PYTHON_MODULE(...){
+         ...
+         bp::class_< ft::vector3 >( "vector3", "documentation" )
+            .def( "get_values"
+                  , &get_values_22786c66e5973b70f714e7662e2aecd2
+                  , ( bp::arg("inst") ) )
+            .def_readwrite( "x", &ft::vector3::x )
+            .def_readwrite( "y", &ft::vector3::y )
+            .def_readwrite( "z", &ft::vector3::z );
+     }
+
+.. _`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/transfer_ownership.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/transfer_ownership.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/transfer_ownership.rest	2007-12-04 13:46:10 UTC (rev 1189)
@@ -0,0 +1,78 @@
+==================================
+``transfer_ownership`` transformer
+==================================
+
+.. contents:: Table of contents
+
+----------
+Definition
+----------
+
+"transfer_ownership" transformer changes type of the function argument, from
+``T*`` to ``std::auto_ptr<T>``. This transformer was born to provide the answer
+to `How can I wrap a function which needs to take ownership of a raw pointer?`_
+FAQ.
+
+.. _`How can I wrap a function which needs to take ownership of a raw pointer?` : http://boost.org/libs/python/doc/v2/faq.html#ownership
+
+"transfer_ownership" transformer takes one argument, name or index of the
+original function argument. The argument type should be "pointer".
+
+New in version greater than 0.8.5.
+
+-------
+Example
+-------
+
+.. code-block:: C++
+
+  struct resource_t{...};
+
+  void do_smth(resource_t* r){
+      ...
+  }
+
+Lets say that you need to expose "do_smth" function. According to the FAQ, you
+have to create small wrapper, which will take ``std::auto_ptr`` as an argument.
+Next `Py++`_ code does it for you:
+
+  .. code-block:: Python
+
+     from pygccxml import declarations
+     from pyplusplus import module_builder
+     from pyplusplus import function_transformers as FT
+
+     mb = module_builder.module_builder_t( ... )
+
+     resource = mb.class_( 'resource_t' )
+     resource.held_type = 'std::auto_ptr< %s >' % resource.decl_string
+     do_smth = mb.free_fun( 'do_smth' )
+     do_smth.add_transformation( FT.transfer_ownership( 0 ) )
+
+What you see below is the relevant pieces of generated code:
+
+  .. code-block:: C++
+
+     namespace bp = boost::python;
+
+     static void do_smth_4cf7cde5fca92efcdb8519f8c1a4bccd( std::auto_ptr< ::resource_t > r ){
+      ::do_smth(r.release());
+     }
+
+     BOOST_PYTHON_MODULE(...){
+         ...
+         bp::def( "do_smth", &do_smth_4cf7cde5fca92efcdb8519f8c1a4bccd, ( bp::arg("r") ) );
+     }
+
+.. _`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	2007-12-04 13:15:03 UTC (rev 1188)
+++ pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest	2007-12-04 13:46:10 UTC (rev 1189)
@@ -78,6 +78,47 @@
 A 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. 
 
+---------------------
+Built-in transformers
+---------------------
+
+`Py++`_ comes with few predefined transformers:
+
+* ``output``
+
+* ``input``
+
+* ``inout``
+
+* ``modify_type``
+
+* ``input_static_array``
+
+* ``output_static_array``
+
+* ``input_c_buffer``
+
+* ``transfer_ownership``
+
+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.
+
+.. _`output` : ./output.html
+
+All built-in transformers could be applied on any function, except constructors
+and pure virtual functions. The support for them be added in future releases.
+
+You don't have to worry about call policies. You can set the call policy and
+`Py++`_ will generate the correct code.
+
+You don't have to worry about the number of arguments, transformers or return
+value. `Py++`_ handles pretty well such use cases.
+
+
 .. _`Py++` : ./../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org


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