Neslib.Clang

Neslib.Clang

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

License

Interface ITranslationUnit

DescriptionHierarchyFieldsMethodsProperties

Unit

Neslib.Clang

Declaration

type ITranslationUnit = interface(IInterface)

Description

A single translation unit, which resides in an IIndex.

Attributes
GUID['{FC9A4ABF-B285-47AF-A063-C8C85CABE02E}']

Hierarchy

  • IInterface
  • ITranslationUnit

Overview

Methods

Public function GetDiagnosticCount: Integer;
Public function GetDiagnostic(const AIndex: Integer): IDiagnostic;
Public function GetAllDiagnostics: IDiagnosticSet;
Public function GetSpelling: String;
Public function GetResourceUsage: IResourceUsage;
Public function GetTargetInfo: ITargetInfo;
Public function GetCursor: TCursor; overload;
Public function GetHandle: TCXTranslationUnit;
Public function GetFile(const AFilename: String): TFile;
Public function GetFileContents(const AFile: TFile): TBytes;
Public function IsFileMultipleIncludeGuarded(const AFile: TFile): Boolean;
Public function GetLocation(const AFile: TFile; const ALine, AColumn: Integer): TSourceLocation; overload;
Public function GetLocation(const AFile: TFile; const AOffset: Integer): TSourceLocation; overload;
Public function GetSkippedRanges(const AFile: TFile): ISourceRangeList;
Public function GetAllSkippedRanges: ISourceRangeList;
Public function Save(const AFilename: String): TSaveResult;
Public procedure Suspend;
Public function Reparse(const AUnsavedFiles: TArray<TUnsavedFile> = nil): TError;
Public function GetCursor(const ASourceLocation: TSourceLocation): TCursor; overload;
Public function GetModule(const AFile: TFile): TModule;
Public function GetTopLevelHeaderCount(const AModule: TModule): Integer;
Public function GetTopLevelHeader(const AModule: TModule; const AIndex: Integer): TFile;
Public function Tokenize(const ARange: TSourceRange): ITokenList;
Public function AnnotateTokens(const ATokens: ITokenList): TArray<TCursor>; overload;
Public function AnnotateTokens(const ATokens: TArray<TToken>): TArray<TCursor>; overload;
Public function GetTokenSpelling(const AToken: TToken): String;
Public function GetTokenLocation(const AToken: TToken): TSourceLocation;
Public function GetTokenExtent(const AToken: TToken): TSourceRange;
Public function CodeCompleteAt(const ACompleteFilename: String; const ACompleteLine, ACompleteColumn: Integer; const AUnsavedFiles: TArray<TUnsavedFile> = nil; const AOptions: TCodeCompleteFlags = []): ICodeCompleteResults;
Public procedure GetInclusions(const AVisitor: TInclusionVisitor); overload;
Public procedure GetInclusions(const AVisitor: TInclusionVisitorMethod); overload;
Public function FindIncludesInFile(const AFile: TFile; const AVisitor: TCursorAndRangeVisitor): TVisitResult; overload;
Public function FindIncludesInFile(const AFile: TFile; const AVisitor: TCursorAndRangeVisitorMethod): TVisitResult; overload;

Properties

Public property DiagnosticCount: Integer read GetDiagnosticCount;
Public property Diagnostics[constAIndex:Integer]: IDiagnostic read GetDiagnostic;
Public property AllDiagnostics: IDiagnosticSet read GetAllDiagnostics;
Public property Spelling: String read GetSpelling;
Public property ResourceUsage: IResourceUsage read GetResourceUsage;
Public property TargetInfo: ITargetInfo read GetTargetInfo;
Public property Cursor: TCursor read GetCursor;
Public property Handle: TCXTranslationUnit read GetHandle;

Description

Methods

Public function GetDiagnosticCount: Integer;
 
Public function GetDiagnostic(const AIndex: Integer): IDiagnostic;
 
Public function GetAllDiagnostics: IDiagnosticSet;
 
Public function GetSpelling: String;
 
Public function GetResourceUsage: IResourceUsage;
 
Public function GetTargetInfo: ITargetInfo;
 
Public function GetCursor: TCursor; overload;
 
Public function GetHandle: TCXTranslationUnit;
 
Public function GetFile(const AFilename: String): TFile;

Retrieve a file handle within this translation unit.

Parameters
AFilename
the name of the file.
Returns

The file handle for the named file in the translation unit, or a Null file handle if the file was not a part of this translation unit.

Public function GetFileContents(const AFile: TFile): TBytes;

Retrieve the buffer associated with the given file.

Parameters
AFile
the file for which to retrieve the buffer.
Returns

The contents of the file, or nil when the file is not loaded.

