Declarations query API¶

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, which 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 yourself, looking for one or many declarations, using one or two declaration properties. 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 the following 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,
                      name=None,
                      function=None,
                      return_type=None,
                      arg_types=None,
                      header_dir=None,
                      header_file=None,
                      recursive=None )

mem_fun = member_function #just an alias

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 )
mem_funs = member_functions

As you can see, from the method 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 their name ends with “impl”.
return_type

the function return type. This argument can be 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, which 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. Its 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 technique as recursive, to allow you to customize the behavior project-wise. The relevant class variable name is ALLOW_EMPTY_MDECL_WRAPPER. Its 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.

Return value of member_functions is not Python list or set, but instance of mdecl_wrapper_t class. This class allows you to work on all selected objects at once. I will give an example from another project - https://pypi.python.org/pypi/pyplusplus/. In order to help Boost.Python to manage objects life time, all functions should have call policies. For example:

struct A{
    A* clone() const { return new A(); }
    ...
};

struct B{
    B* clone() const { return new B(); }
    ...
};

clone member function call policies is return_value_policy<manage_new_object>(). The following code applies the call policies on all clone member functions within the project:

#global_ns - instance of namespace_t class, that contains reference to global namespace
clone = global_ns.member_functions( 'clone' )
clone.call_policies = return_value_policy( manage_new_object )

Another example, from https://pypi.python.org/pypi/pyplusplus/ project. Sometimes it is desirable to exclude declaration, from being exported to Python. The following code will exclude clone member function from being exported:

global_ns.member_functions( 'clone' ).exclude()

As you can see this class allows you to write less code. Basically using this class you don’t have to write loops. If will do it for you. Also if you insist to write loops, mdecl_wrapper_t class implements __len__, __getitem__ and __iter__ methods. So you can write the following code:

for clone in global_ns.member_functions( 'clone' ):
    print clone.parent.name

Implementation details¶

Performance¶

For big projects, performance is critical. When you finished to build/change declarations tree, then you can call scopedef_t.init_optimizer method. This method will initialize few data structures, that will help to minimize the number of compared declarations. The price you are going to pay is memory usage.

Data structures¶

Here is a short explanation of what data structures is initialized.

scopedef_t._type2decls, scopedef_t._type2decls_nr

Python dictionary, that contains mapping between declaration type and declarations in the current scope.

scopedef_t.type2decls_nr contains only declaration from the current scope. scopedef_t.type2decls contains declarations from the current scope and its children
scopedef_t._type2name2decls, scopedef_t._type2name2decls_nr

Python dictionary, that contains mapping between declaration type and another dictionary. This second dictionary contains mapping between a declaration name and declaration.

scopedef_t.type2name2decls_nr contains only declaration from the current scope. scopedef_t.type2name2decls contains declarations from the current scope and its children
scopedef_t._all_decls

A flat list of all declarations, including declarations from the children scopes.

Except scopedef_t.decl and scopedef_t.decls methods, all other queries have information about declaration type.

If you include name into your query, you will get the best performance.

More information¶

I think, I gave you the important information. If you need definition of some query method, you can take a look on API documentation or into source code.