|
From: Roman <rom...@us...> - 2006-04-06 06:16:45
|
Update of /cvsroot/pygccxml/source/pyplusplus/docs In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv28954/pyplusplus/docs Modified Files: download.rest pyplusplus.rest Removed Files: filters.txt tutorials.rest Log Message: There are a lot of changes, sorry CVS did not worked for week or something like this Changes 1. Lots of code clean up 2. Adding and updating documentation 3. Adding new method on decl_wrapper - readme. This method will return list of msgs to the developer. For example if function takes by reference fundamental type it will say that this function could not be called from Python 4. Logging functionlity has been added to file writers too 5. Few bug fixes 6. For operator [] call policies is always set. Index: pyplusplus.rest =================================================================== RCS file: /cvsroot/pygccxml/source/pyplusplus/docs/pyplusplus.rest,v retrieving revision 1.4 retrieving revision 1.5 diff -C2 -d -r1.4 -r1.5 *** pyplusplus.rest 24 Jan 2006 05:46:28 -0000 1.4 --- pyplusplus.rest 6 Apr 2006 06:15:59 -0000 1.5 *************** *** 10,14 **** .. include:: ./definition.rest ! ----------------------- Code generation process --- 10,22 ---- .. include:: ./definition.rest ! ! -------- ! Preamble ! -------- ! ! This introduction will describe code generation process using `pyplusplus`_. ! I hope, that after you finished to read it, you will understand how powerful ! `pyplusplus`_. ! ----------------------- Code generation process *************** *** 22,102 **** ! Next few paragraphs will explain more about every step and what ! customization\\configuration can be done. *"read declarations"* --------------------- ! In order to provide maximum flexibility `pyplusplus`_ does not involved in this ! step at all :-). As you can see, from the process definition, you can read ! declarations from few sources: ! ! * source files - see `pygccxml`_ framework - * xml files - see `pygccxml`_ framework ! * other, for example Microsoft "bsc" files - not implemented yet ! ! Using `pygccxml`_ as declarations reader introduce a small problem. It reads all ! declarations, even those that you do not need. Those unneeded declarations ! could be filtered out. For example *"details"* namespace. It is a common ! practice to put the implementation details into *"details"* namespace. ! Declarations that belong to the *"details"* namespace can be removed. ! ! *"create module"* ----------------- ! `pyplusplus`_ introduces new concept: code creator and code creator's tree. The easiest ! way to explain what is the code creator concept is with example. *include_t* code ! creator is responsible to create code for C++ include directive. Module is the ! top level code creator. It keeps code creator's tree. I can make next analogy ! between code creators concept and XML: ! * code creators <==> Nodes ! * code creators tree <==> XML DOM ! * module <==> DOM Document ! Here you can find UML diagram of all code creators: `class diagram`_. ! .. _`class diagram`: ./code_creators.png ! What is the main role of this step? The main role of this step is to create ! module that keeps code creators tree. It is not as simple as it seems from ! the first sight. Here are few examples: ! 1. Some declarations mapped to more then one code creator. For example for ! C++ class there are more then 2 code creators: *wrapper* and *class_*. ! 2. Base class should be exposed before it's derived classes. ! 3. Type of variable should be exposed before the variable itself. ! I can continue the list of examples, but I think you've got the idea. Mapping, ! between declarations and code creators, implemented by `pyplusplus`_ should be ! good enough for most user. If your case is different, then you can customize ! this step or even implement your own one, using build-in functionality as basis ! for your implementation. To be flexible and expendable, this is one of the goals ! of `pyplusplus`_. Before writing code to files, there is an opportunity to ! change\\customize a lot of things: ! ! * adding custom code creators, this means user code can be placed almost ! any where - * adding namespace aliases, using declarations - - * finalizing "wrappers" of classes/functions - - * renaming exposed declarations - - * changing the structure of code creators tree - - *"write code to files"* ----------------------- ! ! The result of code generation process should not be different from the ! one, that would be achieved by human. For small project single file will ! be good. For big projects multiple files are required. `pyplusplus`_ implements ! both strategies. ------------- --- 30,114 ---- ! Next few paragraphs will explain more about every step. *"read declarations"* --------------------- ! `pyplusplus`_ uses `pygccxml`_ to read all declaration from source files. ! *"build module"* ----------------- ! Only very small and simple projects could be exported as is. Most of the projects ! still require human invocation. Basically there are 2 questions that an user ! should answer: ! 1. which declarations should be exported ! 2. how this specific declaration should be exported ! Of course `pyplusplus`_ can not answer those question, but it provides maximum ! help for the developer to implement/translate an user requirements to code. So ! what help a developer get from `pyplusplus`_ in order to deal with first question? ! `pyplusplus`_ provides very powerful query interface. ! For example in one line of code you can select all free functions that have ! two arguments, where first one is ``int &`` and second one is any: ! :: ! mb = module_builder_t( ... ) #module_builder_t is the main class that ! #will help you with code generation process ! mb.free_functions( arg_types=[ 'int &', None ] ) ! An other example - the developer wants to exclude all protected functions from ! being exported: ! :: ! mb = module_builder_t( ... ) ! mb.calldefs( access_type_matcher_t( 'protected' ) ).exclude() ! The developer can create custom criteria, for example exclude all declarations ! that have 'impl' ( implementation ) string within the name. ! :: ! mb = module_builder_t( ... ) ! mb.decls( lambda decl: 'impl' in decl.name ).exclude() ! ! Okay, enough with code. If you want to read more code please read the tutorials. ! I am sure you already noted some interesting detail: all queries does not specify ! declaration name. It is possible, but still, why I did not? Because this form ! allows you to setup few rules, that will continue to work even after C++ has ! been changed. Thus you don't have to modify code generator source code, every ! time exported C++ code was changed. ! ! So far, so good what about second question? Well, by default `pyplusplus`_ ! generates a code that will satisfy almost all developers. But sometimes a developer ! need to modify generated code. `pyplusplus`_ relevant classes could be configured ! in many ways. But sometimes this is still not enough. Sometimes a developer need ! full control over generated code. One of the bigest problems, that I believe ! `pyplusplus`_ solved, is modifying generated code. How many code generators did ! you use, that allow you to put your code any where, to reorder generated code as ! you wish? `pyplusplus`_ allows you to do that. ! ! `pyplusplus`_ introduces new concept: code creator and code creator's tree. ! Code creator responsibility is to create small well defined piece of code. ! For example *include_t* code creator is responsible to create code for C++ ! include directive. Code creators tree is an ordered set of code creators. ! Some of code creators can contain others. Module is the top level code creator. ! A developer is able to add, delete or modify single/group of code creators. ! Here you can find UML diagram of almost all code creators: `class diagram`_. ! ! .. _`class diagram`: ./code_creators.png ! ! At the end of this step you have code creators tree, that is ready to be written ! to disc. *"write code to files"* ----------------------- ! During this step `pyplusplus`_ reads code creators tree and writes code to the ! disc.The result of code generation process should not be different from the one, ! that would be achieved by human. For small project writing all code into single ! file is good approach, for big ones code should be written into multiple files. ! `pyplusplus`_ implements both strategies. ------------- *************** *** 164,203 **** `Boost Software License`_. - - ------------------------------------ - Structure of `pyplusplus`_ framework - ------------------------------------ - - `pyplusplus`_ is separated to 5 different packages: - - 1. Code creators package. The only responsibility of classes in this - package is to create code. Those classes do not care where code is - going to be written. Neither they care about the order of generated - code. - - 2. Module creator package. This is code creators factory. Classes in this - package analyze C++ declarations and creates relevant code creators. - - 3. File writers package. This package contains classes that write - generated code to file(s). - - 4. Unit tests - right now there are more then 20 unit tests. `pyplusplus`_ - package generated code tested under Windows XP + msvc 7.1 and under - Debian 3.1 + GCC 3.3.5. - - 5. Real world examples. - -------------------------------------------------------------------------------- - - Hosted by |SourceForge|__ - - __ http://sourceforge.net/ - .. |SourceForge| image:: http://sourceforge.net/sflogo.php?group_id=118209&type=4 - :alt: SourceForge.net Logo - :align: middle - :width: 125 - :height: 37 - .. :border: 0 - .. _`pyplusplus` : ./pyplusplus.html .. _`pygccxml` : ./../pygccxml/pygccxml.html --- 176,180 ---- --- filters.txt DELETED --- --- tutorials.rest DELETED --- Index: download.rest =================================================================== RCS file: /cvsroot/pygccxml/source/pyplusplus/docs/download.rest,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** download.rest 23 Jan 2006 06:36:30 -0000 1.1 --- download.rest 6 Apr 2006 06:15:59 -0000 1.2 *************** *** 53,68 **** * `Docutils`_ - only in case you want to create\\extend current documentation - -------------------------------------------------------------------------------- - - Hosted by |SourceForge|__ - - __ http://sourceforge.net/ - .. |SourceForge| image:: http://sourceforge.net/sflogo.php?group_id=118209&type=4 - :alt: SourceForge.net Logo - :align: middle - :width: 125 - :height: 37 - .. :border: 0 - .. _`pyplusplus` : ./pyplusplus.html .. _`pygccxml` : ./../pygccxml/pygccxml.html --- 53,56 ---- |