Public function IsFileMultipleIncludeGuarded(const AFile: TFile): Boolean;

Determine whether the given header is guarded against multiple inclusions, either with the conventional #ifndef, #define, #endif macro guards or with #pragma once.

Public function GetLocation(const AFile: TFile; const ALine, AColumn: Integer): TSourceLocation; overload;

Retrieves the source location associated with a given file/line/column in a particular translation unit.

Public function GetLocation(const AFile: TFile; const AOffset: Integer): TSourceLocation; overload;

Retrieves the source location associated with a given character offset in a particular translation unit.

Public function GetSkippedRanges(const AFile: TFile): ISourceRangeList;

Retrieve all ranges that were skipped by the preprocessor.

The preprocessor will skip lines when they are surrounded by an if/ifdef/ifndef directive whose condition does not evaluate to True.

Public function GetAllSkippedRanges: ISourceRangeList;

Retrieve all ranges from all files that were skipped by the preprocessor.

The preprocessor will skip lines when they are surrounded by an if/ifdef/ifndef directive whose condition does not evaluate to True.

Public function Save(const AFilename: String): TSaveResult;

Saves the translation unit into a serialized representation of that translation unit on disk.

Any translation unit that was parsed without error can be saved into a file. The translation unit can then be deserialized into a new ITranslationUnit with IIndex.CreateTranslationUnit or, if it is an incomplete translation unit that corresponds to a header, used as a precompiled header when parsing other translation units.

Parameters
AFilename
The file to which the translation unit will be saved.
Returns

Save result.

Public procedure Suspend;

Suspend a translation unit in order to free memory associated with it.

A suspended translation unit uses significantly less memory but on the other side does not support any other calls than Reparse to resume it.

Public function Reparse(const AUnsavedFiles: TArray<TUnsavedFile> = nil): TError;

Reparse the source files that produced this translation unit.

This routine can be used to re-parse the source files that originally created the given translation unit, for example because those source files have changed (either on disk or as passed via AUnsavedFiles). The source code will be reparsed with the same command-line options as it was originally parsed.

Reparsing a translation unit invalidates all cursors and source locations that refer into that translation unit. This makes reparsing a translation unit semantically equivalent to destroying the translation unit and then creating a new translation unit with the same command-line arguments. However, it may be more efficient to reparse a translation unit using this routine.

NOTE: The translation unit must originally have been built with IIndex.CreateTranslationUnitFromSource.

Parameters
AUnsavedFiles
(optional) array of files that have not yet been saved to disk but may be required for code completion, including the contents of those files.
Returns

AN error code.

Public function GetCursor(const ASourceLocation: TSourceLocation): TCursor; overload;

Map a source location to the cursor that describes the entity at that location in the source code.

Maps an arbitrary source location within the translation unit down to the most specific cursor that describes the entity at that location. For example, given an expression "x + y", invoking GetCursor with a source location pointing to "x" will return the cursor for "x"; similarly for "y". If the cursor points anywhere between "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() will return a cursor referring to the "+" expression.

Returns

A cursor representing the entity at the given source location, or a NULL cursor if no such entity can be found.

Public function GetModule(const AFile: TFile): TModule;

Given a TFile header file, return the module that contains it, if one exists.

Public function GetTopLevelHeaderCount(const AModule: TModule): Integer;

The number of top level headers associated with a module.

Public function GetTopLevelHeader(const AModule: TModule; const AIndex: Integer): TFile;

The top level headers associated with a module.

Public function Tokenize(const ARange: TSourceRange): ITokenList;

Tokenize the source code described by the given range into raw lexical tokens.

Parameters
ARange
the source range in which text should be tokenized. All of the tokens produced by tokenization will fall within this source range,
Returns

The list of tokens.

Public function AnnotateTokens(const ATokens: ITokenList): TArray<TCursor>; overload;
Public function AnnotateTokens(const ATokens: TArray<TToken>): TArray<TCursor>; overload;

Annotate the given set of tokens by providing cursors for each token that can be mapped to a specific entity within the abstract syntax tree.

This token-annotation routine is equivalent to invoking GetCursor for the source locations of each of the tokens. The cursors provided are filtered, so that only those cursors that have a direct correspondence to the token are accepted. For example, given a function call "f(x)", GetCursor would provide the following cursors:

  • when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'.

  • when the cursor is over the '(' or the ')', a CallExpr referring to 'f'.

  • when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'.

Only the first and last of these cursors will occur within the annotate, since the tokens "f" and "x" directly refer to a function and a variable, respectively, but the parentheses are just a small part of the full syntax of the function call expression, which is not provided as an annotation.

Parameters
ATokens
the set of tokens to annotate.
Returns

