pygccxml.parser package

Overview

Parser sub-package.

pygccxml.parser.parse(files, config=None, compilation_mode='file by file', cache=None)

Parse header files.

Parameters:

• files (list of str) – The header files that should be parsed
• config (parser.config_t) – Configuration object or None
• compilation_mode (parser.COMPILATION_MODE) – Determines whether the files are parsed individually or as one single chunk
• cache (parser.cache_base_t or str) – Declaration cache (None=no cache)

Return type:

list of declarations.declaration_t

pygccxml.parser.parse_string(content, config=None)

pygccxml.parser.parse_xml_file(content, config=None)

Modules

config

defines C++ parser configuration classes

pygccxml.parser.config.config_t

alias of gccxml_configuration_t

class pygccxml.parser.config.gccxml_configuration_t(gccxml_path='', working_directory='.', include_paths=None, define_symbols=None, undefine_symbols=None, start_with_declarations=None, ignore_gccxml_output=False, cflags='', compiler=None)

Bases: pygccxml.parser.config.parser_configuration_t

Configuration object to collect parameters for invoking gccxml.

This class serves as a container for the parameters that can be used to customize the call to gccxml.

Constructor.

clone()

gccxml_path

gccxml binary location

ignore_gccxml_output

set this property to True, if you want pygccxml to ignore any errorwarning that comes from gccxml

raise_on_wrong_settings()

start_with_declarations

list of declarations gccxml should start with, when it dumps declaration tree

pygccxml.parser.config.load_gccxml_configuration(configuration, **defaults)

loads GCC-XML configuration from an .ini file or any other file class ConfigParser.SafeConfigParser is able to parse.

Parameter:configuration – configuration could be string( configuration file path ) or instance of ConfigParser.SafeConfigParser class Return type:gccxml_configuration_t

Configuration file sceleton:

[gccxml]
#path to gccxml executable file - optional, if not provided, os.environ['PATH']
#variable is used to find it
gccxml_path=
#gccxml working directory - optional, could be set to your source code directory
working_directory=
#additional include directories, separated by ';'
include_paths=
#gccxml has a nice algorithms, which selects what C++ compiler to emulate.
#You can explicitly set what compiler it should emulate.
#Valid options are: g++, msvc6, msvc7, msvc71, msvc8, cl.
compiler=

class pygccxml.parser.config.parser_configuration_t(working_directory='.', include_paths=None, define_symbols=None, undefine_symbols=None, cflags='', compiler=None)

Bases: object

C++ parser configuration holder

This class serves as a base class for the parameters that can be used to customize the call to a C++ parser.

This class also allows users to work with relative files paths. In this case files are searched in the following order:

1. current directory
2. working directory
3. additional include paths specified by the user

Constructor.

append_cflags(val)

cflags

additional flags to pass to compiler

clone()

compiler

compiler name to simulate

define_symbols

list of “define” directives

get_compiler()

get compiler name to simulate

include_paths

list of include paths to look for header files

raise_on_wrong_settings()

validates the configuration settings and raises RuntimeError on error

set_compiler(compiler)

set compiler name to simulate

undefine_symbols

list of “undefine” directives

working_directory

declarations_cache

class pygccxml.parser.declarations_cache.cache_base_t

Bases: object

cached_value(source_file, configuration)

Return declarations, we have cached, for the source_file and the given configuration. :param source_file: path to the C++ source file being parsed. :param configuration: configuration( config_t ) that was used for parsing

flush()

Flush (write out) the cache to disk if needed.

update(source_file, configuration, declarations, included_files)

update cache entry

Parameters:

• source_file – path to the C++ source file being parsed
• configuration – configuration used in parsing config_t
• declarations – declaration tree found when parsing
• included_files – files included by parsing.

pygccxml.parser.declarations_cache.configuration_signature(config)

Return a signature for a configuration (config_t) object. This can then be used as a key in the cache. This method must take into account anything about a configuration that could cause the declarations generated to be different between runs.

class pygccxml.parser.declarations_cache.dummy_cache_t

Bases: pygccxml.parser.declarations_cache.cache_base_t

cached_value(source_file, configuration)

flush()

update(source_file, configuration, declarations, included_files)

