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

  - `create_source_fc()`
  - `create_gccxml_fc()`
  - `create_cached_source_fc()`
  - `create_text_fc()`
  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