The cursors corresponding to each token.

Public function GetTokenSpelling(const AToken: TToken): String;

Determine the spelling of the given token.

The spelling of a token is the textual representation of that token, e.g., the text of an identifier or keyword.

Public function GetTokenLocation(const AToken: TToken): TSourceLocation;

Retrieve the source location of the given token.

Public function GetTokenExtent(const AToken: TToken): TSourceRange;

Retrieve a source range that covers the given token.

Public function CodeCompleteAt(const ACompleteFilename: String; const ACompleteLine, ACompleteColumn: Integer; const AUnsavedFiles: TArray<TUnsavedFile> = nil; const AOptions: TCodeCompleteFlags = []): ICodeCompleteResults;

Perform code completion at a given location in the translation unit.

This function performs code completion at a particular file, line, and column within source code, providing results that suggest potential code snippets based on the context of the completion. The basic model for code completion is that Clang will parse a complete source file, performing syntax checking up to the location where code-completion has been requested. At that point, a special code-completion token is passed to the parser, which recognizes this token and determines, based on the current location in the C/Objective-C/C++ grammar and the state of semantic analysis, what completions to provide. These completions are returned via a new ICodeCompleteResults object.

Code completion itself is meant to be triggered by the client when the user types punctuation characters or whitespace, at which point the code-completion location will coincide with the cursor. For example, if "p" is a pointer, code-completion might be triggered after the "-" and then after the ">" in "p->". When the code-completion location is afer the ">", the completion results will provide, e.g., the members of the struct that "p" points to. The client is responsible for placing the cursor at the beginning of the token currently being typed, then filtering the results based on the contents of the token. For example, when code-completing for the expression "p->get", the client should provide the location just after the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the client can filter the results based on the current token text ("get"), only showing those results that start with "get". The intent of this interface is to separate the relatively high-latency acquisition of code-completion results from the filtering of results on a per-character basis, which must have a lower latency.

NOTE: The source files for this translation unit need not be completely up-to-date (and the contents of those source files may be overridden via AUnsavedFiles). Cursors referring into the translation unit may be invalidated by this invocation.

Parameters
ACompleteFilename
The name of the source file where code completion should be performed. This filename may be any file included in the translation unit.
ACompleteLine
The line at which code-completion should occur.
ACompleteColumn
The column at which code-completion should occur. Note that the column should point just after the syntactic construct that initiated code completion, and not in the middle of a lexical token.
AUnsavedFiles
(optional) array of files that have not yet been saved to disk but may be required for parsing or code completion, including the contents of those files.
AOptions
(optional) extra options that control the behavior of code completion. The GetDefaultCodeCompleteOptions function returns a default set of code-completion options.
Returns

If successful, a new ICodeCompleteResults object containing code-completion results. If code completion fails, returns nil.

Public procedure GetInclusions(const AVisitor: TInclusionVisitor); overload;
Public procedure GetInclusions(const AVisitor: TInclusionVisitorMethod); overload;

Visit the set of preprocessor inclusions in a translation unit. The visitor (anonymous) method is called with the provided data for every included file. This does not include headers included by the PCH file (unless one is inspecting the inclusions in the PCH file itself).

Public function FindIncludesInFile(const AFile: TFile; const AVisitor: TCursorAndRangeVisitor): TVisitResult; overload;
Public function FindIncludesInFile(const AFile: TFile; const AVisitor: TCursorAndRangeVisitorMethod): TVisitResult; overload;

Find #import/#include directives in a specific file.

Parameters
AFile
file to search for #import/#include directives.
AVisitor
visitor callback that will receive pairs of TCursor/TSourceRange for each directive found.
Returns

A visit result

Properties

Public property DiagnosticCount: Integer read GetDiagnosticCount;

The number of diagnostics produced for this translation unit.

Public property Diagnostics[constAIndex:Integer]: IDiagnostic read GetDiagnostic;

The diagnostics produced for this translation unit.

Public property AllDiagnostics: IDiagnosticSet read GetAllDiagnostics;

The complete set of diagnostics associated with a translation unit.

Public property Spelling: String read GetSpelling;

Get the original translation unit source file name.

Public property ResourceUsage: IResourceUsage read GetResourceUsage;

The memory usage of this translation unit.

Public property TargetInfo: ITargetInfo read GetTargetInfo;

Target information for this translation unit.

Public property Cursor: TCursor read GetCursor;

The cursor that represents this translation unit.

The translation unit cursor can be used to start traversing the various declarations within the given translation unit.

Public property Handle: TCXTranslationUnit read GetHandle;

Internal handle to C API

Generated by PasDocEx, based on PasDoc 0.14.0.