class pygccxml.parser.declarations_cache.file_cache_t(name)

Bases: pygccxml.parser.declarations_cache.cache_base_t

Cache implementation to store data in a pickled form in a file. This class contains some cache logic that keeps track of which entries have been ‘hit’ in the cache and if an entry has not been hit then it is deleted at the time of the flush(). This keeps the cache from growing larger when files change and are not used again.

Parameter:name – name of the cache file.

cached_value(source_file, configuration)

attempt to lookup the cached declarations for the given file and configuration. If not found or signature check fails, returns None.

flush()

update(source_file, configuration, declarations, included_files)

Update a cached record with the current key and value contents.

pygccxml.parser.declarations_cache.file_signature(filename)

class pygccxml.parser.declarations_cache.record_t(source_signature, config_signature, included_files, included_files_signature, declarations)

Bases: object

config_signature

static create_key(source_file, configuration)

declarations

included_files

included_files_signature

key()

source_signature

was_hit

directory_cache

directory cache implementation.

This module contains the implementation of a cache that uses individual files, stored in a dedicated cache directory, to store the cached contents.

The parser.directory_cache_t class instance could be passed as the cache argument of the parser.parse() function.

class pygccxml.parser.directory_cache.directory_cache_t(dir='cache', compression=False, md5_sigs=True)

Bases: pygccxml.parser.declarations_cache.cache_base_t

cache class that stores its data as multiple files inside a directory.

The cache stores 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).

Parameters:

• dir – cache directory path, it is created, if it does not exist
• compression – if True, the cache files will be compressed using gzip
• md5_sigs – md5_sigs determines whether file modifications is checked by computing a md5 digest or by checking the modification date

cached_value(source_file, configuration)

Return the cached declarations or None.

Parameters:

• source_file (str) – Header file name
• configuration (parser.config_t) – Configuration object

Return type:

Cached declarations or None

flush()

Save the index table to disk.

update(source_file, configuration, declarations, included_files)

Replace a cache entry by a new value.

Parameters:

• source_file (str) – a C++ source file name.
• configuration (config_t) – configuration object.
• declarations (pickable object) – declarations contained in the source_file
• included_files (list of str) – included files

class pygccxml.parser.directory_cache.filename_entry_t(filename)

This is a record stored in the filename_repository_t class.

The class is an internal class used in the implementation of the filename_repository_t class and it just serves as a container for the file name and the reference count.

Constructor.

The reference count is initially set to 0.

dec_ref_count()

Decrease the reference count by 1 and return the new count.

inc_ref_count()

Increase the reference count by 1.

class pygccxml.parser.directory_cache.filename_repository_t(md5_sigs)

File name repository.

This class stores file names and can check whether a file has been modified or not since a previous call. A file name is stored by calling acquire_filename() which returns an ID and a signature of the file. The signature can later be used to check if the file was modified by calling is_file_modified(). If the file name is no longer required release_filename() should be called so that the entry can be removed from the repository.

Constructor.

acquire_filename(name)

Acquire a file name and return its id and its signature.

is_file_modified(id_, signature)

Check if the file referred to by id_ has been modified.

release_filename(id_)

Release a file name.

update_id_counter()

Update the id_ counter so that it doesn’t grow forever.

class pygccxml.parser.directory_cache.index_entry_t(filesigs, configsig)

Entry of the index table in the directory cache index.

Each cached header file (i.e. each .cache file) has a corresponding index_entry_t object. This object is used to determine whether the cache file with the declarations is still valid or not.

This class is a helper class for the directory_cache_t class.

Parameters:

• filesigs – a list of tuples( fileid, sig)...
• configsig – the signature of the configuration object.

patcher

class pygccxml.parser.patcher.casting_operator_patcher_t

Bases: object

class pygccxml.parser.patcher.default_argument_patcher_t(enums)

Bases: object

pygccxml.parser.patcher.fix_calldef_decls(decls, enums)

project_reader

class pygccxml.parser.project_reader.COMPILATION_MODE

pygccxml.parser.project_reader.create_cached_source_fc(header, cached_source_file)

Creates parser.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.

Parameters:

• header (str) – path to C++ source file
• cached_source_file (str) – path to GCC-XML generated XML file

