[pygccxml-commit] SF.net SVN: pygccxml: [405]
Brought to you by:
mbaas,
roman_yakovenko
Menu
▾
▴
[pygccxml-commit] SF.net SVN: pygccxml: [405]
|
From: <rom...@us...> - 2006-08-15 10:41:49
|
Revision: 405 Author: roman_yakovenko Date: 2006-08-15 03:41:00 -0700 (Tue, 15 Aug 2006) ViewCVS: http://svn.sourceforge.net/pygccxml/?rev=405&view=rev Log Message: ----------- fix spelling errors Modified Paths: -------------- index.rest pydsc_dev/docs/pydsc.rest pygccxml_dev/docs/definition.rest pygccxml_dev/docs/design.rest pygccxml_dev/docs/history/history.rest pygccxml_dev/docs/pygccxml.rest pygccxml_dev/docs/query_interface.rest pyplusplus_dev/docs/comparisons/compare_to.rest pyplusplus_dev/docs/comparisons/pyste.rest pyplusplus_dev/docs/documentation/architecture.rest pyplusplus_dev/docs/documentation/best_practices.rest pyplusplus_dev/docs/documentation/containers.rest pyplusplus_dev/docs/documentation/doc_string.rest pyplusplus_dev/docs/documentation/feedback.rest pyplusplus_dev/docs/documentation/how_to.rest pyplusplus_dev/docs/documentation/index.rest pyplusplus_dev/docs/documentation/inserting_code.rest pyplusplus_dev/docs/documentation/tutorials/module_builder/module_builder.rest pyplusplus_dev/docs/documentation/tutorials/tutorials.rest pyplusplus_dev/docs/examples/boost/boost.rest pyplusplus_dev/docs/examples/easybmp/easybmp.rest pyplusplus_dev/docs/examples/examples.rest pyplusplus_dev/docs/history/history.rest pyplusplus_dev/docs/links.rest pyplusplus_dev/docs/peps/call_wrapper_policies.rest pyplusplus_dev/docs/peps/indexing_suite.rest pyplusplus_dev/docs/peps/peps_index.rest pyplusplus_dev/docs/pyplusplus.rest Modified: index.rest =================================================================== --- index.rest 2006-08-15 08:44:45 UTC (rev 404) +++ index.rest 2006-08-15 10:41:00 UTC (rev 405) @@ -1,86 +1,89 @@ -=========================== -C++ Python language binding -=========================== - -.. contents:: Table of contents - ----------------- -pygccxml package ----------------- - -* Do you need to parse C++ code? -* Do you need to build code generator? -* Do you need to create UML diagram? - -`pygccxml`_ is the way to go! `Learn more`__. - -.. __: `pygccxml`_ - ------------- -Py++ package ------------- +=========================== +C++ Python language binding +=========================== -"I love deadlines. I love the whooshing noise they make as they go by." +.. contents:: Table of contents - -- Douglas Adams +---------------- +pygccxml package +---------------- -Meet your deadlines with powerful code generator engine - `Py++`_. +* Do you need to parse C++ code? +* Do you need to build code generator? +* Do you need to create UML diagram? -`Py++`_ package and `Boost.Python`_ library provide a complete solution for -interfacing Python and C++. - ---------------- -pyboost package ---------------- - -`Boost`_ provides free peer-reviewed portable C++ source libraries. `pyboost`_ -package export next libraries to Python: - - * `Boost.Date_Time`_ - date time library designed to provide a basis for - performing efficient time calculations - * `Boost.CRC`_ - cyclic redundancy code computation objects - * `Boost.Rational`_ - rational number class - * `Boost.Random`_ - a complete system for random number generation - -Python bindings for `boost.graph`_ library is also available from -http://www.osl.iu.edu/~dgregor/bgl-python . - -------------- -pydsc package -------------- - -Documentation strings contain spelling errors? `Fix them in a minute`_. - -.. _`Fix them in a minute` : `pydsc`_ - ------------------ -pyeasybmp package ------------------ - -`EasyBMP`_ could be easier? Yes of course! Learn more about `EasyBMP Python bindings`_. - -.. _`EasyBMP Python bindings`: ./pyplusplus/examples/easybmp/easybmp.html +`pygccxml`_ is the way to go! `Learn more`__. -.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html - -.. _`pyboost` : ./pyplusplus/examples/boost/boost.html -.. _`boost.graph` : http://www.boost.org/libs/graph/doc/table_of_contents.html -.. _`boost.date_time` : http://boost.org/doc/html/date_time.html -.. _`boost.crc` : http://boost.org/libs/crc/index.html -.. _`boost.rational` : http://boost.org/libs/rational/index.html -.. _`boost.random` : http://boost.org/libs/random/index.html - -.. _`Boost`: http://boost.org/ -.. _`Python`: http://www.python.org -.. _`pygccxml`: ./pygccxml/pygccxml.html -.. _`Py++`: ./pyplusplus/pyplusplus.html -.. _`pydsc`: ./pydsc/pydsc.html -.. _`EasyBMP`: http://easybmp.sourceforge.net/ - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: +.. __: `pygccxml`_ + +------------ +Py++ package +------------ + +"I love deadlines. I love the whooshing noise they make as they go by." + + -- Douglas Adams + +Meet your deadlines with powerful code generator engine - `Py++`_. + +`Py++`_ package and `Boost.Python`_ library provide a complete solution for +interfacing Python and C++. `Learn more`_. + +.. _`Learn more` : `Py++`_ + +--------------- +pyboost package +--------------- + +`Boost`_ provides free peer-reviewed portable C++ source libraries. `pyboost`_ +package export next libraries to Python: + + * `Boost.Date_Time`_ - date time library designed to provide a basis for + performing efficient time calculations + * `Boost.CRC`_ - cyclic redundancy code computation objects + * `Boost.Rational`_ - rational number class + * `Boost.Random`_ - a complete system for random number generation + +Python bindings for `boost.graph`_ library is also available from +http://www.osl.iu.edu/~dgregor/bgl-python . + +------------- +pydsc package +------------- + +Documentation strings contain spelling errors? `Fix them in a minute`_. + +.. _`Fix them in a minute` : `pydsc`_ + +----------------- +pyeasybmp package +----------------- + +`EasyBMP`_ could be easier? Yes of course! Learn more about `EasyBMP Python bindings`_. + +.. _`EasyBMP Python bindings`: ./pyplusplus/examples/easybmp/easybmp.html + +.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html + +.. _`pyboost` : ./pyplusplus/examples/boost/boost.html +.. _`boost.graph` : http://www.boost.org/libs/graph/doc/table_of_contents.html +.. _`boost.date_time` : http://boost.org/doc/html/date_time.html +.. _`boost.crc` : http://boost.org/libs/crc/index.html +.. _`boost.rational` : http://boost.org/libs/rational/index.html +.. _`boost.random` : http://boost.org/libs/random/index.html + +.. _`Boost`: http://boost.org/ +.. _`Python`: http://www.python.org +.. _`pygccxml`: ./pygccxml/pygccxml.html +.. _`Py++`: ./pyplusplus/pyplusplus.html +.. _`pydsc`: ./pydsc/pydsc.html +.. _`EasyBMP`: http://easybmp.sourceforge.net/ + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: + Modified: pydsc_dev/docs/pydsc.rest =================================================================== --- pydsc_dev/docs/pydsc.rest 2006-08-15 08:44:45 UTC (rev 404) +++ pydsc_dev/docs/pydsc.rest 2006-08-15 10:41:00 UTC (rev 405) @@ -1,34 +1,33 @@ -================== -pydsc introduction -================== - -.. contents:: Table of contents - -.. meta:: - :description: Python documentation string spell checker +================== +pydsc introduction +================== + +.. contents:: Table of contents + +.. meta:: + :description: Python documentation string spell checker :keywords: Python, docstring, documentation, spell, check - , документация, спеллер, орфографическая коррекция, - --------------- -What is pydsc? --------------- - -.. include:: ./definition.rest - ----------------------- -What it is useful for? ----------------------- - -Well, this project was born to solve real problem - I made a lot of mistakes, -while writing documentation for my projects. I needed some way to check all -Python documentation strings, before I generate documentation from source files. -My goal was simplicity + easy customization. I achieved it. Here is example of -usage of pydsc: - + , документация, спеллер, орфографическая коррекция, + +-------------- +What is pydsc? +-------------- + +.. include:: ./definition.rest + +---------------------- +What it is useful for? +---------------------- + +Well, this project was born to solve real problem - I made a lot of mistakes, +when I write source code documentation for my projects. I needed some way to +check all the documentation strings. My goal was simplicity + easy customization. +I achieved it. Here is example of usage of pydsc: + | ``import pydsc`` -| ``#every module that will be imported after pydsc will be checked`` -| ``#all errors will be printed to stdout`` -| ``import readline`` +| ``#every module that will be imported after pydsc will be checked`` +| ``#all errors will be printed to stdout`` +| ``import readline`` -------------- Spell checking @@ -42,7 +41,7 @@ Usage example ------------- -Basic usage is really simple, but sometimes there is a need to: +Basic usage is really simple, but sometimes there is a need to: * skip\\exclude some words from checking * redefine error messages destination, for example to print to some file * exclude(include) files from(to) spell checking process by file location @@ -62,14 +61,15 @@ http://sourceforge.net/project/showfiles.php?group_id=118209 - -.. _`pydsc`: ./pydsc.html + +.. _`pydsc`: ./pydsc.html .. _`PyEnchant`: http://pyenchant.sourceforge.net/ - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: + Modified: pygccxml_dev/docs/definition.rest =================================================================== --- pygccxml_dev/docs/definition.rest 2006-08-15 08:44:45 UTC (rev 404) +++ pygccxml_dev/docs/definition.rest 2006-08-15 10:41:00 UTC (rev 405) @@ -1,11 +1,11 @@ -"...The purpose of the `GCC-XML`_ extension is to generate an XML description -of a C++ program from GCC's internal representation. Since XML is easy to parse, -other development tools will be able to work with C++ programs without the -burden of a complicated C++ parser..." - --- 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. - -.. _`GCC-XML` : http://www.gccxml.org \ No newline at end of file +"...The purpose of the `GCC-XML`_ extension is to generate an XML description +of a C++ program from GCC's internal representation. Since XML is easy to parse, +other development tools will be able to work with C++ programs without the +burden of a complicated C++ parser..." + +-- 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. + +.. _`GCC-XML` : http://www.gccxml.org Modified: pygccxml_dev/docs/design.rest =================================================================== --- pygccxml_dev/docs/design.rest 2006-08-15 08:44:45 UTC (rev 404) +++ pygccxml_dev/docs/design.rest 2006-08-15 10:41:00 UTC (rev 405) @@ -1,296 +1,295 @@ -=============== -pygccxml design -=============== - -.. contents:: Table of contents - ------------------------- -The view from 10000 fits ------------------------- - -`pygccxml`_ has 3 packages: - -* ``declarations`` package defines classes that describe C++ declarations and types - -* ``parser`` package defines classes that parse `GCC-XML`_ generared files. Also - it defines few classes that will help you to eliminate unnecessary parsing of - C++ source files. - -* ``utils`` package defines few functions, I found useful in the whole project. - -------------------------- -``declarations`` package -------------------------- - -Please take a look on `UML diagram`_. This `UML diagram`_ describes almost all -classes defined in the package and their relationship. ``declarations`` package -defines two hierarchies of class: - -1. types hierarchy - used to represent a C++ type - -2. declarations hierarchy - used to represent a C++ declaration. - - -Types hierarchy ---------------- - -Types hierarchy is used to represent an arbitrary type in C++. class ``type_t`` -is the base class. - -``type_traits`` -~~~~~~~~~~~~~~~ - -Are you aware of `boost::type_traits`_ library? The `boost::type_traits`_ -library has been developed by John Maddock, Steve Cleary and others. The -`boost::type_traits`_ library contains a set of very specific traits classes, -each of which encapsulate a single trait from the C++ type system; for example, -is a type a pointer or a reference type? Or does a type have a trivial constructor, -or a const-qualifier? - -`pygccxml`_ implements a lot of functionality from the library: - -* a lot of algorithms has been implemented - - + ``is_same`` - - + ``is_enum`` - - + ``is_void`` - - + ``is_const`` - - + ``is_array`` - - + ``is_pointer`` - - + ``is_volatile`` - - + ``is_integral`` - - + ``is_reference`` - - + ``is_arithmetic`` - - + ``is_convertible`` - - + ``is_fundamental`` - - + ``is_floating_point`` - - + ``is_base_and_derived`` - - + ``is_unary_operator`` - - + ``is_binary_operator`` - - + ``remove_cv`` - - + ``remove_const`` - - + ``remove_alias`` - - + ``remove_pointer`` - - + ``remove_volatile`` - - + ``remove_reference`` - - + ``has_trivial_copy`` - - + ``has_trivial_constructor`` - - + ``has_any_non_copyconstructor`` - - For a full list of implemented algorithms, please consult API documentation. - -* a lot of unit tests has been written base on unit tests from the - `boost::type_traits`_ library. - - -If you are going to build code generator, you will find ``type_traits`` very handy. - -Declarations hierarchy ----------------------- - -A declaration hierarchy is used to represent an arbitrary C++ declaration. -Basically, most of the classes defined in this package are just "set of properties". - -``declaration_t`` is the base class of the declaration hierarchy. Every declaration -has ``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. ``class_t`` and ``namespace_t`` declaration classes derive from the -``scopedef_t`` class. - ------------------- -``parser`` package ------------------- - -Please take a look on `parser package UML diagram`_ . Classes defined in this -package implement parsing and linking functionality. There are few kind of -classes defined by the package: - -* classes, that implements parsing algorithms of `GCC-XML`_ generated XML file - -* classes, that configure "parser" - -* cache - classes, those one will help you to eliminate unnecessary parsing - -* patchers - classes, that fix `GCC-XML`_ generated declarations. ( Yes, sometimes - GCC-XML generates wrong description of C++ declaration. ) - -Parser classes --------------- - -``source_reader_t`` - the only class that have an detailed knowledge about `GCC-XML`_. -It has only one responsibility: it calls `GCC-XML`_ with a source file specified -by user and creates declarations tree. The implementation of this class is split -to 2 classes: - -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. - -Both those classes are implementation details and should not be used by user. -Performance note: ``scanner_t`` class uses Python ``xml.sax`` package in order -to parse XML. As a result, ``scanner_t`` class is able to parse even big XML files -pretty quick. - -``project_reader_t`` - think about this class as a linker. In most cases you work -with few source files. GCC-XML does not supports this mode of work. So, `pygccxml`_ -implements all functionality needed to parse few source files at once. -``project_reader_t`` implements 2 different algorithms, that solves the problem: - -1. ``project_reader_t`` creates temporal source file, that includes all the source - files. - -2. ``project_reader_t`` parse separately every source file, using ``source_reader_t`` - class and then joins the resulting declarations tree into single declarations - tree. - -Both approaches have different trades-off. The first approach does not allow you -to reuse information from already parsed source files. While the second one -allows you to setup cache. - -Parser configuration classes ----------------------------- - -``config_t`` - a class, that accumulates all the settings needed to invoke `GCC-XML`_: - - -``file_configuration_t`` - a class, that contains some data and description how -to treat the data. ``file_configuration_t`` can contain reference to the next types -of data: - -(1) path to C++ source file - -(2) path to `GCC-XML`_ generated XML file - -(3) path to C++ source file and path to `GCC-XML`_ generated XML file - - In this case, if XML file does not exists, it will be created. Next time - you will ask to parse the source file, the XML file will be used instead. - - Small tip: you can setup your makefile to delete XML files every time, - the relevant source file has changed. - -(4) Python string, that contains valid C++ code - -There are few functions, that will help you to construct ``file_configuration_t`` -object: - -* ``def create_source_fc( header )`` - - ``header`` contains path to C++ source file - -* ``def create_gccxml_fc( xml_file )`` - - ``xml_file`` contains path to `GCC-XML`_ generated XML file - -* ``def create_cached_source_fc( header, cached_source_file )`` - - - ``header`` contains path to C++ source file - - ``xml_file`` contains path to `GCC-XML`_ generated XML file - -* ``def create_text_fc( text )`` - - ``text`` - Python string, that contains valid C++ code - - -Cache classes -------------- - -There are few cache classes, that implements different cache strategies. - -1. ``file_configuration_t`` class, that keeps pass to C++ source file and path to - `GCC-XML`_ generated XML file. This class is not a cache class, but it also - allows you to save your time. - -2. ``file_cache_t`` class, will save all declarations from all files within single - binary file. - -3. ``directory_cache_t`` class will store one index file called "index.dat" which - is always read by the cache when the cache object is created. Each header file - will have its corresponding \*.cache file that stores the declarations found - in the header file. The index file is used to determine whether a \*.cache file - is still valid or not (by checking if one of the dependent files - (i.e. the header file itself and all included files) have been modified since - the last run). - -In some cases, ``directory_cache_t`` class gives much better performance, than -``file_cache_t``. Many thanks to Matthias Baas for its implemention. - -**Warning**: when `pygccxml`_ writes information to files, using cache classes, -it does not write any version information. It means, that when you upgrade -`pygccxml`_ you have to delete all your cache files. Otherwise you will get very -strange errors. For example: missing attribute. - - -Patchers --------- - -Well, `GCC-XML`_ has few bugs, that could not be fixed from it. For example -:: - - namespace ns1{ namespace ns2{ - enum fruit{ apple, orange }; - } } - - void fix_enum( ns1::ns2::fruit arg=ns1::ns2::apple ); - -`GCC-XML`_ will report the default value of ``arg`` as ``apple``. Obviously -this in an error. `pygccxml`_ knows how to fix this bug. - -This is not the only bug, that could be fixed, there are few of them. `pygccxml`_ -introduces few classes, that knows how to deal with specific bug. More over, those -bugs are fixed, only if I am 101% sure, that this is the right thing to do. - -------- -Summary -------- - -Thats all. I hope I was clear, at least I tried. Any way, `pygccxml`_ is an open -source project. You always can take a look on the source code. If you need more -information please read API documentation. - -.. _`pygccxml`: ./pygccxml.html -.. _`SourceForge`: http://sourceforge.net/index.php -.. _`Python`: http://www.python.org -.. _`GCC-XML`: http://www.gccxml.org -.. _`UML diagram` : ./declarations_uml.png -.. _`parser package UML diagram` : ./parser_uml.png -.. _`ReleaseForge` : http://releaseforge.sourceforge.net -.. _`boost::type_traits` : http://www.boost.org/libs/type_traits/index.html -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: \ No newline at end of file +=============== +pygccxml design +=============== + +.. contents:: Table of contents + +------------------------ +The view from 10000 fits +------------------------ + +`pygccxml`_ has 3 packages: + +* ``declarations`` package defines classes that describe C++ declarations and types + +* ``parser`` package defines classes that parse `GCC-XML`_ generated files. Also + it defines few classes that will help you to eliminate unnecessary parsing of + C++ source files. + +* ``utils`` package defines few functions, I found useful in the whole project. + +------------------------- +``declarations`` package +------------------------- + +Please take a look on `UML diagram`_. This `UML diagram`_ describes almost all +classes defined in the package and their relationship. ``declarations`` package +defines two hierarchies of class: + +1. types hierarchy - used to represent a C++ type + +2. declarations hierarchy - used to represent a C++ declaration + + +Types hierarchy +--------------- + +Types hierarchy is used to represent an arbitrary type in C++. class ``type_t`` +is the base class. + +``type_traits`` +~~~~~~~~~~~~~~~ + +Are you aware of `boost::type_traits`_ library? The `boost::type_traits`_ +library contains a set of very specific traits classes, each of which +encapsulate a single trait from the C++ type system; for example, is a type +a pointer or a reference? Or does a type have a trivial constructor, or a +const-qualifier? + +`pygccxml`_ implements a lot of functionality from the library: + +* a lot of algorithms were implemented + + + ``is_same`` + + + ``is_enum`` + + + ``is_void`` + + + ``is_const`` + + + ``is_array`` + + + ``is_pointer`` + + + ``is_volatile`` + + + ``is_integral`` + + + ``is_reference`` + + + ``is_arithmetic`` + + + ``is_convertible`` + + + ``is_fundamental`` + + + ``is_floating_point`` + + + ``is_base_and_derived`` + + + ``is_unary_operator`` + + + ``is_binary_operator`` + + + ``remove_cv`` + + + ``remove_const`` + + + ``remove_alias`` + + + ``remove_pointer`` + + + ``remove_volatile`` + + + ``remove_reference`` + + + ``has_trivial_copy`` + + + ``has_trivial_constructor`` + + + ``has_any_non_copyconstructor`` + + For a full list of implemented algorithms, please consult API documentation. + +* a lot of unit tests has been written base on unit tests from the + `boost::type_traits`_ library. + + +If you are going to build code generator, you will find ``type_traits`` very handy. + +Declarations hierarchy +---------------------- + +A declaration hierarchy is used to represent an arbitrary C++ declaration. +Basically, most of the classes defined in this package are just "set of properties". + +``declaration_t`` is the base class of the declaration hierarchy. Every declaration +has ``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. ``class_t`` and ``namespace_t`` declaration classes derive from the +``scopedef_t`` class. + +------------------ +``parser`` package +------------------ + +Please take a look on `parser package UML diagram`_ . Classes defined in this +package, implement parsing and linking functionality. There are few kind of +classes defined by the package: + +* classes, that implements parsing algorithms of `GCC-XML`_ generated XML file + +* parser configuration classes + +* cache - classes, those one will help you to eliminate unnecessary parsing + +* patchers - classes, that fix `GCC-XML`_ generated declarations. ( Yes, sometimes + GCC-XML generates wrong description of C++ declaration. ) + +Parser classes +-------------- + +``source_reader_t`` - the only class that have a detailed knowledge about `GCC-XML`_. +It has only one responsibility: it calls `GCC-XML`_ with a source file specified +by user and creates declarations tree. The implementation of this class is split +to 2 classes: + +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 ids. + +2. ``linker_t`` - this class contains logic for replacing `GCC-XML`_ generated + ids with references to declarations or type class instances. + +Both those classes are implementation details and should not be used by user. +Performance note: ``scanner_t`` class uses Python ``xml.sax`` package in order +to parse XML. As a result, ``scanner_t`` class is able to parse even big XML files +pretty quick. + +``project_reader_t`` - think about this class as a linker. In most cases you work +with few source files. GCC-XML does not supports this mode of work. So, `pygccxml`_ +implements all functionality needed to parse few source files at once. +``project_reader_t`` implements 2 different algorithms, that solves the problem: + +1. ``project_reader_t`` creates temporal source file, which includes all the source + files. + +2. ``project_reader_t`` parse separately every source file, using ``source_reader_t`` + class and then joins the resulting declarations tree into single declarations + tree. + +Both approaches have different trades-off. The first approach does not allow you +to reuse information from already parsed source files. While the second one +allows you to setup cache. + +Parser configuration classes +---------------------------- + +``config_t`` - a class, that accumulates all the settings needed to invoke `GCC-XML`_: + + +``file_configuration_t`` - a class, that contains some data and description how +to treat the data. ``file_configuration_t`` can contain reference to the next types +of data: + +(1) path to C++ source file + +(2) path to `GCC-XML`_ generated XML file + +(3) path to C++ source file and path to `GCC-XML`_ generated XML file + + In this case, if XML file does not exists, it will be created. Next time + you will ask to parse the source file, the XML file will be used instead. + + Small tip: you can setup your makefile to delete XML files every time, + the relevant source file has changed. + +(4) Python string, that contains valid C++ code + +There are few functions that will help you to construct ``file_configuration_t`` +object: + +* ``def create_source_fc( header )`` + + ``header`` contains path to C++ source file + +* ``def create_gccxml_fc( xml_file )`` + + ``xml_file`` contains path to `GCC-XML`_ generated XML file + +* ``def create_cached_source_fc( header, cached_source_file )`` + + - ``header`` contains path to C++ source file + - ``xml_file`` contains path to `GCC-XML`_ generated XML file + +* ``def create_text_fc( text )`` + + ``text`` - Python string, that contains valid C++ code + + +Cache classes +------------- + +There are few cache classes, which implements different cache strategies. + +1. ``file_configuration_t`` class, that keeps pass to C++ source file and path to + `GCC-XML`_ generated XML file. This class is not a cache class, but it also + allows you to save your time. + +2. ``file_cache_t`` class, will save all declarations from all files within single + binary file. + +3. ``directory_cache_t`` class will store one index file called "index.dat" which + is always read by the cache when the cache object is created. Each header file + will have its corresponding \*.cache file that stores the declarations found + in the header file. The index file is used to determine whether a \*.cache file + is still valid or not (by checking if one of the dependent files + (i.e. the header file itself and all included files) have been modified since + the last run). + +In some cases, ``directory_cache_t`` class gives much better performance, than +``file_cache_t``. Many thanks to Matthias Baas for its implementation. + +**Warning**: when `pygccxml`_ writes information to files, using cache classes, +it does not write any version information. It means, that when you upgrade +`pygccxml`_ you have to delete all your cache files. Otherwise you will get very +strange errors. For example: missing attribute. + + +Patchers +-------- + +Well, `GCC-XML`_ has few bugs, which could not be fixed from it. For example +:: + + namespace ns1{ namespace ns2{ + enum fruit{ apple, orange }; + } } + + void fix_enum( ns1::ns2::fruit arg=ns1::ns2::apple ); + +`GCC-XML`_ will report the default value of ``arg`` as ``apple``. Obviously +this in an error. `pygccxml`_ knows how to fix this bug. + +This is not the only bug, which could be fixed, there are few of them. `pygccxml`_ +introduces few classes, which knows how to deal with specific bug. More over, those +bugs are fixed, only if I am 101% sure, that this is the right thing to do. + +------- +Summary +------- + +Thats all. I hope I was clear, at least I tried. Any way, `pygccxml`_ is an open +source project. You always can take a look on the source code. If you need more +information please read API documentation. + +.. _`pygccxml`: ./pygccxml.html +.. _`SourceForge`: http://sourceforge.net/index.php +.. _`Python`: http://www.python.org +.. _`GCC-XML`: http://www.gccxml.org +.. _`UML diagram` : ./declarations_uml.png +.. _`parser package UML diagram` : ./parser_uml.png +.. _`ReleaseForge` : http://releaseforge.sourceforge.net +.. _`boost::type_traits` : http://www.boost.org/libs/type_traits/index.html +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: Modified: pygccxml_dev/docs/history/history.rest =================================================================== --- pygccxml_dev/docs/history/history.rest 2006-08-15 08:44:45 UTC (rev 404) +++ pygccxml_dev/docs/history/history.rest 2006-08-15 10:41:00 UTC (rev 405) @@ -1,289 +1,289 @@ -============================ -pygccxml development history -============================ - -.. contents:: Table of contents - ------------- -Contributors ------------- - -Thanks to all the people that have contributed patches, bug reports and suggestions: - - * My wife - Yulia - * John Pallister - * Matthias Baas - * Allen Bierbaum - * Georgiy Dernovoy - * Darren Garnier - ------ -0.8.1 ------ - -1. `pygccxml`_ has been ported to MacOS X. Many thanks to Darren Garnier! +============================ +pygccxml development history +============================ -2. New type traits have been added: - - * ``enum_traits`` - * ``class_traits`` - * ``class_declaration_traits`` - * ``is_std_string`` - * ``is_std_wstring`` - * ``remove_declarated`` - * ``has_public_less`` - * ``has_public_equal`` - * ``has_public_binary_operator`` - * ``smart_pointer_traits`` - * ``list_traits`` - * ``deque_traits`` - * ``queue_traits`` - * ``priority_queue`` - * ``vector_traits`` - * ``stack_traits`` - * ``map_traits`` - * ``multimap_traits`` - * ``hash_map_traits`` - * ``hash_multimap_traits`` - * ``set_traits`` - * ``hash_set_traits`` - * ``multiset_traits`` - * ``hash_multiset_traits`` - -3. ``enumeration_t`` class interface was changed. Enumeration values are kept - in a list, instead of a dictionary. ``get_name2value_dict`` will build for - you dictionary, where key is an enumeration name, and value is an enumeration - value. - - This has been done in order to provide stable order of enumeration values. - -4. Now you can pass operator symbol, as a name to query functions: +.. contents:: Table of contents - :: +------------ +Contributors +------------ - cls = global_namespace.class_( 'my_class' ) - op = cls.operator( '<' ) - #instead of - op = cls.operator( symbol='<' ) +Thanks to all the people that have contributed patches, bug reports and suggestions: -5. `pygccxml`_ improved a lot functionality related to providing feedback to user: - - * every package has its own logger - - * only important user messages are written to ``stdout`` - - * user messages are clear + * My wife - Yulia + * John Pallister + * Matthias Baas + * Allen Bierbaum + * Georgiy Dernovoy + * Darren Garnier -6. Support to Java native types has been added. +----- +0.8.1 +----- -7. It is possible to pass an arbitrary string as a parameter to `GCC-XML`_. +1. `pygccxml`_ has been ported to MacOS X. Many thanks to Darren Garnier! + +2. New type traits have been added: + + * ``enum_traits`` + * ``class_traits`` + * ``class_declaration_traits`` + * ``is_std_string`` + * ``is_std_wstring`` + * ``remove_declarated`` + * ``has_public_less`` + * ``has_public_equal`` + * ``has_public_binary_operator`` + * ``smart_pointer_traits`` + * ``list_traits`` + * ``deque_traits`` + * ``queue_traits`` + * ``priority_queue`` + * ``vector_traits`` + * ``stack_traits`` + * ``map_traits`` + * ``multimap_traits`` + * ``hash_map_traits`` + * ``hash_multimap_traits`` + * ``set_traits`` + * ``hash_set_traits`` + * ``multiset_traits`` + * ``hash_multiset_traits`` + +3. ``enumeration_t`` class interface was changed. Enumeration values are kept + in a list, instead of a dictionary. ``get_name2value_dict`` will build for + you dictionary, where key is an enumeration name, and value is an enumeration + value. + + This has been done in order to provide stable order of enumeration values. + +4. Now you can pass operator symbol, as a name to query functions: + + :: + + cls = global_namespace.class_( 'my_class' ) + op = cls.operator( '<' ) + #instead of + op = cls.operator( symbol='<' ) + +5. `pygccxml`_ improved a lot functionality related to providing feedback to user: + + * every package has its own logger + + * only important user messages are written to ``stdout`` + + * user messages are clear + +6. Support to Java native types has been added. + +7. It is possible to pass an arbitrary string as a parameter to `GCC-XML`_. + +8. Native java types has been added to fundamental types. + +9. Cache classes implementation was improved. + +10. Few bug were fixed. + +11. Documentation was improved. + + +----------- +Version 0.8 +----------- -8. Native java types has been added to fundamental types. +1. `pygccxml`_ now has power "select" interface. Read more about this cool feature + in tutorials. -9. Cache classes implementation was improved. +2. Improved support for template instantiations. `pygccxml`_ now take into + account demangled name of declarations. Please refer to documentation for + more explanantion. -10. Few bug were fixed. +3. ``dummy_type_t`` - new type in types hierarchy. This is a very useful class + for code generation projects. -11. Documentation was improved. +4. New function - ``get_global_namespace``. As you can guess, it will find and + return reference to global namespace. +5. New functionality in ``type_traits`` - ``has_public_assign``. This function + will return True, if class has public assign operator. ------------ -Version 0.8 ------------ - -1. `pygccxml`_ now has power "select" interface. Read more about this cool feature - in tutorials. - -2. Improved support for template instantiations. `pygccxml`_ now take into - account demangled name of declarations. Please refer to documentation for - more explanantion. - -3. ``dummy_type_t`` - new type in types hierarchy. This is a very useful class - for code generation projects. - -4. New function - ``get_global_namespace``. As you can guess, it will find and - return reference to global namespace. - -5. New functionality in ``type_traits`` - ``has_public_assign``. This function - will return True, if class has public assign operator. - -6. ``declarations.class_t`` has new property - ``aliases``. This is a list of - all class aliases. - -7. Bug fixes. - -8. Documentation has been updated/written/improved. - -------------- -Version 0.7.1 -------------- - -**Attention - this going to be last version that is tested with Python 2.3** - -1. New fundamental types has been added - - * complex float - - * complex double - - * complex long double - -2. **Attention - non backward compatible change** - - ``declarations.filtering.user_defined`` and ``declarations.filtering.by_location`` - implementation has been changed. In previous version of those functions, - ``decls`` list has been changed in place. This was wrong behaviour. Now, - those functions will return new list, that contains all desired declarations. - -3. Few new type traits has been added - - * *type_traits.has_destructor* - - * *type_traits.has_public_destructor* - - * *type_traits.has_public_constructor* - - * *type_traits.is_noncopyable* - -4. ``decl_printer_t`` class and ``print_declarations`` function have been added. - Now you can print in a nice way your declaration tree or part of it. - Thanks to Allen Bierbaum! - -5. New class ``declarations.decl_factory_t`` has been added. This is a default - factory for all declarations. From now all relevant parser classes takes as - input instance of this class or ``Null``. In case of ``Null`` instance of - ``declarations.decl_factory_t`` will be created. Using this class you can - easily extend functionality provided by built-in declarations. - -6. Sometimes, there is a need to find a declaration that match some criteria. - The was such functionality in `pygccxml`_, but it was too limited. This - release fix the situation. `pygccxml`_ adds a set of classes that will help - you to deal with this problem. - -7. New cache - ``parser.directory_cache_t`` has been implemented. - ``parser.directory_cache_t`` uses individual files stored in a dedicated - cache directory to store the cached contents. - Thanks to Matthias Baas! - -8. ``parser.file_cache_t`` has been improved a lot. - Thanks to Allen Bierbaum! - -9. New file configuration is available: "cached source file". - ``parser.project_reader_t`` class will check for existence of `GCC-XML`_ - generated file. If it does not exist it will create one. If it do exist, - then that file will be used by the parser. - -10. Few helper functions has been added in order to make construction of - configuration file to be as easy as possible: - - * ``parser.create_text_fc`` - creates file configuration, that contains text - * ``parser.create_source_fc`` - creates file configuration, that contains - reference to regular source file - * ``parser.create_gccxml_fc`` - creates file configuration, that contains - reference to `GCC-XML`_ generated file - * ``parser.create_cached_source_fc`` - creates file configuration, that - contains reference to 2 files: `GCC-XML`_ generated file and regular source - file - -11. Small bug fixes. - -12. Documentation. Allen Bierbaum and Matthias Baas contributed so much in this - area. Almost every public function/class has now documentation string. - -13. Logging functionality has been added. `pygccxml`_ creates new logger - "pygccxml". Now it is possible to see what `pygccxml`_ is doing right now. - -14. I am sure I forgot something. - - -------------- -Version 0.6.9 -------------- - -1. New functions: - - * *type_traits.is_void_pointer* - - * *type_traits.array_size* - - * *type_traits.array_item_type* - -2. Class *declarations.variable_t* has new property - *bit_fields* - -3. Now it is possible to specify "undefined" directives using - *parser.config_t* class. - -4. *patch* functionality has been introduced. `GCC-XML`_ generates wrong - default values for function arguments. *patch* functionality tries to fix - this. - -5. Small bug fixes - -------------- -Version 0.6.8 -------------- - -1. Small bug has been fixed. - -------------- -Version 0.6.7 -------------- - -1. New functions: - - * *type_traits.remove_pointer* - - * *type_traits.base_type* - - * *type_traits.is_convertible* - -2. A lot of small bug fixes. - -3. Few English mistakes have been fixed. - - .. attention:: - - There are 2 none backward compatible changes: - - * class with name **compaund_t** has been renamed to **compound_t** - - * word **pathes** has been replaced with **paths** - -4. There are new properties on - - * *declarations.declaration_t.top_parent* - - * *declarations.class_t.recursive_bases* returns all base classes of the - class - - * *declarations.class_t.recursive_derived* returns all derived classes of - the class - - * *member_calldef_t.access_type* - -5. New type has been introduced: *unknown_t*. There are use cases when - `GCC-XML`_ does not returns function return type. - -6. New implementation of *make_flatten* algorithm using generators. - By default old implementation will be used. - -7. *parser.file_configuration_t* interface has been changed. Now it is able - to keep: source file, text or `GCC-XML`_ generated file. If you are doing - something with code that is not changing you'd better use `GCC-XML`_ - generated file as content of the *parser.file_configuration_t*. Save your - time. - -8. There are some cases when `GCC-XML`_ reports *"restricted"*. In this case - `pygccxml`_ replaces *"restricted"* with *"volatile"*. - - -.. _`pygccxml`: ./../pygccxml.html -.. _`SourceForge`: http://sourceforge.net/index.php -.. _`GCC-XML`: http://www.gccxml.org -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: \ No newline at end of file +6. ``declarations.class_t`` has new property - ``aliases``. This is a list of + all class aliases. + +7. Bug fixes. + +8. Documentation has been updated/written/improved. + +------------- +Version 0.7.1 +------------- + +**Attention - this going to be last version that is tested with Python 2.3** + +1. New fundamental types has been added + + * complex float + + * complex double + + * complex long double + +2. **Attention - non backward compatible change** + + ``declarations.filtering.user_defined`` and ``declarations.filtering.by_location`` + implementation has been changed. In previous version of those functions, + ``decls`` list has been changed in place. This was wrong behavior. Now, + those functions will return new list, which contains all desired declarations. + +3. Few new type traits has been added + + * *type_traits.has_destructor* + + * *type_traits.has_public_destructor* + + * *type_traits.has_public_constructor* + + * *type_traits.is_noncopyable* + +4. ``decl_printer_t`` class and ``print_declarations`` function have been added. + Now you can print in a nice way your declaration tree or part of it. + Thanks to Allen Bierbaum! + +5. New class ``declarations.decl_factory_t`` has been added. This is a default + factory for all declarations. From now all relevant parser classes takes as + input instance of this class or ``Null``. In case of ``Null`` instance of + ``declarations.decl_factory_t`` will be created. Using this class you can + easily extend functionality provided by built-in declarations. + +6. Sometimes, there is a need to find a declaration that match some criteria. + The was such functionality in `pygccxml`_, but it was too limited. This + release fix the situation. `pygccxml`_ adds a set of classes that will help + you to deal with this problem. + +7. New cache - ``parser.directory_cache_t`` has been implemented. + ``parser.directory_cache_t`` uses individual files stored in a dedicated + cache directory to store the cached contents. + Thanks to Matthias Baas! + +8. ``parser.file_cache_t`` has been improved a lot. + Thanks to Allen Bierbaum! + +9. New file configuration is available: "cached source file". + ``parser.project_reader_t`` class will check for existence of `GCC-XML`_ + generated file. If it does not exist it will create one. If it do exist, + then the parser will use that file. + +10. Few helper functions has been added in order to make construction of + configuration file to be as easy as possible: + + * ``parser.create_text_fc`` - creates file configuration, that contains text + * ``parser.create_source_fc`` - creates file configuration, that contains + reference to regular source file + * ``parser.create_gccxml_fc`` - creates file configuration, that contains + reference to `GCC-XML`_ generated file + * ``parser.create_cached_source_fc`` - creates file configuration, that + contains reference to 2 files: `GCC-XML`_ generated file and regular source + file + +11. Small bug fixes. + +12. Documentation. Allen Bierbaum and Matthias Baas contributed so much in this + area. Almost every public function/class has now documentation string. + +13. Logging functionality has been added. `pygccxml`_ creates new logger + "pygccxml". Now it is possible to see what `pygccxml`_ is doing right now. + +14. I am sure I forgot something. + + +------------- +Version 0.6.9 +------------- + +1. New functions: + + * *type_traits.is_void_pointer* + + * *type_traits.array_size* + + * *type_traits.array_item_type* + +2. Class *declarations.variable_t* has new property - *bit_fields* + +3. Now it is possible to specify "undefined" directives using + *parser.config_t* class. + +4. *patch* functionality has been introduced. `GCC-XML`_ generates wrong + default values for function arguments. *patch* functionality tries to fix + this. + +5. Small bug fixes + +------------- +Version 0.6.8 +------------- + +1. Small bug has been fixed. + +------------- +Version 0.6.7 +------------- + +1. New functions: + + * *type_traits.remove_pointer* + + * *type_traits.base_type* + + * *type_traits.is_convertible* + +2. A lot of small bug fixes. + +3. Few English mistakes have been fixed. + + .. attention:: + + There are 2 none backward compatible changes: + + * class with name **compaund_t** has been renamed to **compound_t** + + * word **pathes** has been replaced with **paths** + +4. There are new properties on + + * *declarations.declaration_t.top_parent* + + * *declarations.class_t.recursive_bases* returns all base classes of the + class + + * *declarations.class_t.recursive_derived* returns all derived classes of + the class + + * *member_calldef_t.access_type* + +5. New type has been introduced: *unknown_t*. There are use cases when + `GCC-XML`_ does not returns function return type. + +6. New implementation of *make_flatten* algorithm using generators. + By default old implementation will be used. + +7. *parser.file_configuration_t* interface has been changed. Now it is able + to keep: source file, text or `GCC-XML`_ generated file. If you are doing + something with code that is not changing you'd better use `GCC-XML`_ + generated file as content of the *parser.file_configuration_t*. Save your + time. + +8. There are some cases when `GCC-XML`_ reports *"restricted"*. In this case + `pygccxml`_ replaces *"restricted"* with *"volatile"*. + + +.. _`pygccxml`: ./../pygccxml.html +.. _`SourceForge`: http://sourceforge.net/index.php +.. _`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: pygccxml_dev/docs/pygccxml.rest =================================================================== --- pygccxml_dev/docs/pygccxml.rest 2006-08-15 08:44:45 UTC (rev 404) +++ pygccxml_dev/docs/pygccxml.rest 2006-08-15 10:41:00 UTC (rev 405) @@ -1,144 +1,144 @@ -====================== -pygccxml documentation -====================== - -.. contents:: Table of contents - -.. meta:: - :description: C++ declarations parser - :keywords: C++, source code, header file, parser, UML, free, declarations - , XML, class hierarchy, analize, AST, code generator, - , синтаксический анализатор, исходный текст, исходная программа - , описание, определение, иерархия классов, генератор кода - ------------- -Introduction ------------- -.. include:: ./definition.rest - ----------------------- -What can I do with it? ----------------------- -Using `pygccxml`_ you can: - -* parse C++ source code -* build a code generator - - + `Py++`_ is heavily based on `pygccxml`_ - + generate `WSDL`_ file from sources - + ... - -* create UML diagrams -* build code analyzer -* ... - -------------- -Usage example -------------- -First of all let's see a small and simple `example`_. This example prints all -declarations, reported by `GCC-XML`_ after parsing `core_class_hierarchy.hpp`_ -file. Also it prints all clasess, and for every class it will print it's base -and derived classes. It was simple task, right? If you are still curious how it -looks "in the real life", I mean how xml file is look like, you may look at the -`original XML file`_ generated by `GCC-XML`_. - -.. _`original XML file` : ./example/core_class_hierarchy.hpp.xml -.. _`core_class_hierarchy.hpp` : ./example/core_class_hierarchy.hpp -.. _`example` : ./example/example.py - --------- -Features --------- - -Caching -------- - -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. - -Type traits ------------ - -`pygccxml`_ provides a lot of functionality to analize C++ types and relationship -between them. For more information please refer to `design`__ document or API -documentation. Just a few names of algorithms: - -* ``is_convertible( from, to )`` - - returns ``True`` if there is a conversion from type ``from`` to type ``to``, - otherwise ``False`` - -* ``is_unary_operator( oper )`` - - returns ``True`` if ``oper`` describes unary operator - -.. __: ./design.html - - -Query interface ---------------- - -`pygccxml`_ provides simple and powerful API to query declarations tree. I will -try to give small example, that will prove my point. If you want to know more -about provided API please read `query interface`__ document or API documentation. -Examples: -:: - - #global_ns is the reference to declarations that describes C++ namespace. - #In our case, instance of that declarations describes global ( :: ) namespace. - global_ns.free_functions( "do_smth", return_type='void', arg_types=[None,'int'] ) - - -Small explanation. Assume that ``None`` means "any type". Now the code is pretty -readable: -:: - - select all free functions - where - name equal to "do_smth" - return type is void - function has two arguments - second argument type is int - -.. __: ./query_interface.html - -------- -License -------- - -`Boost Software License`_. - ------------------ -Test environments ------------------ - -`pygccxml`_ comes with comprehensive unit tests. It is running on Windows XP and -`Ubuntu`_. I am using `Python`_ 2.4 and `GCC-XML`_ 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. - -.. _`WSDL`: http://www.w3.org/TR/wsdl -.. _`Py++`: ./../pyplusplus/pyplusplus.html -.. _`pygccxml`: ./pygccxml.html -.. _`SourceForge`: http://sourceforge.net/index.php -.. _`Docutils`: http://docutils.sourceforge.net -.. _`Python`: http://www.python.org -.. _`GCC-XML`: http://www.gccxml.org -.. _`Boost Software License`: http://boost.org/more/license_info.html -.. _`Ubuntu`: http://www.ubuntu.com/ -.. _`boost::type_traits` : http://www.boost.org/libs/type_traits/index.html -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: \ No newline at end of file +====================== +pygccxml documentation +====================== + +.. contents:: Table of contents + +.. meta:: + :description: C++ declarations parser + :keywords: C++, source code, header file, parser, UML, free, declarations + , XML, class hierarchy, analyze, AST, code generator, + , синтаксический анализатор, исходный текст, исходная программа + , описание, определение, иерархия классов, генератор кода + +------------ +Introduction +------------ +.. include:: ./definition.rest + +---------------------- +What can I do with it? +---------------------- +Using `pygccxml`_ you can: + +* parse C++ source code +* build a code generator + + + `Py++`_ is heavily based on `pygccxml`_ + + generate `WSDL`_ file from sources + + ... + +* create UML diagrams +* build code analyzer +* ... + +------------- +Usage example +------------- +First of all let's see a small and simple `example`_. This example prints all +declarations, reported by `GCC-XML`_ after parsing `core_class_hierarchy.hpp`_ +file. Also it prints all classes, and for every class it will print it's base +and derived classes. It was simple task, right? If you are still curious how it +looks "in the real life", I mean how xml file is look like, you may look at the +`original XML file`_ generated by `GCC-XML`_. + +.. _`original XML file` : ./example/core_class_hierarchy.hpp.xml +.. _`core_class_hierarchy.hpp` : ./example/core_class_hierarchy.hpp +.. _`example` : ./example/example.py + +-------- +Features +-------- + +Caching +------- + +Consider the following situation: you have to parse the same set of files every +day. There are 2 possible 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. + +Type traits +----------- + +`pygccxml`_ provides a lot of functionality to analyze C++ types and relationship +between them. For more information please refer to `design`__ document or API +documentation. Just a few names of algorithms: + +* ``is_convertible( from, to )`` + + returns ``True`` if there is a conversion from type ``from`` to type ``to``, + otherwise ``False`` + +* ``is_unary_operator( oper )`` + + returns ``True`` if ``oper`` describes unary operator + +.. __: ./design.html + + +Query interface +--------------- + +`pygccxml`_ provides simple and powerful API to query declarations tree. I will +try to give small example, that will prove my point. If you want to know more +about provided API please read `query interface`__ document or API documentation. +Examples: +:: + + #global_ns is the reference to declarations that describes C++ namespace. + #In our case, instance of that declarations describes global ( :: ) namespace. + global_ns.free_functions( "do_smth", return_type='void', arg_types=[None,'int'] ) + + +Small explanation. Assume that ``None`` means "any type". Now the code is pretty +readable: +:: + + select all free functions + where + name equal to "do_smth" + return type is void + function has two arguments + second argument type is int + +.. __: ./query_interface.html + +------- +License +------- + +`Boost Software License`_. + +----------------- +Test environments +----------------- + +`pygccxml`_ comes with comprehensive unit tests. It is running on Windows XP and +`Ubuntu`_. I am using `Python`_ 2.4 and `GCC-XML`_ CVS. +Right now I am running more then 150 tests. They test almost every piece of code. +Also I have performance tests. Most of the time I am using "white box" testing +strategy. + +.. _`WSDL`: http://www.w3.org/TR/wsdl +.. _`Py++`: ./../pyplusplus/pyplusplus.html +.. _`pygccxml`: ./pygccxml.html +.. _`SourceForge`: http://sourceforge.net/index.php +.. _`Docutils`: http://docutils.sourceforge.net +.. _`Python`: http://www.python.org +.. _`GCC-XML`: http://www.gccxml.org +.. _`Boost Software License`: http://boost.org/more/license_info.html +.. _`Ubuntu`: http://www.ubuntu.com/ +.. _`boost::type_traits` : http://www.boost.org/libs/type_traits/index.html +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: Modified: pygccxml_dev/docs/query_interface.rest =================================================================== --- pygccxml_dev/docs/query_interface.rest 2006-08-15 08:44:45 UTC (rev 404) +++ pygccxml_dev/docs/query_interface.rest 2006-08-15 10:41:00 UTC (rev 405) @@ -1,287 +1,287 @@ -=============================== -pygccxml.declarations query API -=============================== - -.. contents:: Table of contents - ------------- -Introduction ------------- -You parsed the source files. Now you have to do some real work with the extracted -information, right? `pygccxml`_ provides very powerful and simple interface to -query about extracted declarations. - -Just an example. I want to select all member functions, that have 2 arguments. -I don't care about first argument type, but I do want second argument type to be -a reference to an integer. More over, I want those functions names to end with -"impl" string and they should be protected or private. -:: - - #global_ns is the reference to an instance of namespace_t object, that - #represents global namespace - query = declarations.custom_matcher_t( lambda mem_fun: mem_fun.name.endswith( 'impl' ) - query = query & ~declarations.access_type_matcher_t( 'public' ) - global_ns.member_functions( function=query, arg_types=[None, 'int &'] ) - -The example is complex, but still readable. In many cases you will find your -self looking for one or many declarations using one or two properties of that -declaration(s). For example: -:: - - global_ns.namespaces( 'details' ) - -This call will return all namespaces with name 'details'. - --------------- -User interface --------------- - -As you already know, ``pygccxml.declarations`` package defines next classes: - -* ``scopedef_t`` - base class for all classes, that can contain other declarations - -* ``namespace_t`` - derives from ``scopedef_t`` class, represents C++ namespace - -* ``class_t`` - derives from ``scopedef_t`` class, represents C++ class/struct/union. - -So, the query methods defined on ``scopedef_t`` class could be used on instances -of ``class_t`` and ``namespace_t`` classes. I am sure you knew that. - -Usage examples --------------- - -I will explain the usage of ``member_function`` and ``member_functions`` methods. -The usage of other methods is very similar to them. Here is definition of those -methods: -:: - - def member_function( self, - ... [truncated message content] |
