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.xml_generator_configuration_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.create_compiler_path(xml_generator, compiler_path)

Try to guess a path for the compiler.

If you want ot use a specific compiler, please provide the compiler path manually, as the guess may not be what you are expecting. Providing the path can be done by passing it as an argument (compiler_path) to the xml_generator_configuration_t() or by defining it in your pygccxml configuration file.

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

Loads CastXML or GCC-XML configuration.

Parameters:
  • configuration (string|configparser.ConfigParser) – can be a string (file path to a configuration file) or instance of configparser.ConfigParser.
  • defaults – can be used to override single configuration values.
Returns:

a configuration object

Return type:

xml_generator_configuration_t

The file passed needs to be in a format that can be parsed by configparser.ConfigParser.

An example configuration file skeleton can be found here.

class pygccxml.parser.config.parser_configuration_t(working_directory='.', include_paths=None, define_symbols=None, undefine_symbols=None, cflags='', compiler=None, xml_generator='castxml', keep_xml=False, compiler_path=None, flags=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
append_cflags(val)
cflags

additional flags to pass to compiler

clone()
compiler

get compiler name to simulate

compiler_path

Get the path for the compiler.

define_symbols

list of “define” directives

flags

Optional flags for pygccxml.

include_paths

list of include paths to look for header files

keep_xml

Are xml files kept after errors.

raise_on_wrong_settings()

validates the configuration settings and raises RuntimeError on error

undefine_symbols

list of “undefine” directives

working_directory
xml_generator

get xml_generator (gccxml or castxml)

class pygccxml.parser.config.xml_generator_configuration_t(gccxml_path='', xml_generator_path='', working_directory='.', include_paths=None, define_symbols=None, undefine_symbols=None, start_with_declarations=None, ignore_gccxml_output=False, cflags='', compiler=None, xml_generator='castxml', keep_xml=False, compiler_path=None, flags=None)

Bases: pygccxml.parser.config.parser_configuration_t

Configuration object to collect parameters for invoking gccxml or castxml.

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

clone()
ignore_gccxml_output

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

raise_on_wrong_settings()
start_with_declarations

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

xml_generator_path

XML generator binary location

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.

Parameters:
  • source_file – path to the C++ source file being parsed.
  • configuration – configuration that was used for parsing.
flush()

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

logger = <logging.Logger object>
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 xml_generator_configuration_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 (xml_generator_configuration_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

This is an empty cache object.

By default no caching is enabled in pygccxml.

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.

cached_value(source_file, configuration)

Attempt to lookup the cached declarations for the given file and configuration.

Returns None if declaration not found or signature check fails.

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)

Return a signature for a file.

class pygccxml.parser.declarations_cache.record_t(xml_generator, 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
xml_generator

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, sha1_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).

cached_value(source_file, configuration)

Return the cached declarations or None.

Parameters:
  • source_file (str) – Header file name
  • configuration (parser.xml_generator_configuration_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 (xml_generator_configuration_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)

Bases: object

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.

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(sha1_sigs)

Bases: object

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.

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)

Bases: object

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.

patcher

class pygccxml.parser.patcher.casting_operator_patcher_t

Bases: object

class pygccxml.parser.patcher.default_argument_patcher_t(enums, cxx_std)

Bases: object

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

project_reader

class pygccxml.parser.project_reader.COMPILATION_MODE

Bases: object

ALL_AT_ONCE = 'all at once'
FILE_BY_FILE = 'file by file'
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.

Parameters: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

Parameters: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

Parameters: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:

class CONTENT_TYPE

Bases: object

CACHED_SOURCE_FILE = 'cached source file'
GCCXML_GENERATED_FILE = 'gccxml generated file'
STANDARD_SOURCE_FILE = 'standard source file'
TEXT = 'text'
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)

Bases: object

parses header files and returns the contained declarations

static get_os_file_names(files)

returns file names

Parameters: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.

Parameters: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.

Parameters:decls – list of all declarations
Return type:None
class pygccxml.parser.source_reader.source_reader_t(config, cache=None, decl_factory=None, join_decls=True)

Bases: object

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

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

It has only one responsibility: it calls GCC-XML with a source file specified by the 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

    or CastXML 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 or CastXML generated id’s.

  2. linker_t - this class contains logic for replacing GCC-XML or CastXML

    generated ids with references to declarations or type class instances.

create_xml_file(source_file, destination=None)

This method will generate a xml file using an external tool.

The external tool can be either gccxml or castxml. The method will return the file path of the generated xml file.

Parameters:
  • source_file (str) – path to the source file that should be parsed.
  • destination (str) – if given, will be used as target file path for GCC-XML or CastXML.
Return type:

path to xml 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

join_declarations(declref)
read_cpp_source_file(source_file)

Reads C++ source file and returns declarations tree

Parameters:source_file (str) – path to C++ source file
read_file(source_file)
read_string(content)

Reads a Python string that contains C++ code, and return the declarations tree.

read_xml_file(xml_file)

Read generated XML file.

Parameters:xml_file (str) – path to xml file
Return type:declarations tree