Debian Codegraph @

clang-tools-extra/include-cleaner/include/clang-include-cleaner/Analysis.h

raw
1 //===--- Analysis.h - Analyze symbol references in AST ------------- C++-*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 /// A library that provides usage analysis for symbols based on AST analysis.
9 //===----------------------------------------------------------------------===//
10
11 #ifndef CLANG_INCLUDE_CLEANER_ANALYSIS_H
12 #define CLANG_INCLUDE_CLEANER_ANALYSIS_H
13
14 #include "clang-include-cleaner/Record.h"
15 #include "clang-include-cleaner/Types.h"
16 #include "clang/Format/Format.h"
17 #include "clang/Lex/HeaderSearch.h"
18 #include "clang/Lex/Preprocessor.h"
19 #include "llvm/ADT/ArrayRef.h"
20 #include "llvm/ADT/STLFunctionalExtras.h"
21 #include "llvm/ADT/SmallVector.h"
22 #include "llvm/ADT/StringRef.h"
23 #include <string>
24
25 namespace clang {
26 class SourceLocation;
27 class SourceManager;
28 class Decl;
29 class FileEntry;
30 class HeaderSearch;
31 namespace tooling {
32 class Replacements;
33 struct IncludeStyle;
34 } // namespace tooling
35 namespace include_cleaner {
36
37 /// A UsedSymbolCB is a callback invoked for each symbol reference seen.
38 ///
39 /// References occur at a particular location, refer to a single symbol, and
40 /// that symbol may be provided by several headers.
41 /// FIXME: Provide signals about the providing headers so the caller can filter
42 /// and rank the results.
43 using UsedSymbolCB = llvm::function_ref<void(const SymbolReference &SymRef,
44 llvm::ArrayRef<Header> Providers)>;
45
46 /// Find and report all references to symbols in a region of code.
47 /// It only reports references from main file.
48 ///
49 /// The AST traversal is rooted at ASTRoots - typically top-level declarations
50 /// of a single source file.
51 /// The references to macros must be recorded separately and provided.
52 ///
53 /// This is the main entrypoint of the include-cleaner library, and can be used:
54 /// - to diagnose missing includes: a referenced symbol is provided by
55 /// headers which don't match any #include in the main file
56 /// - to diagnose unused includes: an #include in the main file does not match
57 /// the headers for any referenced symbol
58 void walkUsed(llvm::ArrayRef<Decl *> ASTRoots,
59 llvm::ArrayRef<SymbolReference> MacroRefs,
60 const PragmaIncludes *PI, const Preprocessor &PP,
61 UsedSymbolCB CB);
62
63 struct AnalysisResults {
64 std::vector<const Include *> Unused;
65 std::vector<std::string> Missing; // Spellings, like "<vector>"
66 };
67
68 /// Determine which headers should be inserted or removed from the main file.
69 /// This exposes conclusions but not reasons: use lower-level walkUsed for that.
70 ///
71 /// The HeaderFilter is a predicate that receives absolute path or spelling
72 /// without quotes/brackets, when a phyiscal file doesn't exist.
73 /// No analysis will be performed for headers that satisfy the predicate.
74 AnalysisResults
75 analyze(llvm::ArrayRef<Decl *> ASTRoots,
76 llvm::ArrayRef<SymbolReference> MacroRefs, const Includes &I,
77 const PragmaIncludes *PI, const Preprocessor &PP,
78 llvm::function_ref<bool(llvm::StringRef)> HeaderFilter = nullptr);
79
80 /// Removes unused includes and inserts missing ones in the main file.
81 /// Returns the modified main-file code.
82 /// The FormatStyle must be C++ or ObjC (to support include ordering).
83 std::string fixIncludes(const AnalysisResults &Results,
84 llvm::StringRef FileName, llvm::StringRef Code,
85 const format::FormatStyle &IncludeStyle);
86
87 /// Gets all the providers for a symbol by traversing each location.
88 /// Returned headers are sorted by relevance, first element is the most
89 /// likely provider for the symbol.
90 llvm::SmallVector<Header> headersForSymbol(const Symbol &S,
91 const SourceManager &SM,
92 const PragmaIncludes *PI);
93 } // namespace include_cleaner
94 } // namespace clang
95
96 #endif