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

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