LibClang-3.4.0: Haskell bindings for libclang (a C++ parsing library)

Safe HaskellNone
LanguageHaskell2010

Clang.TranslationUnit

Contents

Description

Functions for manipulating translation units.

To start analyzing a translation unit, call withNew to create a new index and call withParsed in the callback. Inside the callback for withParsed, you'll have access to a TranslationUnit value; you can call getCursor to turn that into an AST cursor which can be traversed using the functions in Clang.Cursor.

This module is intended to be imported qualified.

Synopsis

Creating a translation unit

withParsed Source

Arguments

:: ClangBase m 
=> Index s'

The index into which the translation unit should be loaded.

-> Maybe FilePath

The file to load, or Nothing if the file is specified in the command line arguments.

-> [String]

The command line arguments libclang should use when compiling this file. Most arguments which you'd use with the 'clang' frontend are accepted.

-> Vector UnsavedFile

Unsaved files which may be needed to parse this translation unit. This may include the source file itself or any file it includes.

-> [TranslationUnitFlags]

Flags that affect the processing of this translation unit.

-> (forall s. TranslationUnit s -> ClangT s m a)

A callback.

-> ClangT s' m (Maybe a)

The return value of the callback, or Nothing if the file couldn't be parsed.

Creates a translation unit by parsing source code.

Note that not all command line arguments which are accepted by the 'clang' frontend can be used here. You should avoid passing '-c', '-o', '-fpch-deps', and the various '-M' options. If you provide a FilePath when calling withParsed, also be sure not to provide the filename in the command line arguments as well.

withLoaded Source

Arguments

:: ClangBase m 
=> Index s'

The index into which the translation unit should be loaded.

-> FilePath

The file to load.

-> (forall s. TranslationUnit s -> ClangT s m a)

A callback.

-> ClangT s' m a 

Creates a translation unit by loading a saved AST file.

Such an AST file can be created using save.

withReparsing Source

Arguments

:: ClangBase m 
=> Index s'

The index into which the translation unit should be loaded.

-> Maybe FilePath

The file to load, or Nothing if the file is specified in the command line arguments.

-> [String]

The command line arguments libclang should use when compiling this file. Most arguments which you'd use with the 'clang' frontend are accepted.

-> Vector UnsavedFile

Unsaved files which may be needed to parse this translation unit. This may include the source file itself or any file it includes.

-> [TranslationUnitFlags]

Flags that affect the processing of this translation unit.

-> ReparsingCallback m r

A callback which uses the translation unit. May be called many times depending on the return value. See ParseContinuation for more information.

-> ClangT s' m (Maybe r)

The return value of the callback, as passed to ParseComplete, or Nothing if the file could not be parsed.

Creates a translation unit by parsing source code.

This works like withParsed, except that the translation unit can be reparsed over and over again by returning a Reparse value from the callback. This is useful for interactive analyses like code completion. Processing can be stopped by returning a ParseComplete value.

data TranslationUnitFlags Source

Flags that control how a translation unit is parsed.

  • DetailedPreprocessingRecordFlag: Used to indicate that the parser should construct a "detailed" preprocessing record, including all macro definitions and instantiations. Constructing a detailed preprocessing record requires more memory and time to parse, since the information contained in the record is usually not retained. However, it can be useful for applications that require more detailed information about the behavior of the preprocessor.
  • IncompleteFlag: Used to indicate that the translation unit is incomplete. When a translation unit is considered "incomplete", semantic analysis that is typically performed at the end of the translation unit will be suppressed. For example, this suppresses the completion of tentative declarations in C and of instantiation of implicitly-instantiation function templates in C++. This option is typically used when parsing a header with the intent of producing a precompiled header.
  • PrecompiledPreambleFlag: Used to indicate that the translation unit should be built with an implicit precompiled header for the preamble. An implicit precompiled header is used as an optimization when a particular translation unit is likely to be reparsed many times when the sources aren't changing that often. In this case, an implicit precompiled header will be built containing all of the initial includes at the top of the main file (what we refer to as the "preamble" of the file). In subsequent parses, if the preamble or the files in it have not changed, reparse will re-use the implicit precompiled header to improve parsing performance.
  • CacheCompletionResultsFlag: Used to indicate that the translation unit should cache some code-completion results with each reparse of the source file. Caching of code-completion results is a performance optimization that introduces some overhead to reparsing but improves the performance of code-completion operations.
  • ForSerializationFlag: Used to indicate that the translation unit will be serialized save. This option is typically used when parsing a header with the intent of producing a precompiled header.
  • CXXChainedPCHFlag: DEPRECATED: Enabled chained precompiled preambles in C++. Note: this is a *temporary* option that is available only while we are testing C++ precompiled preamble support. It is deprecated.
  • SkipFunctionBodiesFlag: Used to indicate that function/method bodies should be skipped while parsing. This option can be used to search for declarations/definitions while ignoring the usages.
  • IncludeBriefCommentsInCodeCompletionFlag: Used to indicate that brief documentation comments should be included into the set of code completions returned from this translation unit.

Instances

data ReparseFlags Source

Flags that control how a translation unit is reparsed.

Instances

type ReparsingCallback m r = forall s. TranslationUnit s -> ClangT s m (ParseContinuation m r) Source

A callback for use with withReparsing.

data ParseContinuation m r Source

A continuation returned by a ReparsingCallback.

Constructors

Reparse (ReparsingCallback m r) (Vector UnsavedFile) (Maybe [ReparseFlags])

Reparse signals that the translation unit should be reparsed. It contains a callback which will be called with the updated translation unit after reparsing, a Vector of unsaved files which may be needed to reparse, and a set of flags affecting reparsing. The default reparsing flags can be requested by specifying Nothing.

ParseComplete r

ParseComplete signals that processing is finished. It contains a final result which will be returned by withReparsing.

Saving

save Source

Arguments

:: ClangBase m 
=> TranslationUnit s'

The translation unit to save.

-> FilePath

The filename to save to.

-> Maybe [SaveTranslationUnitFlags]

Flags that affect saving, or Nothing for the default set of flags.

-> ClangT s m Bool 

Saves a translation unit as an AST file with can be loaded later using withLoaded.

data SaveTranslationUnitFlags Source

Flags that control how a translation unit is saved.

Instances

getCursor :: ClangBase m => TranslationUnit s' -> ClangT s m (Cursor s) Source

Retrieve the cursor associated with this translation unit. This cursor is the root of this translation unit's AST; you can begin exploring the AST further using the functions in Clang.Cursor.

getDiagnosticSet :: ClangBase m => TranslationUnit s' -> ClangT s m (DiagnosticSet s) Source

Retrieve the complete set of diagnostics associated with the given translation unit.

getSpelling :: ClangBase m => TranslationUnit s' -> ClangT s m (ClangString s) Source

Retrieve a textual representation of this translation unit.