[pygccxml-commit] SF.net SVN: pygccxml: [149] pygccxml_dev/docs
Brought to you by:
mbaas,
roman_yakovenko
Menu
▾
▴
[pygccxml-commit] SF.net SVN: pygccxml: [149] pygccxml_dev/docs
|
From: <rom...@us...> - 2006-05-22 20:34:34
|
Revision: 149 Author: roman_yakovenko Date: 2006-05-22 13:34:23 -0700 (Mon, 22 May 2006) ViewCVS: http://svn.sourceforge.net/pygccxml/?rev=149&view=rev Log Message: ----------- improving documentation Modified Paths: -------------- pygccxml_dev/docs/design.rest pygccxml_dev/docs/example/example.py pygccxml_dev/docs/pygccxml.rest Modified: pygccxml_dev/docs/design.rest =================================================================== --- pygccxml_dev/docs/design.rest 2006-05-22 06:47:04 UTC (rev 148) +++ pygccxml_dev/docs/design.rest 2006-05-22 20:34:23 UTC (rev 149) @@ -248,7 +248,7 @@ Patchers -------- -????. Well, `GCC-XML`_ has few bugs, that could not be fixed from it. For example +Well, `GCC-XML`_ has few bugs, that could not be fixed from it. For example :: namespace ns1{ namespace ns2{ @@ -258,15 +258,19 @@ 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. +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 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. +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 Modified: pygccxml_dev/docs/example/example.py =================================================================== --- pygccxml_dev/docs/example/example.py 2006-05-22 06:47:04 UTC (rev 148) +++ pygccxml_dev/docs/example/example.py 2006-05-22 20:34:23 UTC (rev 149) @@ -3,21 +3,24 @@ # accompanying file LICENSE_1_0.txt or copy at # http://www.boost.org/LICENSE_1_0.txt) +import sys +sys.path.append('../..') #adding pygccxml to the path + from pygccxml import parser from pygccxml import declarations #configure GCC-XML parser -config = parser.config_t( gccxml_path=r'/home/roman/gccxml/bin/gccxml' ) +config = parser.config_t( gccxml_path='/home/roman/gccxml-build/bin/gccxml' ) + #parsing source file -global_ns = parser.parse( ['core_class_hierarchy.hpp'], config ) +decls = parser.parse( ['core_class_hierarchy.hpp'], config ) +global_ns = declarations.get_global_namespace( decls ) + #printing all declarations found in file and its includes declarations.print_declarations( global_ns ) -#selecting all classes -all_decls = declarations.make_flatten( global_ns ) -all_classes = filter( lambda decl: isinstance( decl, declarations.class_t ) - , all_decls ) + #print all base and derived class names -for class_ in all_classes: +for class_ in global_ns.classes(): print class_.name print '\tbases: ', `[base.related_class.name for base in class_.bases]` print '\tderived: ', `[derive.related_class.name for derive in class_.derived]` Modified: pygccxml_dev/docs/pygccxml.rest =================================================================== --- pygccxml_dev/docs/pygccxml.rest 2006-05-22 06:47:04 UTC (rev 148) +++ pygccxml_dev/docs/pygccxml.rest 2006-05-22 20:34:23 UTC (rev 149) @@ -36,272 +36,91 @@ Usage example ------------- First of all let's see a small and simple `example`_. This example prints all -declarations found in the global namespace after `GCC-XML`_ has parsed -`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`_. +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 - -I like it, but what else can you propose? ------------------------------------------ +-------- +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:: +day. There are 2 possibile ways to complete the task: - * create a header file that includes all files you need to parse +* create a header file that includes all files you need to parse - * parse each file separately and then join the results +* 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. +Type traits +----------- -------- -License -------- +`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: -`Boost Software License`_. +* ``is_convertible( from, to )`` -------------------------- -Declaration class diagram -------------------------- -`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* - - + *decompose_type* - - + *decompose_class* - - + *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* - - + *find_trivial_constructor* - - + *has_any_non_copyconstructor* - - + *...* - -Declaration hierarchy ---------------------- - -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. - ------- -Parser ------- - -User API --------- - -`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: + returns ``True`` if there is a conversion from type ``from`` to type ``to``, + otherwise ``False`` - 1. current directory - - 2. working directory - - 3. additional include paths specified by the user +* ``is_unary_operator( oper )`` -+ *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. + returns ``True`` if ``oper`` describes unary operator -+ *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: +.. __: ./design.html - 1. namespace joining. - 2. joining class hierarchies - 3. rebinding types to new class hierarchies - 4. linking overloaded functions - There are 2 ways to solve the problem: +Query interface +--------------- - 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*. +`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 api`__ document or API documentation. +Examples: +:: - 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 -~~~~~~~~~~~~~~~~~~~~~ - -*project_reader_t* and *source_reader_t* -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -+ *__init__( self, config, declarations_cache )* - *source_reader_t* allows - *declarations_cache* to be or instance of *cache_base_t* or None. *project_reader_t* - allows *declarations_cache* to be also path to cache file. - -+ *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. + #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'] ) -*pygccxml.parser* -^^^^^^^^^^^^^^^^^ -There are 2 functions: +Small explanation. Assume that ``None`` means "any type". Now the code is pretty +readable: +:: - 1. *parse(files, config=None, declarations_cache=None)* - 2. *parse_string(content, config=None)* + select all free functions + where + name equal to "do_smth" + return type is void + function has two arguments + second argument type is int -Those are *"shortcuts"* functions for *project_reader_t* class. +.. __: ./query_api.html +------- +License +------- -Implementation notes -~~~~~~~~~~~~~~~~~~~~ +`Boost Software License`_. -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. - - ----------------- Test environments ----------------- `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 ]. +`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. @@ -314,10 +133,7 @@ .. _`Python`: http://www.python.org .. _`GCC-XML`: http://www.gccxml.org .. _`Boost Software License`: http://boost.org/more/license_info.html -.. _`Debian Linux`: http://www.debian.org -.. _`UML diagram` : ./declarations_uml.png -.. _`Parser package` : ./parser_uml.png -.. _`ReleaseForge` : http://releaseforge.sourceforge.net +.. _`Ubuntu`: http://www.ubuntu.com/ .. _`boost::type_traits` : http://www.boost.org/libs/type_traits/index.html .. Local Variables: This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
