Thread: [pygccxml-commit] source/pygccxml/docs definition.rest,1.2,1.3 pygccxml.rest,1.3,1.4
Brought to you by:
mbaas,
roman_yakovenko
From: Roman <rom...@us...> - 2006-03-05 05:39:13
|
Update of /cvsroot/pygccxml/source/pygccxml/docs In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv11726/pygccxml/docs Modified Files: definition.rest pygccxml.rest Log Message: applying John Pallister <jo...@sy...> documentation changes. Index: pygccxml.rest =================================================================== RCS file: /cvsroot/pygccxml/source/pygccxml/docs/pygccxml.rest,v retrieving revision 1.3 retrieving revision 1.4 diff -C2 -d -r1.3 -r1.4 *** pygccxml.rest 31 Jan 2006 08:15:53 -0000 1.3 --- pygccxml.rest 5 Mar 2006 05:39:08 -0000 1.4 *************** *** 22,32 **** First of all let's see a small and simple `example`_. This example prints all ! declarations found in `core_class_hierarchy.hpp`_ file. Also, for instances, that ! describes C++ class, it will print bases and derived class names. This example ! is also interesting because it `shows`_ us how it can be simple to find out all ! bases and derived classes. If someone still is curious "how it can be in the real ! life" he may look at `GCC-XML`_ `generated file`_. ! .. _`generated file` : ./core_class_hierarchy.hpp.xml .. _`core_class_hierarchy.hpp` : ./core_class_hierarchy.hpp .. _`shows` : ./example_output.txt --- 22,32 ---- First of all let's see a small and simple `example`_. This example prints all ! declarations found in the `core_class_hierarchy.hpp`_ file. Also, for instances ! that describe a C++ class it will print base and derived class names. This example ! is also interesting because it `shows`_ us how simple it is to find all base ! and derived classes. If someone is still curious how it looks "in the real ! life" he may look at the `original XML file`_ generated by `GCC-XML`_. ! .. _`original XML file` : ./core_class_hierarchy.hpp.xml .. _`core_class_hierarchy.hpp` : ./core_class_hierarchy.hpp .. _`shows` : ./example_output.txt *************** *** 36,51 **** ----------------------------------------- ! Consider next situation: you have to parse the same set of files every day. ! There are 2 possibilities to complete the task:: ! * Create header file that includes all files you need to parse ! * Parse each file separately and then join the results ! The difference between these approaches is caching algorithm in second case. ! `pygccxml`_ supports both of them. ! That's not all. Do you familiar with `boost::type_traits`_ library? Well, ! `pygccxml`_ has some functionality offered by that library. ------- --- 36,51 ---- ----------------------------------------- ! Consider the following situation: you have to parse the same set of files every ! day. There are 2 possibile ways to complete the task:: ! * create a header file that includes all files you need to parse ! * parse each file separately and then join the results ! The difference between these approaches is the caching algorithm used in the ! second case. `pygccxml`_ supports both of them. ! That's not all. Do you familiar with the `boost::type_traits`_ library? Well, ! `pygccxml`_ includes some functionality offered by that library. ------- *************** *** 60,95 **** `UML diagram`_: ! Look at this `UML diagram`_. All classes are defined by `pygccxml`_.declarations ! package. Defined classes are used to describe almost any C++ declaration. ! Few words about convention. Every class name ends with "_t". The are several ! reasons for it: ! * I am used to C++ "std" convention. ( small letters with underscores ) ! * Most of the names are already exists in python and have the different meaning. Types hierarchy --------------- ! Types hierarchy is used to represent arbitrary type in C++. Example ~~~~~~~ ! For variable "ptr" *const int\* ptr=0;* ! `pygccxml`_ will create next type *pointer_t( const_t( int_t() ) )* ! The ability to represent almost any type of C++ comes from "decorator" pattern. ! That's not all! Do you aware of `boost::type_traits`_ library? `boost::type_traits`_ ! library has been developed by John Maddock, Steve Cleary and others. `pygccxml`_ ! reuse names proposed by this library. Also I took few ideas for testing ! `pygccxml`_ type traits implementation. Here are some type traits implemented by ! `pygccxml`_. + *base_type* --- 60,96 ---- `UML diagram`_: ! Look at this `UML diagram`_. All the classes are defined by the ! `pygccxml`_.declarations package. Defined classes are used to describe almost ! any C++ declaration. ! A few words about the naming convention used. Every class name ends with "_t". ! The are several reasons for this: ! * I am used to the C++ "std" convention, i.e. lower-case letters with underscores. ! * Most of the names are already used in Python, and have a different meaning. Types hierarchy --------------- ! Types hierarchy is used to represent an arbitrary type in C++. Example ~~~~~~~ ! For a variable "ptr" *const int\* ptr=0;* ! `pygccxml`_ will create the type *pointer_t( const_t( int_t() ) )* ! The ability to represent almost any type of C++ comes from the use of the ! "decorator" pattern. That's not all! Are you aware of `boost::type_traits`_ ! library? The `boost::type_traits`_ library has been developed by John Maddock, ! Steve Cleary and others. `pygccxml`_ reuses the names proposed by this library. ! Also I took few ideas for testing the `pygccxml`_ type traits implementation. ! Here are some of the type traits implemented by `pygccxml`_. + *base_type* *************** *** 156,166 **** --------------------- ! Declaration hierarchy is used to represent arbitrary C++ declaration. ! *"declaration_t"* is a base class of declaration hierarchy. This class has few ! properties. One of them is *"parent"* property. This property keeps reference to ! scope declaration instance in which this declaration is defined. *"scopedef_t"* ! class derives from *"declaration_t"*. This class is used to say - "I may have ! other declarations inside". The pattern that is used here is "composite". ------ --- 157,168 ---- --------------------- ! A declaration hierarchy is used to represent an arbitrary C++ declaration. ! *"declaration_t"* is the base class of the declaration hierarchy. This class has ! a few properties. One of them is the *"parent"* property. This property keeps a ! reference to the scope declaration instance in which this declaration is defined. ! The *"scopedef_t"* class derives from *"declaration_t"*. This class is used to ! say - "I may have other declarations inside". The "composite" design pattern is ! used here. ------ *************** *** 171,180 **** -------- ! `Parser package`_ ( "`pygccxml`_.parser" ). This is the heart of `pygccxml`_ project. ! Classes in this package implements parsing and binding functionality. There are ! 3 classes and 2 functions that user should know about: ! + *config_t* - class that accumulates all settings of `GCC-XML`_ and `pygccxml`_. ! User can work with relative files paths. In this case files are searched in next order: 1. current directory --- 173,183 ---- -------- ! `Parser package`_ ( "`pygccxml`_.parser" ). This is the heart of the `pygccxml`_ ! project. Classes in this package implement parsing and binding functionality. ! There are 3 classes and 2 functions that user should know about: ! + *config_t* - a class that accumulates all the settings of `GCC-XML`_ and ! `pygccxml`_. Users can work with relative files paths. In this case files are ! searched in the following order: 1. current directory *************** *** 185,202 **** + *source_reader_t* - the only class that works with `GCC-XML`_. This class has ! only one responsibility: to convert source file declarations and types to ! `pygccxml`_ objects model. You can think about this class as `GCC-XML`_ generated ! file reader only. ! + *project_reader_t* - think about this class as a linker or a binder. Explanation: ! usually you will define base class in one header file and derived in an other one. ! After running *source_reader_t* on base header and on derived header you will ! get 2 definitions of base class. More then one of the definitions will not ! contain information about derived classes. *project_reader_t* was born to solve ! this situation. It implements few algorithms to solve that problem and other ! similar ones. Right now it implements next algorithms: 1. namespace joining. ! 2. join class hierarchies 3. rebinding types to new class hierarchies 4. linking overloaded functions --- 188,206 ---- + *source_reader_t* - the only class that works with `GCC-XML`_. This class has ! only one responsibility: to convert source file declarations and types into the ! `pygccxml`_ object model. You can think about this class as simply a reader for ! `GCC-XML`_-generated files. ! + *project_reader_t* - think of this class as a linker or a binder. Explanation: ! usually you will define a base class in one header file and a derived class in ! another. After running *source_reader_t* on the base class header file and on ! the derived class header file you will have two definitions of the base class. ! All but one of the definitions will not contain information about the derived ! classes. *project_reader_t* was born to solve this situation. It implements ! several algorithms to solve that problem and other similar ones. Right now it ! implements these algorithms: 1. namespace joining. ! 2. joining class hierarchies 3. rebinding types to new class hierarchies 4. linking overloaded functions *************** *** 204,220 **** There are 2 ways to solve the problem: ! 1. To compile every file and than to run the algorithms. ! In order to run this mode set *compilation_mode* ( in instance of *config_t* ) ! to *COMPILATION_MODE.FILE_BY_FILE*. ! 2. To create a temporal header file, that will include all headers you want to ! compile. In order to run this mode set *compilation_mode* ( in instance of ! *config_t* ) to *COMPILATION_MODE.ALL_AT_ONCE*. In other words, in this ! mode *project_reader_t* acts like *source_reader_t*, no difference. ! Two modes, why?! The answer is simple - cache. You don't want to pay for ! compilation and processing result for files that has not been changed, right? ! *COMPILATION_MODE.FILE_BY_FILE* gives you the possibility to use cache! For ! further explanation please see `Parser package`_ design. Interface description --- 208,223 ---- There are 2 ways to solve the problem: ! 1. Compile every file to run the algorithms. In order to select this mode ! set *compilation_mode* (in the instance of *config_t*) to *COMPILATION_MODE.FILE_BY_FILE*. ! 2. Create a temporary header file, that will include all headers you want to ! compile. In order to select this mode set *compilation_mode* (in the instance ! of *config_t* ) to *COMPILATION_MODE.ALL_AT_ONCE*. In other words, in this ! mode *project_reader_t* acts like *source_reader_t*, there's no difference. ! Two modes, why?! The answer is simple - the cache. You don't want to pay for ! compilation and processing results for files that have not changed, right? ! *COMPILATION_MODE.FILE_BY_FILE* gives you the possibility to use the cache! ! For further explanation please see `Parser package`_ design. Interface description *************** *** 229,256 **** + *read_string(self, content)* - small convenience function. The *content* ! should be valid C++ code. This function will return top level namespaces's list. + *source_reader_t.read_file(self, source_file)* This function will return ! top level namespaces list. ! + *project_reader_t.read_files(self, files)* This function will return ! top level namespaces list. *files* - list of files to be compiled. ! This list may contain a file name ( string ) or instance of class ! *file_configuration_t*. In case the item is an instance of class *file_configuration_t* ! then file will be compiled and parsed using it's configuration. Project ! configuration stays unchanged. + *source_reader_t.create_xml_file(self, source_file, destination_file_path=None)* ! This function will return file name of the file, created by `GCC-XML`_. If *destination_file_path* is not *None* then this file path will be used and returned. ! + *source_reader_t.read_xml_file(self, xmlfile)* This function will return top ! level namespaces list. Right now top level namespaces are: "::" and "std". ! Main purpose of *source_reader_t.create_xml_file* and *source_reader_t.read_xml_file* ! is to make an easy cross-platform development. *pygccxml.parser* --- 232,260 ---- + *read_string(self, content)* - small convenience function. The *content* ! should be valid C++ code. This function will return the list of top level ! namespaces. + *source_reader_t.read_file(self, source_file)* This function will return ! the list of top level namespaces. ! + *project_reader_t.read_files(self, files)* This function will return the top ! level namespaces list. *files* - list of files to be compiled. This list may ! contain a file name ( string ) or instance of class *file_configuration_t*. ! If the item is an instance of class *file_configuration_t* then the file will ! be compiled and parsed using its configuration. The project configuration stays ! unchanged. + *source_reader_t.create_xml_file(self, source_file, destination_file_path=None)* ! This function will return the file name of the file, created by `GCC-XML`_. If *destination_file_path* is not *None* then this file path will be used and returned. ! + *source_reader_t.read_xml_file(self, xmlfile)* This function will return the ! top level namespaces list. Right now top level namespaces are: "::" and "std". ! The main purpose of *source_reader_t.create_xml_file* and *source_reader_t.read_xml_file* ! is to ease cross-platform development. *pygccxml.parser* *************** *** 270,280 **** There are 2 private classes in this package: ! 1. *scanner_t* - this class scans "XML" file, generated by `GCC-XML`_ and creates ! `pygccxml`_ declarations and types classes. After the xml file has been processed ! declarations and types class instances keeps references to each other using ! `GCC-XML`_ generated id's. 2. *linker_t* - this class contains logic for replacing `GCC-XML`_ generated ! ids with references to declarations\\types class instances. --- 274,284 ---- There are 2 private classes in this package: ! 1. *scanner_t* - this class scans the "XML" file, generated by `GCC-XML`_ and ! creates `pygccxml`_ declarations and types classes. After the xml file has ! been processed declarations and type class instances keeps references to ! each other using `GCC-XML`_ generated id's. 2. *linker_t* - this class contains logic for replacing `GCC-XML`_ generated ! ids with references to declarations or type class instances. *************** *** 283,290 **** ----------------- ! `pygccxml`_ comes with comprehensive unit tests. It is running on windows xp and ! `Debian Linux`_. I am using `Python`_ 2.3 and `GCC-XML`_ 0.6.0. Right now I am running ! more then 75 tests. They test almost every piece of code. Also I have performance tests. ! Most of the time I am using "white box" testing strategy. --------- --- 287,295 ---- ----------------- ! `pygccxml`_ comes with comprehensive unit tests. It is running on Windows XP and ! `Debian Linux`_. I am using `Python`_ [ 2.3 | 2.4 ] and `GCC-XML`_ [ 0.6.0 | CVS ]. ! Right now I am running more then 100 tests. They test almost every piece of code. ! Also I have performance tests. Most of the time I am using "white box" testing ! strategy. --------- *************** *** 292,296 **** --------- ! * My wife Yulia - she helped me to edit initial version of this manuals. All mistakes and bugs are mine. I'd like to believe that I know `Python`_ better then English. --- 297,301 ---- --------- ! * My wife Yulia - she helped me to edit the initial version of this manuals. All mistakes and bugs are mine. I'd like to believe that I know `Python`_ better then English. *************** *** 298,302 **** * Brad King for `GCC-XML`_ ! * Detlev Offenbach for `Eric 3.4`_ * `Docutils`_ - easy to use documentation system --- 303,307 ---- * Brad King for `GCC-XML`_ ! * Detlev Offenbach for `Eric 3.6`_ * `Docutils`_ - easy to use documentation system *************** *** 305,308 **** --- 310,315 ---- `SourceForge`_ + * John Pallister <jo...@sy...> - he helped me to edit\\correct documentation + * Hosted by |SourceForge|__ Index: definition.rest =================================================================== RCS file: /cvsroot/pygccxml/source/pygccxml/docs/definition.rest,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -d -r1.2 -r1.3 *** definition.rest 16 Jan 2006 05:59:44 -0000 1.2 --- definition.rest 5 Mar 2006 05:39:08 -0000 1.3 *************** *** 6,10 **** -- Introduction to `GCC-XML`_ ! The purpose of `pygccxml`_ is to read a generated file and provide simple framework to navigate C++ declarations using Python classes. --- 6,10 ---- -- Introduction to `GCC-XML`_ ! The purpose of `pygccxml`_ is to read a generated file and provide a simple framework to navigate C++ declarations using Python classes. |