[pygccxml-commit] SF.net SVN: pygccxml: [163] pygccxml_dev/docs
Brought to you by:
mbaas,
roman_yakovenko
Menu
▾
▴
[pygccxml-commit] SF.net SVN: pygccxml: [163] pygccxml_dev/docs
|
From: <rom...@us...> - 2006-05-25 06:54:22
|
Revision: 163 Author: roman_yakovenko Date: 2006-05-24 23:54:11 -0700 (Wed, 24 May 2006) ViewCVS: http://svn.sourceforge.net/pygccxml/?rev=163&view=rev Log Message: ----------- updating docs Modified Paths: -------------- pygccxml_dev/docs/www_configuration.py Added Paths: ----------- pygccxml_dev/docs/query_interface.rest Removed Paths: ------------- pygccxml_dev/docs/query_api.rest Deleted: pygccxml_dev/docs/query_api.rest =================================================================== --- pygccxml_dev/docs/query_api.rest 2006-05-24 20:36:00 UTC (rev 162) +++ pygccxml_dev/docs/query_api.rest 2006-05-25 06:54:11 UTC (rev 163) @@ -1,91 +0,0 @@ -=============================== -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 with name 'details'. - --------------- -User interface --------------- - -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. - -So, the query methods defined on ``scopedef_t`` class could be used on instances -of ``class_t`` and ``namespace_t`` classes. - -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, - name=None, - function=None, - return_type=None, - arg_types=None, - header_dir=None, - header_file=None, - recursive=None ) - - def member_functions( self, - name=None, - function=None, - return_type=None, - arg_types=None, - header_dir=None, - header_file=None, - recursive=None, - allow_empty=None ) - - - - -.. _`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 Copied: pygccxml_dev/docs/query_interface.rest (from rev 162, pygccxml_dev/docs/query_api.rest) =================================================================== --- pygccxml_dev/docs/query_interface.rest (rev 0) +++ pygccxml_dev/docs/query_interface.rest 2006-05-25 06:54:11 UTC (rev 163) @@ -0,0 +1,185 @@ +=============================== +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 with name 'details'. + +-------------- +User interface +-------------- + +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. + +So, the query methods defined on ``scopedef_t`` class could be used on instances +of ``class_t`` and ``namespace_t`` classes. + +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, + name=None, + function=None, + return_type=None, + arg_types=None, + header_dir=None, + header_file=None, + recursive=None ) + + + def member_functions( self, + name=None, + function=None, + return_type=None, + arg_types=None, + header_dir=None, + header_file=None, + recursive=None, + allow_empty=None ) + +As you can see, from the methods arguments you can search for member function +by: + + * ``name`` + + Python string, that contains member function name or full name. + + ``do_smth = my_class.member_function( 'do_smth' )`` + ``do_smth = my_class.member_function( 'my_namespace::my_class::do_smth' )`` + + * ``function`` + + Python callable object. You would use this functionality, if you need to + build custom query. This object will be called with one argument - declaration, + and it should return ``True`` or ``False``. + + ``impls = my_class.member_functions( lambda decl: decl.name.endswith( 'impl' ) )`` + + ``impls`` will contain all member functions, that thier name ends with "impl". + + * ``return_type`` + + Function return type. This argument can be Python string or an object that + describes C++ type. + + ``mem_funcs = my_class.member_functions( return_type='int' )`` + + ``i = declarations.int_t()`` + ``ref_i = declarations.reference_t( i )`` + ``const_ref_i = declarations.const_t( ref_i )`` + ``mem_funcs = my_class.member_functions( return_type=const_ref_int )`` + + * ``arg_types`` + + Python list that contains description of member function argument types. + This list could be a mix of Python strings and objects that describes C++ + type. Size of list says how many arguments function should have. If you want + to skip some argument type from within comparison, you put ``None``, into + relevant position within the list. + + ``mem_funcs = my_class.member_functions( arg_types=[ None, 'int'] )`` + + ``mem_funcs`` will contain all member functions, that have two arguments + and type of second argument is ``int``. + + * ``header_dir`` + + Python string, that contains full path to directory, which contains file, + which contains the function declaration + + ``mem_funcs = my_namespace.member_functions( header_dir='/home/roman/xyz' )`` + + * ``header_file`` + + Python string, that contains full path to file, which contains the function + declaration. + + ``mem_funcs = my_namespace.member_functions( header_dir='/home/roman/xyz/xyz.hpp' )`` + + * ``recursive`` + + Python boolean object. + + If ``recursive`` is ``True``, then member function will be also searched + within internal declarations. + + If ``recursive`` is ``False``, then member function will be searched only + within current scope. + + What happen if ``recursive`` is ``None``? Well. ``scopedef_t`` class defines + ``RECURSIVE_DEFAULT`` variable. It's initial value is ``True``. So, if you + don't pass ``recursive`` argument, the value of ``RECURSIVE_DEFAULT`` variable + will be used. This "yet another level of indirection" allows you to configure + `pygccxml`_ "select" functions in one place for all project. + + * ``allow_empty`` + + Python boolean object, it says `pygccxml`_ what to do if query returns empty. + + If ``allow_empty`` is ``False``, then exception + ``RuntimeError( "Multi declaration query returned 0 declarations." )`` + will be raised + + ``allow_empty`` uses same tehnique as ``recursive``, to allow you to customize + the behaviour project-wise. The relevant class variable name is + ``ALLOW_EMPTY_MDECL_WRAPPER``. It's initial value is ``False``. + +Now, when you understand, how to call those functions, I will explain what they +return. + +``member_function`` will always return reference to desired declaration. If +declaration could not be found or there are more then one declaration that +match query ``RuntimeError`` exception will be raised. + + + +.. _`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/docs/www_configuration.py =================================================================== --- pygccxml_dev/docs/www_configuration.py 2006-05-24 20:36:00 UTC (rev 162) +++ pygccxml_dev/docs/www_configuration.py 2006-05-25 06:54:11 UTC (rev 163) @@ -1,2 +1,3 @@ name = 'pygccxml' -files_to_skip = ['definition.rest'] \ No newline at end of file +files_to_skip = ['definition.rest'] +names = { 'query_api' : 'query interface' } \ No newline at end of file This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
