Debian Codegraph @

llvm-project/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 "llvm/ADT/ArrayRef.h"
18 #include "llvm/ADT/STLFunctionalExtras.h"
19 #include "llvm/Support/MemoryBufferRef.h"
20 #include <variant>
21
22 namespace clang {
23 class SourceLocation;
24 class Decl;
25 class FileEntry;
26 class HeaderSearch;
27 namespace tooling {
28 class Replacements;
29 struct IncludeStyle;
30 } // namespace tooling
31 namespace include_cleaner {
32
33 /// A UsedSymbolCB is a callback invoked for each symbol reference seen.
34 ///
35 /// References occur at a particular location, refer to a single symbol, and
36 /// that symbol may be provided by several headers.
37 /// FIXME: Provide signals about the providing headers so the caller can filter
38 /// and rank the results.
39 using UsedSymbolCB = llvm::function_ref<void(const SymbolReference &SymRef,
40 llvm::ArrayRef<Header> Providers)>;
41
42 /// Find and report all references to symbols in a region of code.
43 /// It only reports references from main file.
44 ///
45 /// The AST traversal is rooted at ASTRoots - typically top-level declarations
46 /// of a single source file.
47 /// The references to macros must be recorded separately and provided.
48 ///
49 /// This is the main entrypoint of the include-cleaner library, and can be used:
50 /// - to diagnose missing includes: a referenced symbol is provided by
51 /// headers which don't match any #include in the main file
52 /// - to diagnose unused includes: an #include in the main file does not match
53 /// the headers for any referenced symbol
54 void walkUsed(llvm::ArrayRef<Decl *> ASTRoots,
55 llvm::ArrayRef<SymbolReference> MacroRefs,
56 const PragmaIncludes *PI, const SourceManager &, UsedSymbolCB CB);
57
58 struct AnalysisResults {
59 std::vector<const Include *> Unused;
60 std::vector<std::string> Missing; // Spellings, like "<vector>"
61 };
62
63 /// Determine which headers should be inserted or removed from the main file.
64 /// This exposes conclusions but not reasons: use lower-level walkUsed for that.
65 AnalysisResults analyze(llvm::ArrayRef<Decl *> ASTRoots,
66 llvm::ArrayRef<SymbolReference> MacroRefs,
67 const Includes &I, const PragmaIncludes *PI,
68 const SourceManager &SM, HeaderSearch &HS);
69
70 /// Removes unused includes and inserts missing ones in the main file.
71 /// Returns the modified main-file code.
72 /// The FormatStyle must be C++ or ObjC (to support include ordering).
73 std::string fixIncludes(const AnalysisResults &Results, llvm::StringRef Code,
74 const format::FormatStyle &IncludeStyle);
75
76 } // namespace include_cleaner
77 } // namespace clang
78
79 #endif