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.
Only needed with castxml on Mac or Linux.
-
pygccxml.parser.config.
gccxml_configuration_t
¶ alias of
xml_generator_configuration_t
-
pygccxml.parser.config.
load_gccxml_configuration
(configuration, **defaults)¶ loads CastXML or GCC-XML configuration from an .ini file or any other file class
configparser.ConfigParser
is able to parse.Parameters: configuration – configuration could be string(configuration file path) or instance of configparser.ConfigParser
classReturn type: xml_generator_configuration_t
Configuration file skeleton:
[gccxml] #path to gccxml or castxml executable file - optional, if not provided, os.environ['PATH'] #variable is used to find it gccxml_path=(deprecated) xml_generator_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= # gccxml or castxml xml_generator= # Do we keep xml files or not after errors keep_xml= # Set the path to the compiler compiler_path=
-
pygccxml.parser.config.
load_xml_generator_configuration
(configuration, **defaults)¶ loads CastXML or GCC-XML configuration from an .ini file or any other file class
configparser.ConfigParser
is able to parse.Parameters: configuration – configuration could be string(configuration file path) or instance of configparser.ConfigParser
classReturn type: xml_generator_configuration_t
Configuration file skeleton:
[gccxml] #path to gccxml or castxml executable file - optional, if not provided, os.environ['PATH'] #variable is used to find it gccxml_path=(deprecated) xml_generator_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= # gccxml or castxml xml_generator= # Do we keep xml files or not after errors keep_xml= # Set the path to the compiler compiler_path=
-
class
pygccxml.parser.config.
parser_configuration_t
(working_directory='.', include_paths=None, define_symbols=None, undefine_symbols=None, cflags='', compiler=None, xml_generator='gccxml', 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:
- current directory
- working directory
- 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='gccxml', 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
()¶
-
gccxml_path
¶ Gccxml binary location
-
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)¶ Bases:
object
-
pygccxml.parser.patcher.
fix_calldef_decls
(decls, enums)¶
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 fileParameters: 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++ codeParameters: 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:
path to a C++ source file
path to GCC-XML generated XML file
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.
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
]- files (list) – list of strings andor
-
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
-
static
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:
- 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.
- 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