[pygccxml-commit] SF.net SVN: pygccxml: [146] pygccxml_dev/docs
Brought to you by:
mbaas,
roman_yakovenko
Menu
▾
▴
[pygccxml-commit] SF.net SVN: pygccxml: [146] pygccxml_dev/docs
|
From: <rom...@us...> - 2006-05-21 20:01:42
|
Revision: 146 Author: roman_yakovenko Date: 2006-05-21 13:01:26 -0700 (Sun, 21 May 2006) ViewCVS: http://svn.sourceforge.net/pygccxml/?rev=146&view=rev Log Message: ----------- updating documentation Modified Paths: -------------- pygccxml_dev/docs/design.rest pygccxml_dev/pygccxml/parser/project_reader.py Added Paths: ----------- pygccxml_dev/docs/query_api.rest Modified: pygccxml_dev/docs/design.rest =================================================================== --- pygccxml_dev/docs/design.rest 2006-05-21 13:54:20 UTC (rev 145) +++ pygccxml_dev/docs/design.rest 2006-05-21 20:01:26 UTC (rev 146) @@ -1,9 +1,9 @@ -=============== +=============== pygccxml design =============== .. contents:: Table of contents - + ------------------------ The view from 10000 fits ------------------------ @@ -12,8 +12,8 @@ * ``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 +* ``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. @@ -22,105 +22,105 @@ ``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 hiearchy - used to represent a C++ type - +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. +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, +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 +`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. +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. +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 +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. @@ -128,8 +128,8 @@ ``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 +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 @@ -138,73 +138,136 @@ * cache - classes, those one will help you to eliminate unnecessary parsing -* patchers - classes, that fix `GCC-XML`_ generated declarations. ( Yes, sometimes +* 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 intime knowledge about `GCC-XML`_. +``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 + +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 +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 functionlity needed to parse few source files at once. +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. +1. ``project_reader_t`` creates temporal source file, that includes all the source + files. -2. ``project_reader_t`` parse separetly every source file, using ``source_reader_t`` +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 ----------------------------- +to reuse information from already parsed source files. While the second one +allows you to setup cache. -``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 - user will ask to parse the source file, the XML file will be used instead. - -(4) Python string, that contains valid C++ code - - -Cache classes -------------- - +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. My +advise - don't use them. Your best choice is ``file_configuration_t``, +configured to C++ source file + `GCC-XML`_ generated file. + +* ``file_cache_t`` class, will save all declarations from all files within single + binary file. + +* ``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). + +As you can guess, ``directory_cache_t`` class gives much better performance, than +``file_cache_t``. Many thanks to Matthias Baas for its implemention. + + +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 different bugs. + +------- +Summary +------- + +Thats all. I hope I was clear, at least I tried. Any way we are talking about +open source project. You can take a look on source code. If you need more information +you can take a look on API documentation. + .. _`pygccxml`: ./pygccxml.html .. _`SourceForge`: http://sourceforge.net/index.php .. _`Python`: http://www.python.org Added: pygccxml_dev/docs/query_api.rest =================================================================== --- pygccxml_dev/docs/query_api.rest (rev 0) +++ pygccxml_dev/docs/query_api.rest 2006-05-21 20:01:26 UTC (rev 146) @@ -0,0 +1,67 @@ +=============================== +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 declrations. + +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 &'] ) + +As for me the example I gave was too complex. 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 that have 'details' namespace. + +------------------ +How does it works? +------------------ + +As you already know, ``pygccxml.declarations`` packages 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. + +``scopedef_t`` class defines query interface. Basicaly you can ask it about any +declaration it contains, even about some sub declarations. + + + + +.. _`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 Modified: pygccxml_dev/pygccxml/parser/project_reader.py =================================================================== --- pygccxml_dev/pygccxml/parser/project_reader.py 2006-05-21 13:54:20 UTC (rev 145) +++ pygccxml_dev/pygccxml/parser/project_reader.py 2006-05-21 20:01:26 UTC (rev 146) @@ -17,51 +17,38 @@ class file_configuration_t( object ): - """ - file_configuration_t class is cool feature. When you want to parse C++ code - from different sources at once, you should use this class. -class instance you should pass list of files. This list can contain string( == file paths ) and/or instances of file_configuration_t class. + """ + 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: -file_configuration_t is class with fat interface. -It has 4 states: - 1. it could contain reference to source file. - Use "create_source_fc" function to create an instance of file_configuration_t + * L{create_source_fc} + + * L{create_gccxml_fc} + + * L{create_cached_source_fc} - 2. it could contain reference to source file and xml file. In this case if xml file - exist, source file will not be parsed by gccxml. If xml file does not exists, source - file will be parsed and xml file will be saved for future use. - See create_cached_source_fc function - - 3. it could contain reference to xml file only - See create_gccxml_fc - - 4. it could contain some text. In this case, parser will create temporal file on - disk and will pass it as an argument to gccxml. - See create_text_fc - -In most cases you don't all those features. If I were you, I would create regular -source file and put all template instantiation there. - -Any way the code: - -tmpl_inst = ''' -===================== - #include "TempClass.h" - - namespace details{ - inline void export_templates(){ - sizeof( TempClass<int> ); - } - } -''' - -import module_builder -mb = module_builder.module_builder_t( - [ module_builder.create_text_fc( tmpl_inst ) ] - , .... ) - -""" - + * L{create_text_fc} + + """ class CONTENT_TYPE: STANDARD_SOURCE_FILE = 'standard source file' CACHED_SOURCE_FILE = 'cached source file' @@ -101,18 +88,59 @@ cached_source_file = property( __get_cached_source_file ) def create_text_fc( text ): + """ + Creates L{file_configuration_t} instance, configured to contain Python string, + that contains valid C++ code + + @param text: C++ code + @type text: str + + @return: L{file_configuration_t} + """ return file_configuration_t( data=text , content_type=file_configuration_t.CONTENT_TYPE.TEXT ) def create_source_fc( header ): + """ + Creates L{file_configuration_t} instance, configured to contain path to + C++ source file + + @param header: path to C++ source file + @type header: str + + @return: L{file_configuration_t} + """ return file_configuration_t( data=header , content_type=file_configuration_t.CONTENT_TYPE.STANDARD_SOURCE_FILE ) def create_gccxml_fc( xml_file ): + """ + Creates L{file_configuration_t} instance, configured to contain path to + GCC-XML generated XML file. + + @param xml_file: path to GCC-XML generated XML file + @type xml_file: str + + @return: L{file_configuration_t} + """ return file_configuration_t( data=xml_file , content_type=file_configuration_t.CONTENT_TYPE.GCCXML_GENERATED_FILE ) def create_cached_source_fc( header, cached_source_file ): + """ + Creates L{file_configuration_t} instance, configured to contain path to + GCC-XML generated XML file and C++ source file. If XML file does not exists, + it will be created and used for parsing. If XML file exists, it will be used + for parsing. + + @param header: path to C++ source file + @type header: str + + @param cached_source_file: path to GCC-XML generated XML file + @type cached_source_file: str + + @return: L{file_configuration_t} + """ return file_configuration_t( data=header , cached_source_file=cached_source_file , content_type=file_configuration_t.CONTENT_TYPE.CACHED_SOURCE_FILE ) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
