Clang Indexing Library Bindings¶
This module provides an interface to the Clang indexing library. It is a low-level interface to the indexing library which attempts to match the Clang API directly while also being “pythonic”. Notable differences from the C API are:
- string results are returned as Python strings, not CXString objects.
- null cursors are translated to None.
- access to child cursors is done via iteration, not visitation.
The major indexing objects are:
Index
The top-level object which manages some global library state.TranslationUnit
High-level object encapsulating the AST for a single translation unit. These can be loaded from .ast files or parsed on the fly.Cursor
Generic object for representing a node in the AST.SourceRange, SourceLocation, and File
Objects representing information about the input source.
Most object information is exposed using properties, when the underlying API call is efficient.
-
class
clang.cindex.
CompilationDatabase
(obj)[source]¶ The CompilationDatabase is a wrapper class around clang::tooling::CompilationDatabase
It enables querying how a specific source file can be built.
-
static
fromDirectory
(buildDir)[source]¶ Builds a CompilationDatabase from the database found in buildDir
-
static
-
class
clang.cindex.
CompileCommands
(ccmds)[source]¶ CompileCommands is an iterable object containing all CompileCommand that can be used for building a specific file.
-
class
clang.cindex.
CompileCommand
(cmd, ccmds)[source]¶ Represents the compile command used to build a file
-
arguments
¶ Get an iterable object providing each argument in the command line for the compiler invocation as a _CXString.
Invariant : the first argument is the compiler executable
-
directory
¶ Get the working directory for this CompileCommand
-
filename
¶ Get the working filename for this CompileCommand
-
-
class
clang.cindex.
CursorKind
(value)[source]¶ A CursorKind describes the kind of entity that a cursor points to.
-
class
clang.cindex.
Cursor
[source]¶ The Cursor class represents a reference to an element within the AST. It acts as a kind of iterator.
-
access_specifier
¶ Retrieves the access specifier (if any) of the entity pointed at by the cursor.
-
availability
¶ Retrieves the availability of the entity pointed at by the cursor.
-
brief_comment
¶ Returns the brief comment text associated with that Cursor
-
canonical
¶ Return the canonical Cursor corresponding to this Cursor.
The canonical cursor is the cursor which is representative for the underlying entity. For example, if you have multiple forward declarations for the same class, the canonical cursor for the forward declarations will be identical.
-
displayname
¶ Return the display name for the entity referenced by this cursor.
The display name contains extra information that helps identify the cursor, such as the parameters of a function or template or the arguments of a class template specialization.
-
enum_type
¶ Return the integer type of an enum declaration.
Returns a Type corresponding to an integer. If the cursor is not for an enum, this raises.
-
enum_value
¶ Return the value of an enum constant.
-
exception_specification_kind
¶ Retrieve the exception specification kind, which is one of the values from the ExceptionSpecificationKind enumeration.
-
extent
¶ Return the source range (the range of text) occupied by the entity pointed at by the cursor.
-
get_definition
()[source]¶ If the cursor is a reference to a declaration or a declaration of some entity, return a cursor that points to the definition of that entity.
-
get_num_template_arguments
()[source]¶ Returns the number of template args associated with this cursor.
-
get_template_argument_kind
(num)[source]¶ Returns the TemplateArgumentKind for the indicated template argument.
-
get_template_argument_unsigned_value
(num)[source]¶ Returns the value of the indicated arg as an unsigned 64b integer.
-
get_template_argument_value
(num)[source]¶ Returns the value of the indicated arg as a signed 64b integer.
-
get_tokens
()[source]¶ Obtain Token instances formulating that compose this Cursor.
This is a generator for Token instances. It returns all tokens which occupy the extent this cursor occupies.
-
get_usr
()[source]¶ Return the Unified Symbol Resolution (USR) for the entity referenced by the given cursor (or None).
A Unified Symbol Resolution (USR) is a string that identifies a particular entity (function, class, variable, etc.) within a program. USRs can be compared across translation units to determine, e.g., when references in one translation refer to an entity defined in another translation unit.
-
hash
¶ Returns a hash of the cursor as an int.
-
is_abstract_record
()[source]¶ Returns True if the cursor refers to a C++ record declaration that has pure virtual member functions.
-
is_const_method
()[source]¶ Returns True if the cursor refers to a C++ member function or member function template that is declared ‘const’.
-
is_converting_constructor
()[source]¶ Returns True if the cursor refers to a C++ converting constructor.
-
is_copy_assignment_operator_method
()[source]¶ Returnrs True if the cursor refers to a copy-assignment operator.
A copy-assignment operator X::operator= is a non-static, non-template member function of _class_ X with exactly one parameter of type X, X&, const X&, volatile X& or const volatile X&.
That is, for example, the operator= in:
- class Foo {
- bool operator=(const volatile Foo&);
};
Is a copy-assignment operator, while the operator= in:
- class Bar {
- bool operator=(const int&);
};
Is not.
-
is_default_method
()[source]¶ Returns True if the cursor refers to a C++ member function or member function template that is declared ‘= default’.
-
is_definition
()[source]¶ Returns true if the declaration pointed at by the cursor is also a definition of that entity.
-
is_deleted_method
()[source]¶ Returns True if the cursor refers to a C++ member function or member function template that is declared ‘= delete’.
-
is_move_assignment_operator_method
()[source]¶ Returnrs True if the cursor refers to a move-assignment operator.
A move-assignment operator X::operator= is a non-static, non-template member function of _class_ X with exactly one parameter of type X&&, const X&&, volatile X&& or const volatile X&&.
That is, for example, the operator= in:
- class Foo {
- bool operator=(const volatile Foo&&);
};
Is a move-assignment operator, while the operator= in:
- class Bar {
- bool operator=(const int&&);
};
Is not.
-
is_mutable_field
()[source]¶ Returns True if the cursor refers to a C++ field that is declared ‘mutable’.
-
is_pure_virtual_method
()[source]¶ Returns True if the cursor refers to a C++ member function or member function template that is declared pure virtual.
-
is_static_method
()[source]¶ Returns True if the cursor refers to a C++ member function or member function template that is declared ‘static’.
-
is_virtual_method
()[source]¶ Returns True if the cursor refers to a C++ member function or member function template that is declared ‘virtual’.
-
kind
¶ Return the kind of this cursor.
-
lexical_parent
¶ Return the lexical parent for this cursor.
-
linkage
¶ Return the linkage of this cursor.
-
location
¶ Return the source location (the starting character) of the entity pointed at by the cursor.
-
mangled_name
¶ Return the mangled name for the entity referenced by this cursor.
-
objc_type_encoding
¶ Return the Objective-C type encoding as a str.
-
raw_comment
¶ Returns the raw comment text associated with that Cursor
-
referenced
¶ For a cursor that is a reference, returns a cursor representing the entity that it references.
-
result_type
¶ Retrieve the Type of the result for this Cursor.
-
semantic_parent
¶ Return the semantic parent for this cursor.
-
spelling
¶ Return the spelling of the entity pointed at by the cursor.
-
storage_class
¶ Retrieves the storage class (if any) of the entity pointed at by the cursor.
-
tls_kind
¶ Return the thread-local storage (TLS) kind of this cursor.
-
translation_unit
¶ Returns the TranslationUnit to which this Cursor belongs.
-
type
¶ Retrieve the Type (if any) of the entity pointed at by the cursor.
-
underlying_typedef_type
¶ Return the underlying type of a typedef declaration.
Returns a Type for the typedef this cursor is a declaration for. If the current cursor is not a typedef, this raises.
-
-
class
clang.cindex.
Diagnostic
(ptr)[source]¶ A Diagnostic is a single instance of a Clang diagnostic. It includes the diagnostic severity, the message, the location the diagnostic occurred, as well as additional source ranges and associated fix-it hints.
-
category_name
¶ The string name of the category for this diagnostic.
-
category_number
¶ The category number for this diagnostic or 0 if unavailable.
-
disable_option
¶ The command-line option that disables this diagnostic.
-
format
(options=None)[source]¶ Format this diagnostic for display. The options argument takes Diagnostic.Display* flags, which can be combined using bitwise OR. If the options argument is not provided, the default display options will be used.
-
option
¶ The command-line option that enables this diagnostic.
-
-
class
clang.cindex.
File
(obj)[source]¶ The File class represents a particular source file that is part of a translation unit.
-
static
from_name
(translation_unit, file_name)[source]¶ Retrieve a file handle within the given translation unit.
-
name
¶ Return the complete file and path name of the file.
-
time
¶ Return the last modification time of the file.
-
static
-
class
clang.cindex.
FixIt
(range, value)[source]¶ A FixIt represents a transformation to be applied to the source to “fix-it”. The fix-it shouldbe applied by replacing the given source range with the given value.
-
class
clang.cindex.
Index
(obj)[source]¶ The Index type provides the primary interface to the Clang CIndex library, primarily by providing an interface for reading and parsing translation units.
-
static
create
(excludeDecls=False)[source]¶ Create a new Index. Parameters: excludeDecls – Exclude local declarations from translation units.
-
parse
(path, args=None, unsaved_files=None, options=0)[source]¶ Load the translation unit from the given source code file by running clang and generating the AST before loading. Additional command line parameters can be passed to clang via the args parameter.
In-memory contents for files can be provided by passing a list of pairs to as unsaved_files, the first item should be the filenames to be mapped and the second should be the contents to be substituted for the file. The contents may be passed as strings or file objects.
If an error was encountered during parsing, a TranslationUnitLoadError will be raised.
-
static
-
class
clang.cindex.
SourceLocation
[source]¶ A SourceLocation represents a particular location within a source file.
-
column
¶ Get the column represented by this source location.
-
file
¶ Get the file represented by this source location.
-
static
from_offset
(tu, file, offset)[source]¶ Retrieve a SourceLocation from a given character offset.
tu – TranslationUnit file belongs to file – File instance to obtain offset from offset – Integer character offset within file
-
static
from_position
(tu, file, line, column)[source]¶ Retrieve the source location associated with a given file/line/column in a particular translation unit.
-
line
¶ Get the line represented by this source location.
-
offset
¶ Get the file offset represented by this source location.
-
-
class
clang.cindex.
SourceRange
[source]¶ A SourceRange describes a range of source locations within the source code.
-
end
¶ Return a SourceLocation representing the last character within a source range.
-
start
¶ Return a SourceLocation representing the first character within a source range.
-
-
class
clang.cindex.
TLSKind
(value)[source]¶ Describes the kind of thread-local storage (TLS) of a cursor.
-
class
clang.cindex.
Token
[source]¶ Represents a single token from the preprocessor.
Tokens are effectively segments of source code. Source code is first parsed into tokens before being converted into the AST and Cursors.
Tokens are obtained from parsed TranslationUnit instances. You currently can’t create tokens manually.
-
cursor
¶ The Cursor this Token corresponds to.
-
extent
¶ The SourceRange this Token occupies.
-
kind
¶ Obtain the TokenKind of the current token.
-
location
¶ The SourceLocation this Token occurs at.
-
spelling
¶ The spelling of this token.
This is the textual representation of the token in source.
-
-
exception
clang.cindex.
TranslationUnitLoadError
[source]¶ Represents an error that occurred when loading a TranslationUnit.
This is raised in the case where a TranslationUnit could not be instantiated due to failure in the libclang library.
FIXME: Make libclang expose additional error information in this scenario.
-
class
clang.cindex.
TranslationUnit
(ptr, index)[source]¶ Represents a source code translation unit.
This is one of the main types in the API. Any time you wish to interact with Clang’s representation of a source file, you typically start with a translation unit.
-
codeComplete
(path, line, column, unsaved_files=None, include_macros=False, include_code_patterns=False, include_brief_comments=False)[source]¶ Code complete in this translation unit.
In-memory contents for files can be provided by passing a list of pairs as unsaved_files, the first items should be the filenames to be mapped and the second should be the contents to be substituted for the file. The contents may be passed as strings or file objects.
-
cursor
¶ Retrieve the cursor that represents the given translation unit.
-
diagnostics
¶ Return an iterable (and indexable) object containing the diagnostics.
-
classmethod
from_ast_file
(filename, index=None)[source]¶ Create a TranslationUnit instance from a saved AST file.
A previously-saved AST file (provided with -emit-ast or TranslationUnit.save()) is loaded from the filename specified.
If the file cannot be loaded, a TranslationUnitLoadError will be raised.
index is optional and is the Index instance to use. If not provided, a default Index will be created.
filename can be str or PathLike.
-
classmethod
from_source
(filename, args=None, unsaved_files=None, options=0, index=None)[source]¶ Create a TranslationUnit by parsing source.
This is capable of processing source code both from files on the filesystem as well as in-memory contents.
Command-line arguments that would be passed to clang are specified as a list via args. These can be used to specify include paths, warnings, etc. e.g. [“-Wall”, “-I/path/to/include”].
In-memory file content can be provided via unsaved_files. This is an iterable of 2-tuples. The first element is the filename (str or PathLike). The second element defines the content. Content can be provided as str source code or as file objects (anything with a read() method). If a file object is being used, content will be read until EOF and the read cursor will not be reset to its original position.
options is a bitwise or of TranslationUnit.PARSE_XXX flags which will control parsing behavior.
index is an Index instance to utilize. If not provided, a new Index will be created for this TranslationUnit.
To parse source from the filesystem, the filename of the file to parse is specified by the filename argument. Or, filename could be None and the args list would contain the filename(s) to parse.
To parse source from an in-memory buffer, set filename to the virtual filename you wish to associate with this source (e.g. “test.c”). The contents of that file are then provided in unsaved_files.
If an error occurs, a TranslationUnitLoadError is raised.
Please note that a TranslationUnit with parser errors may be returned. It is the caller’s responsibility to check tu.diagnostics for errors.
Also note that Clang infers the source language from the extension of the input filename. If you pass in source code containing a C++ class declaration with the filename “test.c” parsing will fail.
-
get_extent
(filename, locations)[source]¶ Obtain a SourceRange from this translation unit.
The bounds of the SourceRange must ultimately be defined by a start and end SourceLocation. For the locations argument, you can pass:
- 2 SourceLocation instances in a 2-tuple or list.
- 2 int file offsets via a 2-tuple or list.
- 2 2-tuple or lists of (line, column) pairs in a 2-tuple or list.
e.g.
get_extent(‘foo.c’, (5, 10)) get_extent(‘foo.c’, ((1, 1), (1, 15)))
-
get_includes
()[source]¶ Return an iterable sequence of FileInclusion objects that describe the sequence of inclusions in a translation unit. The first object in this sequence is always the input file. Note that this method will not recursively iterate over header files included through precompiled headers.
-
get_location
(filename, position)[source]¶ Obtain a SourceLocation for a file in this translation unit.
The position can be specified by passing:
- Integer file offset. Initial file offset is 0.
- 2-tuple of (line number, column number). Initial file position is (0, 0)
-
get_tokens
(locations=None, extent=None)[source]¶ Obtain tokens in this translation unit.
This is a generator for Token instances. The caller specifies a range of source code to obtain tokens for. The range can be specified as a 2-tuple of SourceLocation or as a SourceRange. If both are defined, behavior is undefined.
-
reparse
(unsaved_files=None, options=0)[source]¶ Reparse an already parsed translation unit.
In-memory contents for files can be provided by passing a list of pairs as unsaved_files, the first items should be the filenames to be mapped and the second should be the contents to be substituted for the file. The contents may be passed as strings or file objects.
-
save
(filename)[source]¶ Saves the TranslationUnit to a file.
This is equivalent to passing -emit-ast to the clang frontend. The saved file can be loaded back into a TranslationUnit. Or, if it corresponds to a header, it can be used as a pre-compiled header file.
If an error occurs while saving, a TranslationUnitSaveError is raised. If the error was TranslationUnitSaveError.ERROR_INVALID_TU, this means the constructed TranslationUnit was not valid at time of save. In this case, the reason(s) why should be available via TranslationUnit.diagnostics().
filename – The path to save the translation unit to (str or PathLike).
-
spelling
¶ Get the original translation unit source file name.
-
-
class
clang.cindex.
TypeKind
(value)[source]¶ Describes the kind of type.
-
spelling
¶ Retrieve the spelling of this TypeKind.
-
-
class
clang.cindex.
Type
[source]¶ The type of an element in the abstract syntax tree.
-
argument_types
()[source]¶ Retrieve a container for the non-variadic arguments for this type.
The returned object is iterable and indexable. Each item in the container is a Type instance.
-
element_count
¶ Retrieve the number of elements in this type.
Returns an int.
If the Type is not an array or vector, this raises.
-
element_type
¶ Retrieve the Type of elements within this Type.
If accessed on a type that is not an array, complex, or vector type, an exception will be raised.
-
get_canonical
()[source]¶ Return the canonical type for a Type.
Clang’s type system explicitly models typedefs and all the ways a specific type can be represented. The canonical type is the underlying type with all the “sugar” removed. For example, if ‘T’ is a typedef for ‘int’, the canonical type for ‘T’ would be ‘int’.
-
get_exception_specification_kind
()[source]¶ Return the kind of the exception specification; a value from the ExceptionSpecificationKind enumeration.
-
is_const_qualified
()[source]¶ Determine whether a Type has the “const” qualifier set.
This does not look through typedefs that may have added “const” at a different level.
-
is_restrict_qualified
()[source]¶ Determine whether a Type has the “restrict” qualifier set.
This does not look through typedefs that may have added “restrict” at a different level.
-
is_volatile_qualified
()[source]¶ Determine whether a Type has the “volatile” qualifier set.
This does not look through typedefs that may have added “volatile” at a different level.
-
kind
¶ Return the kind of this type.
-
spelling
¶ Retrieve the spelling of this Type.
-
translation_unit
¶ The TranslationUnit to which this Type is associated.
-