Return type:

parser.file_configuration_t

pygccxml.parser.project_reader.create_gccxml_fc(xml_file)

Creates parser.file_configuration_t instance, configured to contain path to GCC-XML generated XML file.

Parameter:xml_file (str) – path to GCC-XML generated XML file Return type:parser.file_configuration_t

pygccxml.parser.project_reader.create_source_fc(header)

Creates parser.file_configuration_t instance, configured to contain path to C++ source file

Parameter:header (str) – path to C++ source file Return type:parser.file_configuration_t

pygccxml.parser.project_reader.create_text_fc(text)

Creates parser.file_configuration_t instance, configured to contain Python string, that contains valid C++ code

Parameter:text (str) – C++ code Return type:parser.file_configuration_t

class pygccxml.parser.project_reader.file_configuration_t(data, start_with_declarations=None, content_type='standard source file', cached_source_file=None)

Bases: object

source code location configuration.

The class instance uses “variant” interface to represent the following data:

1. path to a C++ source file

2. path to GCC-XML generated XML file

3. path to a C++ source file and path to GCC-XML generated 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 was changed.

4. Python string, that contains valid C++ code

There are few functions, that will help you to construct file_configuration_t object:

• create_source_fc()
• create_gccxml_fc()
• create_cached_source_fc()
• create_text_fc()

class CONTENT_TYPE

file_configuration_t.cached_source_file

file_configuration_t.content_type

file_configuration_t.data

file_configuration_t.start_with_declarations

class pygccxml.parser.project_reader.project_reader_t(config, cache=None, decl_factory=None)

parses header files and returns the contained declarations

Parameters:

• config (:class:config_t) – GCCXML configuration
• cache (cache_base_t instance or str) – declaration cache, by default a cache functionality will not be used
• decl_factory (decl_factory_t) – declaration factory

static get_os_file_names(files)

returns file names

Parameter:files (list) – list of strings andor file_configuration_t instances.

read_files(files, compilation_mode='file by file')

parses a set of files

Parameters:

• files (list) – list of strings andor file_configuration_t instances.
• compilation_mode (COMPILATION_MODE) – determines whether the files are parsed individually or as one single chunk

Return type:

[declaration_t]

read_string(content)

Parse a string containing C/C++ source code.

Parameter:content (str) – C/C++ source code. Return type:Declarations

read_xml(file_configuration)

parses C++ code, defined on the file_configurations and returns GCCXML generated file content

source_reader

pygccxml.parser.source_reader.bind_aliases(decls)

This function binds between class and it’s typedefs.

Parameter:decls – list of all declarations Return type:None

exception pygccxml.parser.source_reader.gccxml_runtime_error_t(msg)

Bases: exceptions.RuntimeError

class pygccxml.parser.source_reader.source_reader_t(config, cache=None, decl_factory=None)

This class reads C++ source code and returns declarations tree.

This class is the only class that works with GCC-XML directly.

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 two 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.

Parameters:

• config – instance of config_t class, that contains GCC-XML configuration
• cache (instance of cache_base_t class) – reference to cache object, that will be updated after file has been parsed.
• decl_factory – declarations factory, if not given default declarations factory( decl_factory_t ) will be used

create_xml_file(header, destination=None)

This function will return the file name of the file, created by GCC-XML for “header” file. If destination_file_path is not None, then this file path will be used and returned.

Parameters:

• header (str) – path to source file, that should be parsed
• destination (str) – if given, will be used as target file/path for GCC-XML generated file.

Return type:

path to GCC-XML generated file

create_xml_file_from_string(content, destination=None)

Creates XML file from text.

Parameters:

• content (str) – C++ source code
• destination (str) – file name for GCC-XML generated file

Return type:

returns file name of GCC-XML generated file

read_file(source_file)

read_gccxml_file(source_file)

Reads C++ source file and returns declarations tree

Parameter:source_file (str) – path to C++ source file

read_string(content)

Reads Python string, that contains valid C++ code, and returns declarations tree.

read_xml_file(gccxml_created_file)

Reads GCC-XML generated XML file.

Parameter:gccxml_created_file (str) – path to GCC-XML generated file Return type:declarations tree

blog comments powered by Disqus

---