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
25namespace clang {
26class SourceLocation;
27class SourceManager;
28class Decl;
29class FileEntry;
30class HeaderSearch;
31namespace tooling {
32class Replacements;
33struct IncludeStyle;
34} // namespace tooling
35namespace 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.
43using 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
58void walkUsed(llvm::ArrayRef<Decl *> ASTRoots,
59 llvm::ArrayRef<SymbolReference> MacroRefs,
60 const PragmaIncludes *PI, const Preprocessor &PP,
61 UsedSymbolCB CB);
62
63struct 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.
74AnalysisResults
75analyze(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).
83std::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.
90llvm::SmallVector<Header> headersForSymbol(const Symbol &S,
91 const SourceManager &SM,
92 const PragmaIncludes *PI);
93} // namespace include_cleaner
94} // namespace clang
95
96#endif
97

source code of clang-tools-extra/include-cleaner/include/clang-include-cleaner/Analysis.h