[pygccxml-commit] SF.net SVN: pygccxml: [772] pyplusplus_dev/docs/documentation/how_to.rest

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

Revision: 772
          http://svn.sourceforge.net/pygccxml/?rev=772&view=rev
Author:   roman_yakovenko
Date:     2006-12-01 11:47:39 -0800 (Fri, 01 Dec 2006)

Log Message:
-----------
adding new question

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/how_to.rest

Modified: pyplusplus_dev/docs/documentation/how_to.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to.rest	2006-11-30 18:49:18 UTC (rev 771)
+++ pyplusplus_dev/docs/documentation/how_to.rest	2006-12-01 19:47:39 UTC (rev 772)
@@ -1,4 +1,4 @@
-============
+============
 How to ... ?
 ============
 
@@ -28,6 +28,7 @@
 
 .. code-block:: Python
 
+  mb = module_builder_t( ... )
   mb.add_declaration_code( translate_code )
 
 
@@ -320,6 +321,61 @@
 By the way, almost the same problem exists for template classes. But, in the
 classes use case `Py++`_ uses demangled name by default.
 
+
+-------------------------------------
+Py++ generated file name is too long!
+-------------------------------------
+There are use cases, when `Py++`_ generated file name is too long. In some cases
+the code generation process even fails because of this. What can you do in order
+to eliminate the problem?
+
+First of all the problem arises when you expose template instantiated classes 
+and you did not set the class alias.
+
+Let me explain:
+
+.. code-block:: C++
+
+  template < class T>
+  struct holder{ ... };
+  
+
+Lets say that you want to export ``holder< int >`` class. Class name in `Python`_
+has few `constraints`_. `Py++`_ is aware of the `constraints`_ and if you didn't
+set an alias to the class, `Py++`_ will do it for you. In this case, 
+"holder_less_int_grate\_" is the generated alias. Obviously it is much longer 
+and not readable. 
+
+.. _`constraints` : http://www.python.org/doc/current/ref/identifiers.html
+
+There are few pretty good reasons for this behavior:
+
+* when you just start to work on `Python`_ bindings concentrate your attention
+  on really important things
+
+* if you forgot to set the class alias your users still can use the class 
+  functionality, however the class name will be a little bit ugly.
+
+
+In this case the generate alias for ``holder`` instantiation is relatively short.
+Imagine how long it could be for ``std::map`` instantiation.
+
+`Py++`_ uses class alias for the file name. So if you want to force `Py++`_ to
+generate files with short name, you have to set class alias:
+
+.. code-block:: Python
+
+  from pyplusplus import module_builder
+  
+  mb = module_builder_t( ... )
+  holder = mb.class_( 'holder< int >' )
+  holder.alias = 'IntHolder'
+  #next line has same effect as the previous one:
+  holder.rename( 'IntHolder' )
+
+The nice thing about this approach is that now `Python`_ users have "normal"
+class name and you have short file name.
+
 .. _`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.